Scene API

The Scene domain turns model or product state into a portable, browser-oriented package with explicit geometry resources, hierarchy, presentation, and contract metadata.

Documents

Type	Role
SceneRoot	One root item and its presentation identity
SceneSource	Source Model JSON or graph provenance
SceneCompileOptions	Mesh, edge, packaging, and validation policy
SceneDocument	Scene manifest and resource references
EntityDocument	Stable per-entity metadata sidecar
PresentationDocument	Cameras, visibility, styling, and overrides
CompiledScenePackage	Validated documents plus binary blobs

Compile and export

from cadflow.scene import SceneCompileOptions, SceneRoot, compile_scene, export_scene

package = compile_scene(
    scene_id="fixture-review",
    roots=(SceneRoot(root_id="fixture", value=assembly),),
    options=SceneCompileOptions(),
)
export_scene(package=package, path="out/fixture.cadflow-scene")

Use the exact SceneRoot signature for the selected source type. compile_scene returns in-memory documents and blobs; export_scene writes the canonical archive.

Geometry resources

build_render_mesh and build_edge_mesh produce canonical triangle and line blocks. GLB writers serialize those blocks for rendering. CAD-to-glTF helpers convert positions, normals, and directions into the target coordinate convention.

Validation and limits

Validation operates at document, resource, and complete-package levels. SceneValidationReport contains typed issues. SceneContractError signals that a required contract could not be satisfied.

SceneResourceLimits bounds archive bytes, member counts, uncompressed size, compression ratio, JSON depth, identifier lengths, hierarchy depth, resource counts, and decoded mesh sizes. Use the default limits for ordinary trusted artifacts and explicitly reviewed limits for larger scenes.

Preflight helpers can reject oversized archives, suspicious compression, excessive resource counts, malformed GLB counts, or unpacked packages before expensive processing.

Canonicalization

canonical_json_bytes, canonical_json_hash, canonical_zip_bytes, and revision helpers support deterministic artifact identity. Strict parsers reject non-conforming JSON instead of normalizing it silently. Preserve source and package hashes when scenes cross systems.

Validation sequence

1. Preflight archive or unpacked resource limits.
2. Strictly parse the manifest and sidecars.
3. Validate individual documents.
4. Validate referenced blobs and GLB counts.
5. Validate the complete package and revision.
6. Only then expose resources to a renderer.

See all 65 Scene symbols.