Inspect Model
Use forgecad inspect ... when a shaded render is too ambiguous and you need structured evidence: a bundle directory with evidence PNGs plus a root manifest.json (or, for inspect section, a probe directory with result.json, section.svg, section.png). Inspection is not a substitute artifact: look inside with sections, masks, --focus/--hide, and transparency — never edit the model into a cutaway or exploded default to make inspecting easier. Output dirs: let inspect allocate its timestamped directory by default (repeated probes never collide); use /tmp/<model>-inspect for throwaway bundles, a project directory only for persistent artifacts.
Routing: authoring/API questions → forgecad skill; creating a new model → forgecad-build-model.
Workflow
-
Identify the failure question. What would make the model wrong: overlap, thin walls, hidden cavity failure, disconnected or accidentally fused bodies, floating parts, orientation artifacts, identity confusion?
-
Confirm the model executes. If in doubt, run
forgecad run model.forge.jsfirst; add--debug-importsfor suspect imports. -
Pick ONE targeted evidence command from the table below.
forgecad inspect evidencelists everything available. -
Summarize the manifest first, then use
jqagainstmanifest.jsonfor targeted follow-up. The helper ships beside this SKILL.md — invoke it skill-dir-relative; it accepts the bundle directory or amanifest.jsonpath:bashpython <this-skill-dir>/summarize_manifest.py /tmp/model-inspect -
Inspect the PNGs, not only the JSON. View identity/context images first, then the risk evidence's view, then orthogonal cameras (
front,right,top) when iso hides the issue, sections only when internals matter. In automation, resolve file paths through the manifest — custom cameras break canonical filenames. -
Isolate intentional overlaps with
--focus "A,B"or--hide "C"so the remaining report stays meaningful. -
Treat findings as model bugs: unexpected collisions, critical thin regions, high unresolved thickness area, wrong component counts, floating bodies, or surprising gaps mean fix the model and reinspect.
-
Report honestly. Include the exact command, bundle path, manifest highlights, and the PNG views actually inspected. Never claim geometry is verified if you only ran
forgecad run.
Evidence Selection
| Question | Evidence command |
|---|---|
| Quick visual sanity | inspect visual image |
| Kinematic rig, joints, axes, and links | inspect visual rig |
| Object naming and identity | inspect visual objects |
| Exact local section measurement, bore widths, rib thickness through a chosen line | inspect section --ray ... |
| Hidden internals, cavities, pockets, screw paths, captured components | inspect sections at|stack|sample |
| Multi-part interference, fit checks, ghost parts, moving clearances | inspect fit interference |
| Printability, shell walls, ribs, bosses, snaps, slots | inspect manufacture thickness plus inspect sections at|stack|sample when internals matter |
| Parts without a mesh-contact path to the ground | inspect physical floating |
| Accidental fusion, connected solids | inspect physical components |
| Air gaps between physical components | inspect physical gaps |
| Surface orientation, occlusion, faceting, strange protrusions | inspect visual depth or inspect visual normals |
| Loft, fillet, skin, and sweep surface continuity | inspect surface zebra or inspect visual normals |
| Reference-vs-candidate reconstruction comparison | inspect compare overlay --with reference.3mf |
Section Probe + Replay
The agent-native measure-then-recheck loop:
bashforgecad inspect section model.forge.js --plane yz --ray bore:-20,0:20,0 forgecad inspect replay outputs/inspect/<probe>/result.json --source candidate.forge.js
The probe's result.json field contract (frames, rulers, gaps, replaySpec) is documented in the forgecad skill's docs/guides/inspection-bundles.md.
Misread Traps
- Face-touching is not a collision; collision findings are positive-volume overlaps.
- Gray/unresolved thickness area means the evidence is incomplete, not that the model is safe.
- Distance/gap figures are bbox-gap metrics between components, not closest-surface distances.
- Depth, normals, and zebra are visual aids (heatmap, camera-view normals, stripe shader), not exact measurements or curvature proofs.
- Resolve mask colors through the manifest's object list, never by object order.
Reference
Bundle/manifest contract, evidence semantics, and current limits: the forgecad skill's docs/guides/inspection-bundles.md. CLI flags and command tree: its docs/CLI.md.
