@iwsdk/core 0.1.0

package/dist/scene-understanding/mesh.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Types } from '../ecs/index.js';
+/**
+ * Component representing detected real‑world 3D mesh geometry in AR/VR environments. This component
+ * should be attached to entities by the SceneUnderstandingSystem and be queried by custom systems.
+ *
+ * @remarks
+ * - Automatically created by {@link SceneUnderstandingSystem} when meshes are detected.
+ * - Represents complex 3D geometry like furniture, objects, and room structure.
+ * - Supports both bounded 3D objects (furniture, objects) and global mesh (room structure).
+ * - Bounded meshes include semantic labels, bounding boxes, and calculated dimensions.
+ * - Global meshes represent overall room structure without semantic classification.
+ * - Entities are destroyed when the corresponding real‑world mesh is no longer detected.
+ * - Requires WebXR session with 'mesh‑detection' feature enabled.
+ * - Users should not manually create entities with this component and let the scene understanding
+ *   system manage them.
+ *
+ * @example React to detected meshes
+ * ```ts
+ * your-system.query({ required: [XRMesh] }).subscribe('qualify', (entity) => {
+ *   const isBounded = entity.getValue(XRMesh, 'isBounded3D')
+ *   const semanticLabel = entity.getValue(XRMesh, 'semanticLabel')
+ *
+ *   if (isBounded && semanticLabel === 'table') {
+ *     console.log('Table detected!')
+ *     const dimensions = entity.getValue(XRMesh, 'dimensions')
+ *     console.log('Table size:', dimensions)
+ *   }
+ * })
+ * ```
+ *
+ * @category Scene Understanding
+ * @see {@link SceneUnderstandingSystem}
+ * @see {@link XRPlane}
+ */
+export declare const XRMesh: import("elics").Component<{
+    _mesh: {
+        type: Types.Object;
+        default: undefined;
+    };
+    isBounded3D: {
+        type: Types.Boolean;
+        default: false;
+    };
+    semanticLabel: {
+        type: Types.String;
+        default: string;
+    };
+    min: {
+        type: Types.Vec3;
+        default: [number, number, number];
+    };
+    max: {
+        type: Types.Vec3;
+        default: [number, number, number];
+    };
+    dimensions: {
+        type: Types.Vec3;
+        default: [number, number, number];
+    };
+}>;
+//# sourceMappingURL=mesh.d.ts.map

package/dist/scene-understanding/mesh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh.d.ts","sourceRoot":"","sources":["../../src/scene-understanding/mesh.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAmB,MAAM,iBAAiB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;EAWlB,CAAC"}

package/dist/scene-understanding/mesh.js

@@ -0,0 +1,55 @@
+import '@preact/signals-core';
+import '../ecs/world.js';
+import { createComponent, Types } from 'elics';
+import '../ecs/component-registry.js';
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Component representing detected real‑world 3D mesh geometry in AR/VR environments. This component
+ * should be attached to entities by the SceneUnderstandingSystem and be queried by custom systems.
+ *
+ * @remarks
+ * - Automatically created by {@link SceneUnderstandingSystem} when meshes are detected.
+ * - Represents complex 3D geometry like furniture, objects, and room structure.
+ * - Supports both bounded 3D objects (furniture, objects) and global mesh (room structure).
+ * - Bounded meshes include semantic labels, bounding boxes, and calculated dimensions.
+ * - Global meshes represent overall room structure without semantic classification.
+ * - Entities are destroyed when the corresponding real‑world mesh is no longer detected.
+ * - Requires WebXR session with 'mesh‑detection' feature enabled.
+ * - Users should not manually create entities with this component and let the scene understanding
+ *   system manage them.
+ *
+ * @example React to detected meshes
+ * ```ts
+ * your-system.query({ required: [XRMesh] }).subscribe('qualify', (entity) => {
+ *   const isBounded = entity.getValue(XRMesh, 'isBounded3D')
+ *   const semanticLabel = entity.getValue(XRMesh, 'semanticLabel')
+ *
+ *   if (isBounded && semanticLabel === 'table') {
+ *     console.log('Table detected!')
+ *     const dimensions = entity.getValue(XRMesh, 'dimensions')
+ *     console.log('Table size:', dimensions)
+ *   }
+ * })
+ * ```
+ *
+ * @category Scene Understanding
+ * @see {@link SceneUnderstandingSystem}
+ * @see {@link XRPlane}
+ */
+const XRMesh = createComponent('XRMesh', {
+    _mesh: { type: Types.Object, default: undefined },
+    isBounded3D: { type: Types.Boolean, default: false },
+    semanticLabel: { type: Types.String, default: '' },
+    min: { type: Types.Vec3, default: [0, 0, 0] },
+    max: { type: Types.Vec3, default: [0, 0, 0] },
+    dimensions: { type: Types.Vec3, default: [0, 0, 0] },
+}, 'Component for managing 3D meshes in the scene');
+
+export { XRMesh };
+//# sourceMappingURL=mesh.js.map

