Menu

4. JavaScript Image API

Using JavaScript, you can have full control over your Micrio images. You can control what the user sees and handle custom events.

Note: See the JS Modules API documentation for documentation on markers, tours and audio.

The current latest version of the Micrio client is 1.8:
<link rel="stylesheet" type="text/css" href="https://b.micr.io/micrio-1.8.min.css" />
<script src="https://b.micr.io/micrio-1.8.min.js"></script>

4.1. The Micrio class

You can create or access existing Micrio images using Javascript. The Micrio object is the basis for accessing the camera, events, and marker classes.

4.1.1. Accessing the instance

You can access a Micrio image in Javascript either by creating it there (see 3.2.3), or referencing a <micrio> embed like this:

let image = document.getElementById('your-micrio-id').micrio;

4.1.2. Properties

Property Type Description
camera camera A reference to the camera controller object
container HTML element The Micrio main DOM element
data Object The image settings as received from the editor
el HTML Element The Micrio <canvas> DOM element
height Number The original image height
id String The image ID
modules modules A reference to the modules controller object
startView Array The client or editor specified start view
thumbSrc Url The thumbnail image src for this image (direct link)
width Number The original image width

4.1.3. Methods

Method Returns Description
show() Promise This initializes and shows the image, returning a promise for when the initial view is fully downloaded.
image.show().then(function(){
	console.log('The image is ready and shown!');
});
hide() Use this to remove the image from the DOM and remove all event handlers
setSharpRatio(float) Set the image sharpness. 1 is default, 2 would make all pixels 200% larger, but will decrease tile downloads
setZoomLimit(float) Set the maximum level the user can zoom to. Defaults to 1 (100%)

4.1.4. Events

All events are fired on the Micrio container element.

Event name Description
hide Fires when the image is hidden or destroyed
load Fires when the image is loaded and ready to be shown
preset Fires when settings for this image have been loaded and the image is ready for its first draw
show Fires when the image is fully loaded and shown

4.2. The Camera class

The image.camera class gives you full control over what the user sees.

4.2.1. Properties

Property Type Description
events events A reference to the events controller object

4.2.2. Methods

Method Returns Description
draw() Forces a redraw of the current canvas
flyTo(x, y, scale, duration (ms)) Promise Fly to a certain coordinate and zoom level. Returns a promise for when the animation is done.
camera.flyToView(0.5,0.5,1,2000).then(function(){
	console.log('Zoomed 100% into the center of the image!');
});
flyToCoverView(duration (ms)) Promise Fly to a cover-view of the image, like CSS background-size: cover
flyToFullView(duration (ms)) Promise Fly to a full overview of the image
flyToView(viewport ([x0,y0,x1,y1]), duration (ms)) Promise Fly to the specified view of the image
fullScreenToggle() Toggle image fullscreen mode. This only works when called within a user event handler (click, touch).
getCoo([xPx, yPx]) Coordinates Gets relative image coordinates based on X and Y in pixels
getView() Viewport [x0,y0,x1,y1] Gets the current screen viewport
getXY([xPerc, yPerc]) Screen pixels [x,y] Gets screen pixel coordinates based on an image coordinate [x,y]
hook() Hook all event types (resize, pan, zoom, swipe, pinch)
isZoomedOut() Boolean Return true if the user is fully zoomed out
onresize() Resizes the Micrio canvas element to fit its container after a manual element resize
pause() Pauses any camera animation
reset() Resets the viewport to the starting view
resume() Resumes any camera animation
setCoo([xPerc, yPerc]) Sets viewport coordinates without animating
setScale(scale) Immediately sets the image scale to this (1 = 100%)
setView(viewport ([x0,y0,x1,y1])) Immediately sets current viewport
unhook() Unhook all event types (resize, pan, zoom, swipe, pinch)
zoomIn(factor, duration (ms)) Zooms in factor (default 1) taking duration ms (default 0)
zoomOut(factor, duration (ms)) Zooms out factor (default 1) taking duration ms (default 0)

4.2.3. Events

All events are fired on the Micrio container element.

Event name Description
gesture-end When a user ends dragging or zooming
gesture-start When a user starts dragging or zooming
draw Fires on any framedraw. Micrio only draws when necessary, so this is not 60 times / second.
move Fires only on unique framedraws, meaning when the camera has panned/zoomed
zoom Fires only when the image is being zoomed

4.3. The Camera.Events class

This class contains all the internal Micrio event handlers for user interactions (mouse and touch).

4.3.1. Properties

This class has no relevant public properties.

4.3.2. Methods

Method Description
hook() Hook all user input event types (pan, mousewheel zoom, swipe, pinch)
hookDrag() Hook pan and swipe events
hookKeys() Hook keyboard controls
hookScroll() Hook mousewheel zoom events
unhook() Unhook all user input event types (pan, mousewheel zoom, swipe, pinch)
unhookDrag() Unhook pan and swipe events
unhookKeys() Unhook keyboard controls
unhookScroll() Unhook mousewheel zoom events
By Marcel Duin, marcel@q42.nl - Last modified: 08/18/2017