From 2ce6b3f475d55528544a51b4d526c4c0c54e3750 Mon Sep 17 00:00:00 2001 From: NiJingzhe <1448976235@qq.com> Date: Fri, 30 Oct 2026 18:29:02 +0800 Subject: [PATCH] release: 2.2.7 Version in pyproject.toml, the project entry of uv.lock and SKILL.md; the CHANGELOG heading; docs/updates/2.2.7 (EN and zh-CN); the update notes of both READMEs replaced with this version's. Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 2 + README.md | 25 ++++++------ README.zh-CN.md | 22 ++++++----- docs/skill/SKILL.md | 4 +- docs/updates/2.2.7.md | 77 +++++++++++++++++++++++++++++++++++++ docs/updates/2.2.7.zh-CN.md | 72 ++++++++++++++++++++++++++++++++++ pyproject.toml | 2 +- uv.lock | 2 +- 8 files changed, 181 insertions(+), 25 deletions(-) create mode 100644 docs/updates/2.2.7.md create mode 100644 docs/updates/2.2.7.zh-CN.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 04ec22c..9feca02 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ user-facing notes live in [`docs/updates/`](docs/updates/) (English and ## Unreleased +## 2.2.7 — 2026-10-30 + ### Fixed - The editor starts with whatever model file is on disk: a model kept by an older build that leaves parts out, or a damaged one, is not restored (and no longer stops the kernel from starting, which showed as "starting the kernel" for ever), and diff --git a/README.md b/README.md index 5fa8bac..f573e0d 100644 --- a/README.md +++ b/README.md @@ -149,20 +149,22 @@ the full crank cycle sweeps clean in the same sim · --- -## Update Notes (2.2.7b1) +## Update Notes (2.2.7) > Validate generated definitions, assembly constraints, and manufacturing > geometry before production use. -- **The geometry engine is C++ on OpenCASCADE, inside the wheel.** `pip install simplecadapi` needs no - `cadquery-ocp`; the public API and the previous test suite are unchanged. -- **Prebuilt wheels** for Linux x86_64 and aarch64, macOS arm64 (14+) and Windows x86_64, Python 3.10-3.13, - all on the same OpenCASCADE 7.9.3. This is a beta: the first release with prebuilt wheels. -- **Faster and smaller.** On the six-axis arm: cold build 43.8 s to 29.1 s, rebuild with nothing changed - 12.8 s to 6.0 s, `import simplecadapi` 1.6 s / 360 MB to 0.2 s / 68 MB. -- **Errors are English** and the tag and query errors render in full, like operator errors. - -Full notes for this version: [`docs/updates/2.2.7b1.md`](docs/updates/2.2.7b1.md). +- **First stable release of the C++ engine**, inside prebuilt wheels (Linux x86_64 and aarch64, macOS arm64 14+, Windows + x86_64; Python 3.10-3.13; one OpenCASCADE 7.9.3). `pip install simplecadapi` needs no `cadquery-ocp`. +- **The editor is faster.** On the six-axis arm a joint angle never seen before takes 2.7 s (was 5.7 s in the beta), one seen + before 0.6 s (was 5.5 s), and the model reaches the page 0.36-0.41 s after the last cell. The kernel uses about 300 MB more + memory at idle than the beta. +- **`Var` and `Expr` behave like numbers**: `r > 3`, `int(r)`, `round(r, 2)`, `range(n)`, `max(r, 3)`, f-strings work, and + a ql predicate with a value computed from a `Var` matches. `bool(var)` and `json.dumps(var)` still raise. +- **`shape.wrapped` is an OCP shape** when OCP is installed (`simplecadapi[verify]`), a copy, so OCCT verifier scripts run as written. +- Failing fillets, chamfers and ql selections attach their picture again. Notebooks with saved parameter values rebuild once. + +Full notes for this version: [`docs/updates/2.2.7.md`](docs/updates/2.2.7.md). Earlier versions: the [changelog](CHANGELOG.md) and [`docs/updates/`](docs/updates/). --- @@ -183,7 +185,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 release: `simplecadapi==2.2.7b1`. +Current release: `simplecadapi==2.2.7`. ## What It Provides @@ -664,6 +666,7 @@ and the [STEP reconstruction workflow](docs/skill/references/workflows/step-reco ## Documentation +- 2.2.7 update notes: [`docs/updates/2.2.7.md`](docs/updates/2.2.7.md) - 2.2.7b1 update notes: [`docs/updates/2.2.7b1.md`](docs/updates/2.2.7b1.md) - 2.2.6.post2 update notes: [`docs/updates/2.2.6.post2.md`](docs/updates/2.2.6.post2.md) - 2.2.6.post1 update notes: [`docs/updates/2.2.6.post1.md`](docs/updates/2.2.6.post1.md) diff --git a/README.zh-CN.md b/README.zh-CN.md index cc581e8..651de4d 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -133,19 +133,20 @@ CalculiX 静力 FEM（边界面按保真的 `interface.*` 标签选取，仿真 --- -## 更新日志（2.2.7b1） +## 更新日志（2.2.7） > 投入生产前请验证生成的定义、装配约束和制造几何。 -- **几何引擎改为基于 OpenCASCADE 的 C++，随 wheel 发布。** `pip install simplecadapi` 不再需要 `cadquery-ocp`； - 公开 API 和此前的整套测试不变。 -- **预编译 wheel**：Linux x86_64 与 aarch64、macOS arm64（14+）、Windows x86_64，Python 3.10-3.13， - 全部使用同一份 OpenCASCADE 7.9.3。这是 beta，也是第一个带预编译 wheel 的版本。 -- **更快、更小。** 六轴机械臂：冷构建 43.8 s 到 29.1 s，无改动重建 12.8 s 到 6.0 s， - `import simplecadapi` 1.6 s / 360 MB 到 0.2 s / 68 MB。 -- **报错全部为英文**，标签与查询类报错和算子报错一样完整渲染。 +- **C++ 引擎的第一个正式版**，随预编译 wheel 发布（Linux x86_64 与 aarch64、macOS arm64 14+、Windows x86_64； + Python 3.10-3.13；统一使用 OpenCASCADE 7.9.3）。`pip install simplecadapi` 不再需要 `cadquery-ocp`。 +- **编辑器更快。** 六轴机械臂上一个没见过的关节角 2.7 s（beta 是 5.7 s），见过的 0.6 s（beta 是 5.5 s）， + 模型在最后一个 cell 之后 0.36-0.41 s 到达页面。内核空闲时比 beta 多用约 300 MB 内存。 +- **`Var` 和 `Expr` 像数字一样工作**：`r > 3`、`int(r)`、`round(r, 2)`、`range(n)`、`max(r, 3)`、f-string 可用， + 用 `Var` 算出的值写 ql 谓词也能匹配。`bool(var)` 和 `json.dumps(var)` 仍然报错。 +- **装了 OCP 时 `shape.wrapped` 是 OCP 形状**（`simplecadapi[verify]`），是拷贝，OCCT 验证脚本可以原样运行。 +- fillet、chamfer 和 ql 选择失败重新附带图片。保存了参数值的笔记本会重建一次。 -本版本的完整说明：[`docs/updates/2.2.7b1.zh-CN.md`](docs/updates/2.2.7b1.zh-CN.md)。 +本版本的完整说明：[`docs/updates/2.2.7.zh-CN.md`](docs/updates/2.2.7.zh-CN.md)。 更早的版本：见[更新日志](CHANGELOG.md)和 [`docs/updates/`](docs/updates/)。 --- @@ -163,7 +164,7 @@ CalculiX 静力 FEM（边界面按保真的 `interface.*` 标签选取，仿真 SimpleCADAPI 是一个基于 OCP 的 Python CAD SDK，提供清晰的函数式建模操作和可重放的模型图。它在 OpenCascade 几何内核之上提供精简的公共 API，可用于创建实体、应用特征、添加语义标签、查询拓扑、导出制造文件，以及将记录的模型转换为 FreeCAD 工作流。 -当前版本：`simplecadapi==2.2.7b1`。 +当前版本：`simplecadapi==2.2.7`。 ## 核心能力 @@ -558,6 +559,7 @@ uv run --extra gmsh python examples/ap242_gmsh_volume_mesh/export_fem_mesh.py ## 文档 +- 2.2.7 更新说明：[`docs/updates/2.2.7.zh-CN.md`](docs/updates/2.2.7.zh-CN.md) - 2.2.7b1 更新说明：[`docs/updates/2.2.7b1.zh-CN.md`](docs/updates/2.2.7b1.zh-CN.md) - 2.2.6.post2 更新说明：[`docs/updates/2.2.6.post2.zh-CN.md`](docs/updates/2.2.6.post2.zh-CN.md) - 2.2.6.post1 更新说明：[`docs/updates/2.2.6.post1.zh-CN.md`](docs/updates/2.2.6.post1.zh-CN.md) diff --git a/docs/skill/SKILL.md b/docs/skill/SKILL.md index 1a43a1a..93fe6d2 100644 --- a/docs/skill/SKILL.md +++ b/docs/skill/SKILL.md @@ -4,9 +4,9 @@ description: Build, assemble, inspect, reconstruct, and export parametric CAD mo license: Apache-2.0 metadata: project: simplecadapi - version: 2.2.7b1 + version: 2.2.7 package-name: simplecadapi - package-version: 2.2.7b1 + package-version: 2.2.7 --- # SimpleCAD SDK Skill diff --git a/docs/updates/2.2.7.md b/docs/updates/2.2.7.md new file mode 100644 index 0000000..e242cff --- /dev/null +++ b/docs/updates/2.2.7.md @@ -0,0 +1,77 @@ +# 2.2.7 Update Notes + +The first stable release of the C++ engine (2.2.7b1 was the beta): the geometry engine is C++ on OpenCASCADE, shipped inside +prebuilt wheels, and `pip install simplecadapi` needs no `cadquery-ocp` and no OpenCASCADE on the machine. This release makes +the editor much faster, lets `Var` and `Expr` be used like numbers, and fixes what the beta left out. + +## Prebuilt packages + +Linux x86_64 and aarch64 (manylinux_2_28), macOS arm64 (14+) and Windows x86_64, each for Python 3.10, 3.11, 3.12 and 3.13, all +linked against the same OpenCASCADE 7.9.3. There are no wheels for macOS Intel, musl Linux or Windows on ARM; there the source +distribution builds the module and needs a C++20 toolchain and OpenCASCADE >= 7.8. + +## The editor is faster + +Measured on the six-axis arm (`sandbox-envs/desktop_arm_sources`) in the editor, same machine: + +| | 2.2.6.post2 | 2.2.7b1 | 2.2.7 | +|---|---|---|---| +| cold start | 64.5 s | 48.8 s | 34.9 s | +| start with nothing changed | 4.1 s | 2.1 s | 1.6 s | +| a joint angle never seen before | 4.4 s | 5.7 s | 2.7 s | +| a joint angle seen before | 6.2 s | 5.5 s | 0.6 s | +| idle memory | 1038 MB | 322 MB | 617 MB | + +* **The model reaches the page sooner.** The kernel publishes the model as parts identified by the content of their geometry, + the server sends each page only the parts that page lacks, and the page builds geometry only for new parts. A joint angle + moves 115 KB instead of 6.26 MB; from the last cell to the model on screen takes 0.36-0.41 s instead of 1.3-3.2 s. The + model is pushed over the WebSocket in the `preview` event itself, with no second request. +* **The kernel keeps what its cells made** and what `use()` returned, and a saved parameter's digest follows what a cell + reads: changing one joint angle no longer redoes the cell that builds the parts. The cost is memory: about 300 MB more at + idle than the beta (the kernel keeps the twelve most recent cell results). +* One case is still slower than 2.2.6: a new value of `OPEN_STROKE` on the arm takes 5.8 s (2.2.6.post2: 4.7 s; the beta: + 6.8 s), because the assembly solve it triggers is real work. + +## `Var` and `Expr` behave like numbers + +`int(r)`, `round(r, 2)`, `r > 3`, `max(r, 3)`, `sorted([...])`, `range(n)`, `[0] * n`, `lst[n - 1]`, `r // 2`, `r % 3`, +`f"{r:.2f}"` and `str(r)` now work and read the value the variable has now; arithmetic still builds the formula that keeps +the link to the parameters. `r == 5.0` is `True` (it was `False`), and a ql predicate with a value computed from a `Var` +(`ql.prop("geom.length", ">=", 2 * math.pi * radius)`) now matches, where 2.2.6 matched nothing. +Still errors: `bool(var)` (write `if r > 0:`) and `json.dumps(var)`; numpy needs `float(var)`. A notebook that relies on the new +behaviour does not run unchanged on 2.2.6; `float(var)` makes it portable. + +## `shape.wrapped` is an OCP shape + +With OCP installed (`pip install "simplecadapi[verify]"`), `shape.wrapped` is an OCP shape of the class of its kind +(`TopoDS_Solid`, `TopoDS_Face`, ...), so verifier scripts written with the OCCT API run as written. It is a copy: every access +makes a new one, and a change made to it does not reach the SDK's shape. `simplecadapi.verify.to_ocp` / `from_ocp` are the +explicit forms. `SCA_WRAPPED=native|ocp` chooses. Without OCP it stays the SDK's own OCCT shape. The `fem` extra is gone. + +## Failures and fixes + +* A failing fillet or chamfer, and a failing ql `exactly()`, attach their picture again (2.2.7b1 drew one for booleans only). +* The editor starts with whatever model file is on disk: a damaged or partial one is not restored and no longer leaves the + editor "starting the kernel" for ever. A damaged preview is refused with the reason (`400`), not as missing parts. +* Cache entries written by an older build that name classes which no longer exist are replaced; a notebook with such entries + (a child run through `use`, the arm's gripper) takes 0.8 s instead of 3-6 s. +* An OCCT failure while reading a geometry type or closedness makes the property absent, as in 2.2.6. +* A failure that is handled and used to leave no trace prints a `[sca]` line on stderr. + +## Upgrading + +* **Notebooks with saved parameter values rebuild once** after the upgrade (their cells' digests changed). +* `shape.wrapped` is a copy when OCP is installed (above). +* New switches are listed in `docs/environment.md`. + +## The skill + +`discipline/notebook-cell-design.md` states where the cell boundaries go, when a number is a `scad.var`, and why, with the error +you get when a rule is broken. + +## For contributors + +The C++ tree is formatted (`.clang-format`, checked in CI), has a `CONTRIBUTING.md`, a reading order and a landing plan under +`src/cpp/`, named tolerances (`scad::tol`), no swallowed exceptions or unchecked optionals that clang-tidy reports, and its +doctest executables run in CI in Release and under ASan and UBSan. The old tests that do not apply to the soft renderer are +listed in `src/cpp/docs/DEVIATIONS.md`. diff --git a/docs/updates/2.2.7.zh-CN.md b/docs/updates/2.2.7.zh-CN.md new file mode 100644 index 0000000..2e30b9a --- /dev/null +++ b/docs/updates/2.2.7.zh-CN.md @@ -0,0 +1,72 @@ +# 2.2.7 更新说明 + +C++ 引擎的第一个正式版（2.2.7b1 是 beta）：几何引擎是基于 OpenCASCADE 的 C++，随预编译 wheel 一起发布， +`pip install simplecadapi` 不再需要 `cadquery-ocp`，机器上也不需要装 OpenCASCADE。这一版让编辑器快了很多，让 `Var` 和 `Expr` +可以像数字一样使用，并补上了 beta 遗漏的东西。 + +## 预编译包 + +Linux x86_64 与 aarch64（manylinux_2_28）、macOS arm64（14+）、Windows x86_64，各支持 Python 3.10、3.11、3.12、3.13， +全部链接同一份 OpenCASCADE 7.9.3。macOS Intel、musl Linux、Windows ARM 没有预编译包；这些平台由源码包现场构建， +需要 C++20 工具链和 OpenCASCADE >= 7.8。 + +## 编辑器更快 + +六轴机械臂（`sandbox-envs/desktop_arm_sources`）在编辑器中的实测，同一台机器： + +| | 2.2.6.post2 | 2.2.7b1 | 2.2.7 | +|---|---|---|---| +| 冷启动 | 64.5 s | 48.8 s | 34.9 s | +| 无改动启动 | 4.1 s | 2.1 s | 1.6 s | +| 一个没见过的关节角 | 4.4 s | 5.7 s | 2.7 s | +| 一个见过的关节角 | 6.2 s | 5.5 s | 0.6 s | +| 空闲内存 | 1038 MB | 322 MB | 617 MB | + +* **模型更快到达页面。** 内核把模型发布成按几何内容标识的零件，服务器只给每个页面发它缺的零件，页面只为新零件建几何。 + 改一个关节角只传 115 KB（原来 6.26 MB）；从最后一个 cell 到模型显示在屏幕上是 0.36-0.41 s（原来 1.3-3.2 s）。 + 模型随 `preview` 事件直接经 WebSocket 推送，不再有第二次请求。 +* **内核会记住 cell 的结果**和 `use()` 的返回值，保存的参数值的摘要只跟随 cell 真正读到的参数：改一个关节角不会再重做建零件的 cell。 + 代价是内存：空闲时比 beta 多约 300 MB（内核保留最近的 12 个 cell 结果）。 +* 仍有一个场景比 2.2.6 慢：机械臂上一个新的 `OPEN_STROKE` 值要 5.8 s（2.2.6.post2 是 4.7 s；beta 是 6.8 s）， + 因为它触发的装配求解是真实的计算。 + +## `Var` 和 `Expr` 像数字一样工作 + +`int(r)`、`round(r, 2)`、`r > 3`、`max(r, 3)`、`sorted([...])`、`range(n)`、`[0] * n`、`lst[n - 1]`、`r // 2`、`r % 3`、 +`f"{r:.2f}"`、`str(r)` 现在都可用，读取变量当前的值；算术运算仍然生成保留参数联系的公式。`r == 5.0` 为 `True`（原来是 `False`）， +用 `Var` 算出来的值写 ql 谓词（`ql.prop("geom.length", ">=", 2 * math.pi * radius)`）现在能匹配，2.2.6 里匹配不到任何东西。 +仍然报错的：`bool(var)`（请写 `if r > 0:`）和 `json.dumps(var)`；numpy 需要 `float(var)`。依赖新行为的笔记本不能原样在 2.2.6 上运行， +用 `float(var)` 可以保持可移植。 + +## `shape.wrapped` 是 OCP 形状 + +装了 OCP（`pip install "simplecadapi[verify]"`）时，`shape.wrapped` 是对应类别的 OCP 形状（`TopoDS_Solid`、`TopoDS_Face` 等）， +用 OCCT API 写的验证脚本可以原样运行。它是一份拷贝：每次访问都生成新的，对它的修改不会影响 SDK 的形状。 +`simplecadapi.verify.to_ocp` / `from_ocp` 是显式写法。`SCA_WRAPPED=native|ocp` 可以选择。没装 OCP 时仍是 SDK 自己的 OCCT 形状。 +`fem` extra 已移除。 + +## 失败信息与修复 + +* fillet / chamfer 失败和 ql 的 `exactly()` 失败重新附带图片（2.2.7b1 只有布尔运算有）。 +* 编辑器用磁盘上现有的模型文件启动：损坏或不完整的文件不会被恢复，也不会再让编辑器一直停在"starting the kernel"。 + 损坏的预览会带着原因被拒绝（`400`），不再被当成缺零件。 +* 旧版本写入的、指向已不存在的类的缓存条目会被替换；有这类条目的笔记本（通过 `use` 运行的子笔记本、机械臂的夹爪） + 耗时从 3-6 s 降到 0.8 s。 +* 读取几何类型或封闭性时发生的 OCCT 失败会让该属性为"无"，与 2.2.6 一致。 +* 过去被处理但不留痕迹的失败，现在会在 stderr 打印一行 `[sca]`。 + +## 升级须知 + +* **保存了参数值的笔记本在升级后会重建一次**（它们的 cell 摘要变了）。 +* 装了 OCP 时 `shape.wrapped` 是拷贝（见上）。 +* 新增的开关见 `docs/environment.md`。 + +## Skill + +`discipline/notebook-cell-design.md` 规定了 cell 边界放在哪里、什么时候一个数应当是 `scad.var`，以及原因，并给出违反规则时会看到的报错。 + +## 面向贡献者 + +C++ 代码已统一格式（`.clang-format`，CI 检查），有 `CONTRIBUTING.md`、阅读顺序和合入计划（在 `src/cpp/` 下），容差有了名字（`scad::tol`）， +clang-tidy 不再报告被吞掉的异常和未检查的 optional，doctest 可执行文件在 CI 中以 Release 以及 ASan、UBSan 运行。 +不适用于软渲染器的旧测试列在 `src/cpp/docs/DEVIATIONS.md` 里。 diff --git a/pyproject.toml b/pyproject.toml index f1f9ec5..ffd5302 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "simplecadapi" -version = "2.2.7b1" +version = "2.2.7" description = "A simplified OpenCASCADE-native CAD modeling Python API" readme = "README.md" license = { file = "LICENSE" } diff --git a/uv.lock b/uv.lock index 8c61338..68aee42 100644 --- a/uv.lock +++ b/uv.lock @@ -2996,7 +2996,7 @@ wheels = [ [[package]] name = "simplecadapi" -version = "2.2.7b1" +version = "2.2.7" source = { editable = "." } dependencies = [ { name = "cryptography" },