package/dist/scene-understanding/mesh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh.js","sources":["../../src/scene-understanding/mesh.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAAA;;;;;AAKG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCG;AAEI,MAAM,MAAM,GAAG,eAAe,CACnC,QAAQ,EACR;IACE,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE;IACjD,WAAW,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE;IACpD,aAAa,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE;AAClD,IAAA,GAAG,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;AAC7C,IAAA,GAAG,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;AAC7C,IAAA,UAAU,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;CACrD,EACD,+CAA+C;;;;"}

package/dist/scene-understanding/plane.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Types } from '../ecs/index.js';
+/**
+ * Component representing a detected real‑world plane surface in AR/VR environments. This component
+ * should be attached to entities by the SceneUnderstandingSystem and be queried by custom systems.
+ *
+ * @remarks
+ * - Automatically created by {@link SceneUnderstandingSystem} when planes are detected.
+ * - Represents flat surfaces like floors, walls, and ceilings in the real world.
+ * - Entities are destroyed when the corresponding real‑world plane is no longer detected.
+ * - Requires WebXR session with 'plane‑detection' feature enabled.
+ * - Users should not manually create entities with this component and let the scene understanding
+ *   system manage them.
+ *
+ * @example React to detected planes
+ * ```ts
+ * your-system.query({ required: [XRPlane] }).subscribe('qualify', (entity) => {
+ *   const plane = entity.getValue(XRPlane, 'plane')
+ *   console.log('Detected plane orientation:', plane.orientation)
+ *   console.log('Plane position:', entity.object3D?.position)
+ * })
+ * ```
+ *
+ * @category Scene Understanding
+ * @see {@link SceneUnderstandingSystem}
+ * @see {@link XRMesh}
+ */
+export declare const XRPlane: import("elics").Component<{
+    _plane: {
+        type: Types.Object;
+        default: undefined;
+    };
+}>;
+//# sourceMappingURL=plane.d.ts.map

package/dist/scene-understanding/plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plane.d.ts","sourceRoot":"","sources":["../../src/scene-understanding/plane.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAmB,MAAM,iBAAiB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,eAAO,MAAM,OAAO;;;;;EAMnB,CAAC"}

package/dist/scene-understanding/plane.js

@@ -0,0 +1,42 @@
+import '@preact/signals-core';
+import '../ecs/world.js';
+import { createComponent, Types } from 'elics';
+import '../ecs/component-registry.js';
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Component representing a detected real‑world plane surface in AR/VR environments. This component
+ * should be attached to entities by the SceneUnderstandingSystem and be queried by custom systems.
+ *
+ * @remarks
+ * - Automatically created by {@link SceneUnderstandingSystem} when planes are detected.
+ * - Represents flat surfaces like floors, walls, and ceilings in the real world.
+ * - Entities are destroyed when the corresponding real‑world plane is no longer detected.
+ * - Requires WebXR session with 'plane‑detection' feature enabled.
+ * - Users should not manually create entities with this component and let the scene understanding
+ *   system manage them.
+ *
+ * @example React to detected planes
+ * ```ts
+ * your-system.query({ required: [XRPlane] }).subscribe('qualify', (entity) => {
+ *   const plane = entity.getValue(XRPlane, 'plane')
+ *   console.log('Detected plane orientation:', plane.orientation)
+ *   console.log('Plane position:', entity.object3D?.position)
+ * })
+ * ```
+ *
+ * @category Scene Understanding
+ * @see {@link SceneUnderstandingSystem}
+ * @see {@link XRMesh}
+ */
+const XRPlane = createComponent('XRPlane', {
+    _plane: { type: Types.Object, default: undefined },
+}, 'Component for managing 3D planes in the scene');
+
+export { XRPlane };
+//# sourceMappingURL=plane.js.map

package/dist/scene-understanding/plane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plane.js","sources":["../../src/scene-understanding/plane.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAAA;;;;;AAKG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;AAwBG;AAEI,MAAM,OAAO,GAAG,eAAe,CACpC,SAAS,EACT;IACE,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE;CACnD,EACD,+CAA+C;;;;"}

