Embed SDK

Onirix Embed SDK allows you to listen to events and control the scene when embedding experiences in a custom domain or from the online code editor.

Include the library

If you use ES modules, you can just import the library as:

import OnirixEmbedSDK from "https://unpkg.com/@onirix/embed-sdk@latest/dist/ox-embed-sdk.esm.js";

If not, use the UMD library instead by adding a new script tag inside your page's head section:

<script src="https://unpkg.com/@onirix/embed-sdk@latest/dist/ox-embed-sdk.umd.js"></script>

Instantiate and connect

Create a new instance of the SDK by passing the iframe HTML element in the constructor and call the connect method:

const iframeElement = document.getElementById("your_iframe_id_here");
const embedSDK = new OnirixEmbedSDK(iframeElement);
embedSDK.connect();

If there is not any iframe (when using the code editor), you can just instantiate the SDK with arguments:

const embedSDK = new OnirixEmbedSDK();
embedSDK.connect();

Listen to Events

You can listen to the following events for the experience:

Event	Description
OnirixEmbedSDK.Events.READY	Will be triggered when all permissions are accepted and the camera becomes visible
OnirixEmbedSDK.Events.SCENE_LOAD_START	Will be triggered when the scene starts loading. This is, when an image is detected or you select a surface to place the scene
OnirixEmbedSDK.Events.SCENE_LOAD_END	Will be triggered when the scene finishes loading, and thus, the assets are visible
OnirixEmbedSDK.Events.SCENE_LOST	It will be activated when you lose sight of the image or surface and the scene is deleted.
OnirixEmbedSDK.Events.SCENE_DETECTED	It will be activated when when a surface is detected.
OnirixEmbedSDK.Events.SCENE_RADIUS_ENTER	Will be triggered when the user enters the activation radius of a geolocated scene
OnirixEmbedSDK.Events.SCENE_RADIUS_EXIT	Will be triggered when the user exits the activation radius of a geolocated scene
OnirixEmbedSDK.Events.ELEMENT_CLICK	Will be triggered when an element is clicked, receiving its oid as argument and the element's center position(x, y, z) and intersection point.
OnirixEmbedSDK.Events.SCENE_CLICK	Will be triggered when a scene is clicked. Returns an object with the scene coordinates where the user has touched. If an element has been touched, it returns the exact point where it was touched and the information of the touched element
OnirixEmbedSDK.Events.OPEN_MARKERS_PANEL	Will be triggered when image markers panel is opened
OnirixEmbedSDK.Events.CLOSE_MARKERS_PANEL	Will be triggered when image markers panel is closed
OnirixEmbedSDK.Events.MAP_READY	Will be triggered when map is loaded or when there is some error during the map loading process. In the latter case, the event params object will have an error field whose value is the error occurred.
OnirixEmbedSDK.Events.SCENE_LOCATION_CLICK	Will be triggered when the user clicks on a location in the map, receiving its oid as argument.
OnirixEmbedSDK.Events.BACK_TO_MAP	Will be triggered when the user leaves a scene and goes back to the map screen.
OnirixEmbedSDK.Events.ON_TOUCH_START	Will be triggered immediately after the finger touches an element, receiving its oid as argument and the element's center position(x, y, z) and intersection point.
OnirixEmbedSDK.Events.ON_TOUCH_END	Will be triggered immediately after the finger is lifted, receiving its oid as argument and the element's center position(x, y, z) and intersection point.
OnirixEmbedSDK.Events.ON_POSE	Will be triggered every time the camera is updated and receives a param object with the fields 'position', 'quaternion', and 'euler'.
OnirixEmbedSDK.Events.ON_SCENE_TOUCH_START	Will be triggered immediately after the finger touches the scene. Returns an object with the scene coordinates where the user has touched. If an element has been touched, it returns the exact point where it was touched and the information of the touched element
OnirixEmbedSDK.Events.ON_SCENE_TOUCH_END	Will be triggered immediately after the finger is lifted. Returns an object with the scene coordinates where the user has touched. If an element has been touched, it returns the exact point where it was touched and the information of the touched element
OnirixEmbedSDK.Events.SESSION_ENDED	It will be activated on WebXR's exit.
OnirixEmbedSDK.Events.LAZY_LOAD_END	It will be called when an element is loaded lazily or created dynamically

In order to listen to any of those events, you just need to use the subscribe method:

embedSDK.subscribe(OnirixEmbedSDK.Events.ELEMENT_CLICK, (params) => {
    console.log("Element with oid: " + params.oid + " was clicked!");
});

Control the scene with Actions

Actions are useful to create custom behaviour and be able to trigger changes in the scene from HTML elements.

These are the actions you can run with Onirix Embed SDK:

