c454a3af10
* feat(skill): replace skill-pack with per-harness conditional compiler
skillbuild compiles the skill tree into per-target harness builds:
- <!-- skill:if omp,!claude --> blocks include text only for matching
targets; name-list conditions only, no else/nesting, fail-loud on
unknown targets and unpaired/nested directives
- fence-aware: directive-looking lines inside code fences are literal
- layout is the filesystem; tree root configured in skillproj.toml
- post-build assertion: zero directive residue, SKILL.md frontmatter
name check
Migration to the new model:
- docs/skill/ becomes the self-contained source root (SKILL.md,
references/, generated api/stdlib/core/guides now under
references/docs/; SDK_OVERVIEW/LICENSE/inspect are ordinary tree
files)
- auto_docs_gen output redirected into the tree (docs/api ->
docs/skill/references/docs/api, likewise stdlib)
- skills/simplecadapi/ is now the compiled omp target output;
dist/generic/simplecadapi the generic target
- dropped skill-pack entry point (plus dangling evolve/make-export
entries and their orphaned test), release workflow builds via
skillbuild + tar; README updated
First real conditional block: harness reading paths in SKILL.md
(skill:// mount on omp vs disk-relative on generic).
Verified: 59 tests pass (skillbuild 31, auto_docs_gen 19, persistence
regression 9); both targets build; outputs residue-clean; full suite
collects (1376 tests).
* refactor(tools): auto_docs_gen moves out of the installed package
tools/ scripts are repo-checkout dev scripts, not packaged CLIs:
- auto_docs_gen.py now lives in tools/ beside the other generators;
auto_tools/ package removed entirely
- path resolution simplifies: repo root = parent of tools/, fail-loud
if pyproject.toml missing; site-packages/cwd fallback branches were
dead code once the script stopped shipping in the wheel
- auto-docs-gen console script dropped from [project.scripts];
release.yml and README invoke python tools/auto_docs_gen.py
- MANIFEST.in stale src/auto_tools include removed; CadQuery-free
runtime scan no longer needs the auto_tools filter
- run_examples.py retired (user removal): README example-runner text
updated to direct examples/ scripts; dangling runner-contract test
(runpy.run_path into the deleted script) removed
Verified: 53 tests pass (auto_docs_gen + skill_build + ocp runtime
scan) and test_example_model_contract passes; regeneration from
tools/ is byte-identical (zero docs drift).
* refactor(skill): strip harness and build-tool content from the skill tree
The skill is plain harness-neutral content again:
- SKILL.md 'Reading skill files' section removed (the omp skill://
mount block and its !omp complement were the only conditional
blocks; the tree compiles identically for every target now)
- references/README.md: build-tool meta removed ('per-harness
conditional compilation', skillbuild packaging/validation claims —
link validation was never implemented, so the claim was false)
- live test now asserts the tree stays harness-neutral (zero blocks)
- skillproj.toml targets aligned with the user's output table
(omp -> skills/simplecadapi-omp, opencode -> skills/simplecadapi-opencode;
leftover 'generic' entry had no output and failed the build)
- compiled outputs are regenerable artifacts: skills/simplecadapi/
untracked from git, skills/simplecadapi-*/ gitignored, release.yml
and README build via skillbuild and tar the omp output directly
(bsdtar has no --transform; inner dir keeps its suffixed name)
Verified: 49 tests pass; both targets build 372 files with zero
conditional blocks; no omp/conditional/directive residue in the tree
or outputs.
* chore(docs): drop stale architecture review and design notes
107 lines
5.4 KiB
Markdown
107 lines
5.4 KiB
Markdown
# SimpleCADAPI 2.0.2 Update Notes
|
|
|
|
[Chinese](2.0.2.zh-CN.md)
|
|
|
|
> **Experimental release notice:** The capabilities described below are still
|
|
> experimental. Breaking changes may be introduced in later releases, so this
|
|
> version is not recommended for immediate production use.
|
|
|
|
SimpleCADAPI 2.0.2 expands the project from an OCP-native geometry API into an
|
|
end-to-end, inspectable CAD workflow. The release covers model creation,
|
|
parameter and tolerance reasoning, replayable persistence, cross-CAD
|
|
translation, browser inspection, assembly verification, and STEP reverse
|
|
engineering.
|
|
|
|
## 1. Cross-CAD Translation
|
|
|
|
Canonical model JSON can be translated into automation scripts for FreeCAD,
|
|
Fusion 360, and SolidWorks. The FreeCAD backend can also write an editable
|
|
`.FCStd` document when FreeCAD/FreeCADCmd is available, preserving sketches,
|
|
features, parts, assemblies, links, and source selections where supported.
|
|
Fusion 360 exports target its Python automation environment. The SolidWorks
|
|
backend emits automation scripts and can drive a STEP export via COM. A single
|
|
parameterized SimpleCAD model can therefore serve multiple downstream CAD
|
|
systems without maintaining separate scripts.
|
|
|
|
## 2. Browser 3-D Viewer
|
|
|
|
The `viewer/` application opens generated `.scene.zip` packages without
|
|
importing Python or OpenCascade. It renders GLB geometry and CAD edges, provides
|
|
orbit/pan/zoom inspection, exposes an assembly/component tree with per-
|
|
occurrence visibility controls, and lets users select faces, edges, and vertices
|
|
to inspect measured properties and semantic/topological identity.
|
|
|
|
The Features view displays the replayable operation tree, parameters, output
|
|
counts, tags, and embedded source code, including the originating call and
|
|
highlighted source range. Scene packages also validate resource sizes and
|
|
SHA-256 metadata before loading referenced assets.
|
|
|
|
## 3. Structured Persistence, Replay, and Source Mapping
|
|
|
|
Modeling work recorded through `@model` or `GraphSession` can be exported as
|
|
canonical model/session JSON and replayed deterministically with
|
|
`import_model_json(...)` and `replay_model_json(...)`. A scene export can
|
|
package `scene.json`, `model/model.json`, embedded project-relative Python
|
|
sources, and GLB/entity assets into one portable artifact.
|
|
|
|
Every recorded operation captures best-effort source provenance. A feature-tree
|
|
node can be traced to the Python file, function call, assignment target, and
|
|
line range that produced it. This provides a foundation for automation,
|
|
collaboration, regression testing, and versioned model review.
|
|
|
|
## 4. Physical Units and Tolerance Analysis
|
|
|
|
Unit-aware variables preserve declared units in the model graph while converting
|
|
CAD operations to canonical millimeters and degrees. Expressions infer
|
|
dimensions across arithmetic and supported trigonometric operations, reject
|
|
incompatible combinations, and retain their parameter graph for replay.
|
|
|
|
Manufacturing tolerances can be propagated through dimension chains, analyzed
|
|
with nominal and bound results, and checked against explicit requirements. The
|
|
result supports unit conversion, dimensional chains, and assembly tolerance
|
|
studies without reducing the model to unexplained bare numbers.
|
|
|
|
## 5. Standard Mechanical Parts and Gear Performance
|
|
|
|
The standard library includes parameterized bolts and nuts, ball-bearing
|
|
assemblies, roller-chain sprockets, spur/helical/herringbone gears, internal
|
|
ring gears, racks, cycloidal discs, and bevel gears. These factories return
|
|
ordinary SimpleCAD shapes or assemblies, so results can be transformed,
|
|
tagged, combined, serialized, translated, and exported like custom geometry.
|
|
|
|
Gear construction and standard-library graph tracking were also optimized;
|
|
representative gear workloads are reported to complete in about one-third of
|
|
their previous time.
|
|
|
|
## 6. Assemblies, Meshes, and Collision Verification
|
|
|
|
Parts, components, connectors, placements, and assemblies can be persisted as a
|
|
structured product tree with fixed, revolute, prismatic, gear, belt, and
|
|
rack-and-pinion constraints. Constraint solving and residual inspection make
|
|
assembly relationships measurable. Render meshes and edge meshes are generated
|
|
for scene assets and downstream inspection.
|
|
|
|
The optional `simplecadapi[collision]` extra adds static, current-pose mesh
|
|
penetration checks through `python-fcl`, with configurable component scopes,
|
|
penetration tolerances, contact reporting, and non-fatal backend warnings. This
|
|
first verifier checks mesh contact penetration; it does not yet solve motion or
|
|
detect every complete-containment case.
|
|
|
|
## 7. STEP Inspection and Reverse Engineering
|
|
|
|
The `simplecad-brep` CLI and `simplecadapi.inverse_engineer.brep` API inspect
|
|
STEP BREP files and report volumes, surface areas, bounds, topology counts, and
|
|
geometric primitive labels. Bidirectional comparisons can apply a hard gate
|
|
based on geometric point-set equality and a geometry-labelled face-edge-vertex
|
|
incidence graph, rather than relying only on a volume delta.
|
|
|
|
The toolkit also renders consistent STEP views and compares sampled physical
|
|
slices with XOR overlays. These diagnostics help verify whether a reconstructed
|
|
part agrees with the original in both geometry and topology.
|
|
|
|
## Related Documentation
|
|
|
|
- [STEP BREP reverse-engineering guide](../skill/references/inspect/brep-reverse-engineering.md)
|
|
- [Browser viewer README](../../viewer/README.md)
|
|
- [Core serialization and replay documentation](../skill/references/docs/core/serialization/README.md)
|