Feedback and preview
Operation feedback
CadFlow uses immutable data records for machine-readable operation evidence:
| Type | Key fields | Role |
|---|---|---|
Diagnostic | severity, code, message, hint, data | One actionable issue |
OperationReport | operation, status, output, diagnostics, parameters | Whole-operation evidence |
OperationResult | shape, report | Value and evidence together |
OperationResult.value aliases shape so the same container can return scalars, mappings, or geometry. Use report.ok for control flow and report.to_dict() at a JSON boundary.
result = model.apply("box", 10.0, 20.0, 3.0)
payload = result.report.to_dict()
if result.report.ok:
body = result.value
Diagnostics are ordered. Preserve the complete tuple when reporting a failure; a warning may explain why a later step produced degraded evidence even if no exception occurred.
Preview mesh buffer
Shape.preview_mesh_buffer() asks the native runtime for a compact binary buffer. parse_preview_mesh_buffer validates the header and exposes a PreviewMeshBuffer with counts, bounds, and zero-copy memory views for positions, normals, and indices.
from cadflow.preview import parse_preview_mesh_buffer, preview_mesh_buffer_to_glb
raw = body.preview_mesh_buffer(deflection=0.25)
mesh = parse_preview_mesh_buffer(raw)
assert len(mesh.indices) > 0
glb = preview_mesh_buffer_to_glb(raw)
The parser rejects truncated buffers, invalid magic/version values, unsupported index formats, and inconsistent lengths. Keep the original data bytes alive while consuming its memory views.
GLB conversion
preview_mesh_buffer_to_glb packages the validated arrays as a single binary glTF artifact. It performs format conversion only; it does not change the underlying tessellation quality. Select deflection when generating the native buffer.
Preview output is intended for browser display and review. It is not an exact geometry interchange format. Use Shape.export_step() for exact exchange and validate triangle counts and bounds before presenting generated previews.