Skip to content

JS API Client 2.x

WARNING

This page is about the Micrio client version 2, which is no longer supported. Use the links below to navigate to alternative versions.

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.

Accessing the JS instance

You can access a Micrio image in Javascript by referencing a <micr-io> embed like this:

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

Properties

PropertyTypeDescription
cameracameraA reference to the camera controller object
containerHTML elementThe Micrio main DOM element
dataObjectThe image settings as received from the editor
elHTML ElementThe Micrio <canvas> DOM element
heightNumberThe original image height
idStringThe image ID
modulesmodulesA reference to the modules controller object
onDrawArrayArray with functions triggered for every frame drawn
startViewArrayThe client or editor specified start view
thumbSrcUrlThe thumbnail image src for this image (direct link)
widthNumberThe original image width

Methods

MethodReturnsDescription
show()Promise This initializes and shows the image, returning a promise for when the initial view is fully downloaded.
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%)

Events

Event nameDescription
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

2. The Camera class

Properties

PropertyTypeDescription
eventseventsA reference to the events controller object

Methods

MethodReturnsDescription
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.
flyToCoverView(duration (ms))Promise Fly to a cover-view of the image, like CSS background-size: cover
flyToFullView(duration (ms))PromiseFly to a full overview of the image
flyToView(viewport ([x0,y0,x1,y1]), duration (ms))PromiseFly 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])CoordinatesGets 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()BooleanReturn 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)

Events

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

js
micrioInstance.addEventListener('move', e => {
	console.log('Current viewport:', e.detail);
});
Event nameDescription
drawWhen a frame is drawn, even if the camera position didn't change
moveFires only on unique framedraws, meaning when the camera has panned/zoomed
zoomFires only when the image is being zoomed

3. The Camera.Events class

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

Properties

This class has no relevant public properties.

Methods

MethodDescription
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

4. The Micrio.Modules class

The Micrio.Modules class contains all functionality relating to the minimap, markers, tours, and audio.

Properties

PropertyTypeDescription
markersMarkersA reference to the Markers controller object
markerToursMarkerToursA reference to the MarkerTours objects
minimapMiniMapA reference to the MiniMap controller object
navigatorNavigatorA reference to the Navigator controller object
toursToursA reference to the Tour objects

Events

All events are fired on the Micrio container element.

Event nameDescription
metadataFires when all image module metadata (markers, tours, audio) has been loaded

5. The Markers class

Properties

PropertyTypeDescription
_containerHTML ElementThe DOM marker container element
itemsArray of markersAn array of all existing markers

Methods

MethodDescription
place()Places all markers on the image
remove()Removes all markers from the image
addItem(marker)Add a new marker to the image

6. The Marker class

This class is the controller for all Markers that have been added to the image in the editor.

Properties

PropertyTypeDescription
_containerHTML ElementGets the marker HTML container element
_markerHTML ElementGets the marker HTML marker icon element
audioStringThe marker audio URL when entered
bodyStringThe marker body text
classStringAny custom class names entered in the editor
dataObjectAny custom JSON added to the marker
htmlStringAny custom HTML added to the marker in the editor
iconUrlURLGets or sets the icon image URL to use as marker icon
imagesArrayAn array of image URLs added to the marker in the editor
jsonObjectAll marker data from the editor
onbeforeopenFunction Gets or sets the function to call when the marker is opened, but the camera hasn't started animating yet
onbeforecloseFunction Gets or sets the function to call at the start of the marker closing handling
oncloseFunctionGets or sets the function to call when the marker is closed
onflowntoFunction Gets or sets the function to call when the camera animation to the marker view has finished
onopenFunctionGets or sets the function to call when the marker is opened
openedBooleanReturns whether the marker is opened or not
popupPopup controllerThe marker main popup controller object
popupsArray of PopupsAll marker popup controllers
titleStringThe marker title
viewViewportThe viewport to zoom to when the marker is opened
xNumberGets or sets the X-coordinate (0-1) of the marker on the image
yNumberGets or sets the Y-coordinate (0-1) of the marker on the image