Action	Params
enable(oid, transition, time)	oid: element oid / name, transition: NONE = 0 (default), FADE = 1, GROW = 2, GROW_X = 3, GROW_Y = 4, GROW_Z = 5, BOUNCE = 6, time: transition time in seconds (default = 1)
disable(oid, transition, time)	oid: element oid / name, transition: NONE = 0 (default), FADE = 1, GROW = 2, GROW_X = 3, GROW_Y = 4, GROW_Z = 5, BOUNCE = 6, time: transition time in seconds (default = 1)
toggle(oid, transition, time)	oid: element oid / name, transition: NONE = 0 (default), FADE = 1, GROW = 2, GROW_X = 3, GROW_Y = 4, GROW_Z = 5, BOUNCE = 6, time: transition time in seconds (default = 1)
enableAll()	-
disableAll()	-
play(oid)	oid: element oid / name
pause(oid)	oid: element oid / name
translate(oid, x, y, z, time, loop)	oid: element oid / name, x: amount on x axis, y: amount on y axis, z: amount on z axis: time: duration, loop: repeat indefinitely
rotate(oid, x, y, z, time, loop)	oid: element oid / name, x: amount on x axis, y: amount on y axis, z: amount on z axis: time: duration, loop: repeat indefinitely
rotateTo(oid, x, y, z, time, loop)	oid: element oid / name, x: Euler angles (in radians) on x axis, y: Euler angles (in radians) on y axis, z: Euler angles (in radians) on z axis, time: duration
rotateToQuaternion(oid, x, y, z, w, time, loop)	oid: element oid / name, x: x quaternion's component, y: y quaternion's component, z: z quaternion's component, w: w quaternion's component, time: duration
scale(oid, x, y, z, time, loop)	oid: element oid / name, x: amount on x axis, y: amount on y axis, z: amount on z axis, time: duration, loop: repeat indefinitely
playAnimation(oid, name, loop, autoStop, time)	oid: element oid / name, name: animation name, loop: whether you want the animation loop or not (boolean), autoStop: If this parameter is true, the model will return to its original pose after finishing the animation (default false), time: This parameter allows you to specify the duration (in seconds) of the animation. If this parameter is not set, the original duration of the animation will be maintained.
stopAnimation(oid)	oid: element oid / name
setLabelText(oid, text)	oid: element oid / name, text: new label text
translateToPosition(oid, x, y, z, time, lookAt)	oid: oid of the element to be moved / x,y,z: coordinates where the object will be moved / time: movement duration / lookAt: true if the element must look in the direction of the movement
translateToElement(oid, targetOid, time, lookAt)	oid: oid of the element to be moved / targetOid: oid of the target element / time: movement duration / lookAt: true if the element must look in the direction of the movement
resetScenes()	This action takes no parameters and its function is to return the web AR player to its initial state
setCameraRigTransform(matrix)	Sets the camera transform matrix to the specified matrix.
setCameraRigPosition(x, y, z)	Sets the camera position to the specified position.
setCameraRigRotation(x, y, z)	Sets the camera rotation to the specified Euler angle.
setCameraRigQuaternion(x, y, z, w)	Sets the camera rotation to the specified quaternion.
disableCameraControls()	Disables the default camera controls (when using the 3D viewer).
loadElement(oid, params)	oid: element oid / params: an object with any of the following keys: position, euler, scale, transition, time, and sound. For a more detailed description see the appropriate section of the lazy loading tutorial.
createElement(oid, params)	oid: oid assigned to the element to create / params: an object with the following keys: assetOid, name, position, euler, scale, parentOid, transition, time, and sound. For a more detailed description see the appropriate section of the lazy loading tutorial.

In order to run an action, just call its method with required parameters:

embedSDK.disable('your_element_oid');

Onirix Camera Controls Module

Onirix Camera Controls Module is an addon to Onirix Embed SDK that allows manipulating the camera in a more intuitive and direct way than using the low-level camera actions provided by it. It makes many camera-related tasks easy:

• Animating the camera when entering a scene.
• Moving the camera to different points of interest around the scene.
• Customizing camera controls in an advanced way, e.g., using interface elements.
• Restricting camera movement in some ways.

Initialization

Before accessing any of its functions, the camera module must be initialized by providing an instance of the Onirix Embed SDK as shown below:

import OnirixEmbedSDK from 'https://www.unpkg.com/@onirix/embed-sdk@latest/dist/ox-embed-sdk.esm.js';
import OnirixCameraModule from 'https://www.unpkg.com/@onirix/camera-controls-module@latest/dist/ox-camera-controls-module.esm.js';

const embedSDK = new OnirixEmbedSDK();
embedSDK.connect();

const camera = new OnirixCameraModule(embedSDK);

Camera manipulation and animations

The camera can be moved using the camera.animate(...) function. This function receives the following parameters:

