@onirix/ar-engine-sdk 1.5.6 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v1.5.7 (2024-01-22)
+
+### Added
+
+- Improved World-Tracking to handle better outdoor environments and rotation-only movements.
+
 ## v1.5.6 (2023-12-05)
 
 ### Added

package/README.md

@@ -11,6 +11,7 @@ Onirix AR Engine SDK is compatible with the following Onirix **tracking modes**:
 * **Surface**: Will use device camera and motion sensors to track an object fixed over any place or surface. This mode has 2 different sub-modes:
    * **World-Tracking** (Default): Allows to place objects fixed at a surface, so you can walk around and see them from different perspectives. Internally uses WebXR device API if the device is compatible (Android with ARCore support for now), and fallbacks to a custom implementation if not, or when using the config option `disableWebXR = true`.
    * **Rotation-Tracking**: Uses device gyroscope sensor to provide an accurate 360º rotation-only tracking. Useful for scenes where users are not supposed to move and rather look around. Can be enabled using the config option `disableWorldTracking = true`.
+* **Spatial**: Will recognize a previously scanned environment (space), positioning you within it and initiating World-Tracking from that location. 
 
 Onirix AR Engine SDK is agnostic (not tied) to any rendering engine, so you can combine it with any 3D engine library like:
 
@@ -51,7 +52,7 @@ Add a custom script (app.js) to your page html head tag and load it as an async
 Inside your custom script (app.js), import Onirix SDK:
 
 ```
-import OnirixSDK from "https://unpkg.com/@onirix/ar-engine-sdk@latest/dist/ox-sdk.esm.js";
+import OnirixSDK from "https://unpkg.com/@onirix/ar-engine-sdk@1.6.0/dist/ox-sdk.esm.js";
 ```
 
 > If you're using a JavaScript framework or a bundler like Webpack, it is recommended to use the [NPM package](https://www.npmjs.com/package/@onirix/ar-engine-sdk) instead.
@@ -74,6 +75,7 @@ The **mode** can be one of following depending on the tracking type you want to
 * OnirixSDK.TrackingMode.Image
 * OnirixSDK.TrackingMode.QRCode
 * OnirixSDK.TrackingMode.Surface
+* OnirixSDK.TrackingMode.Spatial
 
 This is the complete list of config parameters:
 
@@ -81,8 +83,9 @@ This is the complete list of config parameters:
 | ------ | ----------- | ---------- |
 | **mode** | **OnirixSDK.TrackingType** (required) | The AR mode you want your experience to run with. |
 | **disableWorldTracking** | **boolean** (optional, default: false) | You can use this option to enable Rotation-Tracking. (Surface tracking only) |
-| **disableWebXR** | **boolean** (optional, default: false) | You can use this option to force using Onirix custom World Tracking implementation for more homogeneous experiences between devices and OS. (Surface tracking only) |
+| **disableWebXR** | **boolean** (optional, default: false) | You can use this option to force using Onirix custom World Tracking implementation for more homogeneous experiences between devices and OS. (Surface and Spatial tracking only) |
 | **useVocabulary** | **boolean** (optional, 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) |
+| **sceneOid** | **string** (required for Spatial mode) | OID of the scene in which you want to relocate |
 
 ---
 
@@ -136,7 +139,7 @@ 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.OnDetected** | This event will be called when an Image, QR code or Space is detected, returning an identifier. The identifier corresponds to the Image or Space 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 switches 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.  |
@@ -145,7 +148,7 @@ There are 4 events you may want to subscribe depending on the tracking mode:
 | **OnirixSDK.Events.OnTouchEnd** | Similar to OnTouch, but called when the touch ends. |
 | **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. |
 | **OnirixSDK.Events.OnFrame** | This event will be called every frame. Useful for synchronizing tracking and 3D rendering. |
-| **OnirixSDK.Events.SessionEnd** | Called when user exits the AR experience (only Surface mode when using WebXR). |
+| **OnirixSDK.Events.SessionEnd** | Called when user exits the AR experience (only Surface and Spatial modes when using WebXR). |
 
 This is how you should subscribe to events:
 
@@ -195,7 +198,7 @@ Onirix uses a **right handed** coordinate system with X running horizontally lef
 
 ![](https://docs.onirix.com/user/pages/05.onirix-sdk/08.web-ar/axes.jpg)
 
-This coordinate system was chosen to match WebGL convention that is also used by many 3D librarires like [Three.js](https://threejs.org/?target=_blank). However, there are others like [Babylon.js](https://www.babylonjs.com/?target=_blank) may need some conversions to get the same results. We encourage you to visit our [samples](/onirix-sdk/web-ar#sample-projects) to see how we deal with these coordinate transforms for each 3D engine.
+This coordinate system was chosen to match WebGL convention that is also used by many 3D libraries like [Three.js](https://threejs.org/?target=_blank). However, there are others like [Babylon.js](https://www.babylonjs.com/?target=_blank) may need some conversions to get the same results. We encourage you to visit our [samples](/onirix-sdk/web-ar#sample-projects) to see how we deal with these coordinate transforms for each 3D engine.
 
 #### Surface mode
 
@@ -209,6 +212,10 @@ While in image mode, positive Y is orthogonal coming out from marker image, X go
 
 ![](https://docs.onirix.com/user/pages/05.onirix-sdk/08.web-ar/image-axes.jpg)
 
+#### Spatial mode
+
+While in Spatial mode, the coordinate system aligns with the scanned environment. This means that, similar to Surface mode, the -Z axis points towards the horizon, the Y axis points upward, aligned with gravity, and the X axis is perpendicular to both, forming the cross vector. However, in Spatial mode, these axes are rotated in such a way that they match the orientation and position of the previously scanned space, ensuring that virtual objects are accurately placed within the real-world context.
+
 ## Sample projects
 
 You can visit our GitHub account for samples using different tracking modes and 3D rendering libraries:
@@ -246,7 +253,7 @@ Onirix AR Engine SDK is compatible with the following browsers:
 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).
+* **Gyroscope sensor** (only required for Surface and Spatial modes).
 * **2 GB of RAM**
 
 ## Licensing