Methods

MethodDescription
close()Close the marker
open()Open the marker
draw()Force an individual marker draw action
addPopup(popup)Add an individual Popup to this marker

Events

Event nameDescription
marker-closedFires when this marker has been closed
marker-openFires when this marker has been opened
marker-openedFires when this marker has been opened and the camera has flown to its viewport

7. The Marker.Popup class

Properties

PropertyTypeDescription
_audioHTML ElementReturns the marker audio HTML5 element if entered
_bodyHTML ElementGets the popup body contents element
_containerHTML ElementGets the popup container container element
_contentHTML ElementGets the popup main content element
_htmlHTML ElementGets the popup custom HTML container element
_imagesHTML ElementGets the popup images container element
_titleHTML ElementGets the popup title element
oncloseFunctionGets or sets the function to call when the popup is closed
onopenFunctionGets or sets the function to call when the popup is opened

Methods

MethodDescription
close()Close the popup
open()Open the popup

8. The MarkerTour class

The MarkerTour class contains all functionality relating to the marker tours.

A Marker Tour itself is no more than a sequence of marker IDs coming from the editor. This class allows you to stop and start a marker tour.

PropertyTypeDescription
_controlsHTML Element The HTML controls element shown when the tour is running (previous, next, steps)
stepsArray of MarkersReturns the ordered list of all the tour Marker steps
onstartFunctionGets or sets the function to call when the tour is started
onstopFunctionGets or sets the function to call when the tour is stopped

Methods

MethodDescription
goto(step (index int))Open the specified step in the tour
next()Go to the next step in the tour
prev()Go to the previous step the tour
start()Start the tour
stop()Stop the tour

Events

All events are fired on the main Micrio container element (<micr-io>). The reference to the marker-tour object is the argument event.detail.

Event nameDescription
markerTours-startFires when this tour has been started
markerTours-stopFires when this tour has been stopped

9. The MiniMap class

The MiniMap class contains all functionality relating to the minimap navigator of the image.

Properties

PropertyTypeDescription
_elHTML Element The minimap HTML container element

Methods

MethodDescription
drawForce a redraw of the minimap
hookHook the minimap to the image navigation
hookEventsHook user event listeners (zoom, pan)
removeRemove the minimap
showPlace the minimap
unhookUnhook the minimap to the image navigation
unhookEventsUnhook user event listeners (zoom, pan)

10. The Navigator class

The Navigator class contains all functionality relating to navigating from one image to another.

With Micrio, you can navigate between images inside the same Micrio instance. You can even switch from 360° images to 2D images. When you navigate to another image, any playing audio, including music, also switches to the new image.

Properties

This class has no relevant public properties.

Methods

MethodDescription
goto(id)Navigate to Micrio image with id id
getCurrent()Returns the current active Micrio image

11. The Tours class

A Tour class controls a video tour made in the editor.

This is a sequence of viewports put out over a timeline, with an optional single audio file. Once a tour is started, no user interaction is required to finish it.

Properties

PropertyTypeDescription
_controlsHTML ElementThe controller HTML element container
dataObjectJSON tour data from the editor
timelineArrayThe parsed timeline metadata used for the tour
playingBooleanReturns true if the tour is currently playing
pausedBooleanReturns true if the tour is currently paused
onchangeArray of functions Get or set the functions that are called when a tour step is changed
onstartFunctionGets or sets the function that's called when the tour is started
onstopFunctionGets or sets the function that's called when the tour is stopped

Methods

MethodDescription
hook() Hooks the input event listeners to the control HTML elements (start/stop/pause buttons and interactive timebar)
pause()Pauses the running tour
start()Starts the tour
stop()Stops the tour
unhook() Unhooks the input event listeners to the control HTML elements (start/stop/pause buttons and interactive timebar)

Events

All events are fired on the main Micrio container element (<micr-io>). The reference to the tour object is the argument event.detail.

Event nameDescription
tours-startFires when this tour has been started
tours-stopFires when this tour has been stopped

Last updated: