feat: enforce canonical product capture workflow

This commit is contained in:
NiJingzhe
2026-08-15 16:17:11 +08:00
parent fee5039cc6
commit 9d6703a786
325 changed files with 10551 additions and 6174 deletions
+88 -63
View File
@@ -16,6 +16,12 @@ 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,
cache modes, diagnostics, limitations, and verification coverage.
All formal scripts under `examples/` emit a synchronized `.scadpkg`, AP242
`.step`, and editable `.FCStd` from the same product package. Run
`uv run python tools/run_examples.py` to rebuild and validate the complete
example export set. The Gmsh example accepts `--skip-mesh` when only the CAD
artifacts are required.
---
<div align="center">
@@ -41,8 +47,8 @@ Current development beta: `simplecadapi==2.0.4b3`.
- OCP-native shape types: `Vertex`, `Edge`, `Wire`, `Face`, and `Solid`.
- Functional modeling operations for primitives, profiles, extrude, revolve,
loft, sweep, booleans, transforms, patterns, fillets, chamfers, and shells.
- Replayable modeling with `@model`, `ModelResult`, `capture_result(...)`,
`import_model_json(...)`, and `replay_model_json(...)`.
- Replayable operation graphs with explicit `GraphSession`,
`export_model_json(...)`, `import_model_json(...)`, and `replay_model_json(...)`.
- Expression parameters with `var(...)`, arithmetic expressions, and serialized
expression graphs.
- Physical units with automatic dimension inference, canonical CAD conversion,
@@ -50,7 +56,8 @@ Current development beta: `simplecadapi==2.0.4b3`.
- QL selectors for geometry grounding, topology queries, and stable feature
selections.
- Semantic tags through `apply_tag(shape=..., tag=...)` and `list_tags(shape=...)`.
- STEP/STL export and FreeCAD translation helpers for script or `.FCStd` output.
- STEP/STL export, editable FreeCAD product-package translation, and AP242
product-structure export with material and named metadata properties.
- Agent-oriented STEP/BREP reconstruction with stable entity IDs, focused local
diagnostics, highlighted region renders, and measured acceptance gates.
- Replayable open and periodic interpolated B-spline Edges/Wires for freeform
@@ -84,45 +91,47 @@ from pathlib import Path
import simplecadapi as scad
out = Path("out")
out.mkdir(exist_ok=True)
base = scad.make_box_rsolid(
width=60.0, height=36.0, depth=8.0, bottom_face_center=(0.0, 0.0, 0.0)
)
hole = scad.make_cylinder_rsolid(
radius=5.0, height=14.0, bottom_face_center=(0.0, 0.0, -3.0)
)
slot = scad.make_box_rsolid(
width=18.0, height=8.0, depth=14.0, bottom_face_center=(14.0, 0.0, -3.0)
)
@scad.part(id="bracket")
def build_bracket() -> scad.Solid:
base = scad.make_box_rsolid(
width=60.0, height=36.0, depth=8.0, bottom_face_center=(0.0, 0.0, 0.0)
)
hole = scad.make_cylinder_rsolid(
radius=5.0, height=14.0, bottom_face_center=(0.0, 0.0, -3.0)
)
slot = scad.make_box_rsolid(
width=18.0, height=8.0, depth=14.0, bottom_face_center=(14.0, 0.0, -3.0)
)
body = scad.cut_rsolid(base, hole, slot)
boss = scad.make_cylinder_rsolid(
radius=8.0, height=7.0, bottom_face_center=(-18.0, 0.0, 8.0)
)
return scad.apply_tag(
shape=scad.union_rsolid(body, boss),
tag="role.demo.bracket",
)
part = scad.cut_rsolid(base, hole, slot)
boss = scad.make_cylinder_rsolid(
radius=8.0, height=7.0, bottom_face_center=(-18.0, 0.0, 8.0)
)
part = scad.union_rsolid(part, boss)
part = scad.apply_tag(shape=part, tag="role.demo.bracket")
print("volume", round(part.get_volume(), 3))
print("faces", len(part.get_faces()))
print("tags", scad.list_tags(shape=part))
scad.export_step(shapes=part, filename=str(out / "bracket.step"))
scad.export_stl(shapes=part, filename=str(out / "bracket.stl"))
result = build_bracket()
package_path = out / "bracket.scadpkg"
scad.capture(result, package_path)
print("volume", round(result.part.body.get_volume(), 3))
print("tags", scad.list_tags(shape=result.part.body))
scad.exporter.export_product_package_to_step(package_path, out / "bracket.step")
scad.exporter.export_product_package_to_stl(package_path, out / "bracket.stl")
```
## Replayable Modeling
## Replayable Operation Graphs
Use one `@scad.model` entry point when a model should be inspectable,
serializable, replayable, or translated into another CAD environment. The
decorated function owns its `GraphSession` and returns a `ModelResult`.
Use an explicit `GraphSession` when a geometry flow should be inspectable,
serializable, replayable, or translated into another CAD environment.
```python
import simplecadapi as scad
from simplecadapi import GraphSession, export_model_json, replay_model_json
from simplecadapi import ql as Q
@scad.model(graph_id="chamfered_block")
def build_model():
with GraphSession(graph_id="chamfered_block") as session:
body = scad.make_box_rsolid(
width=40.0, height=24.0, depth=10.0,
bottom_face_center=(0.0, 0.0, 0.0),
@@ -140,25 +149,26 @@ def build_model():
.exactly(1)
)
final = scad.chamfer_rsolid(solid=drilled, edges=bottom_circle, distance=0.6)
scad.capture_result(value=final)
return final
session.capture_result(value=final)
model_json = export_model_json(session=session)
recorded_nodes = session.graph.node_count
result = build_model()
model_json = result.model_json
rebuilt = result.replay()
print("recorded_nodes", result.session.graph.node_count)
rebuilt = replay_model_json(json_str=model_json)
print("recorded_nodes", recorded_nodes)
print("replayed_outputs", len(rebuilt))
```
Pass `export_dir=...` to `@scad.model` when the invocation should also write
one self-contained `<graph_id>.scene.zip`. The package contains `scene.json`,
`model/model.json`, the complete project-relative Python files referenced by
operation source mappings under `sources/`, and the GLB/entity assets required
by the Viewer. Automatic export does not write adjacent model/session JSON,
STEP, STL, or FCStd files; those explicit export APIs remain available. The
package path is `result.artifact_paths["scene"]`. Without `export_dir`, model
execution remains in memory.
An explicit `GraphSession` remains in memory until an export API is called.
For a durable CAD/viewer deliverable, define one physical single-solid part with
`@scad.part` or an assembly with `@scad.assemble`, then capture and write it in one call:
```python
scad.capture(result, "out/product.scadpkg")
```
The package embeds the definition closure, evaluated scene, feature graphs,
source snapshots, topology, and render/selection assets. STEP, STL, FCStd, and
low-level JSON remain explicit exports.
## Persistent Product Builds And Cache
@@ -190,6 +200,26 @@ See the [persistent cache and product build workflow](docs/guides/cache-build-wo
for cache modes, configuration precedence, PRT reuse, incremental invalidation,
corruption repair, and destructive-command confirmation.
```python
scad.capture(warm, "out/mounting_plate.scadpkg")
scad.translator.freecad_translator.translate_product_package_to_fcstd(
"out/mounting_plate.scadpkg", "out/mounting_plate.FCStd"
)
scad.exporter.export_product_package_to_step(
"out/mounting_plate.scadpkg", "out/mounting_plate.step"
)
scad.exporter.export_product_package_to_stl(
"out/mounting_plate.scadpkg", "out/mounting_plate.stl"
)
```
AP242 preserves evaluated BREP, shared definitions, hierarchy, occurrence
names/placements, materials, colors, density, and named SimpleCAD JSON
properties. It does not reconstruct canonical feature history as AP242
features. For the optional `.step -> .msh` volume-mesh workflow, install
`simplecadapi[gmsh]` and run `examples/12_ap242_gmsh_volume_mesh.py`; use
`--skip-mesh` to export only the synchronized CAD artifacts.
## STEP/BREP Inspection
Install the optional rendering dependency when synchronized STEP views,
@@ -201,7 +231,7 @@ pip install "simplecadapi[inspect]"
Inspection lives under `simplecadapi.inspect.brep`. These APIs are diagnostic
tools, not modeling operations: they do not enter the graph and are rejected
inside `GraphSession` and `@model`. Export or obtain the geometry first, then
inside `GraphSession`. Export or obtain the geometry first, then
inspect it outside the modeling script.
Choose calls from the evidence required by the case instead of following a
@@ -281,27 +311,21 @@ expression.
child-geometry getter, such as `get_edges(index)`, `get_faces(index)`,
`get_wires(index)`, or `get_vertices(index)`, so replayable graph workflows
preserve the pick as a geo select node.
- Use model JSON as the interchange boundary for replay, tests, and FreeCAD
translation.
## FreeCAD Translation
Recorded model JSON can be translated into a FreeCAD Python script:
Use model JSON only for graph replay and inspection. External CAD translation and
file export consume the validated `.scadpkg` closure:
```python
script = scad.translator.freecad_translator.translate_model_json_to_freecad_script(model_json)
```
If FreeCAD or FreeCADCmd is available, the same model JSON can be written as an
`.FCStd` file:
```python
scad.translator.freecad_translator.translate_model_json_to_fcstd(model_json, "bracket.FCStd")
script = scad.translator.freecad_translator.translate_product_package_to_freecad_script(
package_path
)
scad.translator.freecad_translator.translate_product_package_to_fcstd(
package_path, "bracket.FCStd"
)
```
Part/Assembly models are written as editable FreeCAD assembly structure: parts are
`App::Part`, assemblies are `Assembly::AssemblyObject`, and components are links.
Explicit compound projections remain available for geometry-only STEP export.
The exporter namespace owns neutral STEP and STL file output.
## Examples
@@ -335,6 +359,7 @@ uv run python examples/20_integrated_bldc_joint_actuator/main.py
[`docs/core/physical-units.md`](docs/core/physical-units.md)
- Operation graph JSON spec:
[`docs/core/operation_graph_json_spec.md`](docs/core/operation_graph_json_spec.md)
`.scadpkg` 产品包规范(中文):[`design-docs/scadpkg-spec.md`](design-docs/scadpkg-spec.md)
## Releasing the Agent Skill
+45 -42
View File
@@ -35,7 +35,7 @@ SimpleCADAPI 是一个基于 OCP 的 Python CAD SDK,提供清晰的函数式
- 基于 OCP 的 `Vertex`、`Edge`、`Wire`、`Face` 和 `Solid` 类型。
- 支持基本体、轮廓、拉伸、旋转、放样、扫掠、布尔运算、变换、阵列、圆角、倒角和抽壳等函数式建模操作。
- 通过 `@model`、`ModelResult`、`capture_result(...)`、`import_model_json(...)` 和 `replay_model_json(...)` 记录并重放建模过程。
- 通过显式 `GraphSession`、`export_model_json(...)`、`import_model_json(...)` 和 `replay_model_json(...)` 记录并重放操作图。
- 通过 `var(...)`、算术表达式和可序列化表达式图定义参数。
- 使用 QL 选择器定位几何、查询拓扑并稳定选择特征。
- 通过 `apply_tag(shape=..., tag=...)` 和 `list_tags(shape=...)` 管理语义标签。
@@ -74,34 +74,38 @@ from pathlib import Path
import simplecadapi as scad
out = Path("out")
out.mkdir(exist_ok=True)
base = scad.make_box_rsolid(
width=60.0, height=36.0, depth=8.0, bottom_face_center=(0.0, 0.0, 0.0)
)
hole = scad.make_cylinder_rsolid(
radius=5.0, height=14.0, bottom_face_center=(0.0, 0.0, -3.0)
)
part = scad.cut_rsolid(base, hole)
part = scad.apply_tag(shape=part, tag="role.demo.bracket")
@scad.part(id="bracket")
def build_bracket() -> scad.Solid:
base = scad.make_box_rsolid(
width=60.0, height=36.0, depth=8.0, bottom_face_center=(0.0, 0.0, 0.0)
)
hole = scad.make_cylinder_rsolid(
radius=5.0, height=14.0, bottom_face_center=(0.0, 0.0, -3.0)
)
body = scad.cut_rsolid(base, hole)
return scad.apply_tag(shape=body, tag="role.demo.bracket")
print("volume", round(part.get_volume(), 3))
print("tags", scad.list_tags(shape=part))
scad.export_step(shapes=part, filename=str(out / "bracket.step"))
scad.export_stl(shapes=part, filename=str(out / "bracket.stl"))
result = build_bracket()
package_path = out / "bracket.scadpkg"
scad.capture(result, package_path)
print("volume", round(result.part.body.get_volume(), 3))
print("tags", scad.list_tags(shape=result.part.body))
scad.exporter.export_product_package_to_step(package_path, out / "bracket.step")
scad.exporter.export_product_package_to_stl(package_path, out / "bracket.stl")
```
## 可重放建模
当模型需要检查、序列化、重放或转换到其他 CAD 环境时,请使用唯一的
`@scad.model` 顶层入口。该入口拥有自己的 `GraphSession` 并返回 `ModelResult`:
## 可重放操作图
几何流程需要检查、序列化、重放或转换到其他 CAD 环境时,请使用显式
`GraphSession`:
```python
import simplecadapi as scad
from simplecadapi import GraphSession, export_model_json, replay_model_json
@scad.model(graph_id="drilled_block")
def build_model():
with GraphSession(graph_id="drilled_block") as session:
body = scad.make_box_rsolid(
width=40.0, height=24.0, depth=10.0,
bottom_face_center=(0.0, 0.0, 0.0),
@@ -110,24 +114,20 @@ def build_model():
radius=4.0, height=16.0, bottom_face_center=(0.0, 0.0, -3.0)
)
drilled = scad.cut_rsolid(body, cutter)
scad.capture_result(value=drilled)
return drilled
session.capture_result(value=drilled)
model_json = export_model_json(session=session)
recorded_nodes = session.graph.node_count
result = build_model()
model_json = result.model_json
rebuilt = result.replay()
print("recorded_nodes", result.session.graph.node_count)
rebuilt = replay_model_json(json_str=model_json)
print("recorded_nodes", recorded_nodes)
print("replayed_outputs", len(rebuilt))
```
如果模型调用还需要写出最终文件,请向 `@scad.model` 传入
`export_dir=...`。显式 `capture_result(...)` 的结果会生成一个自包含的
`<graph_id>.scene.zip`,其中包含 `scene.json`、`model/model.json`、operation
source mapping 引用的完整项目相对 Python 源文件(位于 `sources/`)以及
Viewer 所需的 GLB/entity 资源。自动导出不会在旁边生成 model/session JSON、
STEP、STL 或 FCStd;这些格式仍可通过显式导出 API 生成。文件路径为
`result.artifact_paths["scene"]`。省略 `export_dir` 时不会写文件。
显式 `GraphSession` 在调用导出 API 前只存在于内存。需要持久 CAD/Viewer
交付物时,一个物理单实体零件使用 `@scad.part`,装配使用 `@scad.assemble`,
直接调用 `scad.capture(result, "out/product.scadpkg")`,一次完成捕获和写盘。
`.scadpkg` 包含完整定义闭包、求值场景、特征图、源码快照、拓扑以及渲染/选择资源。
STEP、STL、FCStd 和底层 JSON 仍由显式导出 API 生成。
## 持久产品构建与缓存
@@ -202,16 +202,18 @@ simplecad-brep tool get_model_summary --arguments-file summary-args.json
## FreeCAD 转换
可以把记录的模型 JSON 转换为 FreeCAD Python 脚本:
外部 CAD 转换只接受经过验证的 `.scadpkg` 产品包:
```python
script = scad.translator.freecad_translator.translate_model_json_to_freecad_script(model_json)
```
如果系统中存在 FreeCAD 或 FreeCADCmd,也可以直接生成 `.FCStd` 文件:
```python
scad.translator.freecad_translator.translate_model_json_to_fcstd(model_json, "bracket.FCStd")
package_path = artifacts.artifact_paths["product"]
script = scad.translator.freecad_translator.translate_product_package_to_freecad_script(
package_path
)
scad.translator.freecad_translator.translate_product_package_to_fcstd(
package_path, "bracket.FCStd"
)
scad.exporter.export_product_package_to_step(package_path, "bracket.step")
scad.exporter.export_product_package_to_stl(package_path, "bracket.stl")
```
## 文档
@@ -228,6 +230,7 @@ scad.translator.freecad_translator.translate_model_json_to_fcstd(model_json, "br
- 序列化与重放:[`docs/core/serialization/README.md`](docs/core/serialization/README.md)
- 操作图 JSON 规范:[`docs/core/operation_graph_json_spec.md`](docs/core/operation_graph_json_spec.md)
- 示例索引:[`examples/README.md`](examples/README.md)
`.scadpkg` 产品包规范:[`design-docs/scadpkg-spec.md`](design-docs/scadpkg-spec.md)
## 发布 Agent Skill
+2 -2
View File
@@ -3,7 +3,7 @@
## Class Definition
```python
class AssemblyBuildResult(value: Assembly, definition: AssemblyDefinition, model_json: str, solve_report: AssemblySolveReport, artifact_paths: Mapping[str, Path] = field(default_factory=dict))
class AssemblyBuildResult(value: Assembly, definition: AssemblyDefinition, feature_graph: FeatureGraphArtifact, solve_report: AssemblySolveReport)
```
*Source: build/results.py*
@@ -14,4 +14,4 @@ class AssemblyBuildResult(value: Assembly, definition: AssemblyDefinition, model
## Description
Runtime Assembly plus its external-reference durable definition.
Runtime Assembly plus its durable definition, feature DAG, and solve evidence.
+1 -1
View File
@@ -10,7 +10,7 @@ class BRepComparison(target: str | None, candidate: str | None, target_minus_can
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.BRepComparison(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.BRepComparison(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ class BRepEntityError
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.BRepEntityError(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.BRepEntityError(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ class BRepInspection(source: str | None, valid: bool, counts: dict[str, int], bo
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.BRepInspection(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.BRepInspection(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ class BRepModel(root: TopoDS_Shape, source: str | None, bodies: tuple[TopoDS_Sol
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.BRepModel(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.BRepModel(...)`; unavailable inside GraphSession
## Description
+17
View File
@@ -0,0 +1,17 @@
# CaptureResult
## Class Definition
```python
class CaptureResult(value: Part | Assembly, definition: PartDefinition | AssemblyDefinition, package: ProductPackage, scene: ProductScenePackage, package_bytes: bytes)
```
*Source: capture.py*
## Import Surface
- top-level: `from simplecadapi import CaptureResult`
## Description
Runtime value plus one complete durable product snapshot.
+1 -1
View File
@@ -10,7 +10,7 @@ class EntityInspectionParity(source: str | None, valid: bool, issues: tuple[str,
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.EntityInspectionParity(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.EntityInspectionParity(...)`; unavailable inside GraphSession
## Description
-17
View File
@@ -1,17 +0,0 @@
# FreeCADScriptTranslator
## Class Definition
```python
class FreeCADScriptTranslator
```
*Source: translator/freecad_translator/translator.py*
## Import Surface
- translator backend: `from simplecadapi.translator.freecad_translator import FreeCADScriptTranslator`
## Description
Backward-compatible class name for the FreeCAD translator.
+2 -2
View File
@@ -3,7 +3,7 @@
## Class Definition
```python
class FreeCADTranslator(document_name: str = 'SimpleCADModel')
class FreeCADTranslator(document_name: str = 'SimpleCADProduct')
```
*Source: translator/freecad_translator/translator.py*
@@ -14,4 +14,4 @@ class FreeCADTranslator(document_name: str = 'SimpleCADModel')
## Description
Public, stateless facade for FreeCAD script translation.
Translate validated `.scadpkg` products into FreeCAD scripts.
+2 -2
View File
@@ -3,7 +3,7 @@
## Class Definition
```python
class Fusion360Translator(document_name: str = 'SimpleCADModel', result_node_ids: Optional[Sequence[str]] = None, *, selection_mode: str = 'gsm', source_kernel_fallback: bool = False)
class Fusion360Translator(document_name: str = 'SimpleCADProduct', *, selection_mode: str = 'gsm', source_kernel_fallback: bool = False)
```
*Source: translator/fusion360_translator/translator.py*
@@ -14,4 +14,4 @@ class Fusion360Translator(document_name: str = 'SimpleCADModel', result_node_ids
## Description
Translate canonical model JSON into a Fusion 360 Python script.
Translate validated `.scadpkg` products into Fusion 360 scripts.
+1 -1
View File
@@ -3,7 +3,7 @@
## Class Definition
```python
class GraphSession(graph_id: Optional[str] = None)
class GraphSession(graph_id: Optional[str] = None, *, allow_external_definitions: bool = False)
```
*Source: graph.py*
+1 -1
View File
@@ -10,7 +10,7 @@ class InspectionSummaryComparison(volume_delta: float, surface_area_delta: float
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.InspectionSummaryComparison(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.InspectionSummaryComparison(...)`; unavailable inside GraphSession
## Description
-17
View File
@@ -1,17 +0,0 @@
# ModelResult
## Class Definition
```python
class ModelResult(value: Any, session: GraphSession, result_node_ids: Tuple[str, ...], model_json: str, session_json: str, artifact_paths: Mapping[str, Path] = field(default_factory=dict))
```
*Source: graph.py*
## Import Surface
- top-level: `from simplecadapi import ModelResult`
## Description
The value and durable graph artifacts produced by ``@model``.
+2 -2
View File
@@ -3,7 +3,7 @@
## Class Definition
```python
class PartBuildResult(value: Part, definition: PartDefinition, session: GraphSession, result_node_ids: tuple[str, ...], model_json: str, session_json: str, cache_report: CacheReport, interface_diff: PartInterfaceDiff | None = None, artifact_paths: Mapping[str, Path] = field(default_factory=dict))
class PartBuildResult(value: Part, definition: PartDefinition, feature_graph: FeatureGraphArtifact, cache_report: CacheReport, interface_diff: PartInterfaceDiff | None = None)
```
*Source: build/results.py*
@@ -14,4 +14,4 @@ class PartBuildResult(value: Part, definition: PartDefinition, session: GraphSes
## Description
Runtime Part plus its durable definition, graph, and cache evidence.
Runtime Part plus its durable definition, feature DAG, and cache evidence.
+17
View File
@@ -0,0 +1,17 @@
# ProductSTEPExportReport
## Class Definition
```python
class ProductSTEPExportReport(output_path: Path, schema: str, definition_ids: tuple[str, ...], occurrence_count: int, material_ids: tuple[str, ...], metadata_item_count: int, limitations: tuple[str, ...])
```
*Source: exporter/step.py*
## Import Surface
- exporter namespace: `from simplecadapi import exporter` then `exporter.step.ProductSTEPExportReport(...)`
## Description
Observed AP242 export facts and explicit semantic limitations.
+17
View File
@@ -0,0 +1,17 @@
# ProductSTLExportReport
## Class Definition
```python
class ProductSTLExportReport(output_path: Path, root_definition_id: str, solid_count: int, definition_count: int, quadrilateral_count: int, residual_triangle_count: int, stl_triangle_count: int, quad_fraction: float, mesh_size: float, remesh_backend: str = 'gmsh-quad-dominant')
```
*Source: exporter/stl.py*
## Import Surface
- exporter namespace: `from simplecadapi import exporter` then `exporter.stl.ProductSTLExportReport(...)`
## Description
Evidence from quad-dominant product-surface remeshing and STL export.
+11 -15
View File
@@ -6,7 +6,7 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- Entries marked `top-level` are exported from `simplecadapi` and can be imported with `from simplecadapi import <name>`.
- Entries marked `submodule` are public through the listed submodule, such as `simplecadapi.ql`.
- Entries marked `inspection namespace` are available through `simplecadapi.inspect.brep` and cannot run inside `GraphSession` or `@model`.
- Entries marked `inspection namespace` are available through `simplecadapi.inspect.brep` and cannot run inside `GraphSession`.
- Entries marked `translator backend` are public only through `simplecadapi.translator.<backend>`.
## Basic Creation
@@ -91,22 +91,20 @@ This index includes generated docs for the public SimpleCAD API surface, includi
## Export
- [export_product_package](export_product_package.md) *(from product_packages.py)* `top-level`
- [export_step](export_step.md) *(from operations.py)* `top-level`
- [export_stl](export_stl.md) *(from operations.py)* `top-level`
- [ProductSTEPExportReport](ProductSTEPExportReport.md) *(from exporter/step.py)* `exporter namespace`
- [ProductSTLExportReport](ProductSTLExportReport.md) *(from exporter/stl.py)* `exporter namespace`
- [export_product_package_to_step](export_product_package_to_step.md) *(from exporter/step.py)* `exporter namespace`
- [export_product_package_to_stl](export_product_package_to_stl.md) *(from exporter/stl.py)* `exporter namespace`
## Translator Backends
- [FreeCADScriptTranslator](FreeCADScriptTranslator.md) *(from translator/freecad_translator/translator.py)* `translator backend`
- [FreeCADTranslator](FreeCADTranslator.md) *(from translator/freecad_translator/translator.py)* `translator backend`
- [Fusion360Translator](Fusion360Translator.md) *(from translator/fusion360_translator/translator.py)* `translator backend`
- [SolidWorksTranslator](SolidWorksTranslator.md) *(from translator/solidworks_translator/translator.py)* `translator backend`
- [export_model_json_to_fcstd](export_model_json_to_fcstd.md) *(from translator/freecad_translator/api.py)* `translator backend`
- [export_model_json_to_solidworks_step](export_model_json_to_solidworks_step.md) *(from translator/solidworks_translator/api.py)* `translator backend`
- [translate_model_json_to_fcstd](translate_model_json_to_fcstd.md) *(from translator/freecad_translator/api.py)* `translator backend`
- [translate_model_json_to_freecad_script](translate_model_json_to_freecad_script.md) *(from translator/freecad_translator/api.py)* `translator backend`
- [translate_model_json_to_fusion360_script](translate_model_json_to_fusion360_script.md) *(from translator/fusion360_translator/api.py)* `translator backend`
- [translate_model_json_to_solidworks_script](translate_model_json_to_solidworks_script.md) *(from translator/solidworks_translator/api.py)* `translator backend`
- [translate_product_package_to_fcstd](translate_product_package_to_fcstd.md) *(from translator/freecad_translator/api.py)* `translator backend`
- [translate_product_package_to_freecad_script](translate_product_package_to_freecad_script.md) *(from translator/freecad_translator/api.py)* `translator backend`
- [translate_product_package_to_fusion360_script](translate_product_package_to_fusion360_script.md) *(from translator/fusion360_translator/api.py)* `translator backend`
- [translate_product_package_to_solidworks_script](translate_product_package_to_solidworks_script.md) *(from translator/solidworks_translator/api.py)* `translator backend`
## Math Helpers
@@ -116,8 +114,6 @@ This index includes generated docs for the public SimpleCAD API surface, includi
## Modeling Graph and Replay
- [GraphSession](GraphSession.md) *(from graph.py)* `top-level`
- [ModelResult](ModelResult.md) *(from graph.py)* `top-level`
- [capture_result](capture_result.md) *(from graph.py)* `top-level`
- [export_graph_json](export_graph_json.md) *(from serializer.py)* `top-level`
- [export_model_json](export_model_json.md) *(from serializer.py)* `top-level`
- [export_session_json](export_session_json.md) *(from serializer.py)* `top-level`
@@ -125,10 +121,8 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- [import_graph_json](import_graph_json.md) *(from serializer.py)* `top-level`
- [import_model_json](import_model_json.md) *(from serializer.py)* `top-level`
- [import_session_json](import_session_json.md) *(from serializer.py)* `top-level`
- [model](model.md) *(from graph.py)* `top-level`
- [replay_graph](replay_graph.md) *(from serializer.py)* `top-level`
- [replay_model_json](replay_model_json.md) *(from serializer.py)* `top-level`
- [requires_session](requires_session.md) *(from graph.py)* `top-level`
- [suspend_graph_recording](suspend_graph_recording.md) *(from graph.py)* `top-level`
## Expressions and Parameters
@@ -256,6 +250,7 @@ This index includes generated docs for the public SimpleCAD API surface, includi
## Other
- [Assembly](Assembly.md) *(from product.py)* `top-level`
- [CaptureResult](CaptureResult.md) *(from capture.py)* `top-level`
- [Component](Component.md) *(from product.py)* `top-level`
- [Connector](Connector.md) *(from product.py)* `top-level`
- [ConnectorAnchor](ConnectorAnchor.md) *(from product.py)* `top-level`
@@ -291,6 +286,7 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- [and_](and_.md) *(from ql.py)* `submodule:ql`
- [assign_material_rpart](assign_material_rpart.md) *(from operations.py)* `top-level`
- [build_product_package](build_product_package.md) *(from product_packages.py)* `top-level`
- [capture](capture.md) *(from capture.py)* `top-level`
- [constrain_angle_rsketch](constrain_angle_rsketch.md) *(from operations.py)* `top-level`
- [constrain_coincident_rsketch](constrain_coincident_rsketch.md) *(from operations.py)* `top-level`
- [constrain_collinear_rsketch](constrain_collinear_rsketch.md) *(from operations.py)* `top-level`
+1 -1
View File
@@ -10,7 +10,7 @@ class SliceSpec(plane: SlicePlane, value: float, label: str | None = None)
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.SliceSpec(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.SliceSpec(...)`; unavailable inside GraphSession
## Description
+2 -2
View File
@@ -3,7 +3,7 @@
## Class Definition
```python
class SolidWorksTranslator(document_name: str = 'SimpleCADModel', *, output_path: Optional[str] = None, visible: bool = False, source_kernel_fallback: bool = False)
class SolidWorksTranslator(document_name: str = 'SimpleCADProduct', *, output_path: str | None = None, visible: bool = False, source_kernel_fallback: bool = False)
```
*Source: translator/solidworks_translator/translator.py*
@@ -14,4 +14,4 @@ class SolidWorksTranslator(document_name: str = 'SimpleCADModel', *, output_path
## Description
Translate canonical model JSON into a SolidWorks COM Python script.
Translate one validated `.scadpkg` closure into SolidWorks automation.
+1 -1
View File
@@ -3,7 +3,7 @@
## API Definition
```python
def assemble(func: Callable[_P, _R] | None = None, *, id: str | None = None, revision: str = '1.0.0', definitions: Sequence[Any] = (), cache: CachePolicy | Mapping[str, Any] | str | None = None, export_dir: str | Path | None = None, project_root: str | Path | None = None, tolerance_profile: str = 'simplecad-default') -> Callable[[Callable[_P, _R]], Callable[_P, AssemblyBuildResult]] | Callable[_P, AssemblyBuildResult]
def assemble(func: Callable[_P, _R] | None = None, *, id: str | None = None, revision: str = '1.0.0', definitions: Sequence[Any] = (), cache: CachePolicy | Mapping[str, Any] | str | None = None, project_root: str | Path | None = None, tolerance_profile: str = 'simplecad-default') -> Callable[[Callable[_P, _R]], Callable[_P, AssemblyBuildResult]] | Callable[_P, AssemblyBuildResult]
```
*Source: build/assembly_builder.py*
+17
View File
@@ -0,0 +1,17 @@
# capture
## API Definition
```python
def capture(result: Any, path: str | Path, /) -> CaptureResult
```
*Source: capture.py*
## Import Surface
- top-level: `from simplecadapi import capture`
## Description
Capture a durable product and write its canonical `.scadpkg`.
-17
View File
@@ -1,17 +0,0 @@
# capture_result
## API Definition
```python
def capture_result(*, value: Any) -> Any
```
*Source: graph.py*
## Import Surface
- top-level: `from simplecadapi import capture_result`
## Description
Capture *value* as an explicit result in the active model session.
+1 -1
View File
@@ -10,7 +10,7 @@ def clear_step_model_cache_rnone() -> None
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.clear_step_model_cache_rnone(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.clear_step_model_cache_rnone(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def compare_boundary_distance_rdescriptor(target: ModelInput, current: ModelInpu
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_boundary_distance_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_boundary_distance_rdescriptor(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def compare_entities_rdescriptor(target: ModelInput, target_entity_id: str, curr
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_entities_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_entities_rdescriptor(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def compare_global_properties_rdescriptor(target: ModelInput, current: ModelInpu
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_global_properties_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_global_properties_rdescriptor(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def compare_inspections_rinspectionsummarycomparison(target: BRepInspection, can
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_inspections_rinspectionsummarycomparison(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_inspections_rinspectionsummarycomparison(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def compare_material_rdescriptor(target: ModelInput, current: ModelInput, *, boo
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_material_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_material_rdescriptor(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def compare_model_to_inspection_rentityinspectionparity(model: BRepModel, report
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_model_to_inspection_rentityinspectionparity(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_model_to_inspection_rentityinspectionparity(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def compare_sections_rdescriptor(target: ModelInput, current: ModelInput, plane_
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_sections_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_sections_rdescriptor(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def compare_shape_slices_rslicecomparison(target: TopoDS_Shape, candidate: TopoD
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_shape_slices_rslicecomparison(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_shape_slices_rslicecomparison(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def compare_shapes_rbrepcomparison(target: TopoDS_Shape, candidate: TopoDS_Shape
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_shapes_rbrepcomparison(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_shapes_rbrepcomparison(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def compare_step_slices_rslicecomparison(target_path: str | Path, candidate_path
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_step_slices_rslicecomparison(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_step_slices_rslicecomparison(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def compare_step_to_inspection_rentityinspectionparity(step_path: str | Path, re
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_step_to_inspection_rentityinspectionparity(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_step_to_inspection_rentityinspectionparity(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def compare_steps_rbrepcomparison(target_path: str | Path, candidate_path: str |
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_steps_rbrepcomparison(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.compare_steps_rbrepcomparison(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def evaluate_reconstruction_rdescriptor(target: ModelInput, current: ModelInput,
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.evaluate_reconstruction_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.evaluate_reconstruction_rdescriptor(...)`; unavailable inside GraphSession
## Description
-17
View File
@@ -1,17 +0,0 @@
# export_model_json_to_fcstd
## API Definition
```python
def export_model_json_to_fcstd(json_str: str, output_path: str, *, document_name: str = 'SimpleCADModel', freecad_cmd: Optional[str] = None) -> str
```
*Source: translator/freecad_translator/api.py*
## Import Surface
- translator backend: `from simplecadapi.translator.freecad_translator import export_model_json_to_fcstd`
## Description
Export canonical model JSON to `.FCStd` via FreeCADCmd/FreeCAD.
@@ -1,17 +0,0 @@
# export_model_json_to_solidworks_step
## API Definition
```python
def export_model_json_to_solidworks_step(json_str: str, output_path: str, *, document_name: str = 'SimpleCADModel', visible: bool = False, python_exe: Optional[str] = None, source_kernel_fallback: bool = False) -> str
```
*Source: translator/solidworks_translator/api.py*
## Import Surface
- translator backend: `from simplecadapi.translator.solidworks_translator import export_model_json_to_solidworks_step`
## Description
Execute SolidWorks COM automation and export a STEP file.
-17
View File
@@ -1,17 +0,0 @@
# export_product_package
## API Definition
```python
def export_product_package(package: ProductPackage, path: str | Path) -> Path
```
*Source: product_packages.py*
## Import Surface
- top-level: `from simplecadapi import export_product_package`
## Description
Write one canonical self-contained `.scadpkg` archive.
@@ -0,0 +1,17 @@
# export_product_package_to_step
## API Definition
```python
def export_product_package_to_step(data: ProductPackageInput, output_path: str | Path) -> ProductSTEPExportReport
```
*Source: exporter/step.py*
## Import Surface
- exporter namespace: `from simplecadapi import exporter` then `exporter.step.export_product_package_to_step(...)`
## Description
Export a validated `.scadpkg` closure as XCAF-backed AP242 STEP.
+20
View File
@@ -0,0 +1,20 @@
# export_product_package_to_stl
## API Definition
```python
def export_product_package_to_stl(data: ProductPackageInput, output_path: str | Path, *, mesh_size: float = 1.0, recombination_angle_degrees: float = 45.0) -> ProductSTLExportReport
```
*Source: exporter/stl.py*
## Import Surface
- exporter namespace: `from simplecadapi import exporter` then `exporter.stl.export_product_package_to_stl(...)`
## Description
Export one validated `.scadpkg` as a quad-dominant remeshed STL.
Gmsh recombines each CAD surface into quadrilaterals before its STL writer
splits every quad into two triangles, as required by the STL file format.
-50
View File
@@ -1,50 +0,0 @@
# export_step
## API Definition
```python
def export_step(shapes: Union[AnyShape, Sequence[AnyShape]], filename: str) -> None
```
*Source: operations.py*
## Import Surface
- top-level: `from simplecadapi import export_step`
## Description
Export shapes to STEP.
Use this function when you want to export one shape or many shapes into the
same STEP file. Passing `List[Solid]` is valid for pattern outputs or
explicit shape collections. Boolean operations return a single `Solid`.
## Parameters
### shapes
- **Description**: A single exportable shape or any nested sequence of exportable shapes. Lists of Solid are supported directly, including pattern or explicitly collected multi-shape results.
### filename
- **Description**: Output STEP file path.
## Returns
None: Writes the provided shapes into one STEP file.
## Examples
### Example 1
```python
main_body = make_box_rsolid(10, 4, 4, bottom_face_center=(0, 0, 0))
left_cap = make_sphere_rsolid(2.0, center=(-2.0, 2.0, 2.0))
right_cap = make_sphere_rsolid(2.0, center=(12.0, 2.0, 2.0))
body = union_rsolid(main_body, [left_cap, right_cap])
```
### Example 2
```python
export_step(body, "rounded_bar.step")
```
-50
View File
@@ -1,50 +0,0 @@
# export_stl
## API Definition
```python
def export_stl(shapes: Union[AnyShape, Sequence[AnyShape]], filename: str) -> None
```
*Source: operations.py*
## Import Surface
- top-level: `from simplecadapi import export_stl`
## Description
Export shapes to STL.
Use this function when you want to export one compound, solid, or face into
the same STL file. Passing `List[Solid]` is valid for pattern outputs or
explicit shape collections. Boolean operations return a single `Solid`.
## Parameters
### shapes
- **Description**: A single Compound, Solid, or Face, or any nested sequence of those. Lists of Solid are supported directly, including pattern or explicitly collected multi-shape results.
### filename
- **Description**: Output STL file path.
## Returns
None: Writes the provided shapes into one STL file.
## Examples
### Example 1
```python
main_body = make_box_rsolid(10, 4, 4, bottom_face_center=(0, 0, 0))
left_cap = make_sphere_rsolid(2.0, center=(-2.0, 2.0, 2.0))
right_cap = make_sphere_rsolid(2.0, center=(12.0, 2.0, 2.0))
body = union_rsolid(main_body, [left_cap, right_cap])
```
### Example 2
```python
export_stl(body, "rounded_bar.stl")
```
+1 -1
View File
@@ -10,7 +10,7 @@ def index_shape_rbrepmodel(shape: TopoDS_Shape, *, source: str | Path | None = N
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.index_shape_rbrepmodel(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.index_shape_rbrepmodel(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def inspect_difference_regions_rdescriptor(target: ModelInput, current: ModelInp
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_difference_regions_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_difference_regions_rdescriptor(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def inspect_face_boundaries_rdescriptor(model_or_path: BRepModel | TopoDS_Shape
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_face_boundaries_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_face_boundaries_rdescriptor(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def inspect_nearby_entities_rdescriptor(model: ModelInput, *, location: Sequence
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_nearby_entities_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_nearby_entities_rdescriptor(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def inspect_point_rdescriptor(model_or_path: BRepModel | TopoDS_Shape | str | Pa
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_point_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_point_rdescriptor(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def inspect_section_rdescriptor(model_or_path: BRepModel | TopoDS_Shape | str |
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_section_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_section_rdescriptor(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def inspect_shape_rbrepinspection(shape: TopoDS_Shape, *, source: str | Path | N
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_shape_rbrepinspection(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_shape_rbrepinspection(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def inspect_step_components_rdescriptorlist(step_path: str | Path) -> list[dict[
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_step_components_rdescriptorlist(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_step_components_rdescriptorlist(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def inspect_step_entity_rdescriptor(path: str | Path, entity_id: str, *, include
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_step_entity_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_step_entity_rdescriptor(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def inspect_step_rbrepinspection(path: str | Path) -> BRepInspection
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_step_rbrepinspection(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_step_rbrepinspection(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def inspect_step_rsummary(path: str | Path, *, include_parameter_groups: bool =
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_step_rsummary(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_step_rsummary(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def inspect_topology_neighborhood_rdescriptor(model_or_path: BRepModel | TopoDS_
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_topology_neighborhood_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.inspect_topology_neighborhood_rdescriptor(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def load_step_rbrepmodel(path: str | Path) -> BRepModel
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.load_step_rbrepmodel(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.load_step_rbrepmodel(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def load_step_rshape(path: str | Path, *, require_single_root: bool = True, requ
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.load_step_rshape(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.load_step_rshape(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def make_center_slice_specs_rslicespeclist(minimum: np.ndarray, maximum: np.ndar
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.make_center_slice_specs_rslicespeclist(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.make_center_slice_specs_rslicespeclist(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def measure_entity_relation_rdescriptor(model_or_path: BRepModel | TopoDS_Shape
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.measure_entity_relation_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.measure_entity_relation_rdescriptor(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def measure_shape_mass_rtuple(shape: TopoDS_Shape, kind: PropertyKind) -> tuple[
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.measure_shape_mass_rtuple(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.measure_shape_mass_rtuple(...)`; unavailable inside GraphSession
## Description
-17
View File
@@ -1,17 +0,0 @@
# model
## API Definition
```python
def model(func: Optional[Callable[_P, _R]] = None, *, graph_id: Optional[str] = None, export_dir: str | Path | None = None) -> Union[Callable[[Callable[_P, _R]], Callable[_P, ModelResult]], Callable[_P, ModelResult]]
```
*Source: graph.py*
## Import Surface
- top-level: `from simplecadapi import model`
## Description
Decorate a top-level model function with one owned ``GraphSession``.
+1 -1
View File
@@ -3,7 +3,7 @@
## API Definition
```python
def part(func: Callable[_P, _R] | None = None, *, id: str | None = None, revision: str = '1.0.0', inputs: Sequence[FileInput] = (), cache: CachePolicy | Mapping[str, Any] | str | None = None, export_dir: str | Path | None = None, project_root: str | Path | None = None, tolerance_profile: str = 'simplecad-default') -> Callable[[Callable[_P, _R]], Callable[_P, PartBuildResult]] | Callable[_P, PartBuildResult]
def part(func: Callable[_P, _R] | None = None, *, id: str | None = None, revision: str = '1.0.0', inputs: Sequence[FileInput] = (), cache: CachePolicy | Mapping[str, Any] | str | None = None, project_root: str | Path | None = None, tolerance_profile: str = 'simplecad-default') -> Callable[[Callable[_P, _R]], Callable[_P, PartBuildResult]] | Callable[_P, PartBuildResult]
```
*Source: build/part_builder.py*
+1 -1
View File
@@ -10,7 +10,7 @@ def render_entity_kind_maps_rpath(model_or_path: BRepModel | TopoDS_Shape | str
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_entity_kind_maps_rpath(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_entity_kind_maps_rpath(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def render_entity_map_rpath(model_or_path: BRepModel | TopoDS_Shape | str | Path
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_entity_map_rpath(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_entity_map_rpath(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def render_region_rpath(model_or_path: BRepModel | TopoDS_Shape | str | Path, en
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_region_rpath(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_region_rpath(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def render_shape_views_rpath(shape: TopoDS_Shape, output_path: str | Path, *, ti
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_shape_views_rpath(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_shape_views_rpath(...)`; unavailable inside GraphSession
## Description
@@ -10,7 +10,7 @@ def render_step_components_colored_rpath(step_path: str | Path, component_colors
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_step_components_colored_rpath(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_step_components_colored_rpath(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def render_step_components_rpath(step_path: str | Path, component_names: Sequenc
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_step_components_rpath(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_step_components_rpath(...)`; unavailable inside GraphSession
## Description
+1 -1
View File
@@ -10,7 +10,7 @@ def render_step_views_rpath(step_path: str | Path, output_path: str | Path, **kw
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_step_views_rpath(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.render_step_views_rpath(...)`; unavailable inside GraphSession
## Description
-17
View File
@@ -1,17 +0,0 @@
# requires_session
## API Definition
```python
def requires_session(func: Optional[Callable[_P, _R]] = None) -> Union[Callable[[Callable[_P, _R]], Callable[_P, _R]], Callable[_P, _R]]
```
*Source: graph.py*
## Import Surface
- top-level: `from simplecadapi import requires_session`
## Description
Decorate a builder that must reuse the caller's active GraphSession.
@@ -10,7 +10,7 @@ def select_region_entities_rdescriptor(model_or_path: BRepModel | TopoDS_Shape |
## Import Surface
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.select_region_entities_rdescriptor(...)`; unavailable inside GraphSession/@model
- inspection namespace: `from simplecadapi.inspect import brep` then `brep.select_region_entities_rdescriptor(...)`; unavailable inside GraphSession
## Description
-40
View File
@@ -1,40 +0,0 @@
# translate_model_json_to_fcstd
## API Definition
```python
def translate_model_json_to_fcstd(json_str: str, output_path: str, *, document_name: str = 'SimpleCADModel', freecad_cmd: Optional[str] = None) -> str
```
*Source: translator/freecad_translator/api.py*
## Import Surface
- translator backend: `from simplecadapi.translator.freecad_translator import translate_model_json_to_fcstd`
## Description
Translate canonical model JSON to `.FCStd` via FreeCADCmd/FreeCAD.
Functional sketch promotions are written as visible `Sketcher::SketchObject`
nodes with mapped/skipped constraint evidence. Exact B-spline edges are
exported to FreeCAD using `Part.BSplineCurve().buildFromPolesMultsKnots(...)`.
Safe single-use profile transforms such as section rotate/translate chains are
folded into the section object's placement so downstream `Part::Loft` receives
already-positioned sections instead of placement-bearing `App::Link` proxies.
Geometry results use FreeCAD objects directly: assignment targets name design
objects and shared inputs receive independent occurrences per consumer. Native
features preserve recomputing dependencies, including surface-dependent
Booleans. Their classifications may vary across FreeCAD/OCCT versions. No
presentation proxy, duplicate history tree, or hidden graph-object archive is
created.
`apply_tag_rselection` remains graph metadata rather than a FreeCAD feature;
traceable geometry and visible result objects expose `SimpleCADAppliedTags`,
`SimpleCADTagBindings`, and `SimpleCADTagNodeIds`.
Part/Assembly product nodes are written as editable FreeCAD assembly structure:
parts use `App::Part`, assemblies use native `Assembly::AssemblyObject`, part
components use `App::Link`, and nested assembly components use
`Assembly::AssemblyLink`. Explicit assembly-to-compound projections remain
available for geometry workflows without creating a second user-facing root.
Link source definitions remain in the document for recomputation, but the
Tree View exposes only the resolved product or standalone-geometry roots.
@@ -1,30 +0,0 @@
# translate_model_json_to_freecad_script
## API Definition
```python
def translate_model_json_to_freecad_script(json_str: str, document_name: str = 'SimpleCADModel') -> str
```
*Source: translator/freecad_translator/api.py*
## Import Surface
- translator backend: `from simplecadapi.translator.freecad_translator import translate_model_json_to_freecad_script`
## Description
Translate exported model JSON into a FreeCAD Python script.
Geometry is emitted as FreeCAD occurrence trees. Serialized source assignment
targets name native design objects, shared DAG inputs are copied per consuming
result, and feature links preserve dependencies. Booleans are emitted as native
recomputable `Part::Cut`, `Part::Fuse`, and `Part::Common` features. Stable node
ids remain available as internal metadata.
`apply_tag_rselection` nodes do not create FreeCAD features. Their canonical
bindings and source node ids are attached to traceable geometry and visible
result objects as `SimpleCADAppliedTags`, `SimpleCADTagBindings`, and
`SimpleCADTagNodeIds`.
The Tree View exposes only resolved product or standalone-geometry roots.
Assembly projection compounds and link source definitions remain available
for recomputation but are hidden from the user-facing document tree.
@@ -1,17 +0,0 @@
# translate_model_json_to_fusion360_script
## API Definition
```python
def translate_model_json_to_fusion360_script(json_str: str, document_name: str = 'SimpleCADModel', result_node_ids: Optional[Sequence[str]] = None, *, selection_mode: str = 'gsm', source_kernel_fallback: bool = False) -> str
```
*Source: translator/fusion360_translator/api.py*
## Import Surface
- translator backend: `from simplecadapi.translator.fusion360_translator import translate_model_json_to_fusion360_script`
## Description
Translate canonical model JSON into a Fusion 360 Python script.
@@ -1,17 +0,0 @@
# translate_model_json_to_solidworks_script
## API Definition
```python
def translate_model_json_to_solidworks_script(json_str: str, document_name: str = 'SimpleCADModel', *, output_path: Optional[str] = None, visible: bool = False, source_kernel_fallback: bool = False) -> str
```
*Source: translator/solidworks_translator/api.py*
## Import Surface
- translator backend: `from simplecadapi.translator.solidworks_translator import translate_model_json_to_solidworks_script`
## Description
Translate canonical model JSON into a SolidWorks automation script.
@@ -0,0 +1,17 @@
# translate_product_package_to_fcstd
## API Definition
```python
def translate_product_package_to_fcstd(data: ProductPackageInput, output_path: str, *, document_name: str = 'SimpleCADProduct', freecad_cmd: Optional[str] = None) -> str
```
*Source: translator/freecad_translator/api.py*
## Import Surface
- translator backend: `from simplecadapi.translator.freecad_translator import translate_product_package_to_fcstd`
## Description
Translate one validated `.scadpkg` closure into an editable `.FCStd`.
@@ -0,0 +1,17 @@
# translate_product_package_to_freecad_script
## API Definition
```python
def translate_product_package_to_freecad_script(data: ProductPackageInput, document_name: str = 'SimpleCADProduct') -> str
```
*Source: translator/freecad_translator/api.py*
## Import Surface
- translator backend: `from simplecadapi.translator.freecad_translator import translate_product_package_to_freecad_script`
## Description
Translate one validated `.scadpkg` closure into a FreeCAD script.
@@ -0,0 +1,17 @@
# translate_product_package_to_fusion360_script
## API Definition
```python
def translate_product_package_to_fusion360_script(data: ProductPackageInput, document_name: str = 'SimpleCADProduct', *, selection_mode: str = 'gsm', source_kernel_fallback: bool = False) -> str
```
*Source: translator/fusion360_translator/api.py*
## Import Surface
- translator backend: `from simplecadapi.translator.fusion360_translator import translate_product_package_to_fusion360_script`
## Description
Translate one validated `.scadpkg` closure into a Fusion 360 script.
@@ -0,0 +1,17 @@
# translate_product_package_to_solidworks_script
## API Definition
```python
def translate_product_package_to_solidworks_script(data: ProductPackageInput, document_name: str = 'SimpleCADProduct', *, output_path: str | None = None, visible: bool = False, source_kernel_fallback: bool = False) -> str
```
*Source: translator/solidworks_translator/api.py*
## Import Surface
- translator backend: `from simplecadapi.translator.solidworks_translator import translate_product_package_to_solidworks_script`
## Description
Translate one validated `.scadpkg` closure into SolidWorks automation.
+7 -7
View File
@@ -51,15 +51,15 @@ SimpleCADAPI 的顶层 API 选择是正确的:它没有把用户拖进传统 C
- `GraphSession` + `export_model_json` + `replay_model_json` 的主线是对的。它把脚本建模提升为可交换、可 replay 的模型记录。参考:`src/simplecadapi/graph.py:44`、`src/simplecadapi/serializer.py:416`、`src/simplecadapi/serializer.py:732`。
- `ql` 被放到子模块而非全部塞进顶层,是正确的边界意识。参考:`src/simplecadapi/__init__.py`、`docs/api/README.md:5`。
问题:
当前问题与已完成清理:
- 顶层 API 被 aliases 稀释了。`create_box`、`create_line`、`extrude`、`union`、`to_step` 等别名降低了 canonical API 的唯一性。对用户友好,但对文档、LLM、图记录和长期兼容不友好。参考:`src/simplecadapi/__init__.py:145`、`src/simplecadapi/__init__.py:318`。
- README 说 API 函数统一用 return type 反映命名,但公开面包含 `translate_shape`、`rotate_shape`、`export_step`、`export_stl` 和大量 aliases。这个声明过强。参考:`README.md:200`、`src/simplecadapi/__init__.py:47`、`src/simplecadapi/__init__.py:187`。
- `rsolidlist` 命名混杂了“参数类型”和“返回类型”:`cut_rsolid`、`intersect_rsolid` 实际返回 `Solid`,而 `linear_pattern_rsolidlist` 返回 `List[Solid]`。这会伤害 API 语义一致性。参考:`src/simplecadapi/operations.py:2994`、`src/simplecadapi/operations.py:3102`、`src/simplecadapi/operations.py:4121`。
- public op 名和 graph op 名不完全一致:`translate_shape` 记录为 `make_translate_rshape`,`extrude_rsolid` 记录为 `make_extrude_rsolid`。这种分层可以接受,但必须正式化为“source API”和“canonical IR”的稳定映射表。参考:`src/simplecadapi/operations.py:117`、`src/simplecadapi/serializer.py:116`。
- 一些非 session 分支仍记录 legacy op 名,如 `make_box`、`make_cylinder`、`make_segment_wire`,和 canonical `make_*_r*` 命名不一致。参考:`src/simplecadapi/operations.py:785`、`src/simplecadapi/operations.py:1534`、`src/simplecadapi/operations.py:1638`。
- 已完成:顶层 convenience aliases 以及 `export_step`、`export_stl`、`to_step`、`to_stl` 已从公开面移除,不保留兼容转发。
- 已完成:持久产品只通过 `capture(result, path)` 写出 `.scadpkg`;STEP、STL 和原生 CAD 输出从该产品包显式派生。
- 仍需关注:`rsolidlist` 命名混杂了“参数类型”和“返回类型”:`cut_rsolid`、`intersect_rsolid` 实际返回 `Solid`,而 `linear_pattern_rsolidlist` 返回 `List[Solid]`。
- 仍需关注:public op 名和 graph op 名不完全一致,例如 `translate_shape` 记录为 `make_translate_rshape`,`extrude_rsolid` 记录为 `make_extrude_rsolid`;这种分层需要稳定的 source API 到 canonical IR 映射。
- 仍需关注:部分非 session 分支记录的 graph op 命名与 canonical `make_*_r*` 形式不一致,需要继续收敛。
建议:保留 `make_*_r*`,但把 aliases 降级为 compatibility surface,不作为文档主路径;把 source API 到 canonical graph op 的映射写成稳定规范;把 `rsolidlist` 这种历史命名列入 3.0 前清理清单。
后续重点是稳定 source API 到 canonical graph op 的映射,并在下一次不兼容版本中清理剩余历史命名。
## 函数式架构评价
@@ -52,19 +52,21 @@ SimpleCAD package is imported, and must be assembled in one declared order.
## Translation And Export
Translation is an in-memory operation. It consumes canonical model JSON or an
already imported canonical payload and returns a `TranslationArtifact`.
Translation is an in-memory operation over a validated product-package closure.
It consumes `ProductPackageInput` and returns a `TranslationArtifact` containing
the target script or native artifact description.
Export is an effectful operation. It may write files, invoke an executable, or
call a remote API. Those effects belong in `exporter.py`, not in the translator
or emitters.
call a remote API. Neutral product file effects belong in `simplecadapi.exporter`;
backend-specific executable effects belong in the backend exporter module.
Public naming follows these forms:
- `translate_model_json_to_<artifact>` for in-memory conversion.
- `export_model_json_to_<format>` for file or external-runtime output.
- `translate_product_package_to_<artifact>` for in-memory product translation.
- `export_product_package_to_<format>` for neutral product file output.
Existing public names may remain as compatibility aliases.
Standalone model JSON translation and export entrances are removed. Model JSON
remains a graph replay and inspection format, not a downstream CAD contract.
## Dependencies
+6 -7
View File
@@ -66,7 +66,7 @@ SimpleWorkplane ← local modeling context
- **Shape-first API**: users work with `Vertex`, `Edge`, `Wire`, `Face`, `Shell`, and `Solid`, not graph nodes.
- **Functional modeling style**: public operations return new geometry values, e.g. `make_box_rsolid(...)`, `cut_rsolid(...)`, `fillet_rsolid(...)`.
- **OCP-native runtime**: geometry construction, topology traversal, properties, booleans, transforms, and export use OCP/OpenCascade helpers.
- **Replayable graph workflows**: `@scad.model` owns one `GraphSession` and returns a `ModelResult`; `@scad.requires_session` composes child builders, and `scad.capture_result()` selects canonical output nodes for replay and export.
- **Replayable graph workflows**: an explicit `GraphSession` records operations, `session.capture_result()` selects canonical output nodes, and `export_model_json()` plus `replay_model_json()` provide interchange and replay.
- **Tags and metadata**: tags are useful for lightweight semantics; structured numeric facts should be stored in metadata such as `metadata["geo"]`.
- **Indexed topology access**: use plural methods such as `get_edges()` and `get_faces()` for enumeration, and pass an index to the same getter, such as `get_edges(index)` or `get_faces(index)`, for intentional indexed picks that should become graph selection nodes.
@@ -93,19 +93,18 @@ print(len(top_faces))
```python
import simplecadapi as scad
from simplecadapi import GraphSession, export_model_json, replay_model_json
@scad.model(graph_id="drilled_block")
def build_model():
with GraphSession(graph_id="drilled_block") as session:
body = scad.make_box_rsolid(width=10, height=10, depth=4)
hole = scad.make_cylinder_rsolid(
radius=1.5, height=8, bottom_face_center=(0, 0, -2)
)
part = scad.cut_rsolid(body, hole)
scad.capture_result(value=part)
return part
session.capture_result(value=part)
payload = export_model_json(session=session)
result = build_model()
rebuilt = result.replay()
rebuilt = replay_model_json(json_str=payload)
print(len(rebuilt))
```
+3 -3
View File
@@ -68,10 +68,10 @@ Removed public APIs include:
- `stack_rassembly`
- `stack`
Current supported workflows should model final parts as ordinary geometry:
Current supported workflows should model durable products through explicit boundaries:
- Use `translate_shape(...)`, `rotate_shape(...)`, and `mirror_shape(...)` for explicit placement.
- Use Python sequences of `Solid` objects plus `export_step([...], path)` / `export_stl(...)` for multi-body exports.
- Use `@scad.part` for one physical solid and `@scad.assemble` for a multi-part product.
- Use `scad.capture(result, path)` as the only public `.scadpkg` write boundary.
- Use `union_rsolid(...)`, `cut_rsolid(...)`, and `intersect_rsolid(...)` when a single merged solid is required.
`export_model_json(...)` no longer accepts `assembly=...`, and newly exported model JSON does not include `assembly`, `assembly_registry`, or `constraint_registry` fields.
+2 -2
View File
@@ -371,8 +371,8 @@ projection:
- The outer sleeve is one single-body `Part` with a barrel, gland flange, bolt-hole details, rear eye, and pin hole.
- The inner piston rod is another single-body `Part` with piston lands, a seal groove, chrome rod, rod-eye neck, and rod-eye pin hole.
- The final `Assembly` instantiates both parts with component placement.
- `make_compound_from_assembly_rcompound(...)` produces the flattened preview/STEP projection.
- `translate_model_json_to_fcstd(...)` writes a native FreeCAD Assembly Workbench document where the assembly tree remains visible and editable.
- `make_compound_from_assembly_rcompound(...)` produces the flattened preview projection; `scad.exporter.export_product_package_to_step(...)` writes the package STEP projection.
- `scad.translator.freecad_translator.translate_product_package_to_fcstd(...)` writes a native FreeCAD Assembly Workbench document where the assembly tree remains visible and editable.
Run it from the source checkout:
+12 -16
View File
@@ -9,20 +9,19 @@ The long-form schema reference remains [`../operation_graph_json_spec.md`](../op
```python
import json
import simplecadapi as scad
from simplecadapi import GraphSession, export_model_json, replay_model_json
@scad.model(graph_id="drilled_block")
def build_model():
with GraphSession(graph_id="drilled_block") as session:
body = scad.make_box_rsolid(width=10, height=6, depth=2)
hole = scad.make_cylinder_rsolid(
radius=1, height=4, bottom_face_center=(0, 0, -1)
)
result = scad.cut_rsolid(body, hole)
scad.capture_result(value=result)
return result
session.capture_result(value=result)
model_json = export_model_json(session=session)
model = build_model()
payload = json.loads(model.model_json)
rebuilt = model.replay()
payload = json.loads(model_json)
rebuilt = replay_model_json(json_str=model_json)
```
Inspect these fields:
@@ -36,15 +35,12 @@ Inspect these fields:
- `payload["expression_graph"]`: expression DAG used by expression-backed parameters.
- `payload["tolerance_graph"]`: dimension-chain requirements and validation evidence.
For new top-level models, `ModelResult.model_json` is the preferred artifact
accessor. Use `@scad.requires_session` for reusable builders and
`scad.capture_result(...)` when the final output should not be inferred from
all graph leaves. If a model invocation also needs durable CAD/viewer files,
pass `export_dir=...` to `@scad.model`; its captured geometry/product values
then produce one self-contained `<graph_id>.scene.zip`. It embeds
`model/model.json`, mapped project-relative Python sources, and the evaluated
render/selection assets. It does not create adjacent model/session JSON, STEP,
STL, or FCStd files. No files are written when `export_dir` is omitted.
Use `session.capture_result(...)` when the final output should not be inferred
from all graph leaves, and treat `export_model_json(session=...)` as the
interchange boundary for direct graph workflows. Durable CAD/viewer products use
`@scad.part` or `@scad.assemble`, then `scad.capture(result, "out/product.scadpkg")`
to build and write one canonical self-contained package. No files are written
unless an export API is called.
## Important rule: source API is not always graph API
+2 -1
View File
@@ -5,7 +5,8 @@
reusable prompt for controlled, comparable STEP reconstruction trials.
- [Persistent Cache and Product Build Workflow](cache-build-workflow.md):
durable `@part`/`@assemble` boundaries, PRT reuse, unified cache policy,
incremental invalidation, diagnostics, repair, and maintenance.
diagnostics, `.scadpkg` delivery, FreeCAD/AP242 targets, and optional Gmsh
volume meshing.
The corresponding runnable module and examples live in:
+63 -18
View File
@@ -61,10 +61,10 @@ fixture = build_fixture()
print(fixture.solve_report.component_hits, fixture.solve_report.component_misses)
```
`@scad.part` and `@scad.assemble` are top-level product boundaries and cannot be
nested inside an active `GraphSession`. Continue to use `@scad.model` plus
`@scad.requires_session` for a replayable geometry flow that is not a durable
part/assembly definition.
`@scad.part` and `@scad.assemble` are top-level product boundaries and each owns
its definition-local `GraphSession`; they cannot be nested inside another active
session. Use an explicit `GraphSession` for lower-level replayable geometry that
is not a durable part or assembly definition.
## Policy
@@ -121,23 +121,68 @@ format.
## Product package export
`PartBuildResult` and `AssemblyBuildResult` export one public product format:
the canonical self-contained `.scadpkg` archive. It contains a thin
`package.json` manifest plus the complete content-addressed closure of canonical
`PartDefinition` and `AssemblyDefinition` archives. Repeated definitions are
stored once; assembly instances and relations remain in the ASM definitions.
`PartBuildResult` and `AssemblyBuildResult` are captured and written as one
canonical product package by a single API call:
```python
part_package = warm.export_artifacts(output_dir="out")
assembly_package = fixture.export_artifacts(output_dir="out")
scad.capture(warm, "out/part.scadpkg")
scad.capture(fixture, "out/assembly.scadpkg")
root = scad.load_product_package(assembly_package.artifact_paths["product"])
root = scad.load_product_package("out/assembly.scadpkg")
rebuilt = scad.materialize_definition(root)
```
Use `build_product_package(...)`, `export_product_package(...)`,
`read_product_package(...)`, and `load_product_package(...)` for explicit
package handling. `validate_product_package(...)` verifies every object hash and
size, the complete recursive definition graph, cycle/depth limits, and rejects
missing or unreferenced objects. Keep `export_definition(...)` only for low-level
definition exchange or inspection; it is not the product delivery format.
Use `build_product_package(...)`, `encode_product_package(...)`,
`read_product_package(...)`, and `load_product_package(...)` only for explicit
in-memory package handling. `validate_product_package(...)` verifies every object
hash and size, the complete recursive definition graph, cycle/depth limits, and
rejects missing or unreferenced objects. Use `export_part_definition(...)` or
`export_assembly_definition(...)` only for low-level definition exchange or
inspection; neither is the product delivery format.
## Downstream CAD and mesh targets
Keep `.scadpkg` as the canonical SimpleCAD delivery artifact. Choose a
downstream target from the consumer contract:
| Target | Use when | Preserved contract | Boundary |
| --- | --- | --- | --- |
| `.scadpkg` | Rebuild, replay, cache, or further SimpleCAD editing is required | Complete durable definition closure, feature graphs, source snapshots, topology, connectors, constraints, and materials | SimpleCAD-specific archive |
| `.FCStd` | A FreeCAD user needs an editable native document | Definition-owned, dependency-first native feature graphs; final body links; repeated instances; nested assemblies; names; solved placements; materials; connectors; constraints; grounding; revision; and content hashes | Requires FreeCADCmd/FreeCAD |
| AP242 `.step` | Neutral CAD exchange or downstream OpenCASCADE tooling is required | Evaluated BREP, product hierarchy, shared definitions, occurrence names/placements, materials, colors, density, and named SimpleCAD property payloads | Canonical feature history is not reconstructed as AP242 features |
```python
package_path = assembly_package.artifact_paths["product"]
fcstd_path = scad.translator.freecad_translator.translate_product_package_to_fcstd(
package_path,
"out/product.FCStd",
)
step_report = scad.exporter.export_product_package_to_step(
package_path,
"out/product.step",
)
stl_report = scad.exporter.export_product_package_to_stl(
package_path,
"out/product.stl",
)
print(step_report.definition_ids, step_report.occurrence_count)
print(stl_report.solid_count, stl_report.stl_triangle_count)
```
AP242 definition and occurrence metadata is stored in one standard
`PROPERTY_DEFINITION_REPRESENTATION`. Its named
`DESCRIPTIVE_REPRESENTATION_ITEM` records use
`SimpleCAD:definition:<kind>:<definition_id>` and
`SimpleCAD:occurrence:<parent_definition_id>:<component_id>`. Each description
is canonical sorted JSON containing durable IDs, revision, content hash,
connectors, constraints, grounding, name, and solved placement.
`ProductSTEPExportReport` reports the schema, definition IDs, occurrence
count, material IDs, metadata item count, and explicit limitations.
For tetrahedral meshing, install `simplecadapi[gmsh]` and run
`examples/12_ap242_gmsh_volume_mesh.py`. The example exports one `.scadpkg`,
converts it to AP242 STEP, imports it with Gmsh's OpenCASCADE kernel, rejects
imports with no 3D volumes, generates a dimension-3 mesh, writes `.msh`, and
always finalizes Gmsh. Gmsh remains optional and is never imported by the core
SDK or the product exporters.
@@ -294,7 +294,7 @@ The program must:
- run in a fresh process;
- export `{CASE_NAME}_rebuilt.step` under `OUTPUT_DIR`;
- produce a valid BREP;
- use `@scad.model` and strict replay when supported;
- record supported feature operations in an explicit `GraphSession` and verify strict replay;
- clearly label exact transcription, fitting, and approximation.
Prefer compact design intent over arbitrary point clouds. Do not describe a
+2 -2
View File
@@ -10,8 +10,8 @@ src/simplecadapi/inspect/brep/
All of these functions are diagnostic, tool-grade APIs, not modeling
operations: they do not record graph nodes and must not run inside a
`GraphSession` or `@model` modeling script. Export or obtain the geometry
under test first, then call them outside the modeling script:
`GraphSession`. Export or obtain the geometry under test first, then call them
outside the modeling script:
```python
from simplecadapi.inspect import brep
+29 -7
View File
@@ -67,7 +67,25 @@ Inspection and default prune are read-only. Explicit `--repair`, `--apply`, or
object presence, byte length, and SHA-256. Namespace clearing preserves objects
still referenced elsewhere.
## 6. Native render crash isolation
## 6. Product-package CAD translation
Validated `.scadpkg` definition closures now translate to one editable FreeCAD
document or one XCAF-backed AP242 STEP file. FreeCAD output uses a
dependency-first definition registry so repeated parts, nested assemblies,
occurrence names, solved placements, materials, connectors, constraints,
grounding, revision, and content hashes survive in native document structure.
AP242 output uses `AP242_MANAGED_MODEL_BASED_3D_ENGINEERING`, preserves evaluated
BREP and product occurrences, and writes materials, colors, density, plus named
definition/occurrence properties. The property descriptions contain canonical
sorted JSON for durable IDs and semantics. Feature history is not reconstructed
as AP242 features; `.scadpkg` remains the canonical replayable artifact.
The optional `gmsh` extra and `examples/12_ap242_gmsh_volume_mesh.py` demonstrate
`.scadpkg -> AP242 STEP -> tetrahedral .msh` without adding Gmsh to the core
runtime dependency set.
## 7. Native render crash isolation
On macOS, VTK 9.5's Cocoa offscreen backend can terminate the interpreter with
`SIGSEGV` after repeated or concurrent render-window use. Inspection and SDK
@@ -76,7 +94,7 @@ workers guarded by a cross-process lock. Completion markers distinguish a
finished image from a partial native crash; incomplete workers retry, while a
post-write teardown crash cannot terminate the modeling or test process.
## 7. Verification
## 8. Verification
Regression coverage exercises artifact schema closure, deterministic IDs and
@@ -84,15 +102,19 @@ hashes, atomic concurrent write deduplication, corruption quarantine, all cache
modes, in-process same-key PRT reuse, concurrent PRT build deduplication,
cross-wrapper persistent part restore, interface invalidation, assembly
definition DAGs, incremental dependency propagation, residual verification,
and nested connector changes.
nested connector changes, translator backend contracts, and generated API docs.
The representative external-reference gear-train smoke builds two cached parts,
solves repeated and nested assembly instances, exports an independent assembly
definition archive, reloads it, materializes it, and verifies nested constraint
residuals.
The nested package smoke writes and reads a native FreeCAD hierarchy with shared
definitions and solved placements. AP242 round-trip checks the managed-model
schema, five-level product explorer records, material and color data, plus seven
named metadata property items for three definitions and four occurrences. The
Gmsh smoke imports AP242 as one 3D volume and generates a non-empty tetrahedral
mesh.
## Related documentation
- [Persistent cache and product build workflow](../guides/cache-build-workflow.md)
- [Product package STEP/STL export APIs](../api/export_product_package_to_step.md)
- [Editable FreeCAD product package API](../api/translate_product_package_to_fcstd.md)
- [Modeling workflows](../../skills/simplecadapi/references/MODELING_WORKFLOWS.md)
- [Previous 2.0.4b2 update notes](2.0.4b2.md)
+1 -1
View File
@@ -6,6 +6,6 @@ out/
*.FCBak
*.fcstd
*.fcbak
*.scene.zip
*.scadpkg
*.zip
*.log
+59 -24
View File
@@ -10,11 +10,19 @@ from pathlib import Path
import simplecadapi as scad
OUT = Path("examples/out")
OUT = Path(__file__).resolve().parent / "out" / "dimension_tolerance_chain"
PACKAGE_PATH = OUT / "dimension_tolerance_chain.scadpkg"
STEP_PATH = OUT / "dimension_tolerance_chain.step"
FCSTD_PATH = OUT / "dimension_tolerance_chain.FCStd"
@scad.model(graph_id="dimension_tolerance_chain")
def build_model():
@scad.part(
id="dimension_tolerance_chain",
revision="1.0.0",
cache="off",
project_root=Path(__file__).resolve().parents[1],
)
def build_dimension_tolerance_chain_part() -> scad.Part:
housing_span = scad.var(
name="housing_span",
default=100.0,
@@ -38,13 +46,8 @@ def build_model():
comment="Spacer width",
)
axial_clearance = housing_span - bearing_width - spacer_width
worst_case = scad.analyze_tolerance(
value=axial_clearance,
method="worst_case",
)
rss = scad.analyze_tolerance(value=axial_clearance, method="rss")
scad.analyze_tolerance(value=axial_clearance, method="worst_case")
scad.analyze_tolerance(value=axial_clearance, method="rss")
housing = scad.make_box_rsolid(
width=housing_span,
height=10.0,
@@ -54,7 +57,7 @@ def build_model():
)
session = scad.get_active_session()
if session is None:
raise RuntimeError("dimension tolerance model has no active session")
raise RuntimeError("dimension tolerance builder requires an active session")
session.require_tolerance(
value=axial_clearance,
tolerance=(-0.25, 0.24),
@@ -62,28 +65,60 @@ def build_model():
method="worst_case",
name="axial_clearance",
)
report = session.validate_tolerances(raise_on_failure=True)
scad.capture_result(value=housing)
return {
"housing": housing,
session.validate_tolerances(raise_on_failure=True)
return scad.make_part_rpart(
part_id="dimension_tolerance_chain",
body=housing,
name="Dimension tolerance chain housing",
)
def build_model():
result = build_dimension_tolerance_chain_part()
session = result.feature_graph.restore_session()
requirement = session.tolerance_graph.requirements[0]
expression = session.expression_graph.get(requirement.target_expr_id)
if expression is None:
raise RuntimeError("tolerance target expression was not restored")
worst_case = scad.analyze_tolerance(value=expression, method="worst_case")
rss = scad.analyze_tolerance(value=expression, method="rss")
data = {
"housing": result.part,
"worst_case": worst_case,
"rss": rss,
"report": report,
"report": session.validate_tolerances(raise_on_failure=True),
}
return (
data,
scad.export_model_json(session),
scad.export_session_json(session),
result,
)
def main() -> None:
OUT.mkdir(parents=True, exist_ok=True)
result = build_model()
report_data = result.value
report_data, model_json, session_json, result = build_model()
(OUT / "dimension_tolerance_chain.model.json").write_text(
result.model_json,
model_json,
encoding="utf-8",
)
(OUT / "dimension_tolerance_chain.session.json").write_text(
session_json,
encoding="utf-8",
)
package_path = OUT / "dimension_tolerance_chain.scadpkg"
scad.capture(result, package_path)
step_report = scad.exporter.export_product_package_to_step(package_path, STEP_PATH)
scad.translator.freecad_translator.translate_product_package_to_fcstd(
package_path,
str(FCSTD_PATH),
document_name="DimensionToleranceChain",
)
worst_case = report_data["worst_case"]
rss = report_data["rss"]
print("housing_volume", round(report_data["housing"].get_volume(), 3))
print("housing_volume", round(report_data["housing"].body.get_volume(), 3))
print(
"worst_case",
round(worst_case.nominal, 3),
@@ -98,10 +133,10 @@ def main() -> None:
round(rss.upper_bound, 3),
)
print("requirements_passed", report_data["report"].passed)
print(
"serialized_tolerance_graph",
"tolerance_graph" in json.loads(result.model_json),
)
print("serialized_tolerance_graph", "tolerance_graph" in json.loads(model_json))
print("product_package", package_path)
print("ap242_step", step_report.output_path)
print("fcstd", FCSTD_PATH)
if __name__ == "__main__":
+71 -70
View File
@@ -6,7 +6,7 @@ Run from the repository root with:
Generated files:
examples/out/constrained_sketch.model.json
examples/out/constrained_sketch.step
examples/out/constrained_sketch.fcstd
examples/out/constrained_sketch.FCStd
When the intent is a sketch/profile, use the sketch APIs. Concrete geometry
APIs remain for paths, pure geometry, and lowering targets.
@@ -20,11 +20,11 @@ from pathlib import Path
import simplecadapi as scad
OUT = Path("examples/out")
OUT = Path(__file__).resolve().parent / "out" / "constrained_sketch"
MODEL_JSON_PATH = OUT / "constrained_sketch.model.json"
SESSION_JSON_PATH = OUT / "constrained_sketch.session.json"
STEP_PATH = OUT / "constrained_sketch.step"
FCSTD_PATH = OUT / "constrained_sketch.fcstd"
FREECAD_CMD = Path("/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd")
FCSTD_PATH = OUT / "constrained_sketch.FCStd"
def _solve_and_report(name: str, sketch: scad.Sketch) -> None:
@@ -53,7 +53,6 @@ def _solve_and_report(name: str, sketch: scad.Sketch) -> None:
)
@scad.requires_session
def _promote_face(name: str, sketch: scad.Sketch):
_solve_and_report(name=name, sketch=sketch)
return scad.make_face_from_sketch_rface(
@@ -62,7 +61,6 @@ def _promote_face(name: str, sketch: scad.Sketch):
)
@scad.requires_session
def make_rect_profile(name, x0, y0, width, height):
sketch = scad.make_sketch_rsketch(name=name, plane="XY")
@@ -154,7 +152,6 @@ def make_rect_profile(name, x0, y0, width, height):
return _promote_face(name=name, sketch=sketch)
@scad.requires_session
def make_circle_profile(name, center_x, center_y, radius, circle_id):
sketch = scad.make_sketch_rsketch(name=name, plane="XY")
sketch = scad.add_point_rsketch(
@@ -178,7 +175,6 @@ def make_circle_profile(name, center_x, center_y, radius, circle_id):
return _promote_face(name=name, sketch=sketch)
@scad.requires_session
def make_guided_diamond_profile(name, center_x, center_y, width, height, guide_gap):
half_w = width / 2.0
half_h = height / 2.0
@@ -263,7 +259,6 @@ def make_guided_diamond_profile(name, center_x, center_y, width, height, guide_g
return _promote_face(name=name, sketch=sketch)
@scad.requires_session
def make_curve_guided_relief_profile(name, center_x, center_y, radius, guide_span):
sketch = scad.make_sketch_rsketch(name=name, plane="XY")
@@ -374,8 +369,7 @@ def make_curve_guided_relief_profile(name, center_x, center_y, radius, guide_spa
return _promote_face(name=name, sketch=sketch)
@scad.model(graph_id="constrained_sketch")
def build_model():
def _build_model_body():
plate_w = scad.var(name="plate_w", default=96.0, comment="plate width")
plate_h = scad.var(name="plate_h", default=54.0, comment="plate height")
plate_t = scad.var(name="plate_t", default=6.0, comment="plate thickness")
@@ -604,7 +598,6 @@ def build_model():
shape=part,
tag="demo.constrained_sketch_bracket",
)
scad.capture_result(value=part)
return {
"part": part,
"plate_profile": plate_profile,
@@ -613,73 +606,81 @@ def build_model():
}
def main() -> None:
OUT.mkdir(parents=True, exist_ok=True)
result = build_model()
data = result.value
MODEL_JSON_PATH.write_text(result.model_json, encoding="utf-8")
rebuilt = result.replay()
scad.export_step(shapes=rebuilt, filename=str(STEP_PATH))
freecad_cmd = str(FREECAD_CMD) if FREECAD_CMD.exists() else None
scad.translator.freecad_translator.translate_model_json_to_fcstd(
json_str=result.model_json,
output_path=str(FCSTD_PATH),
document_name="SimpleCADConstrainedSketchDemo",
freecad_cmd=freecad_cmd,
def _profile_entity_tags(profile: scad.Face) -> list[str]:
return sorted(
tag
for edge in scad.ql.select(items=profile.get_edges())
.where(scad.ql.tag(pattern="sketch_entity.*"))
.all()
for tag in scad.list_tags(shape=edge)
if tag.startswith("sketch_entity.")
)
payload = json.loads(result.model_json)
@scad.part(
id="constrained_sketch",
revision="1.0.0",
cache="off",
project_root=Path(__file__).resolve().parents[1],
)
def build_constrained_sketch_part() -> scad.Part:
data = _build_model_body()
part = scad.make_part_rpart(
part_id="constrained_sketch",
body=data["part"],
name="Constrained sketch bracket",
)
part.set_metadata(
"example.profile_entity_tags",
{
"plate": _profile_entity_tags(data["plate_profile"]),
"diamond": _profile_entity_tags(data["diamond_profile"]),
"curve": _profile_entity_tags(data["curve_relief_profile"]),
},
)
return part
def build_model():
result = build_constrained_sketch_part()
session = result.feature_graph.restore_session()
return result, scad.export_model_json(session), scad.export_session_json(session)
def main() -> None:
OUT.mkdir(parents=True, exist_ok=True)
result, model_json, session_json = build_model()
MODEL_JSON_PATH.write_text(model_json, encoding="utf-8")
SESSION_JSON_PATH.write_text(session_json, encoding="utf-8")
package_path = OUT / "constrained_sketch.scadpkg"
scad.capture(result, package_path)
step_report = scad.exporter.export_product_package_to_step(package_path, STEP_PATH)
scad.translator.freecad_translator.translate_product_package_to_fcstd(
package_path,
str(FCSTD_PATH),
document_name="SimpleCADConstrainedSketchDemo",
)
payload = json.loads(model_json)
ops = [node["op"] for node in payload["graph"]["nodes"]]
promotion_nodes = [
node
for node in payload["graph"]["nodes"]
if node["op"]
in {"make_face_from_sketch_rface", "make_wire_from_sketch_rwire"}
if node["op"] in {"make_face_from_sketch_rface", "make_wire_from_sketch_rwire"}
]
diamond_promotion = next(
node
for node in promotion_nodes
if node["params"]["sketch"].get("name") == "guided_diamond_pocket"
)
diamond_constraints = diamond_promotion["params"]["sketch"].get(
"constraints",
[],
)
diamond_constraints = diamond_promotion["params"]["sketch"].get("constraints", [])
curve_promotion = next(
node
for node in promotion_nodes
if node["params"]["sketch"].get("name") == "curve_guided_relief"
)
curve_constraints = curve_promotion["params"]["sketch"].get(
"constraints",
[],
)
sketch_entity_tags = sorted(
tag
for edge in scad.ql.select(items=data["plate_profile"].get_edges())
.where(scad.ql.tag(pattern="sketch_entity.*"))
.all()
for tag in scad.list_tags(shape=edge)
if tag.startswith("sketch_entity.")
)
diamond_entity_tags = sorted(
tag
for edge in scad.ql.select(items=data["diamond_profile"].get_edges())
.where(scad.ql.tag(pattern="sketch_entity.*"))
.all()
for tag in scad.list_tags(shape=edge)
if tag.startswith("sketch_entity.")
)
curve_entity_tags = sorted(
tag
for edge in scad.ql.select(items=data["curve_relief_profile"].get_edges())
.where(scad.ql.tag(pattern="sketch_entity.*"))
.all()
for tag in scad.list_tags(shape=edge)
if tag.startswith("sketch_entity.")
)
curve_constraints = curve_promotion["params"]["sketch"].get("constraints", [])
entity_tags = result.part.get_metadata("example.profile_entity_tags")
print("graph_nodes", len(ops))
print("sketch_ops", sum(1 for op in ops if "sketch" in op))
@@ -687,14 +688,12 @@ def main() -> None:
print(
"promotion_solve_snapshots",
sum(
1
for node in promotion_nodes
if "solve_snapshot" in node.get("params", {})
1 for node in promotion_nodes if "solve_snapshot" in node.get("params", {})
),
)
print("contains_public_solve_node", "make_solve_sketch_rsketchresult" in ops)
print("plate_sketch_entity_tags", sketch_entity_tags)
print("diamond_sketch_entity_tags", diamond_entity_tags)
print("plate_sketch_entity_tags", entity_tags["plate"])
print("diamond_sketch_entity_tags", entity_tags["diamond"])
print("diamond_constraint_count", len(diamond_constraints))
print(
"diamond_parallel_equal_constraints",
@@ -704,7 +703,7 @@ def main() -> None:
if constraint.get("kind") in {"parallel", "equal_length"}
),
)
print("curve_sketch_entity_tags", curve_entity_tags)
print("curve_sketch_entity_tags", entity_tags["curve"])
print("curve_constraint_count", len(curve_constraints))
print(
"curve_tangent_equal_radius_constraints",
@@ -715,10 +714,12 @@ def main() -> None:
in {"tangent", "equal_radius", "concentric", "point_on"}
),
)
print("volume", round(data["part"].get_volume(), 3))
print("volume", round(result.part.body.get_volume(), 3))
print("wrote", MODEL_JSON_PATH)
print("wrote", STEP_PATH)
print("wrote", SESSION_JSON_PATH)
print("wrote", step_report.output_path)
print("wrote", FCSTD_PATH)
print("product_package", package_path)
if __name__ == "__main__":
+54 -29
View File
@@ -7,7 +7,7 @@ Generated files:
examples/out/naca0016_blade/naca0016_blade.model.json
examples/out/naca0016_blade/naca0016_blade.session.json
examples/out/naca0016_blade/naca0016_blade.step
examples/out/naca0016_blade/naca0016_blade.fcstd
examples/out/naca0016_blade/naca0016_blade.FCStd
The NACA section generator starts from sampled airfoil points. The evolve helper
fits those samples into exact cubic B-spline control data before calling
@@ -25,11 +25,18 @@ import simplecadapi as scad
DEFAULT_OUTPUT_DIR = Path("examples/out/naca0016_blade")
DEFAULT_FREECAD_CMD = Path("/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd")
DEFAULT_FREECAD_CMD = Path(
"/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd"
)
@scad.model(graph_id="naca0016_blade")
def build_blade() -> scad.ModelResult:
@scad.part(
id="naca0016_blade",
revision="1.0.0",
cache="off",
project_root=Path(__file__).resolve().parents[1],
)
def build_naca0016_blade_part() -> scad.Part:
blade = scad.make_naca_propeller_blade_rsolid(
blade_length=4.0,
root_chord=1.25,
@@ -39,8 +46,17 @@ def build_blade() -> scad.ModelResult:
)
blade = scad.apply_tag(shape=blade, tag="role.naca0016.blade")
blade = scad.apply_tag(shape=blade, tag="part.naca0016.blade")
scad.capture_result(value=blade)
return blade
return scad.make_part_rpart(
part_id="naca0016_blade",
body=blade,
name="NACA 0016 propeller blade",
)
def build_blade() -> tuple[scad.PartBuildResult, str, str]:
result = build_naca0016_blade_part()
session = result.feature_graph.restore_session()
return result, scad.export_model_json(session), scad.export_session_json(session)
def write_blade_artifacts(
@@ -52,20 +68,26 @@ def write_blade_artifacts(
model_json_path = output_dir / "naca0016_blade.model.json"
session_json_path = output_dir / "naca0016_blade.session.json"
step_path = output_dir / "naca0016_blade.step"
fcstd_path = output_dir / "naca0016_blade.fcstd"
fcstd_path = output_dir / "naca0016_blade.FCStd"
result = build_blade()
blade = result.value
payload = json.loads(result.model_json)
model_json_path.write_text(result.model_json, encoding="utf-8")
session_json_path.write_text(result.session_json, encoding="utf-8")
scad.export_step(shapes=blade, filename=str(step_path))
result, model_json, session_json = build_blade()
payload = json.loads(model_json)
model_json_path.write_text(model_json, encoding="utf-8")
session_json_path.write_text(session_json, encoding="utf-8")
bspline_nodes = [
node for node in payload["graph"]["nodes"] if node.get("op") == "make_spline_redge"
node
for node in payload["graph"]["nodes"]
if node.get("op") == "make_spline_redge"
]
loft_nodes = [
node
for node in payload["graph"]["nodes"]
if node.get("op") == "make_loft_rsolid"
]
control_counts = [
len(node["params"].get("control_points", [])) for node in bspline_nodes
]
loft_nodes = [node for node in payload["graph"]["nodes"] if node.get("op") == "make_loft_rsolid"]
control_counts = [len(node["params"].get("control_points", [])) for node in bspline_nodes]
knot_counts = [len(node["params"].get("knots", [])) for node in bspline_nodes]
print("graph_nodes", len(payload["graph"]["nodes"]))
@@ -74,21 +96,24 @@ def write_blade_artifacts(
print("loft_nodes", len(loft_nodes))
print("bspline_control_counts", control_counts[:6])
print("bspline_knot_counts", knot_counts[:6])
print("volume", round(blade.get_volume(), 6))
package_path = output_dir / "naca0016_blade.scadpkg"
scad.capture(result, package_path)
step_report = scad.exporter.export_product_package_to_step(package_path, step_path)
print("wrote", model_json_path)
print("wrote", session_json_path)
print("wrote", step_path)
if freecad_cmd is not None and freecad_cmd.exists():
scad.translator.freecad_translator.translate_model_json_to_fcstd(
json_str=result.model_json,
output_path=str(fcstd_path),
document_name="NACA0016Blade",
freecad_cmd=str(freecad_cmd),
)
print("wrote", fcstd_path)
else:
print("skipped_fcstd", "FreeCADCmd not found")
resolved_freecad_cmd = (
str(freecad_cmd) if freecad_cmd is not None and freecad_cmd.exists() else None
)
scad.translator.freecad_translator.translate_product_package_to_fcstd(
package_path,
str(fcstd_path),
document_name="NACA0016Blade",
freecad_cmd=resolved_freecad_cmd,
)
print("wrote", step_report.output_path)
print("wrote", fcstd_path)
print("product_package", package_path)
return payload
@@ -100,7 +125,7 @@ def main() -> None:
"--freecad-cmd",
type=Path,
default=DEFAULT_FREECAD_CMD,
help="FreeCADCmd path used to write .fcstd; skipped if the path does not exist.",
help="Optional FreeCAD executable override; auto-discovered when unavailable.",
)
args = parser.parse_args()
write_blade_artifacts(args.output_dir, freecad_cmd=args.freecad_cmd)
+116 -60
View File
@@ -12,8 +12,7 @@ from simplecadapi import ql
OUT_DIR = Path(__file__).resolve().parent / "out" / "hydraulic_rod_assembly"
@scad.model(graph_id="hydraulic_rod_assembly", export_dir=OUT_DIR)
def build_hydraulic_rod_assembly():
def _build_hydraulic_rod_assembly_body():
flange_holes = [
("zplus", 0.0, 16.0),
("yplus", 16.0, 0.0),
@@ -21,7 +20,6 @@ def build_hydraulic_rod_assembly():
("yminus", -16.0, 0.0),
]
@scad.requires_session
def _build_in_session():
def _named_cylinder(
*,
@@ -403,73 +401,129 @@ def build_hydraulic_rod_assembly():
part=piston_rod_part, connector=rod_connector
)
hydraulic_assembly = scad.make_assembly_rassembly(
assembly_id="hydraulic_rod_assembly", name="Hydraulic rod assembly"
)
hydraulic_assembly = scad.add_component_rassembly(
assembly=hydraulic_assembly,
item=sleeve_part,
component_id="outer_sleeve",
placement=scad.identity_placement_rplacement(),
)
hydraulic_assembly = scad.add_component_rassembly(
assembly=hydraulic_assembly,
item=piston_rod_part,
component_id="inner_piston_rod",
placement=scad.identity_placement_rplacement(),
)
hydraulic_assembly = scad.ground_component_rassembly(
assembly=hydraulic_assembly, component_id="outer_sleeve"
)
hydraulic_assembly = scad.add_prismatic_constraint_rassembly(
assembly=hydraulic_assembly,
constraint_id="rod_slide",
connector_a=scad.make_connector_ref_rconnectorref(
component_id="outer_sleeve", connector_id="slide_axis"
),
connector_b=scad.make_connector_ref_rconnectorref(
component_id="inner_piston_rod", connector_id="slide_axis"
),
drive_distance=0.0,
distance_limit=scad.make_scalar_limit_rscalarlimit(
lower_value=0.0, upper_value=100.0
),
)
hydraulic_assembly = scad.solve_assembly_constraints_rassembly(
assembly=hydraulic_assembly
return sleeve_part, piston_rod_part
return _build_in_session()
def _assemble_hydraulic_rod(*, sleeve_part: scad.Part, piston_rod_part: scad.Part):
hydraulic_assembly = scad.make_assembly_rassembly(
assembly_id="hydraulic_rod_assembly", name="Hydraulic rod assembly"
)
identity = scad.identity_placement_rplacement()
hydraulic_assembly = scad.add_component_rassembly(
assembly=hydraulic_assembly,
item=sleeve_part,
component_id="outer_sleeve",
placement=identity,
)
hydraulic_assembly = scad.add_component_rassembly(
assembly=hydraulic_assembly,
item=piston_rod_part,
component_id="inner_piston_rod",
placement=identity,
)
hydraulic_assembly = scad.ground_component_rassembly(
assembly=hydraulic_assembly, component_id="outer_sleeve"
)
hydraulic_assembly = scad.add_prismatic_constraint_rassembly(
assembly=hydraulic_assembly,
constraint_id="rod_slide",
connector_a=scad.make_connector_ref_rconnectorref(
component_id="outer_sleeve", connector_id="slide_axis"
),
connector_b=scad.make_connector_ref_rconnectorref(
component_id="inner_piston_rod", connector_id="slide_axis"
),
drive_distance=0.0,
distance_limit=scad.make_scalar_limit_rscalarlimit(
lower_value=0.0, upper_value=100.0
),
)
return scad.solve_assembly_constraints_rassembly(assembly=hydraulic_assembly)
@scad.part(
id="outer_sleeve",
revision="1.0.0",
cache="off",
project_root=Path(__file__).resolve().parents[1],
)
def build_outer_sleeve_part() -> scad.Part:
return _build_hydraulic_rod_assembly_body()[0]
@scad.part(
id="piston_rod",
revision="1.0.0",
cache="off",
project_root=Path(__file__).resolve().parents[1],
)
def build_piston_rod_part() -> scad.Part:
return _build_hydraulic_rod_assembly_body()[1]
def build_hydraulic_product() -> scad.AssemblyBuildResult:
sleeve_result = build_outer_sleeve_part()
rod_result = build_piston_rod_part()
@scad.assemble(
id="hydraulic_rod_assembly",
revision="1.0.0",
definitions=(sleeve_result, rod_result),
cache="off",
project_root=Path(__file__).resolve().parents[1],
)
def build_assembly() -> scad.Assembly:
return _assemble_hydraulic_rod(
sleeve_part=sleeve_result.part,
piston_rod_part=rod_result.part,
)
preview = scad.make_compound_from_assembly_rcompound(
assembly=hydraulic_assembly
return build_assembly()
def build_hydraulic_rod_assembly():
session = scad.GraphSession(graph_id="hydraulic_rod_assembly")
with session:
sleeve_part, piston_rod_part = _build_hydraulic_rod_assembly_body()
assembly = _assemble_hydraulic_rod(
sleeve_part=sleeve_part,
piston_rod_part=piston_rod_part,
)
preview = scad.make_compound_from_assembly_rcompound(assembly=assembly)
preview = scad.apply_tag(
shape=preview,
tag="assembly.hydraulic.preview",
)
return hydraulic_assembly, preview
hydraulic_assembly, preview = _build_in_session()
scad.capture_result(value=(hydraulic_assembly, preview))
return hydraulic_assembly, preview
session.capture_result(value=(assembly, preview))
model_json = scad.export_model_json(session)
session_json = scad.export_session_json(session)
return assembly, preview, model_json, session_json
def main() -> None:
OUT_DIR.mkdir(parents=True, exist_ok=True)
result = build_hydraulic_rod_assembly()
assembly, preview = result.value
product_result = build_hydraulic_product()
assembly = product_result.assembly
preview = scad.make_compound_from_assembly_rcompound(assembly=assembly)
package_path = OUT_DIR / "hydraulic_rod_assembly.scadpkg"
scad.capture(product_result, package_path)
_, _, model_json, session_json = build_hydraulic_rod_assembly()
model_path = OUT_DIR / "hydraulic_rod_assembly.model.json"
session_path = OUT_DIR / "hydraulic_rod_assembly.session.json"
model_path.write_text(model_json, encoding="utf-8")
session_path.write_text(session_json, encoding="utf-8")
step_path = OUT_DIR / "hydraulic_rod_assembly.step"
fcstd_path = OUT_DIR / "hydraulic_rod_assembly.FCStd"
fcstd_status = "skipped"
try:
scad.translator.freecad_translator.translate_model_json_to_fcstd(
json_str=result.model_json,
output_path=str(fcstd_path.resolve()),
)
fcstd_status = str(fcstd_path)
except Exception as exc: # pragma: no cover - depends on local FreeCAD install
fcstd_status = f"skipped ({exc.__class__.__name__})"
step_report = scad.exporter.export_product_package_to_step(package_path, step_path)
scad.translator.freecad_translator.translate_product_package_to_fcstd(
package_path,
str(fcstd_path.resolve()),
document_name="HydraulicRodAssembly",
)
payload = json.loads(result.model_json)
payload = json.loads(model_json)
face_count = len(ql.faces().resolve(preview))
print("assembly", assembly.assembly_id)
print("components", assembly.component_ids())
@@ -477,9 +531,11 @@ def main() -> None:
print("preview_faces", face_count)
print("preview_volume", round(preview.get_volume(), 3))
print("graph_nodes", len(payload["graph"]["nodes"]))
for path in result.artifact_paths.values():
print("wrote", path)
print("fcstd", fcstd_status)
print("wrote", model_path)
print("wrote", session_path)
print("step", step_report.output_path)
print("fcstd", fcstd_path)
print("product_package", package_path)
if __name__ == "__main__":
+18 -4
View File
@@ -146,10 +146,21 @@ def build_external_reference_gear_train() -> scad.AssemblyBuildResult:
def main() -> None:
OUT_DIR.mkdir(parents=True, exist_ok=True)
result = build_external_reference_gear_train()
path = result.export_definition(
path=OUT_DIR / "nested_external_reference_gear_trains.assembly-definition.zip"
package_path = OUT_DIR / "nested_external_reference_gear_trains.scadpkg"
scad.capture(result, package_path)
step_path = OUT_DIR / "nested_external_reference_gear_trains.step"
fcstd_path = OUT_DIR / "nested_external_reference_gear_trains.FCStd"
step_report = scad.exporter.export_product_package_to_step(package_path, step_path)
scad.translator.freecad_translator.translate_product_package_to_fcstd(
package_path,
str(fcstd_path),
document_name="NestedExternalReferenceGearTrains",
)
loaded = scad.load_assembly_definition(path)
definition_path = scad.export_assembly_definition(
result.definition,
OUT_DIR / "nested_external_reference_gear_trains.assembly-definition.zip",
)
loaded = scad.load_product_package(package_path)
rebuilt = scad.materialize_definition(loaded)
nested = rebuilt.get_component("train_left").item
report = scad.inspect_assembly_constraints_rconstraintreport(nested)
@@ -162,7 +173,10 @@ def main() -> None:
f"definition_refs={len(loaded.definition_refs)} "
f"content_hash={loaded.content_hash}"
)
print(f"artifact={path}")
print(f"definition_artifact={definition_path}")
print(f"product_package={package_path}")
print(f"step={step_report.output_path}")
print(f"fcstd={fcstd_path}")
if __name__ == "__main__":
+169
View File
@@ -0,0 +1,169 @@
"""Export one durable SimpleCAD part as FCStd, AP242 STEP, and Gmsh MSH."""
from __future__ import annotations
import argparse
from dataclasses import dataclass
import importlib
from pathlib import Path
from typing import Any
import simplecadapi as scad
OUT_DIR = Path(__file__).resolve().parent / "out" / "ap242_gmsh_volume_mesh"
CACHE = scad.CachePolicy(root=OUT_DIR / ".cache")
@dataclass(frozen=True, slots=True)
class GmshMeshReport:
step_path: Path
mesh_path: Path
volume_count: int
node_count: int
element_count: int
@scad.part(
id="ap242_gmsh_bracket",
revision="1.0.0",
inputs=(scad.file_input(path="examples/12_ap242_gmsh_volume_mesh.py"),),
cache=CACHE,
)
def build_bracket() -> scad.Part:
body = scad.make_box_rsolid(
width=40.0,
height=24.0,
depth=8.0,
bottom_face_center=(0.0, 0.0, 0.0),
)
hole = scad.make_cylinder_rsolid(
radius=4.0,
height=12.0,
bottom_face_center=(-12.0, 0.0, -2.0),
)
slot = scad.make_box_rsolid(
width=14.0,
height=6.0,
depth=12.0,
bottom_face_center=(10.0, 0.0, -2.0),
)
body = scad.cut_rsolid(body, hole, slot)
part = scad.make_part_rpart(
part_id="ap242_gmsh_bracket",
body=body,
name="AP242 Gmsh bracket",
)
material = scad.make_material_rmaterial(
material_id="aluminum_6061_t6",
name="Aluminum 6061-T6",
density=2.70e-6,
density_unit="kg/mm^3",
color=(0.72, 0.74, 0.78),
)
return scad.assign_material_rpart(part, material)
def mesh_step_with_gmsh(
step_path: str | Path,
mesh_path: str | Path,
*,
mesh_size: float = 2.0,
gmsh_module: Any | None = None,
) -> GmshMeshReport:
"""Import AP242 STEP with Gmsh's OCC kernel and write a 3D MSH mesh."""
if mesh_size <= 0.0:
raise ValueError("mesh_size must be positive")
source = Path(step_path).expanduser().resolve()
destination = Path(mesh_path).expanduser().resolve()
if not source.is_file():
raise FileNotFoundError(source)
destination.parent.mkdir(parents=True, exist_ok=True)
gmsh = gmsh_module
if gmsh is None:
try:
gmsh = importlib.import_module("gmsh")
except ImportError as exc:
raise RuntimeError(
"Gmsh is optional; install it with `pip install simplecadapi[gmsh]`"
) from exc
initialized = False
try:
gmsh.initialize()
initialized = True
gmsh.model.add(source.stem)
gmsh.option.setString("Geometry.OCCTargetUnit", "MM")
imported = gmsh.model.occ.importShapes(str(source))
gmsh.model.occ.synchronize()
volumes = gmsh.model.getEntities(3)
if not volumes:
raise RuntimeError(
f"Gmsh imported no 3D volumes from {source}; imported entities: {imported}"
)
physical_group = gmsh.model.addPhysicalGroup(
3,
[tag for _dimension, tag in volumes],
)
gmsh.model.setPhysicalName(3, physical_group, source.stem)
gmsh.option.setNumber("Mesh.MeshSizeMin", float(mesh_size))
gmsh.option.setNumber("Mesh.MeshSizeMax", float(mesh_size))
gmsh.model.mesh.generate(3)
node_tags, _coordinates, _parameters = gmsh.model.mesh.getNodes()
_types, element_tags, _node_tags = gmsh.model.mesh.getElements(3)
element_count = sum(len(tags) for tags in element_tags)
if not len(node_tags) or not element_count:
raise RuntimeError("Gmsh generated an empty 3D mesh")
gmsh.write(str(destination))
finally:
if initialized:
gmsh.finalize()
if not destination.is_file() or destination.stat().st_size <= 0:
raise RuntimeError(
f"Gmsh did not create a non-empty mesh file at {destination}"
)
return GmshMeshReport(
step_path=source,
mesh_path=destination,
volume_count=len(volumes),
node_count=len(node_tags),
element_count=element_count,
)
def main(*, generate_mesh: bool = True) -> None:
result = build_bracket()
package_path = OUT_DIR / "ap242_gmsh_bracket.scadpkg"
scad.capture(result, package_path)
step_path = OUT_DIR / "ap242_gmsh_bracket.step"
mesh_path = OUT_DIR / "ap242_gmsh_bracket.msh"
fcstd_path = OUT_DIR / "ap242_gmsh_bracket.FCStd"
step_report = scad.exporter.export_product_package_to_step(package_path, step_path)
scad.translator.freecad_translator.translate_product_package_to_fcstd(
package_path,
str(fcstd_path),
document_name="AP242GmshBracket",
)
mesh = mesh_step_with_gmsh(step_path, mesh_path) if generate_mesh else None
print("product_package", package_path)
print("ap242_step", step_report.output_path)
print("fcstd", fcstd_path)
print("ap242_metadata_items", step_report.metadata_item_count)
if mesh is not None:
print("gmsh_mesh", mesh.mesh_path)
print("gmsh_volumes", mesh.volume_count)
print("gmsh_nodes", mesh.node_count)
print("gmsh_3d_elements", mesh.element_count)
if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"--skip-mesh",
action="store_true",
help="Export .scadpkg, AP242 STEP, and FCStd without optional Gmsh meshing.",
)
args = parser.parse_args()
main(generate_mesh=not args.skip_mesh)
@@ -38,7 +38,8 @@
- Fix the output flange to the stage 2 carrier/output shaft.
- Add external gear constraints from each sun to its planets using `add_gear_constraint_rassembly`.
- Add internal ring-to-planet mesh constraints using same-direction `add_belt_constraint_rassembly` with ring and planet pitch radii.
- Use `GraphSession`, `export_session_json`, `export_model_json`, `import_model_json`, and `replay_model_json` in the build script for replayable output.
- Build every physical single-solid component through `@scad.part`, preserve the reusable bearing as a nested `@scad.assemble`, and build the reducer root through `@scad.assemble` with explicit immutable definitions.
- Export `compact_two_stage_planetary_reducer.scadpkg` as the primary product; derive optional model/session JSON and STEP artifacts from the same durable feature DAG and validate strict product replay.
- Ground every build step with concise QL-backed prints: part face counts, volumes, tags, bearing component counts, gear radii, constraint residuals, replay counts, and exported file paths.
## Validation Assumptions

Some files were not shown because too many files have changed in this diff Show More