Commit Graph

50 Commits

Author SHA1 Message Date
NiJingzhe aac0fbb29d feat(cache): script-anchored part cache, keyword-form corpus, 2.1.2
- @scad.part/@scad.assemble anchor defaults to the builder script's own
  directory: cache + interface state land beside the source, standalone
  scripts run anywhere, and the pyproject.toml walk-up requirement is
  gone (explicit project_root still relocates the anchor)
- file_input() paths resolve relative to the anchor; in-repo examples
  rewritten to script-relative declarations
- HistCAD translator emits keyword-form sketch-family calls (corpus
  self-documentation), pinned by tests; booleans stay positional by
  *solids signature
- both translators emit project_root=Path(__file__).parent explicitly;
  examples/histcad_demo regenerated (STEP volume reconciliation held)
- FTC convention documents @scad.part parameters and the cache contract
- version stamps 2.1.2 + bilingual update notes
2026-09-10 00:11:28 +08:00
NiJingzhe f2ceed75a3 chore(examples): track bowl_connector target STEP (reverse-eng example input) 2026-09-07 05:47:34 +08:00
NiJingzhe 237702c7a8 feat(examples): unnumbered self-contained layout with per-example out/
- rename every numbered example (04/08/10/11/7ep scripts, 12/16/20/21 dirs)
  to clean names; each example now writes artifacts to its own out/ folder
- examples/README rewritten as a category index (part / assembly / reverse
  engineering / FEM); stale run_examples.py reference removed
- flange_plate gains the quickstart FTC part (model.py + external verify.py
  + README); u_link/ap242/flange demo builders read the new asset paths
- ap242_gmsh_volume_mesh gains render_views.py for the demo gallery

fix(artifacts): round-trip-stable geometry fingerprint bounds

AddOptimal bounds wobble by one shape-tolerance quantum between a fresh
shape and the same shape read back from BRep bytes, so definitions sitting
on a quantization cell edge failed every package re-validation. Quantize
bounds at a fixed 1e-4 mm grid, far coarser than the wobble; full suite
green (1503 passed). Stored packages captured before this change must be
recaptured.
2026-09-07 05:46:15 +08:00
NiJingzhe bdee2e16c4 feat(render): opt-in studio style, tubed BRep edges, tessellation and camera-roll controls
Reviewed keep of the BLDC-GIF render pipeline changes (all opt-in; the
default inspection path is byte-identical, verified by A/B render):

- render_screenshot_rpath: + linear_deflection / angular_deflection
  (tighten tessellation for high-res diagnosis), style='studio'
  (product-shot look: black stage, camera-derived three-point lighting,
  metal specular), edge_width_scale (tubed-edge radius as span fraction,
  validated [0, 0.02]), view_up (explicit camera roll for inclined
  orbits)
- BRep edges as vtkTubeFilter geometry in studio style: LineWidth is
  capped ~3px on macOS, so edges must be geometry to stay readable at
  high resolution / for small features
- contracts: unknown style, studio+views grid and out-of-range
  edge_width_scale are rejected with guidance errors
- tests: three rejection contracts + studio/standard divergence smoke
  (size-threshold assertion replaced with a behavioral one: outputs must
  differ); 11/11 pass
- API doc regenerated via tools/auto_docs_gen.py (also picked up the
  view_up parameter the hand edit had missed)
- examples/20 render_showcase.py: four-module axial explode (ESC /
  motor / two-stage reducer / output shaft) with concentric radius-band
  peeling, inclined camera orbit, exploded turntable GIF export
2026-09-06 02:01:27 +08:00
NiJingzhe f53dec2f70 showcase: viewer BRep renders + before/after re-parameterization slots
- flange/bracket demo images re-rendered through the in-repo Scene Viewer
  (BRep face shading + edges, camera normalized to the scene bounding
  sphere) via headless Chrome capture; raw-solid VTK renders replaced
- flange demo: caption bug fixed ('六特征块' read as six holes vs the
  8-hole final model); renders tab now leads with the 6-hole @PCD 78
  initial state next to the final 8-hole @PCD 84.5, making the turn-2
  re-parameterization visible; glCap states the final state explicitly
