@onirix/webar-sdk NPM

Onirix Web AR SDK

Onirix Web AR SDK allows to create Augmented Reality experiencies that run in a web browser.

It internally uses advanced web standards like WebGL or WebAssembly combined with in-house computer vision algorithms optimized to run in a web browser.

Onirix Web AR SDK is compatible with the following Onirix tracking modes:

Image: Will load the image classifier generated for your Onirix project and perform detection and tracking.
QR Code: Will detect any QR in the camera feed, return its decoded content and perform tracking.
Surface: Will use device motion sensors to track an object fixed over any place or surface.

Onirix Web AR SDK is agnostic (not tied) to any rendering engine, so you can combine it with any 3D engine library like:

ThreeJS
BabylonJS
Aframe

If you want to have an overview of how the SDK works and make a quick test you may want to go straight to the samples section.

Getting Started

Onirix Studio configuration

First of all, you'll need to access Onirix Studio and create a Project.

If you plan to use Image-Tracking mode, then you'll also need to create an image scene for every marker image you want to be detected so Onirix can generate the required image classifier. If not, then there is no need to create any scene as, when using the SDK, you can provide your own assets and interaction through your hosting and code.

Finally, you will have to publish your project and copy the Web SDK token from the "share" and "settings" top-menu options respectively.

Integrating with your Web App

Whether you are integrating Onirix Web AR SDK to an existing Web App, or creating a new one from the scratch, the following steps are required:

Include Onirix Web AR SDK

Add a custom script (app.js) to your page html head tag and load it as an async module:

<head>
 ...
    <script async type="module" src="app.js"></script>
 ...    
</head>

Inside your custom script (app.js), import Onirix SDK:

import OnirixSDK from "https://sdk.onirix.com/0.3.0/ox-sdk.esm.js";

Instantiate OnirixSDK and create a configuration object

Whenever you want to launch the AR experience, create a new OnirixSDK instance with your Onirix project's token and a configuration object with the tracking mode and other desired paramenters:

    let OX = new OnirixSDK("<your_sdk_token>");

    let config = {
        mode: OnirixSDK.TrackingMode.Image
    }

The mode can be one of following depending on the tracking type you want to use for your experience:

OnirixSDK.TrackingMode.Image
OnirixSDK.TrackingMode.QRCode
OnirixSDK.TrackingMode.Surface

This is the complete list of config parameters:

Parameter	Type	Description
mode	OnirixSDK.TrackingType (required)	The AR mode you want your experience to run with.
useWebXR	boolean (default: true)	Whether you want to use WebXR API (if supported) or emulate tracking using gyroscope sensor. (Surface tracking only)
useVocabulary	boolean (default: false)	Enabling this setting will speed up image detection in exchange of downloading an additional file (25MB) when the experience loads. It is recommended when number of marker images per project is bigger than 10. (Image tracking only)

Initialize Onirix Web AR SDK

Call init function with prior configuration object as a parameter:

   OX.init(config).then(rendererCanvas => {
       // Onirix SDK has been initialized. Now it's time to set up a 3D renderer 
       // with any library (Three, Babylon ...) and subscribe to Onirix events.
   }).catch(error => {
       // Check error name and display accordingly
   });

When calling init, Onirix WebAR SDK will:

Check your license
Download required resources (i.e image classifier)
Request camera and sensors access
Add a canvas for 3D rendering and a video element for camera background to your page, both adjusted to full screen size.
Return the canvas so you can initialize your desired 3D renderer library with it.

This may take some time to complete, so it is recommended to show a loading screen before calling it, and hide it when the function completes.

Note that init function returns a promise. You may want to use the new ES6 async / await syntax.

Handle errors

There are 4 types of errors that might occur when initializing Onirix Web AR SDK. You should check the error type by inspecting its name or using instanceof JavaScript operator to compare with its corresponding error class and display in the form you decide to the user.

In the following table, you will find useful information about error types:

Class name	Name property	Description
OnirixSDK.LicenseError	LICENSE_ERROR	Might occur if the project is not published, your account has run out of views, has expired, or website domain is not valid
OnirixSDK.CameraError	CAMERA_ERROR	Might occur if could not detect or access to back-facing camera, or if camera permissions have been rejected
OnirixSDK.SensorsError	SENSORS_ERROR	Might occur if could not detect or access to gyroscope sensor, or motion sensor permissions have been rejected
OnirixSDK.InternalError	INTERNAL_ERROR	Might occur in non-compatible devices. Check compatibility for more info

Subscribe to SDK events

Once Onirix Web AR has been successfully initialized, you will have to subscribe to events in order to know when an Surface, Image or QR code has been detected and retrieve its AR pose to update the 3D renderer camera accordingly.

