Jerry
3.7 KiB
Serialization and Replay Operation Guides
This directory documents how SimpleCADAPI serializes replayable modeling operations into the canonical low-level model.json operation graph.
The long-form schema reference remains ../operation_graph_json_spec.md. These files are more practical, operation-by-operation guides intended for people comparing source code with exported JSON.
Recommended workflow
import json
import simplecadapi as scad
@scad.model(graph_id="drilled_block")
def build_model():
body = scad.make_box_rsolid(width=10, height=6, depth=2)
hole = scad.make_cylinder_rsolid(
radius=1, height=4, bottom_face_center=(0, 0, -1)
)
result = scad.cut_rsolid(body, hole)
scad.capture_result(value=result)
return result
model = build_model()
payload = json.loads(model.model_json)
rebuilt = model.replay()
Inspect these fields:
payload["graph"]["nodes"]: canonical operation nodes in topological order.node["op"]: stable replay operation name.node["params"]: numeric / JSON-compatible parameter snapshot.node["param_exprs"]: optional expression links intoexpression_graph.node["inputs"]: upstream node ids used by replay.payload["leaf_ids"]: explicit final result node ids.payload["expression_graph"]: expression DAG used by expression-backed parameters.payload["tolerance_graph"]: dimension-chain requirements and validation evidence.
For new top-level models, ModelResult.model_json is the preferred artifact
accessor. Use @scad.requires_session for reusable builders and
scad.capture_result(...) when the final output should not be inferred from
all graph leaves. If a model invocation also needs durable CAD/viewer files,
pass export_dir=... to @scad.model; its captured geometry/product values
then produce one self-contained <graph_id>.scene.zip. It embeds
model/model.json, mapped project-relative Python sources, and the evaluated
render/selection assets. It does not create adjacent model/session JSON, STEP,
STL, or FCStd files. No files are written when export_dir is omitted.
Important rule: source API is not always graph API
Many user-facing functions are convenience APIs. During an active GraphSession, they lower to canonical low-level nodes:
| Source call | Serialized graph result |
|---|---|
make_box_rsolid(...) |
rectangle profile + make_extrude_rsolid |
make_cylinder_rsolid(...) |
circle face + make_extrude_rsolid |
make_sphere_rsolid(...) |
profile + make_revolve_rsolid |
make_cone_rsolid(...) |
profile + make_revolve_rsolid |
make_rectangle_rwire(...) |
line edges + make_wire_from_edges_rwire |
make_circle_rface(...) |
circle edge + wire + face |
make_polyline_rwire(...) |
line edges + wire |
linear_pattern_rsolidlist(...) |
explicit make_translate_rshape nodes |
radial_pattern_rsolidlist(...) |
explicit make_rotate_rshape nodes |
helical_sweep_rsolid(...) |
helix wire + profile face + make_sweep_rsolid |
Guides
- Primitive and profile operations
- Features, booleans, transforms, patterns, and selectors
- Expressions and replay behavior
- Physical units and dimension inference
- Dimension tolerance chains
Examples
The retained examples use the same model/session contract. See
../../../examples/08_constrained_sketch.py
for sketch promotion and replay, and
../../../examples/10_part_assembly.py
for product hierarchy and automatic artifact export.