@hraness/slopcamera 3.2.7 → 3.3.1

package/apps/desktop/application/spatial-spz.ts

@@ -2,10 +2,35 @@ import { Readable } from "node:stream";
 import { finished } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
 
+import type { Bounds } from "../../../src/spatial-scene/math";
 import { SpatialSpzFactsSchema, SPATIAL_SPLAT_LIMITS, spatialSpzAllocationBounds, type SpatialSpzFacts } from "../contracts/spatial-world";
 
-/** Inspect the complete gzip stream without allocating its advertised output. No decoder/browser runs before admission. */
-export async function inspectSpatialSpz(input: Uint8Array, signal: AbortSignal): Promise<SpatialSpzFacts> {
+export interface SpatialSpzInspection {
+  readonly facts: SpatialSpzFacts;
+  /**
+   * Model-space axis-aligned bounds decoded from the SPZ position section —
+   * the signed int24 fixed-point XYZ each splat stores before any scene
+   * normalization. This is the only honest splat enclosure available before a
+   * renderer decodes gaussian extent, so object-ID proxies derive from it.
+   */
+  readonly modelBounds: Bounds;
+}
+
+/** Decodes one signed little-endian int24 fixed-point coordinate. */
+function spzPositionComponent(data: Uint8Array, offset: number, fractionalBits: number): number {
+  let raw = data[offset]! | (data[offset + 1]! << 8) | (data[offset + 2]! << 16);
+  if (raw >= 0x80_00_00) raw -= 0x1_00_00_00;
+  return raw / 2 ** fractionalBits;
+}
+
+/**
+ * Inspect the complete gzip stream without allocating its advertised output.
+ * No decoder/browser runs before admission. Besides structural facts, the
+ * returned inspection carries model-space bounds decoded from the position
+ * section — bytes [16, 16 + splats × 9) of the decompressed body — so object-ID
+ * proxies and geometric audits share one trusted enclosure.
+ */
+export async function inspectSpatialSpz(input: Uint8Array, signal: AbortSignal): Promise<SpatialSpzInspection> {
   if (!(input instanceof Uint8Array) || input.byteLength < 18 || input.byteLength > SPATIAL_SPLAT_LIMITS.sourceBytes || input[0] !== 0x1f || input[1] !== 0x8b) throw new RangeError("The qualified splat profile requires bounded gzip SPZ v2/v3 bytes.");
   signal.throwIfAborted();
   const gunzip = createGunzip({ chunkSize: 16 * 1024 });
@@ -15,10 +40,12 @@ export async function inspectSpatialSpz(input: Uint8Array, signal: AbortSignal):
   source.pipe(gunzip);
   const header = new Uint8Array(16);
   let count = 0, facts: SpatialSpzFacts | undefined;
+  let positions: Uint8Array | undefined;
   try {
     for await (const chunkInput of gunzip) {
       signal.throwIfAborted();
       const chunk = chunkInput as Buffer;
+      const chunkStart = count;
       if (count < 16) header.set(chunk.subarray(0, Math.min(16 - count, chunk.byteLength)), count);
       count += chunk.byteLength;
       if (count > SPATIAL_SPLAT_LIMITS.decompressedBytes) throw new RangeError("SPZ decompression exceeds its byte budget.");
@@ -29,12 +56,30 @@ export async function inspectSpatialSpz(input: Uint8Array, signal: AbortSignal):
         if (flags === 1) throw new RangeError("Antialiased-training SPZ is not supported by the initial qualified Spark profile.");
         const decompressedBytes = 16 + splats * (9 + 1 + 3 + 3 + (version === 3 ? 4 : 3) + 3 * ((shDegree + 1) ** 2 - 1));
         facts = SpatialSpzFactsSchema.parse({ kind: "slopcamera.spz-admission", schemaVersion: 1, version, splats, shDegree, fractionalBits, antialiased: flags === 1, decompressedBytes, ...spatialSpzAllocationBounds(splats, input.byteLength, decompressedBytes) });
+        positions = new Uint8Array(facts.splats * 9);
       }
       if (facts !== undefined && count > facts.decompressedBytes) throw new RangeError("SPZ body exceeds the exact admitted attribute layout.");
+      if (positions !== undefined) {
+        // SPZ lays out splat sections back-to-back: every position lands in
+        // decompressed bytes [16, 16 + splats × 9) ahead of scales/rotations.
+        const windowEnd = 16 + positions.byteLength;
+        const copyStart = Math.max(chunkStart, 16), copyEnd = Math.min(count, windowEnd);
+        if (copyEnd > copyStart) positions.set(chunk.subarray(copyStart - chunkStart, copyEnd - chunkStart), copyStart - 16);
+      }
     }
     if (facts === undefined || count !== facts.decompressedBytes) throw new RangeError("SPZ attribute body is truncated or does not match its header.");
     signal.throwIfAborted();
-    return Object.freeze(facts);
+    const positionBytes = positions ?? new Uint8Array(0);
+    if (positionBytes.byteLength !== facts.splats * 9) throw new RangeError("SPZ position section is truncated or does not match its header.");
+    const minimum = [Infinity, Infinity, Infinity] as [number, number, number], maximum = [-Infinity, -Infinity, -Infinity] as [number, number, number];
+    for (let index = 0; index < facts.splats; index++) {
+      for (const axis of [0, 1, 2] as const) {
+        const value = spzPositionComponent(positionBytes, index * 9 + axis * 3, facts.fractionalBits);
+        if (value < minimum[axis]) minimum[axis] = value;
+        if (value > maximum[axis]) maximum[axis] = value;
+      }
+    }
+    return Object.freeze({ facts: Object.freeze(facts), modelBounds: Object.freeze({ min: Object.freeze(minimum), max: Object.freeze(maximum) }) });
   } finally {
     signal.removeEventListener("abort", abort);
     const settled = [finished(source, { cleanup: true }), finished(gunzip, { cleanup: true })];

package/apps/desktop/application/spatial-world-import.ts

@@ -9,7 +9,8 @@ import { SpatialAssetManifestSchema, SpatialEntitySchema } from "../../../src/sp
 import { canonicalJson, canonicalJsonSha256 } from "../core/canonical-json";
 import { createNodeSpatialDurability } from "../core/spatial-durability";
 import { createNodeBundleFileSystem } from "../core/storage";
-import { SavedSpatialWorldImportInputSchema, SavedSpatialWorldImportOutputSchema, SpatialWorldImportManifestSchema, SPATIAL_SPLAT_LIMITS, type SavedSpatialWorldImportOutput } from "../contracts/spatial-world";
+import { SavedSpatialWorldImportInputSchema, SavedSpatialWorldImportOutputSchema, SpatialWorldImportManifestSchema, SPATIAL_SPLAT_LIMITS, type SavedSpatialWorldImportOutput, type SpatialWorldSuggestedNormalization } from "../contracts/spatial-world";
+import { extractWorldProviderMetadata } from "./spatial-world-metadata";
 import { inspectSpatialSpz } from "./spatial-spz";
 import { WorldLabsProvenanceSchema } from "./spatial-world-provenance";
 
@@ -59,7 +60,8 @@ export async function importSavedSpatialWorld(options: {
 }): Promise<SavedSpatialWorldImportOutput> {
   const input = SavedSpatialWorldImportInputSchema.parse(options.input);
   if (input.provenance.receipt !== undefined && input.provenance.receipt.bytes > SPATIAL_SPLAT_LIMITS.metadataBytes) throw new RangeError("World provenance receipt exceeds one MiB.");
-  const sourceClosureBytes = input.splat.bytes + (input.collider?.bytes ?? 0) + (input.provenance.receipt?.bytes ?? 0);
+  if (input.providerMetadata !== undefined && input.providerMetadata.bytes > SPATIAL_SPLAT_LIMITS.metadataBytes) throw new RangeError("World provider metadata exceeds one MiB.");
+  const sourceClosureBytes = input.splat.bytes + (input.collider?.bytes ?? 0) + (input.provenance.receipt?.bytes ?? 0) + (input.providerMetadata?.bytes ?? 0);
   // Reserve the bounded import manifest as part of the returned asset closure
   // before reading/copying any payload, so a successful import is renderable
   // under the same 256 MiB source-asset ceiling.
@@ -67,7 +69,7 @@ export async function importSavedSpatialWorld(options: {
   options.signal.throwIfAborted();
   const sourceRoot = await physicalRoot(options.sourceRoot), destinationRoot = await physicalRoot(options.destinationRoot);
   const splatBytes = await readExact(sourceRoot, input.splat, options.signal);
-  const facts = await inspectSpatialSpz(splatBytes, options.signal);
+  const { facts } = await inspectSpatialSpz(splatBytes, options.signal);
   const colliderBytes = input.collider === undefined ? undefined : await readExact(sourceRoot, input.collider, options.signal);
   if (colliderBytes !== undefined) parseSpatialGlb(colliderBytes);
   const providerBytes = input.provenance.receipt === undefined ? undefined : await readExact(sourceRoot, input.provenance.receipt, options.signal);
@@ -78,6 +80,19 @@ export async function importSavedSpatialWorld(options: {
     if (!matches(value.assets.splat, input.splat) || input.collider === undefined || !matches(value.assets.collider, input.collider)
       || (input.provenance.worldId !== undefined && value.world.worldId !== input.provenance.worldId)) throw new RangeError("World provider provenance does not match the retained world and exact SPZ/collider bytes.");
   }
+  let suggestedNormalization: SpatialWorldSuggestedNormalization | undefined;
+  let providerMetadataBytes: Uint8Array | undefined;
+  if (input.providerMetadata !== undefined) {
+    providerMetadataBytes = await readExact(sourceRoot, input.providerMetadata, options.signal).catch((error: unknown) => {
+      if (options.signal.aborted || error instanceof RangeError) throw error;
+      throw new RangeError("World provider metadata source could not be read as declared.", { cause: error });
+    });
+    let document: unknown;
+    try { document = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(providerMetadataBytes)); }
+    catch (error) { throw new RangeError("World provider metadata is not valid UTF-8 JSON.", { cause: error }); }
+    const captured = createBoundedJsonSnapshot(document, 256 * 1024, "World provider metadata", { maximumDepth: 16, maximumValues: 4096 });
+    suggestedNormalization = { ...extractWorldProviderMetadata(captured.value), artifactSha256: input.providerMetadata.sha256 };
+  }
   const fs = createNodeBundleFileSystem(destinationRoot), durability = createNodeSpatialDurability(destinationRoot);
   const published: Artifact[] = [];
   const attempted: Artifact[] = [];
@@ -98,11 +113,15 @@ export async function importSavedSpatialWorld(options: {
   try {
     const splat = await publishBytes(splatBytes, "spz"), collider = colliderBytes === undefined ? undefined : await publishBytes(colliderBytes, "glb");
     const receipt = providerBytes === undefined ? undefined : await publishBytes(providerBytes, "json");
+    // The provider metadata artifact is retained verbatim — the exact source
+    // bytes publish under their own content address, never canonicalized.
+    const providerMetadata = providerMetadataBytes === undefined ? undefined : await publishBytes(providerMetadataBytes, "json");
     const manifest = SpatialWorldImportManifestSchema.parse({ kind: "slopcamera.spatial-world-import", schemaVersion: 1,
       splat: { payload: splat, facts }, collider: collider === undefined ? null : { payload: collider, role: "approximate-collider", validation: "bounded-glb-structure-only" },
       identities: input.identities, normalization: input.normalization,
       provenance: { ...input.provenance, ...(receipt === undefined ? {} : { receipt }) },
-      capabilities: { beauty: true, semanticIds: "authored-wrapper-only", depth: "unsupported", objectId: "unsupported", physics: collider === undefined ? "unavailable" : "unvalidated" },
+      ...(suggestedNormalization === undefined ? {} : { suggestedNormalization }),
+      capabilities: { beauty: true, semanticIds: "authored-wrapper-only", depth: "unsupported", objectId: "bounding-box-proxy", physics: collider === undefined ? "unavailable" : "unvalidated" },
     });
     const text = `${canonicalJson(manifest)}\n`, sha256 = createHash("sha256").update(text).digest("hex");
     const manifestArtifact = { path: `spatial/worlds/receipts/${sha256}.json`, sha256, bytes: Buffer.byteLength(text) };
@@ -115,10 +134,12 @@ export async function importSavedSpatialWorld(options: {
     const interpretation = { metersPerUnit: input.normalization.metersPerUnit, sourceUp: input.normalization.sourceUp };
     const manifestAssetId = `asset_world_manifest_${manifestArtifact.sha256}`;
     const receiptAssetId = receipt === undefined ? undefined : `asset_world_provider_${receipt.sha256}`;
+    const providerMetadataAssetId = providerMetadata === undefined ? undefined : `asset_world_provider_metadata_${providerMetadata.sha256}`;
     const assets = [
       ...(collider === undefined ? [] : [SpatialAssetManifestSchema.parse({ assetId: input.identities.colliderAssetId, payload: collider, interpretation: { kind: "gltf", format: "glb", ...interpretation }, dependencies: [], provenance })]),
-      SpatialAssetManifestSchema.parse({ assetId: manifestAssetId, payload: manifestArtifact, interpretation: { kind: "metadata", format: "json", schema: "slopcamera.spatial-world-import" }, dependencies: receiptAssetId === undefined ? [] : [receiptAssetId], provenance }),
+      SpatialAssetManifestSchema.parse({ assetId: manifestAssetId, payload: manifestArtifact, interpretation: { kind: "metadata", format: "json", schema: "slopcamera.spatial-world-import" }, dependencies: [...(receiptAssetId === undefined ? [] : [receiptAssetId]), ...(providerMetadataAssetId === undefined ? [] : [providerMetadataAssetId])], provenance }),
       ...(receipt === undefined ? [] : [SpatialAssetManifestSchema.parse({ assetId: receiptAssetId, payload: receipt, interpretation: { kind: "metadata", format: "json", schema: "slopcamera.world-labs-provenance" }, dependencies: [], provenance })]),
+      ...(providerMetadata === undefined ? [] : [SpatialAssetManifestSchema.parse({ assetId: providerMetadataAssetId, payload: providerMetadata, interpretation: { kind: "metadata", format: "json", schema: "slopcamera.provider-metadata" }, dependencies: [], provenance })]),
       SpatialAssetManifestSchema.parse({ assetId: input.identities.assetId, payload: splat, interpretation: { kind: "splat", format: "spz", ...interpretation }, dependencies: [...(input.identities.colliderAssetId === undefined ? [] : [input.identities.colliderAssetId]), manifestAssetId], provenance }),
     ];
     if (new Set(assets.map(asset => asset.assetId)).size !== assets.length) throw new RangeError("World metadata asset IDs conflict with requested identities.");

package/apps/desktop/application/spatial-world-metadata.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+
+import type { SpatialWorldSuggestedNormalization } from "../contracts/spatial-world";
+
+// World Labs Marble `semantics_metadata` documents are not formally versioned.
+// The documented fields are `metric_scale_factor` and `ground_plane_offset`
+// (both number-or-null; the ground plane offset is defined on the Y axis of the
+// metric-scaled frame). The documented carrier chain is
+// `world.assets.splats.semantics_metadata`: a world document nests it under
+// `assets.splats`, `world`/`response` envelopes wrap one world document, and a
+// saved `assets` object carries it under `splats` directly. A bare document and
+// a wrapping `semantics_metadata`/`semanticsMetadata` object are also read —
+// including the camelCase spelling retained inside slopcamera.world-labs-
+// provenance receipts. Recognized keys are validated strictly while unknown
+// keys are ignored, so newer provider fields never break parsing. Within one
+// scope the snake_case spelling wins, and an outer carrier wins over a more
+// deeply nested one. Every extracted value is provider-declared, never
+// verified.
+const metricScaleFactor = z.number().finite().positive().max(1_000_000).nullable();
+const groundPlaneOffset = z.number().finite().min(-1_000_000).max(1_000_000).nullable();
+const axisLabel = z.string().min(1).max(16).nullable();
+const recognizedScope = z.object({
+  metric_scale_factor: metricScaleFactor.optional(), metricScaleFactor: metricScaleFactor.optional(),
+  ground_plane_offset: groundPlaneOffset.optional(), groundPlaneOffset: groundPlaneOffset.optional(),
+  ground_plane_axis: axisLabel.optional(), groundPlaneAxis: axisLabel.optional(),
+  up_axis: axisLabel.optional(), upAxis: axisLabel.optional(),
+});
+// Each carrier level may hold the document under either documented spelling.
+const splatCarrier = z.object({
+  semantics_metadata: recognizedScope.nullable().optional(),
+  semanticsMetadata: recognizedScope.nullable().optional(),
+});
+const assetsCarrier = z.object({ splats: splatCarrier.nullable().optional() });
+const worldCarrier = z.object({ assets: assetsCarrier.nullable().optional() });
+const documentSchema = recognizedScope.extend({
+  semantics_metadata: recognizedScope.nullable().optional(),
+  semanticsMetadata: recognizedScope.nullable().optional(),
+  splats: splatCarrier.nullable().optional(),
+  assets: assetsCarrier.nullable().optional(),
+  world: worldCarrier.nullable().optional(),
+  response: worldCarrier.nullable().optional(),
+});
+type RecognizedScope = z.infer<typeof recognizedScope>;
+type SplatCarrier = z.infer<typeof splatCarrier>;
+type Declared = SpatialWorldSuggestedNormalization["declared"];
+type Suggested = SpatialWorldSuggestedNormalization["suggestion"];
+export type WorldProviderMetadataSuggestion = Omit<SpatialWorldSuggestedNormalization, "artifactSha256">;
+
+const positiveAxes = new Set(["x", "y", "z"]);
+function positiveAxis(label: string | null | undefined): "x" | "y" | "z" | undefined {
+  if (label === null || label === undefined) return undefined;
+  const normalized = label.trim().toLowerCase().replace(/^\+/u, "");
+  return positiveAxes.has(normalized) ? normalized as "x" | "y" | "z" : undefined;
+}
+
+/** Scopes carried by one splat-level object: snake_case first, then camelCase. */
+function carrierScopes(carrier: SplatCarrier | null | undefined): RecognizedScope[] {
+  if (carrier === null || carrier === undefined) return [];
+  return [
+    ...(carrier.semantics_metadata === null || carrier.semantics_metadata === undefined ? [] : [carrier.semantics_metadata]),
+    ...(carrier.semanticsMetadata === null || carrier.semanticsMetadata === undefined ? [] : [carrier.semanticsMetadata]),
+  ];
+}
+
+/** Extract the recognized provider-declared fields into an advisory suggestion record. */
+export function extractWorldProviderMetadata(document: unknown): WorldProviderMetadataSuggestion {
+  const parsed = documentSchema.safeParse(document);
+  if (!parsed.success) throw new RangeError("World provider metadata is not a recognized semantics_metadata document.");
+  // Outer carriers win over deeper nesting; each carrier's snake_case spelling
+  // precedes its camelCase spelling — matching the bare-before-wrapped rule.
+  const scopes: RecognizedScope[] = [
+    parsed.data,
+    ...carrierScopes(parsed.data),
+    ...carrierScopes(parsed.data.splats),
+    ...carrierScopes(parsed.data.assets?.splats),
+    ...carrierScopes(parsed.data.world?.assets?.splats),
+    ...carrierScopes(parsed.data.response?.assets?.splats),
+  ];
+  const first = <T>(select: (scope: RecognizedScope) => T | undefined): T | undefined => {
+    for (const scope of scopes) {
+      const value = select(scope);
+      if (value !== undefined) return value;
+    }
+    return undefined;
+  };
+  const metricScaleFactorValue = first(scope => scope.metric_scale_factor !== undefined ? scope.metric_scale_factor : scope.metricScaleFactor);
+  const groundPlaneOffsetValue = first(scope => scope.ground_plane_offset !== undefined ? scope.ground_plane_offset : scope.groundPlaneOffset);
+  const groundPlaneAxisValue = first(scope => scope.ground_plane_axis !== undefined ? scope.ground_plane_axis : scope.groundPlaneAxis);
+  const upAxisValue = first(scope => scope.up_axis !== undefined ? scope.up_axis : scope.upAxis);
+  const declared: Declared = {};
+  if (metricScaleFactorValue !== undefined) declared.metricScaleFactor = metricScaleFactorValue;
+  if (groundPlaneOffsetValue !== undefined) declared.groundPlaneOffset = groundPlaneOffsetValue;
+  if (groundPlaneAxisValue !== undefined) declared.groundPlaneAxis = groundPlaneAxisValue;
+  if (upAxisValue !== undefined) declared.upAxis = upAxisValue;
+  const suggestion: Suggested = {};
+  if (typeof declared.metricScaleFactor === "number" && declared.metricScaleFactor >= 0.000001) suggestion.metersPerUnit = declared.metricScaleFactor;
+  const sourceUp = positiveAxis(declared.upAxis);
+  if (sourceUp !== undefined) suggestion.sourceUp = sourceUp;
+  if (typeof declared.groundPlaneOffset === "number") {
+    // Marble defines ground_plane_offset on the Y axis of the metric-scaled
+    // frame; a declared axis only overrides that when it names a known axis.
+    suggestion.groundPlane = { axis: positiveAxis(declared.groundPlaneAxis) ?? "y", offset: declared.groundPlaneOffset };
+  }
+  return { provider: "worldlabs-marble", schema: "semantics_metadata", status: "unverified-provider-declared", declared, suggestion };
+}