Models and environments

Sources of truth: element assets, LOD pairs, asset manager.

Logical element identity is independent of its URL, LOD or number of visible occurrences. An immutable resource request identifies format, URL, revision and decoder/extension requirements. Updating content at a stable URL therefore requires an appropriate revision change.

Low and High must occupy a common authored reference frame, pivot and orientation. Do not independently center/normalize them: that would produce jumps during refinement. Verified manifests use a right-handed frame with +Y up, +Z front and metres. A provisional shared frame is supported, but it does not prove physical dimensions. Physical metadata needs documented provenance.

A representation records its canonical transform, selected root, exclusions, material bindings and estimated costs. Posters provide the non-GPU presentation. Environment and decoder resources must be explicitly deployable by the host. An enum listing a decoder requirement is not a guarantee that every consumer has configured that decoder.

Decoded source geometry/materials belong to the asset manager; live instances, local material clones and render targets belong to presentation owners. A retained capture pins its resources independently of DOM registration. CPU cache residency, live instance ownership and GPU preparation are distinct states. Disposal must respect those boundaries.

Validation should cover frame compatibility, resource URLs/requirements, bounds, material assumptions, actual visual Low/High alignment and ownership after repeated navigation. Estimated texture/geometry bytes are useful budgets, not complete driver memory measurements.

The procedural fixtures are reproducible and redistributable. The website also serves prepared product models and photographs for its public showcase. These product assets have separate provenance and rights; they are not part of the package license. See authoring for consumer configuration and the asset attribution for the website's media.

The showcase keeps the product description, photos, presentation pose and geometry manifests separate. One product ID joins them together. Generated assets live in apps/website/static/assets/showcase/<product-id>/; source assets remain outside the published static directory.

Each model has a low-detail variant for category grids, carousels and minimaps, and a higher-detail variant for the product view. Simplification preserves their common frame and reuses the source's materials, textures and normal maps where present. Texture resizing and material consolidation reduce work as well as triangle counts. This pipeline does not automatically bake arbitrary geometric detail into new normal maps.

Fallback images use the same authored model pose and camera orientation as the detail view. The transparent 1024 × 1024 WebP remains useful while the interactive model loads, without JavaScript or on a browser without WebGPU. Supplied photographs are converted to WebP without upscaling, with a 1600-pixel maximum edge and smaller 640-pixel alternatives for responsive galleries and media selectors.

npm run assets:showcase
npm run assets:showcase:render
npm run assets:showcase:check

Run these commands from the repository root. Generation needs the source collection; poster rendering also needs a browser with WebGPU. The committed outputs are sufficient to build the website. The asset pipeline instructions describe the inputs, commands and quality checks. Inspect silhouettes, materials and Low/High alignment alongside the generated resource reports before publishing a new model.