• position_x, position_y, and position_z: The coordinates the camera should move to. If any of them is undefined, the camera will stay in place.

• look_at_x, look_at_y, and look_at_z: The coordinates the camera should look at. If any of them is undefined, the camera will keep looking at the point it is currently looking at.

• mode: How to animate the transition to these positions. It is specified by a string with two components: an interpolator (a component that describes the path the camera should take) and an easing function (a component that describes the speed of the camera along said path). This string must be formatted as <interpolator> <ease function>. Alternatively, any of the components can be omitted. If the mode is optional (can be undefined).

  There are two interpolators available:

  • linear: The camera moves in a straight line.
  • spherical: The camera moves following an arc around a center. The default center is the target of the controls or, if they are not defined, the x=0, y=0, z=0 point.

  There are seven easing functions available:

  • linear-in-out: The camera moves always at the same speed.
  • ease-in: The camera starts slower.
  • ease-out: The camera reduces its speed as it reaches its destination.
  • ease-in-out: The camera accelerates at the beginning and decelerates as it reaches the end.
  • bounce-in: The camera anticipates the movement by going in the opposite direction for a short period of time.
  • bounce-out: The camera overshoots the destination for a short period of time.
  • bounce-in-out: The camera anticipates the movement by going in the opposite direction and overshoots the destination for a short period of time.

  Some examples of valid modes are 'linear', 'ease-in-out', 'spherical bounce-out'.

• time: Length of the animation in seconds. If not provided it is assumed to be 0 .

• center_x, center_y, and center_z: When using a spherical interpolator, the center of the arc. Otherwise it is ignored. Its default value is the target of the controls or, if they are not defined, the x=0, y=0, z=0 point.

Controls

The camera controls are the components that describe how user interactions (touches, mouse clicks, key presses...) are translated to camera movements around the scene. Camera controls are optional and you may use none if the camera should not be controlled by the user.

Currently, the camera controls module supports the following camera controls:

• Orbit controls: The camera moves around a point (the target). The user can zoom using the mouse wheel or by doing pinch gestures, pan by dragging while pressing right mouse button or sliding with two fingers, and cycle around by dragging while pressing left mouse button or sliding with a single finger. They can be enabled using camera.enableOrbitControls().

The function camera.disableControls() can be used to disable the current camera controls.

Orbit controls

Some functions allow setting limits to the camera transformations that the user can perform:

• camera.setOrbitControlsPanRange(min_x, max_x, min_y, max_y, min_z, max_z): allows setting a minimum and maximum pan value for each of the coordinate axes.
• camera.setOrbitControlsRotateRange(min_x, max_x, min_y, max_y, min_z, max_z): allows setting a minimum and maximum rotation value for each of the coordiante axes. This rotation is measured as the angle from the camera to the axis.
• camera.setOrbitControlsZoomRange(min, max): allows setting a minimum and maximum zoom value.

Also, there is a function that allows setting the orbit target: camera.setOrbitControlsTarget(x, y, z).

Examples

Moving to a position on scene load

import OnirixEmbedSDK from 'https://www.unpkg.com/@onirix/embed-sdk@latest/dist/ox-embed-sdk.esm.js';
import OnirixCameraModule from 'https://www.unpkg.com/@onirix/camera-controls-module@latest/dist/ox-camera-controls-module.esm.js';

const embedSDK = new OnirixEmbedSDK();
embedSDK.connect();

const camera = new OnirixCameraModule(embedSDK);
camera.enableOrbitControls();

embedSDK.subscribe(OnirixEmbedSDK.Events.SCENE_LOAD_END, () => {
    camera.animateTo(
      -1, 0, 1,
      1, 0, -1,
      'spherical ease-in-out',
      5
    );
});

An orbit and zoom animation on scene load

import OnirixEmbedSDK from 'https://www.unpkg.com/@onirix/embed-sdk@latest/dist/ox-embed-sdk.esm.js';
import OnirixCameraModule from 'https://www.unpkg.com/@onirix/camera-controls-module@latest/dist/ox-camera-controls-module.esm.js';

const embedSDK = new OnirixEmbedSDK();
embedSDK.connect();

const camera = new OnirixCameraModule(embedSDK);
camera.enableOrbitControls();

embedSDK.subscribe(OnirixEmbedSDK.Events.SCENE_LOAD_END, async () => {
    await camera.animateTo(
        0, 0.5, -5,
        0, 0.5, 0
    );
    await camera.animateTo(
        0, 0.5, 5,
        0, 0.5, 0,
        'spherical ease-in-out',
        2,
        0, 0.5, 0
    );
    await camera.animateTo(
        0, 0.5, 2,
        0, 0.5, 0,
        'linear ease-in-out',
        2,
        0, 0.5, 0
    );
});