Skip to main content

Graphs and replay

CadFlow provides two distinct graph workflows:

  • cadflow.Graph is a compact builder for native operations executed through one C ABI call.
  • Model JSON in the serialization domain records the richer compatibility graph for strict replay, semantics, and product workflows.

Choose based on what you need to preserve.

Execute a native batch​

Each Graph.add() returns the zero-based node index used by later nodes:

import cadflow as cad


graph = cad.Graph()
wire = graph.add(
    "polyline",
    ((0, 0, 0), (40, 0, 0), (40, 25, 0), (0, 25, 0)),
    True,
)
face = graph.add("face", wire)
body = graph.add("extrude", face, 0, 0, 6)
graph.add("volume", body)
graph.add("bbox", body)

output = graph.execute()
print("volume:", float(output[3]))
print("bbox:", tuple(map(float, output[4].split())))

execute() compiles the nodes and sends them to the native runtime as one batch. Results are returned in node order as strings because the call crosses the stable C ABI.

Shape lifetime

When Graph.execute() creates its own session, that session closes after execution. Use the graph for batch results, not for retaining Shape objects. Use Model when subsequent interactive shape work is required.

Supported graph operations​

The native graph covers primitives, curves, surfaces, features, booleans, transforms, subshape operations, measurements, and imports. Operations reference earlier node indices rather than Python Shape values.

Use Graph when:

  • the operation plan is known before execution;
  • reducing Python/C++ round trips matters;
  • scalar results or files are the final output;
  • the plan only needs the native operation set.

Use Model when you need interactive inspection, conditional construction, or repeated use of returned shapes.

Preserve richer design state​

The serialization domain exposes Model JSON and strict replay through public helpers such as:

model_json = cad.export_model_json(session=session)
replayed = cad.replay_model_json(json_str=model_json, strict=True)

This workflow belongs to the compatibility feature layer and can preserve higher-level graph nodes, semantic tags, source mappings, assemblies, and other structured state that the small native Graph does not model.

Reproducibility rules​

  • Record the CadFlow version and backend in the artifact report.
  • Prefer explicit operation parameters over ambient state.
  • Use strict=True for release replay.
  • Keep referenced source files or imported BREP inputs addressable and hashed.
  • Validate the replayed terminal geometry rather than assuming successful replay implies equivalent output.
  • Store units alongside numeric values in external schemas.