@viamrobotics/motion-tools 1.19.0 → 1.21.0

package/dist/hooks/useRelationships.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { Entity } from 'koota';
+import type { Relationship } from '../metadata';
+export declare const provideRelationships: () => {
+    apply(entity: Entity, relationships: Relationship[] | undefined): void;
+    flush(targetUuid: string): void;
+    clear(): void;
+};
+export declare const useRelationships: () => {
+    apply(entity: Entity, relationships: Relationship[] | undefined): void;
+    flush(targetUuid: string): void;
+    clear(): void;
+};

package/dist/hooks/useRelationships.svelte.js

@@ -0,0 +1,78 @@
+import { getContext, setContext } from 'svelte';
+import { uuidBytesToString } from '../draw';
+import { relations, traits, useQuery } from '../ecs';
+const RELATIONSHIPS_CONTEXT_KEY = Symbol('relationships');
+export const provideRelationships = () => {
+    const uuids = useQuery(traits.UUID);
+    const pending = new Map();
+    const addPending = (targetUuid, relationship) => {
+        const next = pending.get(targetUuid) ?? [];
+        next.push(relationship);
+        pending.set(targetUuid, next);
+    };
+    return setContext(RELATIONSHIPS_CONTEXT_KEY, {
+        apply(entity, relationships) {
+            const desired = relationships ?? [];
+            const currentTargets = entity.targetsFor(relations.SubEntityLink);
+            const desiredByUuid = new Map();
+            for (const rel of desired) {
+                const targetUUID = uuidBytesToString(rel.targetUuid);
+                if (!targetUUID)
+                    continue;
+                desiredByUuid.set(targetUUID, rel);
+            }
+            for (const target of currentTargets) {
+                if (!target.isAlive())
+                    continue;
+                const targetUuid = target.get(traits.UUID);
+                if (!targetUuid || !desiredByUuid.has(targetUuid)) {
+                    entity.remove(relations.SubEntityLink(target));
+                }
+            }
+            for (const [uuid, relationship] of desiredByUuid) {
+                const targetEntity = uuids.current.find((e) => e.get(traits.UUID) === uuid);
+                if (!targetEntity) {
+                    addPending(uuid, {
+                        entity: entity,
+                        type: relationship.type,
+                        indexMapping: relationship.indexMapping,
+                    });
+                    continue;
+                }
+                const existing = entity.get(relations.SubEntityLink(targetEntity));
+                if (existing &&
+                    existing.type === relationship.type &&
+                    existing.indexMapping === (relationship.indexMapping ?? 'index')) {
+                    continue;
+                }
+                entity.add(relations.SubEntityLink(targetEntity, {
+                    type: relationship.type,
+                    indexMapping: relationship.indexMapping ?? 'index',
+                }));
+            }
+        },
+        flush(targetUuid) {
+            const relationship = pending.get(targetUuid);
+            if (!relationship)
+                return;
+            pending.delete(targetUuid);
+            const targetEntity = uuids.current.find((e) => e.get(traits.UUID) === targetUuid);
+            if (!targetEntity)
+                return;
+            for (const { entity, type, indexMapping } of relationship) {
+                if (!entity.isAlive())
+                    continue;
+                entity.add(relations.SubEntityLink(targetEntity, {
+                    type,
+                    indexMapping: indexMapping ?? 'index',
+                }));
+            }
+        },
+        clear() {
+            pending.clear();
+        },
+    });
+};
+export const useRelationships = () => {
+    return getContext(RELATIONSHIPS_CONTEXT_KEY);
+};

package/dist/hooks/useWorldState.svelte.js

@@ -9,6 +9,7 @@ import { isPointCloud } from '../geometry';
 import { metadataFromStruct } from '../metadata';
 import { createPose } from '../transform';
 import { usePartID } from './usePartID.svelte';
