Topology, query, and exchange
Native topology queries
Model.faces(shape) returns deterministic zero-based face handles. Model.subshapes(shape, shape_type) extracts the requested OpenCascade topology type. Model.free_boundaries(shape, tolerance=1e-6) returns open boundary wires.
All returned subshapes remain owned by the same session. Their indices are local to the current topology and can change after booleans, fillets, chamfers, shelling, or reconstruction.
Selection levels
| Level | Use when | API |
|---|---|---|
| Immediate index | The selection is consumed in the next operation on unchanged topology | Model.faces, edge indices, subshapes |
| Query predicate | Geometry can be reselected from measurable properties | cadflow.query, Selection, filter helpers |
| Semantic identity | A product workflow must preserve intent across graph operations | tags, GeometryRef, connectors, semantic tracking |
Prefer semantic or predicate-based references in serialized workflows. Treat topology indices as transient implementation coordinates.
Measurements
Core Shape exposes volume, area, length, center of mass, bounding box, topology counts, and distance. Compatibility query functions add selection summaries, extrema, surface or curve descriptors, and aggregate measurements. The modeling catalog is the complete inventory.
Measurements use model coordinates and the active length convention. A scalar result does not include a unit object unless the expression or engineering domain explicitly wraps it.
Validation boundary
Combine checks according to the intended claim:
Shape.validate()for finite native measurements and basic solid-count evidence;free_boundaries()for open-shell evidence;- BREP inspection for detailed topology neighborhoods and comparisons;
- domain validators for assemblies, scenes, physical connections, and simulation handoffs.
A model can be topologically valid yet wrong in dimensions, placement, material assignment, or intended connectivity. Keep those acceptance criteria in the calling application or domain report.
Exchange formats
| Format | Read | Write | Preserves |
|---|---|---|---|
| STEP | Model.import_step | Shape.export_step | Exact exchange geometry and topology |
| BREP | Model.import_brep | compatibility BREP exporters | Native boundary representation |
| STL | Model.import_stl | Shape.export_stl | Triangles only |
| GLB | Scene/preview readers | Shape.export_preview_glb, Scene compiler | Render mesh and presentation data |
| Model JSON | serialization API | serialization API | Declarative operation graph and structured workflow state |
File extension alone is not validation. After writing, check existence and non-zero size; for critical exchange, re-import and compare measurements or topology. Scene packages provide stricter schema and resource validation for browser-facing artifacts.
Paths and security
Resolve paths within an application-controlled root. For untrusted archives or JSON, enforce resource limits before allocation or extraction. Scene preflight helpers cover archive size, member size, compression ratio, resource count, and GLB counts.