SpatialPack — 3D asset readiness

Run the SpatialPack analyzer against a GLB or glTF file. Returns the full structured report: vertex / triangle / texture / animation counts, cohort tags (texture, animation, poly), KHR / EXT extensions used, estimated GPU texture memory, and a per-target compatibility rollup (Three.js, Babylon, model-viewer, AR Quick Look, Scene Viewer). Read-only — does not modify the input.

SPEC-0125/0126: repair a GLB / glTF so it is commerce-ready for AR Quick Look + web, and prove it. Runs floater removal + USDZ-safe material bake (transmission→alpha; clearcoat/sheen/etc. flattened) + preset optimization, then RE-SCORES readiness and returns the before→after report: applied repairs, size reduction, resolvedBlockers (what it fixed) and remainingBlockers (what needs manual work). Writes the repaired GLB to output_path (sandbox). Set bake_usdz_safe=false to keep lossy materials (leaves the AR blocker).

SPEC-0128: repair + re-score every GLB / glTF under the given files/dirs (recursive), writing each repaired asset + a per-asset report into out_dir, plus a roll-up that tallies readiness status transitions (not-ready→ready/warnings), how many assets were rescued, how many remain not-ready, and total size reduction. The agency / generator catalog surface. Set bake_usdz_safe=false to keep lossy materials.

Walk a list of files and/or directories (recursive for .glb/.gltf), run the SpatialPack optimizer on each at the requested preset, and write per-asset reports + optimized GLBs into out_dir. Continues on per-asset error by default (failFast=false). Honors a resume mode that skips assets whose report file already exists.

Pack a primary GLB plus sidecar files (textures/, etc.) into a single `.glb.zip` archive with a versioned manifest. Sidecar paths inside the archive default to their basenames; pass `sidecar_arcnames` to override. Auto-DEFLATE per entry, falling back to stored when DEFLATE wastes bytes. Returns the manifest and on-disk size.

Compute the SPEC-0055 16-char hex SHA-256 prefix of the canonicalized geometry stream. Robust to mesh / primitive / attribute ordering and endianness; excludes textures and materials. Use as a deterministic geometry-identity key for caching and deduplication.

Run TPE recipe-search per cohort bucket (poly × animation × material) using a representative subset of the corpus. Emits a sidecar `cohort-recipes.json` the runtime / batch pipeline can use to pick the right recipe for any given asset by its cohort tags.

Read a cohort-recipes.json manifest and resolve the recipe for the given cohort tags. Falls back to same-poly+animation, then same-poly only, then null.

SPEC-0124: score whether a GLB / glTF is commerce-ready for AR Quick Look + web. Composes ACG-2.0 conformance with AR-parity (lossy materials like KHR_materials_transmission, structural USDZ risks, geometry) into ONE verdict — ready | warnings | not-ready — plus explicit must-fix blockers and review warnings. Read-only; does not modify the input. Use this to gate AI-generated 3D output before publishing.

Pixel-precise comparison of two PNG buffers of identical dimensions. Returns differing-pixel count, MAE per channel, ΔE94 mean/max/p95 (CIE perceptual colour distance), Sobel-edge delta, and SSIM. Inputs are file paths (sandbox-relative).

Run the analyzer against the input asset and surface the per-target compatibility matrix: Three.js, Babylon.js, model-viewer, AR Quick Look, Scene Viewer. Returns warnings and notes per target so a caller can pick a delivery format.

Scan a set of GLBs for byte-identical embedded images and extract any image shared by ≥ `min_occurrences` GLBs into a shared sidecar directory. Rewrites each input GLB to reference the sidecar via `image.uri`. Returns the per-image and per-GLB savings report. Set `dry_run: true` to plan without writing. Default `min_occurrences` is 2.

Run analyze + compatibility-check on the asset and return a structured list of recommendations the caller can act on (e.g. "enable channelPack — material has separate occlusion + metallicRoughness"). Each recommendation includes a `tool` + `suggested_args` so the model can chain into `optimize` with confidence.

Return the SPEC-0030 cohort budget table (texture / animation / poly), the SPEC-0046 cohort attribute-quantization budgets, and the SPEC-0059 per-cohort meshopt method scheduler. Pure data — useful for the model to explain trade-offs to the user.

Embed the query asset, query an on-disk AssetEmbeddingIndex, and return the top-K nearest neighbors by cosine similarity. The index must have been built by `spatialpack index build` (or the equivalent core helpers); pass its sandbox-relative path. K defaults to 5. Read-only — does not modify either the query or the index.