- bracket demo: three viewer views (iso/top/detail)
- README cards: flange/bracket images swapped to viewer renders; captions
  clarified to '6→8-bolt'
2026-09-05 21:26:53 +08:00
NiJingzhe f65109c6e7 docs(showcase): four-capability README front section with session replay demos
- README.md / README.zh-CN.md: capability pillars (single part / assembly /
  reverse engineering / simulation) with case images and replay demo links
- examples/demo_kit: config-driven single-file replay demo builder
  (generalized from u_link demo; app.js consumes per-case config payload)
- examples/flange_plate: full single-part-modeling workflow case (agent
  session transcript + verifier scripts + 8-hole re-parameterization with
  guard rejection chain) + replay demo
- examples/12_ap242_gmsh_volume_mesh: model.py rebuilt through the workflow
  (FTC feature blocks, named vars; volume rel 0.00e+00 vs legacy, FEM
  interface tags preserved) + REQUIREMENTS/BUILD_PLAN/verify + replay demo
- examples/u_link_motor_mount/demo: committed single-file replay demo,
  rebuilt via demo_kit
- examples/20_integrated_bldc_joint_actuator/render_showcase.py: assembled
  + staged cylindrical exploded views from the captured package
- img/capability: showcase renders (BLDC assembly/exploded, bracket FEM
  von Mises, case ISO views)
2026-09-05 21:02:43 +08:00
NiJingzhe 48c77c2055 feat(histcad): pure training-data translation, tools under research/histjson
Generated sources carry the model only: the dual-path constraint fallback,
SKETCH_CONFLICTS/SKETCH_TIER_FALLBACKS audit globals and strict=False
inspection are gone from translated code. Tier decisions and conflict
auditing moved to translation time: auto mode solves each feature's
constrained sketch prefix in-process (preflight), emits sketch tier when it
solves AND reproduces the transcribed coordinates (max point move <= 1e-3,
the drift gate), otherwise transcribed geometry; diagnostics go to the
sidecar report (<case>.ftc.py.report.json).

Root causes found by the new histcad_conflicts.py residual analyzer and
fixed in the translator:
- point-pair H/V distances are directed: sign now taken from coordinates
  (the stored length is a magnitude) — was the top Fusion conflict source
- Tangent on arcs needs an endpoint selector: picked as the nearest shared
  junction with the other curve
- MajorRadius/MinorRadius store full axis lengths: halved to semi-axes
  (solver was stretching ellipses 2x)
- Horizontal/Vertical flat line lists map each line individually
- variadic Equal chains get per-pair constraint ids (duplicate-id crash)
- Coincident entries whose refs pooled onto the same point are elided:
  degenerate point-coincident equations made the solver Jacobian singular
  and showed exact-geometry sketches as conflicting

SDK: constrain_concentric_rsketch now accepts ellipse targets (backend
resolves the ellipse center point).

Validation (100-case samples, constraints=auto): Fusion360 72 pass,
sketch-tier retention 77.5% (conflicts: 19 diverged + 1 conflicting);
DeepCAD 83 pass, retention 85.0% (9 diverged, 0 solver-conflicting).
Demos regenerated, volumes reconcile to STEP. Purity pinned by
test/test_histcad_translation_output.py (9 tests). Full suite 1489 passed.
2026-09-04 14:28:49 +08:00
NiJingzhe c092b3d49e feat(research): constraint translation channel with per-conflict dataset auditing
The translator now emits native sketch constraints (auto mode): every
HistCAD entry maps to a constrain_* call tagged with its source identity
(constraint_id='h7_Distance'), variadic chains decompose with suffixed
ids, and value_exprs evaluate through a unit-aware expression parser
(mm/in/cm/m/ft/yd plus arithmetic and mixed-unit sums like
'61.5 in + 8ft').

