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 3.0:

<script src="https://b.micr.io/micrio-3.0.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 <micr-io> 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
`onDraw`	Array	Array with functions triggered for every frame drawn
`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

These events are fired on the Micrio JS instance (not the HTML element)

micrioInstance.addEventListener('move', e => {
	console.log('Current viewport:', e.detail);
});

Event name	Description
`draw`	When a frame is drawn, even if the camera position didn't change
`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 panning and dragging events
`hookKeys()`	Hook keyboard controls
`hookPinch()`	Hook trackpad/touchscreen pinching for zooming
`hookScroll()`	Hook mousewheel/trackpad scrolling for zooming
`unhook()`	Unhook all user input event types (pan, mousewheel zoom, swipe, pinch)
`unhookDrag()`	Unhook pan and dragging events
`unhookKeys()`	Unhook keyboard controls
`unhookPinch()`	Unhook trackpad/touchscreen pinching controls
`unhookScroll()`	Unhook mousewheel/trackpad scrolling for zooming

Log in with your Google account