forgecad-inspect-model

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

1. 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?

2. Confirm the model executes. If in doubt, run forgecad run model.forge.js first; add --debug-imports for suspect imports.

3. Pick ONE targeted evidence command from the table below. forgecad inspect evidence lists everything available.

4. Summarize the manifest first, then use jq against manifest.json for targeted follow-up. The helper ships beside this SKILL.md — invoke it skill-dir-relative; it accepts the bundle directory or a manifest.json path:

   python <this-skill-dir>/summarize_manifest.py /tmp/model-inspect
   

5. 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.

6. Isolate intentional overlaps with --focus "A,B" or --hide "C" so the remaining report stays meaningful.

7. 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.

8. 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:

forgecad 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.