Stability comes from an honest dual path per feature: entities bind to
s_geo, constraints derive s, promotion tries the constrained sketch and
falls back to the geometry prefix when the solver reports conflict. The
except branch re-inspects with strict=False and records WHICH constraint
entries failed into SKETCH_CONFLICTS — the pipeline doubles as a dataset
constraint-quality auditor (rounded coordinates vs over-determined
systems are the observed conflict source).

Sampled auto-mode results (volume still machine-exact on passes):
- DeepCAD 100: 83 pass, sketch-tier retention 92.1% (conflicts:
  Length 7, Distance 6, Diameter 2, Equal 1)
- Fusion360 100: 67 pass, retention 66.2% (Distance dominates with 49 —
  its halfSpace signed-offset dialect needs side semantics work)
Demo regenerated with 28 constraint calls, volume unchanged at 349.4558.
2026-09-04 13:09:32 +08:00
NiJingzhe 957b1c0cf4 feat(research): render demo models and rename arcs demo 2026-09-04 05:56:15 +08:00
NiJingzhe 6ffa52ceed feat(research): histcad FTC demo cases and validation reports
Three translated demo sources (Fusion360 arcs+ellipse 166-line feature
tree, degree-5 NURBS profile, DeepCAD 480-line multi-feature chain), all
reconciled against the packaged STEP ground truth at 1.6e-16 / 8.2e-5 /
2.8e-13 relative volume error.
2026-09-04 05:55:26 +08:00
NiJingzhe 77ad2c9440 chore(verifier): drop collision verifier module superseded by external implementation
Removes src/simplecadapi/verifier (current-pose mesh penetration checks
via python-fcl), its test, and the planetary-reducer collision probe
example. Collision verification now lives in an external implementation
outside this SDK.

The python-fcl>=0.7.0.11 dependency is dropped with it: the verifier
module was its only consumer.

BREAKING CHANGE: scad.verifier and check_collision_rcollisionreport are
no longer exported. Workflow docs mentioning 'verifier' refer to the
Verifier Planner role, not this module, and are unchanged.

Full suite: 1425 passed, 5 skipped.
2026-09-04 02:19:29 +08:00
NiJingzhe a5e6bf8eb6 feat(core)!: QL-only topology enumeration — remove bare getter list form
Plural topology getters (get_edges/get_faces/get_wires/get_vertices/
get_solids/get_inner_wires/get_edge_occurrences and the Compound
variants) now accept ONLY an index. The no-argument list form raises a
SimpleCADError with migration guidance (enumerate via
ql.<kind>().resolve(shape), pick via get_X(index)). This closes the
selection channel that escapes the graph: Python loops over bare lists
lose the predicate, capture kernel artifacts (the periodic-face seam
edges that broke FCStd translation), and leave no cardinality contract.

- each shape class keeps its enumeration logic as private _iter_<kind>();
  indexed picks record geo-select nodes as before (contract test added);
  Compound getters gain the same indexed recording they lacked
- _TopologySelectionList (the __getitem__ recording vehicle, which also
  made get_X()[i] a silent escape hatch) is retired
- all 109 internal call sites, 165 test call sites, and 31 example call
  sites migrated: SDK/tests use the private channel, user-facing
  examples use ql.<kind>().resolve(...)
- QL _resolve_scope_items switches to the private channel; scene
  contract profile descriptions synced; error strings recommending
  bracket indexing rewritten
- skill docs: strict prohibition added to SKILL.md global rules (new
  rule 6), core README contract statement rewritten, solid/wire/face/
  shell/tagged_mixin pages re-exemplified with QL, geometric-validation
  anti-pattern section updated; mirrors rebuilt via tools/skillbuild.py

Gates: full suite 1418 passed / 5 skipped; translator suites 133 passed;
u_link stage verifiers + render check ALL PASS; scadpkg->FCStd
retranslation verified (5 visible deliverables, 167-object editable
tree).
2026-09-01 02:09:29 +08:00
NiJingzhe 9feb23a530 fix(example): kernel-independent edge selections via QL
Replace Python-predicate edge lists with serializable QL selectors for
both detail features, and restrict the global fillet to CIRCLE edges.