+import { useRelationships } from './useRelationships.svelte';
 export const provideWorldStates = () => {
     const partID = usePartID();
     const resourceNames = useResourceNames(() => partID.current, 'world_state_store');
@@ -83,6 +84,7 @@ const decodeWorldStateChunk = (response, fallbackStart) => {
 const createWorldState = (client) => {
     const { invalidate } = useThrelte();
     const world = useWorld();
+    const relationships = useRelationships();
     const entities = new Map();
     const chunkLoader = createChunkLoader({
         world,
@@ -105,10 +107,12 @@ const createWorldState = (client) => {
         if (entities.has(transform.uuidString)) {
             return;
         }
-        const entity = drawTransform(world, transform, traits.WorldStateStoreAPI, { removable: false });
-        entities.set(transform.uuidString, entity);
+        const spawned = drawTransform(world, transform, traits.WorldStateStoreAPI, { removable: false });
+        entities.set(transform.uuidString, spawned.entity);
+        relationships.apply(spawned.entity, spawned.relationships);
         const parsedMetadata = metadataFromStruct(transform.metadata?.fields);
-        chunkLoader.start(transform.uuidString, entity, parsedMetadata);
+        chunkLoader.start(transform.uuidString, spawned.entity, parsedMetadata);
+        relationships.flush(transform.uuidString);
         if (isPointCloud(transform.physicalObject?.geometryType))
             invalidate();
     };
@@ -140,9 +144,11 @@ const createWorldState = (client) => {
             }
         }
         if (metadataDirty) {
-            updateMetadata(entity, metadataFromStruct(transform.metadata?.fields), {
+            const parsedMetadata = metadataFromStruct(transform.metadata?.fields);
+            updateMetadata(entity, parsedMetadata, {
                 pointCloud: isPointCloud(transform.physicalObject?.geometryType),
             });
+            relationships.apply(entity, parsedMetadata.relationships);
         }
     };
     let initialized = false;

package/dist/metadata.d.ts

@@ -1,7 +1,11 @@
 import type { PlainMessage, Struct } from '@viamrobotics/sdk';
-import { Metadata as MetadataProto } from './buf/draw/v1/metadata_pb';
-/** Metadata for a `Drawing` or `Transform`. */
-export type Metadata = PlainMessage<MetadataProto>;
+import { Metadata as MetadataProto, type Relationship as RelationshipProto } from './buf/draw/v1/metadata_pb';
+/** Metadata for a `Drawing` or `Transform`. Relationships default to empty. */
+export type Metadata = Omit<PlainMessage<MetadataProto>, 'relationships'> & {
+    relationships?: PlainMessage<MetadataProto>['relationships'];
+};
+/** Plain-object representation of a Relationship, usable outside proto classes. */
+export type Relationship = PlainMessage<RelationshipProto>;
 /** Type guard that checks whether a string is a recognised metadata wire key. */
 export declare const isMetadataField: (key: string) => boolean;
 /**

package/dist/metadata.js

@@ -1,4 +1,4 @@
-import { ColorFormat, Metadata as MetadataProto } from './buf/draw/v1/metadata_pb';
+import { ColorFormat, Metadata as MetadataProto, } from './buf/draw/v1/metadata_pb';
 /** Type guard that checks whether a string is a recognised metadata wire key. */
 export const isMetadataField = (key) => {
     return (key === 'colors' ||
@@ -6,7 +6,8 @@ export const isMetadataField = (key) => {
         key === 'opacities' ||
         key === 'show_axes_helper' ||
         key === 'invisible' ||
-        key === 'chunks');
+        key === 'chunks' ||
+        key === 'relationships');
 };
 /**
  * Extracts typed {@link Metadata} from a proto `Struct` fields map.
@@ -77,6 +78,29 @@ export const metadataFromStruct = (fields = {}) => {
                 }
                 break;
             }
+            case 'relationships': {
+                if (Array.isArray(unwrappedValue)) {
+                    json.relationships = unwrappedValue
+                        .filter((item) => typeof item === 'object' && item !== null)
+                        .map((item) => {
+                        const targetUuidStr = item['target_uuid'];
+                        let targetUuid = new Uint8Array();
+                        if (typeof targetUuidStr === 'string' && targetUuidStr.length > 0) {
+                            const binary = atob(targetUuidStr);
+                            targetUuid = new Uint8Array(binary.length);
+                            for (let i = 0; i < binary.length; i++) {
+                                targetUuid[i] = binary.charCodeAt(i);
+                            }
+                        }
+                        return {
+                            targetUuid,
+                            type: typeof item['type'] === 'string' ? item['type'] : '',
+                            indexMapping: typeof item['index_mapping'] === 'string' ? item['index_mapping'] : undefined,
+                        };
+                    });
+                }
+                break;
+            }
         }
     }
     return json;

package/dist/snapshot.d.ts

@@ -2,6 +2,11 @@ import type { Entity, World } from 'koota';
 import type { Snapshot } from './buf/draw/v1/snapshot_pb';
 import type { Settings } from './hooks/useSettings.svelte';
 import { type SceneMetadata } from './buf/draw/v1/scene_pb';
+import type { Relationship } from './metadata';
+export type SnapshotEntity = {
+    entity: Entity;
+    relationships: Relationship[] | undefined;
+};
 /**
  * Merges scene-level metadata (grid, camera, point/line settings) into the
  * current viewer settings. Millimeter values from the proto are converted
@@ -18,4 +23,4 @@ export declare const applySceneMetadata: (settings: Settings, metadata: SceneMet
  *
  * @returns The spawned entities
  */
-export declare const spawnSnapshotEntities: (world: World, snapshot: Snapshot) => Entity[];
+export declare const spawnSnapshotEntities: (world: World, snapshot: Snapshot) => SnapshotEntity[];

package/dist/snapshot.js

@@ -58,13 +58,18 @@ export const spawnSnapshotEntities = (world, snapshot) => {
     const entities = [];
     const options = { removable: true, showAxesHelper: false };
     for (const transform of snapshot.transforms) {
-        entities.push(drawTransform(world, transform, traits.SnapshotAPI, options));
+        const spawned = drawTransform(world, transform, traits.SnapshotAPI, options);
+        entities.push({
+            entity: spawned.entity,
+            relationships: spawned.relationships,
+        });
     }
     for (const drawing of snapshot.drawings) {
-        const drawingEntities = drawDrawing(world, drawing, traits.SnapshotAPI, options);
-        for (const e of drawingEntities) {
-            entities.push(e);
-        }
+        const spawned = drawDrawing(world, drawing, traits.SnapshotAPI, options);
+        entities.push({
+            entity: spawned.entity,
+            relationships: spawned.relationships,
+        });
     }
     return entities;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viamrobotics/motion-tools",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "Motion visualization with Viam",
   "license": "Apache-2.0",
   "type": "module",
@@ -32,6 +32,7 @@
     "@types/bun": "1.2.21",
     "@types/earcut": "^3.0.0",
     "@types/lodash-es": "4.17.12",
+    "@types/node": "^25.6.0",
     "@types/three": "0.183.1",
     "@typescript-eslint/eslint-plugin": "8.56.1",
     "@typescript-eslint/parser": "8.56.1",
@@ -65,6 +66,7 @@
     "runed": "0.31.1",
     "svelte": "5.55.0",
     "svelte-check": "4.4.5",
+    "svelte-tweakpane-ui": "^1.5.16",
     "svelte-virtuallists": "1.4.2",
     "tailwindcss": "4.1.13",
     "three": "0.183.2",
@@ -104,6 +106,7 @@
     "lucide-svelte": ">=0.511",
     "runed": ">=0.28",
     "svelte": ">=5",
+    "svelte-tweakpane-ui": ">=1.5",
     "svelte-virtuallists": ">=1"
   },
   "engines": {
@@ -123,7 +126,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/viam-labs/motion-tools.git"
+    "url": "git+https://github.com/viamrobotics/visualization.git"
   },
   "files": [
     "dist",