Return the configured preset ids (web-mobile, web-desktop, quality-max) and their key budget knobs: maxTextureSize, useWebpTextures, preferKtx2, meshoptLevel.

Bake multiple quality tiers (default: high / medium / low) of a single source GLB and emit a sidecar spatialpack.lod.json manifest pointing at them. The runtime picks the largest tier whose recommendedMinPixelHeight ≤ the projected screen height.

SPEC-0161: score whether a USDZ will load + render in Safari 27's HTML <model> element and Apple AR Quick Look. Composes USDZ packaging conformance with the AR-Quick-Look render constraints and the <model>-specific deltas (centimeter 100x scale bug, .usdz extension/MIME negotiation, empty-stage) into ONE verdict — ready | warnings | not-ready — plus explicit must-fix blockers and review warnings. Read-only; does not modify the input. HONESTY: this is documented-constraint conformance, NOT a live Safari/Quick Look render — Apple ships no headless <model>/RealityKit renderer, so verify high-value SKUs on a real device.

Run the full SpatialPack optimization pipeline against a preset. Writes a new GLB to `output_path` (must be inside the sandbox) and returns the structured optimization report — pass-by-pass before/after stats, baseline comparison, KTX2 status, quality notes. All opt-in passes (decimate, saliencyAware decimation, channelPack ORM, palette PNG re-encode, materialClustering, symmetry detection, cohort-quantize, lockBorder, etc.) are exposed as flat options.

Compute the SPEC-0052 64-bit DCT-based perceptual hash of a PNG. Returns a 16-character hex string. Pair with `phash_distance` to short-circuit visual diffs when two renders are byte-equivalent.

Compute the Hamming distance (count of differing bits) between two 16-char hex pHashes. Convention: ≤ 5 = near-duplicate, 6–15 = ambiguous, > 15 = clearly different.

Sweep optimization recipes (preset × meshopt × decimate × KTX2 quality) for the input asset and return the winning recipe under the configured policy. Uses cohort-aware pruning + grid warm-start + TPE Bayesian search (SPEC-0044). The visual-quality gate is OFF by default — pass `with_quality_gate: true` to enable Playwright + ΔE94 / SSIM gating (much slower, ~30s per candidate).

Run multi-fidelity TPE recipe search (SPEC-0044) against the input asset, but seed the queue with the winning recipes already cached for the input's k nearest neighbors in the supplied AssetEmbeddingIndex. Composes SPEC-0087 Phase 2 (k-NN recipe inheritance) + SPEC-0096 (index management). Visual quality gate is OFF — same constraint as `recipe_search`.

Apply SpatialPack's cohort-aware quality gate (SPEC-0036 thresholds + SPEC-0090 reporting) to a set of per-asset visual-diff metrics. Each input asset carries its cohort tags (textured/untextured · animated/static · low/medium/high poly) and worst-of-N ssim/ΔE94/edgeDelta numbers from an orbit-8 render. Returns per-asset verdicts plus an aggregate `summary` (`pass` iff every asset passed); optionally writes a JSON report and a `gate-report.md` to `output_path`.

Convert a Gaussian splat file (PLY, .splatz, or KHR_gaussian_splatting GLB) into an Apple ParticleField3DGaussianSplat USDZ (OpenUSD 26.03 schema pin) for RealityKit / Reality Composer Pro / Safari `<model>`. Pure-TS — no Apple toolchain. Optionally also writes the RealityKit per-channel f32 buffer set + layout.json sidecar via `realitykit_buffers_dir`. STRUCTURAL CONFORMANCE ONLY — the emitted USDZ is a valid package whose ParticleField3DGaussianSplat prim this tool re-parses; it is NOT RealityKit/visionOS render-verified (that requires Apple hardware, SPEC-0160 Phase D).

Read a `.glb.zip` and write the primary GLB + every sidecar to `out_dir`, preserving the relative paths recorded in the manifest. Verifies CRC32 + cross-checks manifest names against archive entries. Returns the manifest and per-entry output paths.

Read a binary USDC file and emit the equivalent USDA text — the same conversion the Pixar `usdcat` tool performs. Returns the rendered text directly; pass `output_path` to also write it to disk (sandbox-relative). Useful for inspecting a USDZ payload, diffing generated USDC against a Pixar reference, or letting an AI agent read scene structure as plain text.

Convert a GLB to a USDZ for AR Quick Look using the local converter (usd_from_gltf, usdzconvert, or xcrun usdz_converter — the first one found on PATH). Includes a post-export validation pass when `validate: true` (default true).

Open a .usdz, walk its contents, and report compatibility warnings (size budget, asset-ref resolution, missing textures, file-size cap). Pure-JS read; no converter required.