There are 4 events you may want to subscribe depending on the tracking mode:

Event	Description
OnirixSDK.Events.OnDetected	This event will be called when an Image or QR code is detected, returning an identifier. The identifier corresponds to the Image scene OID in Onirix Studio or the QR Code decoded content in case of a QR code. This event won't never be called in Surface mode.
OnirixSDK.Events.OnLost	This event will be called when an already detected Image or QR code is lost, returning an identifier. The identifier corresponds to the Image scene OID in Onirix Studio or the QR Code decoded content in case of a QR code. This event won't never be called in Surface mode.
OnirixSDK.Events.OnPose	This event will be called every time a new object pose is computed. Returned pose is a column major view-model matrix in OpenGL coordinates that you must forward to your 3D renderer.
OnirixSDK.Events.OnResize	This event will be called every time your device switchs between landscape and portrait orientation. When that happens, you must obtain new camera parameters through getCameraParameters function of the SDK and update your renderer with them.
OnirixSDK.Events.OnTouch	This event will be called every time users tap the screen, returning the clip-space (between -1 and 1) screen position of the touch. You may wan't to use it for raycasting and interacting with the scene when users touch.
OnirixSDK.Events.OnHitTestResult	This event will be called every time a surface is detected throwing a ray forward from camera origin (screen center). It is useful to display a placeholder of a surface before placing the 3D scene. It only works with surface tracking mode.

This is how you should subscribe to events:

OX.subscribe(OnirixSDK.Events.OnDetected, function (id) {
   renderer.load3DScene(id);
});

OX.subscribe(OnirixSDK.Events.OnPose, function (pose) {
   renderer.updateCameraPose(pose);
});

OX.subscribe(OnirixSDK.Events.OnLost, function (id) {
   renderer.unload3DScene(id);
});

OX.subscribe(OnirixSDK.Events.OnResize, function () {
   renderer.updateCameraParams();
});

OX.subscribe(OnirixSDK.Events.OnTouch, function (touchPos) {
   renderer.onTouch(touchPos);
});

OX.subscribe(OnirixSDK.Events.OnHitTestResult, function (hitResult) {
   renderer.onHitTestResult(hitResult);
});

Coordinate system

Onirix uses a right handed coordinate system with X running horizontally left to right, Y running vertically bottom to top, and positive Z coming out of the screen:

npm.io

This coordinate system was chosen to match WebGL convention that is also used by many 3D librarires like Three.js. However, there are others like Babylon.js may need some conversions to get the same results. We encourage you to visit our samples to see how we deal with these coordinate transforms for each 3D engine.

Surface mode

While in surface mode, -Z points the horizon, Y points up aligned with gravity, and X is the cross vector between both.

npm.io

Image mode

While in image mode, positive Y is orthogonal coming out from marker image, X goes right and Z down (-Y in 2D marker coordinates).

npm.io

Sample projects

You can visit our GitHub account for samples using different tracking modes and 3D rendering libraries:

https://github.com/onirix-ar/webar-sdk-samples

Local development and testing

Onirix Web AR SDK usage is restricted to purchased domains, however, the following domains and addresses are whitelisted for development:

localhost
127.0.0.1
192.168.*
10.50.*
10.10.*

In order to test the SDK from these local addresses, it is mandatory you serve your files through HTTPs. There are plenty of tools out there that may help you with this by generating an self-signed certificate and serving your files with a single command.

Take a look at http-server utility.

Compatibility and browser support

Onirix Web AR SDK is compatible with the following browsers:

OS	Version	Supported browsers
iOS	iOS 11+	Safari, Safari web views (iOS 14.3+)
Android	Any	Chrome, Firefox, Samsung Internet, Edge, native Android web views (Android 4.4+) *

*Other browsers may be also compatible if supporting the following capabilities: WebGL, CameraAPI, DeviceMotionAPI, WebAssembly (WASM).

Devices must also conform to the following hardware requirements:

Rear camera with at least VGA resolution (640x480px)
Gyroscope sensor (only required for surface-tracking mode).
2 GB of RAM

Licensing

Using Onirix Web AR SDK is limited to Onirix users (including test accounts).

There is no limit to the number of Web AR experiences you create with the SDK. However, they could be only consumed a limited number of times, regulated by your plan's montly views. A view is generated every time a user opens your experience and it loads without errors.

Self-hosting the experience in a public site (not local development) requires to purchase a domain (often a domain is included with certain Onirix plans).

See Onirix Pricing for more information.

bowser

@infinitebrahmanuniverse/nolb-_oni @everything-registry/sub-chunk-682

0.3.0

3 years ago