Merge branch 'release/2.1.0' into dev
This commit is contained in:
@@ -134,19 +134,22 @@ the full crank cycle sweeps clean in the same sim ·
|
||||
|
||||
---
|
||||
|
||||
## Update Notes (2.0.4b3 development)
|
||||
## Update Notes (2.1.0)
|
||||
|
||||
> **Beta release:** Validate generated definitions, assembly constraints, and
|
||||
> **Release notice:** Validate generated definitions, assembly constraints, and
|
||||
> manufacturing geometry before production use.
|
||||
|
||||
SimpleCADAPI 2.0.4b3 adds reproducible `@part`/`@assemble` product boundaries,
|
||||
incremental assembly solves, and a persistent crash-safe cache for whole parts.
|
||||
See the [full English update notes](docs/updates/2.0.4b3.md) for contracts,
|
||||
SimpleCADAPI 2.1.0 turns the SDK into an agent-first CAD toolkit: the Feature
|
||||
Tree Convention authoring discipline, external CAD-history import, the
|
||||
browser reverse-engineering studio, DXF engineering drawings, and
|
||||
self-contained runnable examples — on top of the reproducible
|
||||
`@part`/`@assemble` product boundaries and the persistent crash-safe cache.
|
||||
See the [full English update notes](docs/updates/2.1.0.md) for contracts,
|
||||
cache modes, diagnostics, limitations, and verification coverage.
|
||||
|
||||
All formal single-script examples emit a synchronized `.scadpkg`, AP242
|
||||
`.step`, and editable `.FCStd` from the same product package. The
|
||||
split AP242/Gmsh example under `examples/12_ap242_gmsh_volume_mesh/` exposes
|
||||
split AP242/Gmsh example under `examples/ap242_gmsh_volume_mesh/` exposes
|
||||
each build and export stage as a separate directly runnable script.
|
||||
|
||||
---
|
||||
@@ -167,7 +170,7 @@ in a compact public API for creating solids, applying features, tagging semantic
|
||||
intent, querying topology, exporting manufacturing files, and translating recorded
|
||||
models into FreeCAD workflows.
|
||||
|
||||
Current development beta: `simplecadapi==2.0.4b3`.
|
||||
Current release: `simplecadapi==2.1.0`.
|
||||
|
||||
## What It Provides
|
||||
|
||||
@@ -519,7 +522,7 @@ uv run python examples/20_integrated_bldc_joint_actuator/main.py
|
||||
|
||||
## Documentation
|
||||
|
||||
- 2.0.4b3 update notes: [`docs/updates/2.0.4b3.md`](docs/updates/2.0.4b3.md)
|
||||
- 2.1.0 update notes: [`docs/updates/2.1.0.md`](docs/updates/2.1.0.md)
|
||||
- Reconstruction Agent test specification:
|
||||
[`docs/guides/reconstruction-agent-test-prompt.md`](docs/guides/reconstruction-agent-test-prompt.md)
|
||||
- STEP BREP reverse-engineering guide:
|
||||
|
||||
+8
-6
@@ -120,13 +120,15 @@ CalculiX 静力 FEM(边界面按保真的 `interface.*` 标签选取,仿真
|
||||
|
||||
---
|
||||
|
||||
## 更新日志(2.0.4b3 开发中)
|
||||
## 更新日志(2.1.0)
|
||||
|
||||
> **Beta 版本:** 用于生产前,请验证生成的定义、装配约束和制造几何。
|
||||
|
||||
SimpleCADAPI 2.0.4b3 新增可复现的 `@part`/`@assemble` 产品边界、增量装配求解,
|
||||
以及整零件的持久化崩溃安全缓存。契约、cache mode、诊断、限制和验证范围见
|
||||
[完整中文更新说明](docs/updates/2.0.4b3.zh-CN.md)。
|
||||
SimpleCADAPI 2.1.0 把 SDK 推向 agent-first CAD 工具箱:Feature Tree Convention
|
||||
建模纪律、外部 CAD 历史导入、浏览器逆向工作台、DXF 工程图与自包含示例,全部
|
||||
建立在可复现的 `@part`/`@assemble` 产品边界与持久化崩溃安全缓存之上。契约、
|
||||
cache mode、诊断、限制和验证范围见
|
||||
[完整中文更新说明](docs/updates/2.1.0.zh-CN.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -143,7 +145,7 @@ SimpleCADAPI 2.0.4b3 新增可复现的 `@part`/`@assemble` 产品边界、增
|
||||
|
||||
SimpleCADAPI 是一个基于 OCP 的 Python CAD SDK,提供清晰的函数式建模操作和可重放的模型图。它在 OpenCascade 几何内核之上提供精简的公共 API,可用于创建实体、应用特征、添加语义标签、查询拓扑、导出制造文件,以及将记录的模型转换为 FreeCAD 工作流。
|
||||
|
||||
当前开发 Beta:`simplecadapi==2.0.4b3`。
|
||||
当前版本:`simplecadapi==2.1.0`。
|
||||
|
||||
## 核心能力
|
||||
|
||||
@@ -363,7 +365,7 @@ uv run --extra fem python examples/12_ap242_gmsh_volume_mesh/study_mesh_converge
|
||||
|
||||
## 文档
|
||||
|
||||
- 2.0.4b3 更新说明:[`docs/updates/2.0.4b3.zh-CN.md`](docs/updates/2.0.4b3.zh-CN.md)
|
||||
- 2.1.0 更新说明:[`docs/updates/2.1.0.zh-CN.md`](docs/updates/2.1.0.zh-CN.md)
|
||||
- Reconstruction Agent 测试规范:
|
||||
[`docs/guides/reconstruction-agent-test-prompt.md`](docs/guides/reconstruction-agent-test-prompt.md)
|
||||
- STEP BREP 逆向工程指南:
|
||||
|
||||
+2
-2
@@ -4,9 +4,9 @@ description: Build, assemble, inspect, reconstruct, and export parametric CAD mo
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
project: simplecadapi
|
||||
version: 2.0.4b3
|
||||
version: 2.1.0
|
||||
package-name: simplecadapi
|
||||
package-version: 2.0.4b3
|
||||
package-version: 2.1.0
|
||||
---
|
||||
|
||||
# SimpleCAD SDK Skill
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
# SimpleCADAPI 2.1.0 Update Notes
|
||||
|
||||
[Chinese](2.1.0.zh-CN.md)
|
||||
|
||||
> **Release notice:** Validate generated definitions, assembly constraints,
|
||||
> and manufacturing geometry before production use.
|
||||
|
||||
SimpleCADAPI 2.1.0 turns the SDK into an agent-first CAD toolkit: a
|
||||
Feature-Tree-Convention authoring discipline with compiler-verified skill
|
||||
guidance, an external CAD-history import path, a reverse-engineering studio
|
||||
in the browser, DXF engineering drawings, and self-contained runnable
|
||||
examples — on top of the reproducible product boundaries and crash-safe
|
||||
cache introduced during the 2.0.4 beta cycle.
|
||||
|
||||
## 1. Durable part and assembly definitions
|
||||
|
||||
`@scad.part` builds exactly one physical single-solid part and returns a
|
||||
`PartBuildResult`: runtime `Part`, `PartDefinition`, graph/session state,
|
||||
model and session JSON, interface differences, and a per-build `CacheReport`.
|
||||
Its content-derived key covers normalized arguments, builder source, declared
|
||||
file inputs, revision, tolerance profile, and generator/ABI profile.
|
||||
|
||||
`@scad.assemble` requires explicit external `PartDefinition` or nested
|
||||
`AssemblyDefinition` inputs. Repeated instances share immutable definitions;
|
||||
closed validation rejects missing, unused, cyclic, conflicting, or
|
||||
incompatible references. Definitions round-trip independently from
|
||||
process-local runtime objects. Connector interface hashing is stable across
|
||||
processes, so identical interfaces no longer produce spurious definition
|
||||
diffs.
|
||||
|
||||
## 2. Incremental assembly solve, cache, and diagnostics
|
||||
|
||||
Assembly state records component dependencies and public connector
|
||||
interfaces; changes propagate only along affected dependency paths, and every
|
||||
restored placement still passes constraint-residual verification. The shared
|
||||
content-addressed store uses canonical closed records, SHA-256 objects,
|
||||
atomic writes, per-key locks, stale-lock recovery, and deduplication. One
|
||||
`CachePolicy` (`off` / `read_only` / `read_write` / `refresh`) governs part
|
||||
and assembly caching, and the `simplecad-cache` CLI emits stable JSON status
|
||||
and verify/repair reports.
|
||||
|
||||
## 3. Feature Tree Convention (FTC)
|
||||
|
||||
Model sources follow an explicit feature-block discipline — sketch/profile,
|
||||
operations, booleans, modifiers — recorded as a readable dataflow
|
||||
(`body = op(body, tools)`), with per-feature header comments
|
||||
(`# ---- feature: <slug> (<role>) ----`). The convention is backed by:
|
||||
|
||||
- a constrained 2D sketch API (dimension-driven profiles, wire offset for
|
||||
shell-like walls) with open chain promotion to wires;
|
||||
- canonical plane/axes conventions for planar makers, covered by regression
|
||||
tests;
|
||||
- a verified QL selection playbook (33 selection patterns) documenting the
|
||||
structured selection channels and their reach.
|
||||
|
||||
## 4. DXF engineering drawings
|
||||
|
||||
A deterministic DXF engine turns a modeled part into 2D engineering drawings
|
||||
through HLR projection: sheet plans, views, dimension chains, and diagnostic
|
||||
plots, driven by the same package pipeline as the 3D exporters.
|
||||
|
||||
## 5. External CAD history import
|
||||
|
||||
`tools/research/histjson` plus the SDK translation layer import external
|
||||
CAD-history dialects (Fusion-style histories) into FTC model sources:
|
||||
constraints are translated unconditionally with per-item conflict audit
|
||||
output instead of silent fallbacks. On the reference benchmark the deep
|
||||
multi-feature case reproduces geometry at machine precision (Deep ~85%,
|
||||
Fusion ~77% exact-match) and the constraint channel solves ~90% (Deep) /
|
||||
~93% (Fusion) of cases.
|
||||
|
||||
## 6. Reverse-engineering studio in the browser
|
||||
|
||||
`viewer/re.html` is a human-in-the-loop reverse-engineering workbench:
|
||||
pick faces/edges or lasso a region on the target STEP, annotate with inline
|
||||
entity and operation chips, and submit — the server composes a
|
||||
`submission.json` (annotations + per-entity one-level adjacency context +
|
||||
operation tips + snapshot), an agent rebuilds, and the UI streams the
|
||||
comparison and evaluation back. The composer is IME-safe (CJK composition
|
||||
never submits), the same operation tip can be cited multiple times, and
|
||||
user selections are never truncated. The studio UI is built with React 19 +
|
||||
Tailwind 4 + shadcn-style components over the imperative three.js kernel.
|
||||
|
||||
The companion `.scadpkg` browser inspector loads v3 packages with full
|
||||
closure-hash validation, so tampered packages are rejected by name.
|
||||
|
||||
## 7. Unified rendering and FEM-ready exports
|
||||
|
||||
One screenshot pipeline serves all 3D rendering needs: 1–4 view grids,
|
||||
studio styling, deterministic anti-aliasing, and per-view annotation
|
||||
placement with occlusion handling. The AP242/Gmsh example chains the package
|
||||
through AP242 STEP, Gmsh volume meshing, and a Calculix static solve with
|
||||
von-Mises reporting; MJCF export covers MuJoCo assembly consumers.
|
||||
|
||||
## 8. Open-source readiness
|
||||
|
||||
- Relicensed from AGPL-3.0 to Apache-2.0.
|
||||
- The packaged skill is compiled per host harness (omp, opencode, zcode,
|
||||
claudecode, codex, dsh, kimicode) from one source tree with conditional
|
||||
host-binding blocks; a typo in a target name fails the build.
|
||||
- Examples are self-contained folders (sources + verification + fresh
|
||||
artifacts under `examples/<name>/out/`), cover part / assembly / reverse
|
||||
engineering / FEM, and every example is verified to run end-to-end.
|
||||
- `scad.verifier` and the `python-fcl` dependency are removed; collision
|
||||
verification is external to the SDK.
|
||||
|
||||
## 9. Reliability
|
||||
|
||||
Geometry fingerprints are stable across BRep serialize/deserialize
|
||||
round-trips (bounds quantized on a fixed 1e-4 mm grid, far coarser than the
|
||||
sub-tolerance recomputation wobble), so package re-validation no longer
|
||||
fails on cell-edge geometries. The Python type-check baseline was reduced
|
||||
by an order of magnitude, and the suite stands at 1503 passing tests across
|
||||
Python 3.10–3.13.
|
||||
@@ -0,0 +1,88 @@
|
||||
# SimpleCADAPI 2.1.0 更新说明
|
||||
|
||||
[English](2.1.0.md)
|
||||
|
||||
> **发布提示:** 用于生产前,请验证生成的定义、装配约束和制造几何。
|
||||
|
||||
SimpleCADAPI 2.1.0 把 SDK 推向 agent-first CAD 工具箱:Feature Tree
|
||||
Convention 建模纪律 + 编译器校验的 skill 指引、外部 CAD 历史导入、浏览器内
|
||||
逆向工作台、DXF 工程图、自包含可运行示例——全部建立在 2.0.4 beta 周期落地的
|
||||
可复现产品边界与崩溃安全缓存之上。
|
||||
|
||||
## 1. 持久零件与装配定义
|
||||
|
||||
`@scad.part` 构建且只构建一个物理单实体零件,返回 `PartBuildResult`:运行时
|
||||
`Part`、`PartDefinition`、图和 session 状态、model/session JSON、接口差异以及
|
||||
单次构建的 `CacheReport`。内容派生 key 覆盖规范化参数、builder 源码、声明的
|
||||
文件输入、revision、容差 profile 和 generator/ABI profile。
|
||||
|
||||
`@scad.assemble` 要求显式传入外部 `PartDefinition` 或嵌套
|
||||
`AssemblyDefinition`。重复实例共享不可变定义;封闭校验会拒绝缺失、未使用、
|
||||
循环、冲突或不兼容引用。定义可脱离进程内运行时对象独立往返。connector 接口
|
||||
哈希跨进程稳定,相同接口不再产生虚假定义差异。
|
||||
|
||||
## 2. 增量装配求解、缓存与诊断
|
||||
|
||||
装配状态记录组件依赖和公共 connector 接口;变化只沿受影响的依赖路径传播,
|
||||
每个恢复位置仍必须先通过约束残差验证。共享内容寻址存储使用规范封闭 record、
|
||||
SHA-256 object、原子写入、逐 key 锁、陈旧锁恢复和对象去重。一个 `CachePolicy`
|
||||
(`off` / `read_only` / `read_write` / `refresh`)同时治理零件与装配缓存,
|
||||
`simplecad-cache` CLI 输出稳定 JSON 的 status 与 verify/repair 报告。
|
||||
|
||||
## 3. Feature Tree Convention(FTC)
|
||||
|
||||
模型源码遵循显式特征块纪律——sketch/profile、操作、布尔、修改器——以可读的
|
||||
数据流记录(`body = op(body, tools)`),每个特征带头部注释
|
||||
(`# ---- feature: <slug> (<role>) ----`)。该纪律由以下部分支撑:
|
||||
|
||||
- 约束 2D 草图 API(尺寸驱动轮廓、面向等壁结构的 wire 偏置),开链可提升为
|
||||
wire;
|
||||
- 平面 maker 的规范平面/轴向约定,带回归测试覆盖;
|
||||
- 经过验证的 QL 选择 playbook(33 个已验证选择模式),沉淀结构化选择通道及
|
||||
其覆盖范围。
|
||||
|
||||
## 4. DXF 工程图
|
||||
|
||||
确定性 DXF 引擎通过 HLR 投影把建模零件变成 2D 工程图:SheetPlan、视图、尺寸
|
||||
链与诊断图,与 3D 导出器共用同一 package 管线。
|
||||
|
||||
## 5. 外部 CAD 历史导入
|
||||
|
||||
`tools/research/histjson` 加上 SDK 翻译层把外部 CAD 历史(Fusion 系)导入为
|
||||
FTC 模型源码:约束无条件翻译,逐条输出冲突审计而不是静默回落。在参考基准上,
|
||||
深多特征案例以机器精度复现几何(Deep ~85%、Fusion ~77% 全等),约束通道约
|
||||
90%(Deep)/ 93%(Fusion)可解。
|
||||
|
||||
## 6. 浏览器内逆向工作台
|
||||
|
||||
`viewer/re.html` 是人在回路的逆向工作台:在目标 STEP 上点面/点边或套索圈选,
|
||||
用内联实体与操作 chip 做标注并提交——服务端组装 `submission.json`(标注 +
|
||||
逐实体一级邻接上下文 + 操作提示 + 截图),agent 重建,UI 回流对比与评审。
|
||||
输入框对输入法安全(CJK 组词期永不提交)、同一操作提示可引用多次、用户的
|
||||
选择集合永不截断。工作台 UI 用 React 19 + Tailwind 4 + shadcn 风格组件构建,
|
||||
命令式 three.js 内核保持不变。
|
||||
|
||||
配套的 `.scadpkg` 浏览器检查器加载 v3 包并做全闭包哈希校验,被篡改的包会
|
||||
按成员点名拒绝。
|
||||
|
||||
## 7. 统一渲染与 FEM 就绪导出
|
||||
|
||||
一条截图管线覆盖全部 3D 出图需求:1–4 视图网格、studio 风格、确定性抗锯齿、
|
||||
逐视角标注放置与遮挡处理。AP242/Gmsh 示例把同一 package 串过 AP242 STEP、
|
||||
Gmsh 体网格与 Calculix 静力求解并输出 von-Mises 报告;MJCF 导出覆盖 MuJoCo
|
||||
装配消费者。
|
||||
|
||||
## 8. 开源就绪
|
||||
|
||||
- 许可证从 AGPL-3.0 改为 Apache-2.0。
|
||||
- 打包 skill 从单一源码树按 host harness 条件编译(omp、opencode、zcode、
|
||||
claudecode、codex、dsh、kimicode);目标名拼写错误会让构建直接失败。
|
||||
- 示例是自包含目录(源码 + 验证脚本 + `examples/<name>/out/` 下最新产物),
|
||||
覆盖零件 / 装配 / 逆向 / FEM 四类,且每个例子都验证过端到端可运行。
|
||||
- `scad.verifier` 与 `python-fcl` 依赖移除;碰撞验证外置于 SDK。
|
||||
|
||||
## 9. 可靠性
|
||||
|
||||
几何指纹在 BRep 序列化往返下保持稳定(bounds 在固定 1e-4 mm 网格上量化,
|
||||
远粗于亚容差的重算抖动),包重开校验不再在格边界几何上失败。Python 类型
|
||||
检查基线下降一个数量级,测试套件在 Python 3.10–3.13 上共 1503 个用例通过。
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[project]
|
||||
name = "simplecadapi"
|
||||
version = "2.0.4b3"
|
||||
version = "2.1.0"
|
||||
description = "A simplified OCP-native CAD modeling Python API"
|
||||
readme = "README.md"
|
||||
license = { file = "LICENSE" }
|
||||
|
||||
Reference in New Issue
Block a user