The fillet's y+length window captured 4 periodic-face seam artifacts
(pocket-wall r=12 seams at z=+12 x2, outer cylinder r=15 seam at
z=-15 x2) alongside the 12 design circles. Seam placement is kernel
implementation freedom — OCP puts them on the generators, FreeCAD's
OCC does not, which orphaned those selectors in FCStd translation
(best score ~52, no counterpart exists). Measured: seam-edge fillets
contribute exactly 0 volume (16-edge vs 12-circle fillet differ by
0.000000), so exclusion is exact, and the selection set becomes
kernel-independent.

The gusset-hypotenuse selector carries its count contract as
.exactly(16), replacing the in-script assert.

All stage verifiers pass (s1-s5, s5_render, s10, s12); the package now
translates to an editable 167-object FCStd whose final solids match
SCA to 4-5 significant digits (body 14418.27 vs 14418.29, shell
7933.93 vs 7933.86).
2026-08-31 23:18:31 +08:00
NiJingzhe 0140ec16c2 chore(example): archive dead-contract verify scripts (s9/s10 hypothesis, s9 verify)
s9_verify.py imported cover.py, a model the S10 user-directed pivot
explicitly retired ('弃方形腔 → 75% 剖分两件 + 轮廓贴合 shell'); cover.py
was never committed, so the import fails by design and predates the
feat/ftc path migration. s9_hypothesis.py asserts the abandoned S9
geometry contract; s10_hypothesis.py references the removed transcribed
path helper _u_path_edges.

Moved to verify/archive/ with deprecation headers and a README stating
why each file is dead and what the live verifier set is
(s1-s5, s5_render_check, s10, s12 — re-run ALL PASS after the move).
2026-08-31 21:13:56 +08:00
NiJingzhe 4abe3462a5 refactor(example): migrate u_link sweep path to constrained sketch
Replace the transcribed _u_path_edges (hand-computed 45-degree arc
midpoints) with _u_path_wire: a 5-entity open chain sketch whose four
endpoint-tangent constraints own the tangent continuity, promoted via
make_wire_from_sketch_rwire with require_fully_constrained=True (dof=0).

Both consumers (build_u_rod, _eroded_sweep) now sweep along the
sketch-promoted path; solved coordinates are bit-identical to the old
transcription, so all stage verifiers pass unchanged:

- s1/s2/s3/s4/s5/s5_render/s10/s12 verify: ALL PASS
- s9_verify fails on 'import cover' — cover.py was never committed and
  the failure predates this change (reproduced on the unmodified tree)

Note: verify/s10_hypothesis.py still references the removed
_u_path_edges; it is an archived S10 hypothesis script, not a verifier
contract, and was left untouched.
2026-08-31 21:00:07 +08:00
NiJingzhe 3e205983a5 docs(skill): opencode question payload workflow; add u_link_motor_mount example
Teach the single-part modeling workflow how to design the Role 1 question
payload for opencode's native question tool (header-keyed ledger rows,
recommended-first ordering, free-text passthrough). Include the
u_link_motor_mount worked example: requirements/build plan, part and
assembly scripts, export pipeline, and the staged verify/probe scripts.
The DXF drawing scripts land separately with the dxf_engine branch.
2026-08-31 12:46:59 +08:00
NiJingzhe 152bbf3432 refactor!: reorganize package root into themed subpackages
- operators/: _support + geometry/features/boolean/transform/selection/sketch/product
- product/: semantic value model, solver, occurrence, packages, capture
- topology/: model, tagging, tracking, autotag (package re-exports model symbols)
- params/: units, expr, tolerance, frame
- recording/: graph, serializer, source_mapping
- _internal/: canonical_json, vendor_warning_filters, semantic, mesh, brep_region

