Merge pull request #16 from Yulia2233/master
docs: add bilingual 2.0.2 update notes
This commit is contained in:
@@ -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">
|
||||
|
||||
@@ -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">
|
||||
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user