Merge pull request #16 from Yulia2233/master

docs: add bilingual 2.0.2 update notes
This commit is contained in:
Ni Jingzhe
2026-07-28 23:58:20 +08:00
committed by GitHub
4 changed files with 212 additions and 0 deletions
+12
View File
@@ -6,6 +6,18 @@
[中文说明](README.zh-CN.md)
## Update Notes (2.0.2)
> **Experimental release:** The capabilities in this release may introduce
> breaking changes in later versions and are not recommended for immediate
> production use.
SimpleCADAPI 2.0.2 expands the workflow with cross-CAD translation, a browser
scene viewer, replayable model artifacts with source mapping, units and
tolerance analysis, standard mechanical parts, assembly verification, and STEP
reverse-engineering tools. See the [full English update notes](docs/updates/2.0.2.md)
for implementation details and usage boundaries.
---
<div align="center">
+9
View File
@@ -6,6 +6,15 @@
[English](README.md)
## 更新日志(2.0.2)
> **试验性版本:** 本版本中的功能后续可能引入 breaking changes
> (不兼容变更),不建议立即用于生产环境。
SimpleCADAPI 2.0.2 新增跨 CAD 转换、浏览器三维场景查看、可回放模型与源代码
映射、单位和公差分析、机械标准件、装配验证以及 STEP 逆向工程工具。具体实现
细节和使用边界请阅读[完整中文更新说明](docs/updates/2.0.2.zh-CN.md)。
---
<div align="center">
+106
View File
@@ -0,0 +1,106 @@
# SimpleCADAPI 2.0.2 Update Notes
[中文](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](../guides/step-brep-reverse-engineering.md)
- [Browser viewer README](../../viewer/README.md)
- [Core serialization and replay documentation](../core/serialization/README.md)
+85
View File
@@ -0,0 +1,85 @@
# SimpleCADAPI 2.0.2 更新说明
[English](2.0.2.md)
> **试验性版本提示:** 以下能力均为试验性功能,后续版本可能引入
> breaking changes(不兼容变更),因此不建议立即用于生产环境。
SimpleCADAPI 2.0.2 从 OCP 原生几何 API 进一步扩展为覆盖模型创建、参数与
公差分析、模型保存与回放、跨 CAD 转换、浏览器查看、装配验证和 STEP 逆向工程
的完整工作流。
## 1. FreeCAD、Fusion 360 和 SolidWorks 转换
规范化模型 JSON 可以转换为 FreeCAD、Fusion 360 和 SolidWorks 的自动化脚本。
安装 FreeCAD/FreeCADCmd 后,FreeCAD 后端还可以生成可编辑的 `.FCStd` 文档,
并在支持的范围内保留草图、特征、零件、装配体、链接和源选择信息。Fusion 360
后端面向其 Python 自动化环境生成脚本;SolidWorks 后端生成自动化脚本,并支持
通过 COM 驱动 STEP 导出。同一套参数化 SimpleCAD 模型可以作为多个 CAD 软件的
共同来源,无需维护互相分叉的脚本。
## 2. 浏览器三维场景查看器
`viewer/` 应用可以直接打开生成的 `.scene.zip` 包,无需导入 Python 或
OpenCascade。查看器支持 GLB 几何和 CAD 边线渲染,提供旋转、平移、缩放等交互,
通过装配体/组件树查看模型结构,并控制单个实例的显示和隐藏。用户可以选择面、
边和顶点,查看面积、长度、体积或坐标等测量属性,以及语义标签和拓扑身份。
Features 视图会展示可回放的特征树、参数、输出数量、标签和内嵌源代码,并定位
到产生该特征的 Python 调用和高亮源代码行。场景包在加载资源前还会检查资源大小
和 SHA-256 完整性元数据。
## 3. 结构化保存、回放与源代码映射
通过 `@model` 或 `GraphSession` 记录的建模过程,可以导出规范化的模型/会话 JSON,
并使用 `import_model_json(...)` 和 `replay_model_json(...)` 确定性地重新生成模型。
场景导出可以把 `scene.json`、`model/model.json`、项目相对路径的 Python 源文件以及
GLB/entity 资源统一打包为一个可移植文件。
每个建模操作都会尽可能记录源代码溯源信息,因此特征树节点可以追溯到具体 Python
文件、函数调用、赋值目标和行号范围。这为自动化、协作、回归测试和版本化模型审查
提供了基础。
## 4. 物理单位和尺寸公差分析
带单位的变量会在模型图中保留声明单位,同时将 CAD 操作统一转换为毫米和角度。
表达式会在算术运算和受支持的三角函数中自动推导物理维度,拒绝不兼容的维度混用,
并把参数关系保留到可回放的模型数据中。
制造公差可以沿尺寸链传播,生成名义值和上下界,并与显式的公差要求进行检查,
用于单位换算、尺寸链分析和装配公差研究。
## 5. 机械标准件库与齿轮性能
标准件库新增或完善了参数化螺栓、螺母、滚珠轴承、滚子链链轮,以及直齿、斜齿、
人字齿、内齿圈、齿条、摆线盘和直齿锥齿轮等常用机械零件。这些工厂函数返回普通
SimpleCAD 形状或装配体,可以像自定义几何一样继续进行变换、打标签、布尔组合、
序列化、跨软件转换和导出。
齿轮构造和标准件库的图追踪也进行了优化;在代表性齿轮工作负载下,建模时间约
缩短到原来的三分之一。
## 6. 装配体、网格和碰撞检查
零件、组件、连接器、放置关系和装配体可以保存为结构化产品树,并支持固定、旋转、
移动、齿轮、皮带以及齿轮齿条等约束。约束求解和残差检查让装配关系变得可计算、
可度量。系统可以生成用于场景资源和后续检查的三角网格与边线网格。
安装可选依赖 `simplecadapi[collision]` 后,可以通过 `python-fcl` 对当前姿态执行
静态网格穿透检查,配置组件范围和允许穿透量,并输出接触点、法向和穿透深度。当前
版本的检查器针对网格接触穿透,不负责运动求解,也不能覆盖所有完全包含的实体重叠情况。
## 7. STEP 检查和逆向工程诊断
`simplecad-brep` 命令行工具以及 `simplecadapi.inverse_engineer.brep` API 可以读取
STEP BREP,报告体积、表面积、包围盒、拓扑数量和几何基元类型。双向比较可以将几何
点集一致性和带几何标签的面-边-顶点关联图作为严格门槛,避免仅凭体积差判断模型一致性。
工具还支持生成统一视角的 STEP 渲染图,并对指定物理截面进行采样和 XOR 叠加比较,
用于验证重建零件在几何形状和拓扑结构上是否与原始零件一致。
## 相关文档
- [STEP BREP 逆向工程指南](../guides/step-brep-reverse-engineering.md)
- [浏览器查看器说明](../../viewer/README.md)
- [序列化与模型回放文档](../core/serialization/README.md)