Root shrinks from 46 to 7 modules. Drop the legacy geometry/boolean/transform/
selection monolith copies and the operations.py facade; unified operator
exports now live in operators/__init__ with monkeypatch mirroring preserved.
Remove the legacy evolve generators and their example/tests/docs. Import paths
for simplecadapi.topology keep working via package re-export; update all
in-repo consumers, tests, tools/auto_docs_gen source tables, and regenerate
the skill API reference docs.
2026-08-31 12:46:57 +08:00
NiJingzhe dc143f3f9c fix(persistence): evaluate Var/Expr primitive geometry before serialization
Expression objects leaked into primitive geo metadata (make_cylinder/cone/
sphere) and were rejected by .scadpkg serialization. Write evaluated values
at the source (_operators_geometry) and project Var/Expr to float in
topology snapshots; add parametrized regression for var-driven primitive
positions.

Found during session 01a02469 (arc handle build) as two independent
serialization failures.
2026-08-22 16:57:20 +08:00
NiJingzhe f471216ec0 feat(example): model the four-bar links as forged bars with pivot bolts
Replace the plain box bars with realistic forged connecting rods: two
chamfered circular bearing eyes joined by an I-beam web (wide top and
bottom flanges over a thin mid web), a bearing bore through each eye,
and lightening holes in the coupler web. Add a hex-head pivot bolt
part (hex prism head, washer shoulder, plain shank pinning the bar
stack) instanced once per joint and fixed to one adjacent bar so it
shares that bar's rigid group without adding kinematic DOFs. Split
geometry into per-part modules per the SDK coding standard (link_bar,
pivot_bolt, assembly) and assign steel materials so MJCF export gets
densities without a fallback. Verified end to end: 8 components and 8
constraints solve with zero residuals, the MJCF keeps the loop closure
at 5e-16 over 500 MuJoCo steps with all eight geoms present, and the
STL/STEP outputs show eye-and-web link silhouettes instead of boxes.
2026-08-21 14:22:46 +08:00
NiJingzhe 00cef32b94 feat(mjcf): emit equality/connect constraints for loop-closing joints
A movable joint whose two groups are already connected through the
spanning tree (a kinematic loop such as a four-bar linkage) previously
landed in redundant_movable_joints and was silently dropped, exporting
an open-chain model whose末端 swung freely. Loop closure is a nonlinear
pose constraint that neither a tree hinge (MJCF bodies form a strict
hierarchy) nor the linear fixed-tendon equalities can express, but
MuJoCo solves it natively as an equality/connect.

Emit one closure site per endpoint group at the connector frame and one
equality/connect joining them; record closures in the mapping, add
closure_count to the report, and empty redundant_movable_joints (every
non-tree movable edge is now either a coupling equality or a closure).
Add example 21 (planar Grashof four-bar with a closed-form assembled
pose, all drives None so the authored closure is the solve reference)
with build/export scripts, update the shared-connector test to the new
closure contract, and lock the loop topology with a dedicated test.
MuJoCo verification: the exported model loads, holds the closure gap at
1e-16 over 500 steps, and behaves as a 1-DOF mechanism.
2026-08-21 13:57:06 +08:00
NiJingzhe 02b6f0601e feat(example): split BLDC exports into parallel scripts and fix FCStd multi-wire sweep
- capture() accepts include_scene=False; the BLDC build skips the
  tessellated Scene projection (STEP/MJCF/FCStd read meshes and feature
  graphs from the definition closure), shrinking the package from 230MB
  to 75MB and capture from ~460s to ~39s.
- main.py is now build + capture only with per-stage timing; the replay
  verification and preview compound stages are dropped.
- export_mjcf.py / export_step.py / export_fcstd.py each translate the
  captured .scadpkg independently; export_all.py runs them concurrently
  (MJCF 84s, STEP 51s, FCStd 569s wall on BLDC).
- FreeCAD twisted-sweep emulation rejected multi-loop profile faces
  ('requires a face with one outer wire'), so the new ring-gear sweep
  path failed FCStd export. Loft each wire of the face separately and
  cut the inner plugs from the outer loft, matching the kernel's
  sewn-shell semantics for annular and multi-hole profiles.
