Files
make-cad/docs/updates/2.1.1.md
T
NiJingzhe 197bf40c6b chore(release): bump version to 2.1.1
Tooling patch: SDK API unchanged. Adds the CadQuery→FTC translator toolset
with snapshot constraint recovery (merged in #49) and its bilingual update
notes; version stamps updated in pyproject+lock, SKILL frontmatter, and
both READMEs.
2026-09-09 22:12:13 +08:00

80 lines
3.7 KiB
Markdown

# SimpleCADAPI 2.1.1 Update Notes
[Chinese](2.1.1.zh-CN.md)
> **Release notice:** Validate generated definitions, assembly constraints,
> and manufacturing geometry before production use.
2.1.1 is a tooling patch: the SDK public API is unchanged. It adds the
CadQuery→FTC translation toolset under `tools/research/cadqueryftc`
together with a constraint-recovery engine that turns planar geometry
snapshots into fully-riveted sketch constraint sets.
## CadQuery → FTC translator toolset
Four-stage research tooling aligned with `tools/research/histjson`
(trace / translate / validate / profile). The responsibility wall is the
same: the translator only translates; correctness questions live in the
external validator.
- **Runtime tracer** (`cadquery_trace.py`): runs programs under a real
cadquery 2.8 interpreter (a separate Python 3.11 venv; the repo pin is
untouched), monkey-patching `cq.Workplane` to record resolved plane
frames, serialized arguments, selector strings, and geometric
fingerprints of actually-selected faces/edges — no CadQuery topology
indices, geometry only. Ground-truth volume and bounding box are
captured per program; the trace JSON is the only handoff between the
two environments.
- **FTC translator** (`cadquery_to_ftc.py`): a single-pass replayer
emits current-convention FTC source — closed-vocabulary role block
headers, sketch-API planar profiles annotated `profile=geometry`
(transcribed geometry, exact local coordinates, pooled points,
circumcenter arcs), list-form booleans over a bodies dataflow, QL
predicate selections synthesized from fingerprints with
`.take(n).exactly(n)` cardinality, bounding-box-derived through-cut
depths, and keyword-only call emission so the training corpus carries
parameter meaning in the source itself. Zero in-source verification.
- **External validator** (`cadquery_validate.py`): executes generated
sources and reconciles volume/bbox against the tracer ground truth
(accepted / partial / rejected).
## Snapshot constraint recovery
`--constraints on` additionally recovers inferred constraint sets from
per-block geometry snapshots (`*.sketches.json` — a source-agnostic
interface any planar-loop producer can emit):
- candidates are only snapshot-entailed relations;
- admission is the production SolveSpace solver's DOF drop, with
redundancy-introducing candidates rejected — the DOF counter alone is
fooled by rank-deficient systems;
- a perturbation basin test (jittered rebuild must converge back onto
the snapshot) is the final fidelity gate;
- measured values emit verbatim; ids carry an `inf` prefix marking them
as inferred, never as dataset-native constraints.
Sketch capture has a single choke point (`SketchScript.render` fires the
sink), so every construction site — plain profiles, loft/taper sections,
countersink cones, sweep paths, pattern seeds — is captured by
construction.
## Verification
- Real traces captured with cadquery 2.8.0 ship as fixtures; 26 tests
run in CI **without** cadquery and pin format contracts, volume
reconciliation, keyword-only emission, and capture completeness.
- Reconciliation: washer 1.6e-16, rarray 0.0, revolve 1.8e-16, hexnut
2.2e-12 relative volume error (including a `edges(">Y").chamfer` QL
selection); the tapered 16-pin pulley has 5/5 sketches
constraint-riveted.
## Limitations
- Taper extrusion is exact for circular profiles only (conical frustum
via two-section loft); open wires cannot sweep; pattern sketches
support rect/circle/closed wires.
- 60+ point freeform outlines degrade honestly to `timeout` under the
recovery budgets; geometry translation is unaffected.
- Hand-expanded arrays in source programs translate as-is (feature-level
pattern folding is a recognized future capability).