allaun/Research-Stack
1
0
Fork 0
mirror of https://github.com/allaunthefox/Research-Stack.git synced 2026-08-09 17:15:47 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
Research-Stack/5-Applications/text-to-cad/skills/cad/references/cadref.md

3.4 KiB
Raw Blame History

CAD Ref Tool

5-Applications/scripts/cadref resolves prompt-ready @cad[...] refs directly from STEP entries.

Run commands from the project or workspace directory that makes your target paths resolve.

Canonical Command

python <cad-skill>/scripts/cadref --help

Command Surface

python <cad-skill>/scripts/cadref inspect '<text containing @cad[...] refs>' --json

python <cad-skill>/scripts/cadref planes models/path/to/entry --json

python <cad-skill>/scripts/cadref diff models/path/to/before models/path/to/after --json

Whole-entry refs default to a cheap summary so large STEP files do not dump every selector list. Use --topology only when you explicitly need full selector lists:

python <cad-skill>/scripts/cadref inspect '@cad[models/path/to/entry]' --json

python <cad-skill>/scripts/cadref inspect '@cad[models/path/to/entry#f10]' --detail --facts --json

python <cad-skill>/scripts/cadref inspect --refs '@cad[models/path/to/assembly#o1.1.1.f10]' '@cad[models/path/to/assembly#o1.1.1.e20]' --detail --facts --json

python <cad-skill>/scripts/cadref planes '@cad[models/path/to/entry]' --json

python <cad-skill>/scripts/cadref diff models/path/to/before models/path/to/after --json

You can also read text from a file or stdin:

python <cad-skill>/scripts/cadref inspect --input-file /tmp/prompt.txt --json

cat /tmp/prompt.txt | python <cad-skill>/scripts/cadref inspect --json

Ref Rules

See references/prompt-refs.md for token shapes, selector semantics, stale-ref handling, and prompt interpretation workflow.

Output Contract

inspect --json returns:

  • per-token STEP context: cadPath, source STEP path, STEP hash, and occurrence-aware summary counts
  • per-selection resolution status (resolved or error)
  • cheap STEP-derived summary payload for whole-entry refs, including bounds, occurrence count, shape count, face count, edge count, and vertex count
  • full occurrence/shape/face/edge/vertex selector lists for whole-entry refs only when --topology is passed
  • selected occurrence/shape/face/edge/vertex geometry facts when --detail is passed, including bbox, center, surface or curve params, and adjacency selectors when available
  • compact entryFacts and per-selection geometryFacts when --facts is passed
  • top-level ok plus structured errors

planes --json returns:

  • cadPath, STEP path, and normal entry summary
  • grouped major planar-face bands under planes, keyed by dominant axis and plane coordinate
  • total area, face count, merged bbox, and contributing selectors for each group

Use this when you need to identify the main plates or walls of a part instead of guessing from screenshots.

diff --json returns:

  • left/right entry summaries plus compact entry facts
  • selector-level topologyChanged, geometryChanged, and bboxChanged flags
  • face/edge/shape count deltas
  • bbox center/size deltas

Use this for before/after checks when a change may have invalidated old prompt refs or moved important planes.

If a selector no longer resolves against the current STEP topology, inspect returns a structured error and exits non-zero.

Source Of Truth

  • 5-Applications/scripts/cadref resolves STEP refs from STEP files and generated selector artifacts.
  • Assembly refs resolve from generated assembly STEP files, not from reconstructed Python instance summaries.
  • It does not read package-local viewer runtime assets to interpret refs.