2026-08-21 13:05:24 +08:00
NiJingzhe d946403479 refactor(example): build BLDC actuator bearings from stdlib durable builder
Replace the hand-rolled _build_bearing_definition wrapper (extract ring
parts, re-declare ground/revolute/public connectors) with
scad.std.bearing.build_ball_bearing for all five bearing sizes. The
actuator now consumes the standard bearing sub-assembly directly as a
definition while keeping the reducer-level dual fixed topology
(outer-to-seat, inner-to-carrier-pin, 22 bearing interfaces).
2026-08-21 10:28:35 +08:00
NiJingzhe bc0a967c85 feat: propagate public connectors to exporters 2026-08-20 14:52:47 +08:00
NiJingzhe e6896d7baf fix: preserve nested assembly state 2026-08-19 14:02:58 +08:00
NiJingzhe ba1e06a489 feat: expand product exporters and FEM workflow 2026-08-18 01:36:44 +08:00
NiJingzhe 9d6703a786 feat: enforce canonical product capture workflow 2026-08-15 16:17:11 +08:00
NiJingzhe fee5039cc6 feat: add canonical product package export 2026-08-11 23:16:20 +08:00
NiJingzhe 89564ee1f5 Add durable part and assembly caching 2026-08-11 17:06:00 +08:00
NiJingzhe 675afb9b85 feat: consolidate BREP inspection workflow 2026-08-04 23:45:23 +08:00
NiJingzhe a413b0fe48 Use fused standard bearings in BLDC example 2026-08-02 04:07:04 +08:00
NiJingzhe 5c451d9406 Ignore generated example artifacts 2026-07-23 03:19:22 +08:00
NiJingzhe bde6c50f16 Migrate examples to the model workflow 2026-07-23 03:17:35 +08:00
NiJingzhe f4472a4917 Remove superseded example applications 2026-07-23 03:17:12 +08:00
NiJingzhe af660294b1 Merge feat/dimension-chain into dev 2026-07-16 01:05:21 +08:00
NiJingzhe 88983fe70f Add physical units and tolerance chains 2026-07-15 21:48:06 +08:00
NiJingzhe 0369769684 Add semantic CAD workflows and advanced examples 2026-07-15 19:58:30 +08:00
NiJingzhe a6ce3d7ab5 Fix articulated actuator assembly exports 2026-07-10 23:00:57 +08:00
NiJingzhe dab03777ec Add mesh extraction and collision verification 2026-07-10 10:09:17 +08:00
NiJingzhe c2e0a37128 Add compact two-stage reducer example 2026-07-06 17:46:59 +08:00
NiJingzhe d54a1e25e4 Refactor FreeCAD translator namespace 2026-07-06 01:55:01 +08:00
NiJingzhe 7196a75a57 Add standard gear library and release 2.0.1 2026-06-29 14:32:56 +08:00
NiJingzhe 5cf3516407 Update hydraulic rod example with QL face connectors and prismatic limit
Replace pure-frame connector placement with QL-selected end faces,
auto-detect normal alignment for the flip parameter, ground the outer
sleeve, and add a prismatic constraint with drive_distance=0 and a
ScalarLimit of (0, 100) so the solver clamps the slide range.
2026-06-26 17:38:59 +08:00
NiJingzhe 61a15fa9dc Document product assembly workflows 2026-06-26 05:02:30 +08:00
NiJingzhe b79f5605c1 Add constrained sketch and NACA blade examples 2026-06-20 22:13:20 +08:00
NiJingzhe 4e046152ca Add constrained sketch API 2026-06-13 03:13:26 +08:00
fanfengxiao c12e918713 fix: rename solid boolean APIs to rsolid 2026-06-08 15:11:34 +08:00
NiJingzhe f185406516 Support indexed geo select nodes 2026-06-02 23:29:27 +08:00
NiJingzhe 7425f71d79 Refactor SDK contract and QL selection replay 2026-06-01 01:14:19 +08:00
NiJingzhe 3a53d7ee63 Add serialization operation tree docs and example 2026-05-11 19:56:27 +08:00
NiJingzhe 65beee4c81 Prepare 2.0.0b1 beta release 2026-05-09 23:17:08 +08:00