@onirix/ar-engine-sdk 0.4.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (8) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +236 -0
  3. package/dist/onirix_native_sdk.wasm +0 -0
  4. package/dist/ox-sdk.esm.js +1 -0
  5. package/dist/ox-sdk.js +1 -0
  6. package/dist/ox-sdk.modern.js +1 -0
  7. package/dist/ox-sdk.umd.js +1 -0
  8. package/package.json +28 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,34 @@
1
+ # Changelog
2
+
3
+ ## v0.4.0 (2022-02-24)
4
+
5
+ - Decreased size of WASM module significantly.
6
+
7
+ ## v0.3.0 (2021-07-16)
8
+
9
+ ### Breaking changes:
10
+
11
+ - SDK has now an **ES6 module** version. This allows for tree-shacking and other language improvements.
12
+ - SDK token is now passed in the OnirixSDK constructor instead of the config object.
13
+
14
+ ### New
15
+
16
+ - Added **stop()** method for stopping the SDK and free resources.
17
+ - Added **hit test support** for Surface-Tracking mode. A new hit test event will be triggered each time a surface is detected.
18
+ - Added **addImage(url)** method to allow adding image markers on runtime. Currently only 640x480px images are supported.
19
+ - Added **unsubscribe(eventListener)** method to allow unsubscribing from OnirixSDK events.
20
+ - Other minor improvements
21
+
22
+ ## v0.2.0 (2021-05-22)
23
+
24
+ ### New
25
+
26
+ - Added **support for WebXR device API**. This means, when using surface mode, objects will remain anchored to a surface (both in position and rotation) and thus, provide a more reallistic AR experience. This feature is now used by default on compatible devices, and automatically falled back to the old gyroscope emulated mode for non-compatible devices.
27
+
28
+ ## v0.1.0 (2021-03-26)
29
+
30
+ - Initial release.
31
+ - Includes 3 tracking modes:
32
+ - Surface (gyroscope emulated)
33
+ - Image
34
+ - QR Code
package/README.md ADDED
@@ -0,0 +1,236 @@
1
+ # Onirix AR Engine SDK
2
+
3
+ Onirix AR Engine SDK allows to **create Augmented Reality experiencies that run in a web browser**.
4
+
5
+ It internally uses advanced web standards like WebGL or WebAssembly combined with in-house computer vision algorithms optimized to run in a web browser.
6
+
7
+ Onirix AR Engine SDK is compatible with the following Onirix **tracking modes**:
8
+
9
+ * **Image**: Will load the image classifier generated for your Onirix project and perform detection and tracking.
10
+ * **QR Code**: Will detect any QR in the camera feed, return its decoded content and perform tracking.
11
+ * **Surface**: Will use device motion sensors to track an object fixed over any place or surface.
12
+
13
+ Onirix AR Engine SDK is agnostic (not tied) to any rendering engine, so you can combine it with any 3D engine library like:
14
+
15
+ * ThreeJS
16
+ * BabylonJS
17
+ * Aframe
18
+
19
+ > 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](#sample-projects) section.
20
+
21
+ ---
22
+
23
+ ## Getting Started
24
+
25
+ ### Onirix Studio configuration
26
+
27
+ First of all, you'll need to access [Onirix Studio](https://studio.onirix.com?target=_blank) and create a Project.
28
+
29
+ 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.
30
+
31
+ Finally, you will have to **publish** your project and **copy the Web SDK token** from the "share" and "settings" top-menu options respectively.
32
+
33
+ ### Integrating with your Web App
34
+
35
+ Whether you are integrating Onirix AR Engine SDK to an existing Web App, or creating a new one from the scratch, the following steps are required:
36
+
37
+ #### Include Onirix AR Engine SDK
38
+
39
+ Add a custom script (app.js) to your page html head tag and load it as an async module:
40
+
41
+ ```
42
+ <head>
43
+ ...
44
+ <script async type="module" src="app.js"></script>
45
+ ...
46
+ </head>
47
+ ```
48
+
49
+ Inside your custom script (app.js), import Onirix SDK:
50
+
51
+ ```
52
+ import OnirixSDK from "https://sdk.onirix.com/0.3.0/ox-sdk.esm.js";
53
+ ```
54
+
55
+ #### Instantiate OnirixSDK and create a configuration object
56
+
57
+ 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:
58
+
59
+ ```
60
+ let OX = new OnirixSDK("<your_sdk_token>");
61
+
62
+ let config = {
63
+ mode: OnirixSDK.TrackingMode.Image
64
+ }
65
+ ```
66
+
67
+ The **mode** can be one of following depending on the tracking type you want to use for your experience:
68
+
69
+ * OnirixSDK.TrackingMode.Image
70
+ * OnirixSDK.TrackingMode.QRCode
71
+ * OnirixSDK.TrackingMode.Surface
72
+
73
+ This is the complete list of config parameters:
74
+
75
+ | Parameter | Type | Description |
76
+ | ------ | ----------- | ---------- |
77
+ | **mode** | **OnirixSDK.TrackingType** (required) | The AR mode you want your experience to run with. |
78
+ | **useWebXR** | **boolean** (default: true) | Whether you want to use WebXR API (if supported) or emulate tracking using gyroscope sensor. (Surface tracking only) |
79
+ | **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) |
80
+
81
+ ---
82
+
83
+ #### Initialize Onirix AR Engine SDK
84
+
85
+ Call **init** function with prior configuration object as a parameter:
86
+
87
+ ```
88
+ OX.init(config).then(rendererCanvas => {
89
+ // Onirix SDK has been initialized. Now it's time to set up a 3D renderer
90
+ // with any library (Three, Babylon ...) and subscribe to Onirix events.
91
+ }).catch(error => {
92
+ // Check error name and display accordingly
93
+ });
94
+ ```
95
+
96
+ When calling **init**, Onirix AR Engine SDK will:
97
+
98
+ * Check your license
99
+ * Download required resources (i.e image classifier)
100
+ * Request camera and sensors access
101
+ * Add a canvas for 3D rendering and a video element for camera background to your page, both adjusted to full screen size.
102
+ * Return the canvas so you can initialize your desired 3D renderer library with it.
103
+
104
+ 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.
105
+
106
+ > Note that **init** function returns a promise. You may want to use the new ES6 async / await syntax.
107
+
108
+ ---
109
+
110
+ #### Handle errors
111
+
112
+ There are 4 types of errors that might occur when initializing Onirix AR Engine 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.
113
+
114
+ In the following table, you will find useful information about error types:
115
+
116
+ | Class name | Name property | Description |
117
+ | ------ | ----------- | ---------- |
118
+ | **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 |
119
+ | **OnirixSDK.CameraError** | **CAMERA_ERROR** | Might occur if could not detect or access to back-facing camera, or if camera permissions have been rejected |
120
+ | **OnirixSDK.SensorsError** | **SENSORS_ERROR**| Might occur if could not detect or access to gyroscope sensor, or motion sensor permissions have been rejected |
121
+ | **OnirixSDK.InternalError** | **INTERNAL_ERROR**| Might occur in non-compatible devices. Check compatibility for more info |
122
+
123
+ ---
124
+
125
+ #### Subscribe to SDK events
126
+
127
+ Once Onirix AR Engine SDK 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.
128
+
129
+ There are 4 events you may want to subscribe depending on the tracking mode:
130
+
131
+ | Event | Description |
132
+ | ------ | ----------- |
133
+ | **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. |
134
+ | **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. |
135
+ | **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. |
136
+ | **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. |
137
+ | **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. |
138
+ | **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. |
139
+
140
+ This is how you should subscribe to events:
141
+
142
+ ```
143
+ OX.subscribe(OnirixSDK.Events.OnDetected, function (id) {
144
+ renderer.load3DScene(id);
145
+ });
146
+
147
+ OX.subscribe(OnirixSDK.Events.OnPose, function (pose) {
148
+ renderer.updateCameraPose(pose);
149
+ });
150
+
151
+ OX.subscribe(OnirixSDK.Events.OnLost, function (id) {
152
+ renderer.unload3DScene(id);
153
+ });
154
+
155
+ OX.subscribe(OnirixSDK.Events.OnResize, function () {
156
+ renderer.updateCameraParams();
157
+ });
158
+
159
+ OX.subscribe(OnirixSDK.Events.OnTouch, function (touchPos) {
160
+ renderer.onTouch(touchPos);
161
+ });
162
+
163
+ OX.subscribe(OnirixSDK.Events.OnHitTestResult, function (hitResult) {
164
+ renderer.onHitTestResult(hitResult);
165
+ });
166
+ ```
167
+
168
+ ### Coordinate system
169
+
170
+ 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:
171
+
172
+ ![](https://docs.onirix.com/user/pages/05.onirix-sdk/08.web-ar/axes.jpg)
173
+
174
+ 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.
175
+
176
+ #### Surface mode
177
+
178
+ While in surface mode, -Z points the horizon, Y points up aligned with gravity, and X is the cross vector between both.
179
+
180
+ ![](https://docs.onirix.com/user/pages/05.onirix-sdk/08.web-ar/device-axes.png)
181
+
182
+ #### Image mode
183
+
184
+ While in image mode, positive Y is orthogonal coming out from marker image, X goes right and Z down (-Y in 2D marker coordinates).
185
+
186
+ ![](https://docs.onirix.com/user/pages/05.onirix-sdk/08.web-ar/image-axes.jpg)
187
+
188
+ ## Sample projects
189
+
190
+ You can visit our GitHub account for samples using different tracking modes and 3D rendering libraries:
191
+
192
+ [https://github.com/onirix-ar/webar-sdk-samples](https://github.com/onirix-ar/webar-sdk-samples?target=_blank)
193
+
194
+
195
+ ## Local development and testing
196
+
197
+ Onirix AR Engine SDK usage is restricted to purchased domains, however, the following domains and addresses are whitelisted for development:
198
+
199
+ * **localhost**
200
+ * **127.0.0.1**
201
+ * <b>192.168.*</b>
202
+ * <b>10.50.*</b>
203
+ * <b>10.10.*</b>
204
+ * <b>*.ngrok.io</b>
205
+
206
+ 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.
207
+
208
+ >Take a look at [http-server](https://www.npmjs.com/package/http-server?target=blank) utility.
209
+
210
+
211
+ ## Compatibility and browser support
212
+
213
+ Onirix AR Engine SDK is compatible with the following browsers:
214
+
215
+ |OS|Version|Supported browsers|
216
+ |----------|--------------|----------|
217
+ |iOS|iOS 11+|Safari, Safari web views (iOS 14.3+)|
218
+ |Android|Any|Chrome, Firefox, Samsung Internet, Edge, native Android web views (Android 4.4+) *|
219
+
220
+ *_Other browsers may be also compatible if supporting the following capabilities: WebGL, CameraAPI, DeviceMotionAPI, WebAssembly (WASM)._
221
+
222
+ Devices must also conform to the following **hardware requirements**:
223
+
224
+ * **Rear camera** with at least VGA resolution (640x480px)
225
+ * **Gyroscope sensor** (only required for surface-tracking mode).
226
+ * **2 GB of RAM**
227
+
228
+ ## Licensing
229
+
230
+ Using Onirix AR Engine SDK is limited to Onirix users (including test accounts).
231
+
232
+ 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.
233
+
234
+ 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).
235
+
236
+ See [Onirix Pricing](https://www.onirix.com/pricing/?target=blank) for more information.
package/dist/onirix_native_sdk.wasm ADDED
Binary file