Scene API
Scene 领域把 Model 或 Product 状态转换为可移植、面向浏览器的 Package，其中包含明确的 Geometry Resource、Hierarchy、Presentation 与 Contract Metadata。
文档类型
| 类型 | 作用 |
|---|---|
SceneRoot | 一个 Root Item 及其展示身份 |
SceneSource | Model JSON 或 Graph 来源 |
SceneCompileOptions | Mesh、Edge、Packaging 与 Validation 策略 |
SceneDocument | Scene Manifest 与资源引用 |
EntityDocument | 每个实体的稳定 Metadata Sidecar |
PresentationDocument | Camera、Visibility、Style 与 Override |
CompiledScenePackage | 已验证文档与二进制 Blob |
编译与导出
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")
不同 Source 类型应按 SceneRoot 的精确签名构造。compile_scene 返回内存中的 Document 和 Blob；export_scene 写出规范 Archive。
几何资源
build_render_mesh 与 build_edge_mesh 生成规范 Triangle 和 Line Block。GLB Writer 把这些 Block 序列化用于渲染。CAD-to-glTF 辅助函数把 Position、Normal 与 Direction 转换到目标坐标约定。
验证与限制
验证可作用于单个 Document、Resource 或完整 Package。SceneValidationReport 包含类型化问题；SceneContractError 表示必要契约无法满足。
SceneResourceLimits 限制 Archive Byte、Member 数量、解压大小、压缩比、JSON 深度、ID 长度、Hierarchy 深度、资源数量与解码网格规模。普通可信产物可使用默认限制；更大 Scene 必须显式审查并配置限制。
Preflight 辅助函数可在昂贵处理前拒绝过大 Archive、可疑压缩、资源过多、GLB 数量无效或未打包 Scene。
规范化
canonical_json_bytes、canonical_json_hash、canonical_zip_bytes 与 Revision 辅助函数支持确定性产物身份。严格 Parser 会拒绝不符合契约的 JSON，不会静默归一化。Scene 跨系统传递时应保留 Source 与 Package Hash。
验证顺序
- 对 Archive 或未打包资源执行 Limit Preflight。
- 严格解析 Manifest 与 Sidecar。
- 验证各个 Document。
- 验证引用 Blob 与 GLB 数量。
- 验证完整 Package 与 Revision。
- 通过后再向 Renderer 暴露资源。
全部符号见 65 个 Scene API。