Shape
Shape is an immutable Python wrapper around a NativeSession and opaque ShapeHandle. Users obtain it from Model; constructing it directly couples code to low-level ownership details.
Identity and ownership
Two wrappers may refer to different native handles even when their geometry is equivalent. Use measurements, topology, or exported evidence for geometric comparison rather than Python object identity. Operations involving two shapes require the exact same session.
with cad.Model() as model:
left = model.box(10, 10, 10)
right = model.translate(left, 20, 0, 0)
clearance = left.distance_to(right)
Measurements
| Member | Return | Notes |
|---|---|---|
kind | str | Native shape category such as solid, face, or wire |
volume | float | Zero for non-volumetric geometry |
area | float | Surface area in squared model units |
length | float | Curve or edge length in model units |
center_of_mass | (x, y, z) | Mass-properties centroid under uniform density |
bbox | six floats | (xmin, ymin, zmin, xmax, ymax, zmax) |
topology | dict[str, int] | Counts of solids, shells, faces, wires, edges, and vertices |
distance_to(other) | float | Minimum separation; same-session only |
describe(detail="summary") combines measurements into JSON-safe lists and mappings. detail="mesh" additionally includes tessellation. Any other detail value raises ValueError.
Validation
validate() returns an OperationReport. It checks finite measurements and flags unexpected multi-solid output for shapes normally expected to be one solid. This is an inexpensive structural check, not a substitute for application-specific dimensional or manufacturability checks.
report = body.validate()
if not report.ok:
raise RuntimeError(report.to_dict())
Mesh and preview
| Member | Contract |
|---|---|
mesh(deflection=0.1) | Return flat vertex and triangle-index arrays |
preview_mesh_buffer(deflection=0.35) | Return the compact native preview buffer |
preview_glb(deflection=0.35) | Convert that buffer to in-memory GLB bytes |
export_preview_glb(path, deflection=0.35) | Write browser-ready GLB |
Smaller deflection values generally produce a denser approximation and larger output. Tessellation is derived display geometry; use STEP/BREP and native measurements when exact geometry matters.
Surface evidence
face_properties(u=0.5, v=0.5) evaluates point and normal data on a face. surface_metrics() returns exact native face measurements used by simulation preprocessing. contact_metrics(other) returns proximity and relative-orientation evidence for two same-session faces.
The normalized (u, v) interpretation and supported result fields depend on the face type; preserve the returned mapping instead of assuming every surface supplies identical evidence.
Export
body.export_step("out/part.step")
body.export_stl("out/part.stl", binary=True)
body.export_preview_glb("out/part.glb")
STEP preserves exact exchange geometry. STL and preview GLB are tessellated. Export methods write to the supplied path and return None; create parent directories and verify the artifact in the calling application.
See the generated Shape reference for exact signatures and topology/query/exchange for selection and subshape rules.