package/dist/scene-understanding/scene-understanding-system.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Types } from '../ecs/index.js';
+declare const SceneUnderstandingSystem_base: import("elics").SystemConstructor<{
+    showWireFrame: {
+        type: Types.Boolean;
+        default: false;
+    };
+}, {
+    planeEntities: {
+        required: import("elics").Component<{
+            _plane: {
+                type: Types.Object;
+                default: undefined;
+            };
+        }>[];
+    };
+    meshEntities: {
+        required: import("elics").Component<{
+            _mesh: {
+                type: Types.Object;
+                default: undefined;
+            };
+            isBounded3D: {
+                type: Types.Boolean;
+                default: false;
+            };
+            semanticLabel: {
+                type: Types.String;
+                default: string;
+            };
+            min: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            max: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            dimensions: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+        }>[];
+    };
+    anchoredEntities: {
+        required: import("elics").Component<{
+            attached: {
+                type: Types.Boolean;
+                default: false;
+            };
+        }>[];
+    };
+}, import("../ecs/world.js").World, import("../ecs/system.js").System<{
+    showWireFrame: {
+        type: Types.Boolean;
+        default: false;
+    };
+}, {
+    planeEntities: {
+        required: import("elics").Component<{
+            _plane: {
+                type: Types.Object;
+                default: undefined;
+            };
+        }>[];
+    };
+    meshEntities: {
+        required: import("elics").Component<{
+            _mesh: {
+                type: Types.Object;
+                default: undefined;
+            };
+            isBounded3D: {
+                type: Types.Boolean;
+                default: false;
+            };
+            semanticLabel: {
+                type: Types.String;
+                default: string;
+            };
+            min: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            max: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            dimensions: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+        }>[];
+    };
+    anchoredEntities: {
+        required: import("elics").Component<{
+            attached: {
+                type: Types.Boolean;
+                default: false;
+            };
+        }>[];
+    };
+}>>;
+/**
+ * Manages WebXR scene understanding features including plane detection, mesh detection, and anchoring.
+ *
+ * @remarks
+ * - Automatically detects and visualizes real‑world planes and meshes in AR/VR environments.
+ * - Creates entities with {@link XRPlane} components for detected planes (floors, walls, ceilings).
+ * - Creates entities with {@link XRMesh} components for detected 3D geometry.
+ * - Supports anchoring objects to real‑world positions using {@link XRAnchor} components.
+ * - Requires WebXR session features: 'plane‑detection', 'mesh‑detection', 'anchor' when using the related features.
+ * - Automatically manages entity lifecycle as real‑world geometry changes.
+ * - Provides optional visual feedback with wireframe meshes for detected geometry.
+ * - Objects with {@link XRAnchor} are automatically attached to a stable world‑anchored group.
+ *
+ * @example Basic scene understanding setup
+ * ```ts
+ * // WebXR session must request required features
+ * World.create(document.getElementById('scene-container'), {
+ *   assets,
+ *   xr: {
+ *     sessionMode: SessionMode.ImmersiveAR,
+ *     features: { planeDetection: true, meshDetection: true, anchors: true },
+ *   }
+ * })
+ *
+ * // Add to your world to enable scene understanding
+ * world.addSystem(SceneUnderstandingSystem)
+ *
+
+ * ```
+ *
+ * @example Create an anchored object
+ * ```ts
+ * const cube = world.createTransformEntity(cubeObject)
+ * cube.addComponent(XRAnchor) // Will be anchored to real-world position
+ * ```
+ *
+ * @example React to detected planes
+ * ```ts
+ * // Planes are automatically created as entities with XRPlane component
+ * system.query({ required: [XRPlane] }).subscribe('qualify', (entity) => {
+ *   const plane = entity.getValue(XRPlane, '_plane')
+ *   console.log('New plane detected:', plane.orientation)
+ * })
+ * ```
+ *
+ * @category Scene Understanding
+ * @see {@link XRPlane}
+ * @see {@link XRMesh}
+ * @see {@link XRAnchor}
+ */
+export declare class SceneUnderstandingSystem extends SceneUnderstandingSystem_base {
+    private planeFeatureEnabled;
+    private meshFeatureEnabled;
+    private anchorFeatureEnabled;
+    private anchorRequested;
+    private xrAnchor;
+    private currentPlanes;
+    private currentMeshes;
+    private anchoredGroup;
+    private matrixBuffer;
+    init(): void;
+    update(_delta: number, _time: number): void;
+    private updatePlanes;
+    private updateMeshes;
+    private updateEnabledFeatures;
+    private createAnchor;
+    private updateAnchoredObject;
+    private flatToVec3Array;
+    private findMinMaxEntries;
+}
+export {};
+//# sourceMappingURL=scene-understanding-system.d.ts.map

package/dist/scene-understanding/scene-understanding-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-understanding-system.d.ts","sourceRoot":"","sources":["../../src/scene-understanding/scene-understanding-system.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAwB,KAAK,EAAE,MAAM,iBAAiB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAe9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,wBAAyB,SAAQ,6BAS7C;IACC,OAAO,CAAC,mBAAmB,CAAsB;IACjD,OAAO,CAAC,kBAAkB,CAAsB;IAChD,OAAO,CAAC,oBAAoB,CAAsB;IAClD,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,aAAa,CAAsB;IAE3C,OAAO,CAAC,YAAY,CAAiB;IAErC,IAAI,IAAI,IAAI;IAkCZ,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAuC3C,OAAO,CAAC,YAAY;IAqEpB,OAAO,CAAC,YAAY;IA6EpB,OAAO,CAAC,qBAAqB;YAgCf,YAAY;IAoB1B,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,iBAAiB;CAkB1B"}