Merge pull request #57 from PhySpace/release/2.2.6.post2

release: 2.2.6.post2 (operators move to their family module; generated API docs for all)
This commit is contained in:
Ni Jingzhe
2026-10-21 01:29:44 +08:00
committed by GitHub
36 changed files with 1440 additions and 754 deletions
+4
View File
@@ -89,3 +89,7 @@ sandbox-envs/
.agents/
.sharednet/
design-docs/
# local, not part of the SDK
examples/workspace/
phase2-contract-review.md
+25
View File
@@ -6,6 +6,31 @@ user-facing notes live in [`docs/updates/`](docs/updates/) (English and
## Unreleased
## 2.2.6.post2 — 2026-10-21
### Changed
- Operators: `scale_rsolid` and `transform_rsolid` are implemented in `operators/transform.py`,
`boolean_rsolidlist` in `operators/boolean.py`, and `offset_rsolid`, `draft_rsolid`,
`extrude_taper_rsolid`, `extrude_until_rsolid` and `sweep_multisection_rsolid` in
`operators/features.py`, next to the operators of their family. `from simplecadapi import ...`
is unchanged. The one-feature modules they were first written in (`operators.deformation`,
`draft`, `section_features`, `limited_extrusion`) remain as aliases: importing a name from
them still works and raises a `DeprecationWarning` that names the new place.
### Fixed
- Skill API docs: the documentation generator listed its source files and public functions by
hand and had never been told about those four modules, so the docs of the eight operators
above were kept by hand and deleted by the generator's clean-up. `operators/` is now
discovered, a function the package exports is public, the content of the hand-written docs
(examples, error conditions, replay notes) is in the docstrings, and tests check that every
public operator has a doc and that the committed docs are exactly what the generator writes.
`boolean_rsolidlist` had no doc at all.
- Skill API docs of `NotebookRun`, `run_notebook` and `add_bspline_rsketch` caught up with the
code (`through`, `product` and `timeout`; a partial run's `product` is `None`; closed
B-splines).
## 2.2.6.post1 — 2026-10-21
### Fixed
+10 -10
View File
@@ -149,20 +149,19 @@ the full crank cycle sweeps clean in the same sim ·
---
## Update Notes (2.2.6.post1)
## Update Notes (2.2.6.post2)
> Validate generated definitions, assembly constraints, and manufacturing
> geometry before production use.
- **Keyword `scad.var` is a parameter again.** `scad.var(name="j1", default=0.0)` is read
by the editor's parameter panel like the positional form; before, it was skipped.
- **A cached run costs much less.** On the desktop arm: cold 80 s to 35 s, nothing changed
24 s to 4 s, one joint edited 18 s to 3 s, cache 1.7 GB to 96 MB. Restored shapes are built
on first use, parameters and imported names are keyed by value, and the `use` calls of a
cell run in worker processes (`SCA_JOBS`, 1 turns it off).
- **Slider drags are sent when they settle**, not step by step.
- **Operators live with their family.** `scale_rsolid`, `transform_rsolid`, `boolean_rsolidlist`,
`offset_rsolid`, `draft_rsolid`, `extrude_taper_rsolid`, `extrude_until_rsolid` and
`sweep_multisection_rsolid` moved into `operators/transform.py`, `boolean.py` and `features.py`.
`from simplecadapi import ...` is unchanged; the old module paths warn and still work.
- **Every operator's API reference is generated**, and tests fail when one has no doc or the
committed docs differ from the generator's output.
Full notes for this version: [`docs/updates/2.2.6.post1.md`](docs/updates/2.2.6.post1.md).
Full notes for this version: [`docs/updates/2.2.6.post2.md`](docs/updates/2.2.6.post2.md).
Earlier versions: the [changelog](CHANGELOG.md) and [`docs/updates/`](docs/updates/).
---
@@ -183,7 +182,7 @@ in a compact public API for creating solids, applying features, tagging semantic
intent, querying topology, exporting manufacturing files, and translating recorded
models into FreeCAD workflows.
Current release: `simplecadapi==2.2.6.post1`.
Current release: `simplecadapi==2.2.6.post2`.
## What It Provides
@@ -698,6 +697,7 @@ and the [STEP reconstruction workflow](docs/skill/references/workflows/step-reco
## Documentation
- 2.2.6.post2 update notes: [`docs/updates/2.2.6.post2.md`](docs/updates/2.2.6.post2.md)
- 2.2.6.post1 update notes: [`docs/updates/2.2.6.post1.md`](docs/updates/2.2.6.post1.md)
- 2.2.6 update notes: [`docs/updates/2.2.6.md`](docs/updates/2.2.6.md)
- 2.2.5 update notes: [`docs/updates/2.2.5.md`](docs/updates/2.2.5.md)
+8 -9
View File
@@ -133,18 +133,16 @@ CalculiX 静力 FEM(边界面按保真的 `interface.*` 标签选取,仿真
---
## 更新日志(2.2.6.post1)
## 更新日志(2.2.6.post2)
> 投入生产前请验证生成的定义、装配约束和制造几何。
- **关键字写法的 `scad.var` 重新被识别为参数。** `scad.var(name="j1", default=0.0)` 现在和
位置参数写法一样出现在参数面板;之前会被跳过。
- **缓存运行便宜得多。** 桌面机械臂:冷启动 80 秒到 35 秒,什么都没改 24 秒到 4 秒,改一个关节 18 秒到 3 秒,
缓存 1.7 GB 到 96 MB。形状在第一次用到时才构建,参数和导入的名字按值定键,cell 里的 `use` 调用在 worker
进程里并行(`SCA_JOBS`,设为 1 关闭)。
- **滑块拖动在停下来时才发送**,不再逐步发送。
- **算子放在自己家族的模块里。** `scale_rsolid`、`transform_rsolid`、`boolean_rsolidlist`、`offset_rsolid`、
`draft_rsolid`、`extrude_taper_rsolid`、`extrude_until_rsolid`、`sweep_multisection_rsolid` 搬进了
`operators/transform.py`、`boolean.py`、`features.py`。`from simplecadapi import ...` 用法不变;旧的模块路径仍可用,并会给出警告。
- **每个算子的 API 参考都由生成器生成**,缺文档、或已提交的文档与生成器输出不一致,测试都会失败。
本版本的完整说明:[`docs/updates/2.2.6.post1.zh-CN.md`](docs/updates/2.2.6.post1.zh-CN.md)。
本版本的完整说明:[`docs/updates/2.2.6.post2.zh-CN.md`](docs/updates/2.2.6.post2.zh-CN.md)。
更早的版本:见[更新日志](CHANGELOG.md)和 [`docs/updates/`](docs/updates/)。
---
@@ -162,7 +160,7 @@ CalculiX 静力 FEM(边界面按保真的 `interface.*` 标签选取,仿真
SimpleCADAPI 是一个基于 OCP 的 Python CAD SDK,提供清晰的函数式建模操作和可重放的模型图。它在 OpenCascade 几何内核之上提供精简的公共 API,可用于创建实体、应用特征、添加语义标签、查询拓扑、导出制造文件,以及将记录的模型转换为 FreeCAD 工作流。
当前版本:`simplecadapi==2.2.6.post1`。
当前版本:`simplecadapi==2.2.6.post2`。
## 核心能力
@@ -588,6 +586,7 @@ uv run --extra fem python examples/ap242_gmsh_volume_mesh/run_calculix.py
## 文档
- 2.2.6.post2 更新说明:[`docs/updates/2.2.6.post2.zh-CN.md`](docs/updates/2.2.6.post2.zh-CN.md)
- 2.2.6.post1 更新说明:[`docs/updates/2.2.6.post1.zh-CN.md`](docs/updates/2.2.6.post1.zh-CN.md)
- 2.2.6 更新说明:[`docs/updates/2.2.6.zh-CN.md`](docs/updates/2.2.6.zh-CN.md)
- 2.2.5 更新说明:[`docs/updates/2.2.5.zh-CN.md`](docs/updates/2.2.5.zh-CN.md)
+2 -2
View File
@@ -4,9 +4,9 @@ description: Build, assemble, inspect, reconstruct, and export parametric CAD mo
license: Apache-2.0
metadata:
project: simplecadapi
version: 2.2.6.post1
version: 2.2.6.post2
package-name: simplecadapi
package-version: 2.2.6.post1
package-version: 2.2.6.post2
---
# SimpleCAD SDK Skill
@@ -3,7 +3,7 @@
## Class Definition
```python
class NotebookRun(config: NotebookConfig, product: Product, values: Mapping[str, Any], cells: tuple[CellReport, ...], dependencies: frozenset[Path])
class NotebookRun(config: NotebookConfig, product: Product | None, values: Mapping[str, Any], cells: tuple[CellReport, ...], dependencies: frozenset[Path])
```
*Source: runtime/runner.py*
@@ -17,6 +17,7 @@ class NotebookRun(config: NotebookConfig, product: Product, values: Mapping[str,
The outcome of :func:`run_notebook`.
``product`` is the notebook's product and ``definition`` its durable
definition; ``values`` holds every top-level variable, ``cells`` one
report per cell in notebook order, and ``dependencies`` the files
outside the cells the run depends on.
definition (``None`` for a partial run — see ``through``/``product``);
``values`` holds every top-level variable, ``cells`` one report per cell
in notebook order, and ``dependencies`` the files outside the cells the
run depends on.
+8
View File
@@ -77,9 +77,12 @@ This index includes generated docs for the public SimpleCAD API surface, includi
## 3D Operations
- [extrude_rsolid](extrude_rsolid.md) *(from operators/features.py)* `top-level`
- [extrude_taper_rsolid](extrude_taper_rsolid.md) *(from operators/features.py)* `top-level`
- [extrude_until_rsolid](extrude_until_rsolid.md) *(from operators/features.py)* `top-level`
- [loft_rshell](loft_rshell.md) *(from operators/geometry.py)* `top-level`
- [loft_rsolid](loft_rsolid.md) *(from operators/features.py)* `top-level`
- [revolve_rsolid](revolve_rsolid.md) *(from operators/features.py)* `top-level`
- [sweep_multisection_rsolid](sweep_multisection_rsolid.md) *(from operators/features.py)* `top-level`
- [sweep_rsolid](sweep_rsolid.md) *(from operators/features.py)* `top-level`
## Tagging and Selection
@@ -345,6 +348,7 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- [add_revolute_constraint_rassembly](add_revolute_constraint_rassembly.md) *(from operators/product.py)* `top-level`
- [and_](and_.md) *(from ql.py)* `submodule:ql`
- [assign_material_rpart](assign_material_rpart.md) *(from operators/product.py)* `top-level`
- [boolean_rsolidlist](boolean_rsolidlist.md) *(from operators/boolean.py)* `top-level`
- [canonical_frame](canonical_frame.md) *(from product/placement.py)* `submodule:product/placement`
- [capture](capture.md) *(from product/capture.py)* `top-level`
- [constrain_angle_rsketch](constrain_angle_rsketch.md) *(from operators/sketch.py)* `top-level`
@@ -377,6 +381,7 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- [constrain_symmetric_rsketch](constrain_symmetric_rsketch.md) *(from operators/sketch.py)* `top-level`
- [constrain_tangent_rsketch](constrain_tangent_rsketch.md) *(from operators/sketch.py)* `top-level`
- [constrain_vertical_rsketch](constrain_vertical_rsketch.md) *(from operators/sketch.py)* `top-level`
- [draft_rsolid](draft_rsolid.md) *(from operators/features.py)* `top-level`
- [explain_tag](explain_tag.md) *(from operators/selection.py)* `top-level`
- [fill_holes_rshell](fill_holes_rshell.md) *(from operators/geometry.py)* `top-level`
- [fit_point_grid_rface](fit_point_grid_rface.md) *(from operators/geometry.py)* `top-level`
@@ -394,6 +399,7 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- [measure_constraint_residual_rconstraintresidual](measure_constraint_residual_rconstraintresidual.md) *(from operators/product.py)* `top-level`
- [meta](meta.md) *(from ql.py)* `submodule:ql`
- [not_](not_.md) *(from ql.py)* `submodule:ql`
- [offset_rsolid](offset_rsolid.md) *(from operators/features.py)* `top-level`
- [operation_event](operation_event.md) *(from ql.py)* `submodule:ql`
- [or_](or_.md) *(from ql.py)* `submodule:ql`
- [origin_role](origin_role.md) *(from ql.py)* `submodule:ql`
@@ -404,6 +410,7 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- [placement_ticks](placement_ticks.md) *(from product/placement.py)* `submodule:product/placement`
- [radial_pattern_rsolidlist](radial_pattern_rsolidlist.md) *(from operators/transform.py)* `top-level`
- [render_screenshot_rpath](render_screenshot_rpath.md) *(from operators/features.py)* `top-level`
- [scale_rsolid](scale_rsolid.md) *(from operators/transform.py)* `top-level`
- [select](select.md) *(from ql.py)* `submodule:ql`
- [set_public_connector_rassembly](set_public_connector_rassembly.md) *(from operators/product.py)* `top-level`
- [sew_faces_rshell](sew_faces_rshell.md) *(from operators/geometry.py)* `top-level`
@@ -412,6 +419,7 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- [source_binding](source_binding.md) *(from ql.py)* `submodule:ql`
- [source_topology](source_topology.md) *(from ql.py)* `submodule:ql`
- [tag](tag.md) *(from ql.py)* `submodule:ql`
- [transform_rsolid](transform_rsolid.md) *(from operators/transform.py)* `top-level`
- [trim_surface_rface](trim_surface_rface.md) *(from operators/geometry.py)* `top-level`
- [twisted_sweep_rsolid](twisted_sweep_rsolid.md) *(from operators/features.py)* `top-level`
- [unground_component_rassembly](unground_component_rassembly.md) *(from operators/product.py)* `top-level`
@@ -17,4 +17,6 @@ def add_bspline_rsketch(sketch: Sketch, entity_id: str, start: Union[SketchRef,
Add a B-spline curve entity to a sketch.
The start/end point refs link the B-spline into a closed profile
loop. Control points may be literal 2-D coordinates or point refs.
loop. A closed curve may reuse one seam ref for both endpoints.
Control points may be literal 2-D coordinates or point refs. A periodic
seam links topology without replacing the periodic curve's poles.
@@ -0,0 +1,45 @@
# boolean_rsolidlist
## API Definition
```python
def boolean_rsolidlist(left: Sequence[Solid], right: Sequence[Solid], operation: str) -> list[Solid]
```
*Source: operators/boolean.py*
## Import Surface
- top-level: `from simplecadapi import boolean_rsolidlist`
## Description
Apply a set boolean to two body groups, retaining every result solid.
Members of each group are a geometric set. Unlike single-solid booleans,
a cut or intersection may return several solids or an empty list.
Topology lineage is partial; the ordered inputs and all output slots are
recorded so downstream features can replay the same geometry.
## Parameters
### left
- **Description**: The first group of solids.
### right
- **Description**: The second group of solids.
### operation
- **Description**: ``"cut"``, ``"intersect"`` or ``"union"``.
## Returns
The result solids, possibly several or none.
## Raises
- **TypeError**: A group contains something that is not a Solid.
- **ValueError**: ``operation`` is unknown, or a member is invalid or empty.
+54 -24
View File
@@ -1,39 +1,69 @@
# draft_rsolid
## API Definition
```python
def draft_rsolid(
solid: Solid,
faces_to_draft: Sequence[Face] | ShapeSelector,
angle: ScalarLike,
plane_origin: Sequence[float] = (0, 0, 0),
plane_normal: Sequence[float] = (0, 0, 1),
) -> Solid
def draft_rsolid(solid: Solid, faces_to_draft: Sequence[Face] | ShapeSelector, angle: ScalarLike, plane_origin: Sequence[float] = (0, 0, 0), plane_normal: Sequence[float] = (0, 0, 1)) -> Solid
```
*Source: operators/draft.py*
*Source: operators/features.py*
Import with `from simplecadapi import draft_rsolid`.
## Import Surface
Apply a signed draft angle in degrees to selected planar, cylindrical, or
conical faces. The neutral plane retains its original section while the selected
faces lean toward or away from it. Its origin and normal use the current
coordinate system. The input solid is preserved, and the output must be one
valid solid. A zero angle records an unchanged result.
- top-level: `from simplecadapi import draft_rsolid`
## Description
Draft planar, cylindrical or conical faces by a signed angle in degrees.
The neutral plane fixes the unchanged section: the selected faces lean
toward or away from it. Its origin and normal are in current
coordinate-system coordinates. Face selection is checked against the input
body and retained as graph inputs for strict replay. The input solid is
preserved, the output must be one valid solid, and a zero angle records an
unchanged result. Other surface families are explicitly rejected.
The operation is recorded as ``make_draft_rsolid``; the body and selected
faces are ordered inputs, and the angle, neutral plane and face selection
nodes are parameters, so model JSON replay is strict.
## Parameters
### solid
- **Description**: The body to draft.
### faces_to_draft
- **Description**: Faces of ``solid``, or a QL selector that picks them.
### angle
- **Description**: Draft angle in degrees, strictly between -90 and 90.
### plane_origin
- **Description**: A point of the neutral plane.
### plane_normal
- **Description**: Normal of the neutral plane; must be nonzero.
## Returns
The drafted solid.
## Raises
- **TypeError**: ``solid`` is not a Solid.
- **ValueError**: Empty selection, a selection that is not made of faces of ``solid``, an unsupported surface family, a zero plane normal, or a nonfinite or out-of-range angle.
## Examples
```python
import simplecadapi as scad
from simplecadapi import ql
body = scad.make_box_rsolid(10, 10, 10)
right = ql.faces().where(ql.prop("geom.normal.x", ">", 0.9)).exactly(1)
drafted = scad.draft_rsolid(body, right, angle=10)
```
Selections may be explicit faces from the body or a QL selector. Empty
selections, faces from another body, unsupported surface families, a zero plane
normal, and nonfinite parameters are rejected. The angle must be strictly
between -90 and 90 degrees. Kernel failures and invalid topology raise errors.
The operation `make_draft_rsolid` records the body and selected faces as ordered
inputs. Parameters preserve the angle, neutral plane, and face selection nodes
for strict model JSON replay.
@@ -1,13 +1,51 @@
# extrude_taper_rsolid
## API Definition
```python
def extrude_taper_rsolid(profile: Face, vector: Sequence[float],
taper: float, flip_inner: bool = True) -> Solid
def extrude_taper_rsolid(profile: Face, vector: Sequence[float], taper: float, flip_inner: bool = True) -> Solid
```
Extrude a planar sketch face by a nonzero vector, in current coordinate-system
coordinates. The finite taper angle is in degrees and must lie strictly between
-90 and 90. Positive taper shrinks the outer section; inner loops taper in the
opposite direction when `flip_inner=True`. Uses an analytic draft prism where
applicable and exact offset sections with lofts otherwise. Raises on collapsed
loops or invalid topology. Records `make_extrude_taper_rsolid` for replay.
*Source: operators/features.py*
## Import Surface
- top-level: `from simplecadapi import extrude_taper_rsolid`
## Description
Extrude a planar sketch face by a vector, with a taper in degrees.
The vector is nonzero and in current coordinate-system coordinates. The
finite taper angle lies strictly between -90 and 90; a positive taper
shrinks the outer section, and inner loops taper the opposite way when
``flip_inner`` is true. An analytic draft prism is used where applicable
and exact offset sections with lofts otherwise. Collapsed loops and invalid
topology raise errors. The operation is recorded as
``make_extrude_taper_rsolid`` for replay.
## Parameters
### profile
- **Description**: The planar face to extrude.
### vector
- **Description**: Extrusion vector (nonzero).
### taper
- **Description**: Taper angle in degrees, strictly between -90 and 90.
### flip_inner
- **Description**: Taper inner loops in the opposite direction.
## Returns
The tapered solid.
## Raises
- **ValueError**: A zero vector, an out-of-range taper, a nonplanar profile, collapsed loops or an invalid result.
@@ -1,53 +1,75 @@
# extrude_until_rsolid
## API Definition
```python
def extrude_until_rsolid(
profile: Face,
target: Solid | Sequence[Solid],
direction: Sequence[float] = (0, 0, 1),
until: str = "NEXT",
) -> Solid
def extrude_until_rsolid(profile: Face, target: Solid | Sequence[Solid], direction: Sequence[float] = (0, 0, 1), until: str = 'NEXT') -> Solid
```
*Source: operators/limited_extrusion.py*
*Source: operators/features.py*
Import with `from simplecadapi import extrude_until_rsolid`.
## Import Surface
Extrude a planar face until it reaches an actual boundary on one or more target
solids. Planar and curved termination surfaces are supported. The direction is
interpreted in the current coordinate system and normalized before construction.
- top-level: `from simplecadapi import extrude_until_rsolid`
| Mode | Direction | Termination |
| --- | --- | --- |
| `NEXT` | Forward | Nearest intersecting target surface |
| `LAST` | Forward | Farthest intersecting target surface |
| `PREVIOUS` | Reverse | Nearest intersecting target surface |
| `FIRST` | Reverse | Farthest intersecting target surface |
## Description
The implementation intersects a temporary prism with the target, obtains target
boundary faces from kernel history, sews the contact faces into surfaces, and
splits the prism on the selected surface. Bounding boxes only determine a
sufficient temporary prism length; they do not define the termination surface.
Side walls parallel to the direction do not join separate near and far limits.
Extrude a planar face until a target surface, including curved surfaces.
The direction is interpreted in the current coordinate system and
normalized before construction. ``until`` selects the termination:
``NEXT`` (forward, nearest intersecting target surface), ``LAST`` (forward,
farthest), ``PREVIOUS`` (reverse, nearest) and ``FIRST`` (reverse,
farthest). The temporary prism is intersected with the target, the target's
boundary faces are taken from kernel history and sewn into surfaces, and
the prism is split on the selected one. Bounding boxes only size the
temporary prism; they do not define the termination surface, and side
walls parallel to the direction do not join separate near and far limits.
Targets must cover the profile at the requested contact: an uncovered,
open or disconnected output is rejected, as are a missing contact, an
invalid mode, a zero or nonfinite direction and an empty target sequence.
Inputs are preserved. The operation is recorded as
``make_extrude_until_rsolid``; its ordered inputs are the profile followed
by every target solid and its parameters keep ``direction``, ``until`` and
``target_count``, so a changed target is recomputed on replay (no final
BRep is embedded).
## Parameters
### profile
- **Description**: The planar face to extrude.
### target
- **Description**: A solid, or a sequence of solids, that bounds the extrusion.
### direction
- **Description**: Extrusion direction in current coordinate-system coordinates.
### until
- **Description**: ``"NEXT"``, ``"LAST"``, ``"PREVIOUS"`` or ``"FIRST"``.
## Returns
One valid solid.
## Raises
- **TypeError**: ``profile`` is not a Face, or ``target`` is not a Solid or a sequence of Solid.
- **ValueError**: No target, no contact, insufficient coverage, a bad mode or direction, or an invalid kernel result.
## Examples
```python
import simplecadapi as scad
profile = scad.make_rectangle_rface(2, 2)
ceiling = scad.make_box_rsolid(10, 10, 2, bottom_face_center=(0, 0, 5))
near = scad.extrude_until_rsolid(profile, ceiling, until="NEXT") # Volume 20
far = scad.extrude_until_rsolid(profile, ceiling, until="LAST") # Volume 28
near = scad.extrude_until_rsolid(profile, ceiling, until="NEXT") # volume 20
far = scad.extrude_until_rsolid(profile, ceiling, until="LAST") # volume 28
sphere = scad.make_sphere_rsolid(5, center=(0, 0, 10))
curved = scad.extrude_until_rsolid(profile, sphere)
```
Targets must cover the profile at the requested contact. Missing contact,
insufficient coverage, an invalid mode, a zero/nonfinite direction, and invalid
kernel output raise errors. An empty target sequence is rejected. A successful
result is one valid solid; inputs are preserved.
The recorded operation is `make_extrude_until_rsolid`. Its ordered inputs are the
profile followed by every target solid. Parameters retain `direction`, `until`,
and `target_count`, so model JSON replay recomputes the boundary when a target
changes. No final BRep is embedded in the feature.
+50 -10
View File
@@ -1,15 +1,55 @@
# offset_rsolid
## API Definition
```python
def offset_rsolid(solid: Solid, amount: ScalarLike,
openings: Sequence[Face] | ShapeSelector = (), *,
tolerance: float = 1e-4, kind: str = "ARC") -> Solid
def offset_rsolid(solid: Solid, amount: ScalarLike, openings: Sequence[Face] | ShapeSelector = (), *, tolerance: float = 0.0001, kind: str = 'ARC') -> Solid
```
Positive `amount` offsets outward; negative offsets inward. The amount must
be finite and nonzero. QL-selected `openings` form an open shell. With no
openings, produce a closed offset solid. Join `kind` is `ARC` or
`INTERSECTION`. Invalid kernel results raise an error. Records a replayable
`make_offset_rsolid` node with explicit face selections; topology tag lineage
is conservatively partial. `shell_rsolid` retains its existing positive
inward wall-thickness contract.
*Source: operators/features.py*
## Import Surface
- top-level: `from simplecadapi import offset_rsolid`
## Description
Offset a solid outward (positive) or inward (negative).
The amount must be finite and nonzero. Faces passed as ``openings`` form an
open shell; with no openings the result is the closed offset solid. The
join ``kind`` is ``ARC`` or ``INTERSECTION``. Invalid kernel results raise
an error. The operation is recorded as ``make_offset_rsolid`` with explicit
face selections; topology tag lineage is conservatively partial.
``shell_rsolid`` keeps its own contract (a positive inward wall thickness);
this one supports both signs.
## Parameters
### solid
- **Description**: The solid to offset.
### amount
- **Description**: Offset distance; positive outward, negative inward.
### openings
- **Description**: Faces of ``solid`` (or a QL selector) left open.
### tolerance
- **Description**: Kernel tolerance of the offset.
### kind
- **Description**: Join type, ``"ARC"`` or ``"INTERSECTION"``.
## Returns
The offset solid.
## Raises
- **ValueError**: ``amount`` is zero or not finite, ``tolerance`` is not finite and positive, ``kind`` is unknown, ``openings`` do not select faces, or the kernel produced an invalid result.
@@ -3,7 +3,7 @@
## API Definition
```python
def run_notebook(path: str | Path, *, id: str | None = None, overrides: Mapping[str, Any] | None = None, cache: bool = True) -> NotebookRun
def run_notebook(path: str | Path, *, id: str | None = None, overrides: Mapping[str, Any] | None = None, cache: bool = True, through: int | None = None, product: bool = True, timeout: float | None = None) -> NotebookRun
```
*Source: runtime/runner.py*
@@ -22,3 +22,9 @@ value with that id, and cells read it with ``notebook_id()``.
not run (marimo requires such a cell's variables to be overridden all
together). ``cache=False`` neither reads nor writes the cell cache.
Errors raised by a cell propagate unchanged.
*through* runs only the first *through* cells, in notebook order — the
validation of a stage the tail does not have to exist for. With
``product=False`` the run does not look for the notebook's product at
all. *timeout* (seconds) fails the run with :class:`TimeoutError` when
it takes longer; ``None`` (the default) runs unbounded.
+39 -5
View File
@@ -1,11 +1,45 @@
# scale_rsolid
## API Definition
```python
def scale_rsolid(solid: Solid, factors: Sequence[float], center: Sequence[float] = (0, 0, 0)) -> Solid
```
Scale a solid along the current coordinate system's axes about `center`.
The three factors must be finite and nonzero. Uniform scaling preserves
analytic curves and surfaces; nonuniform scaling uses the CAD kernel's
general affine transform. The source stays unchanged. Records a replayable
`make_scale_rsolid` operation. Topology tag lineage is conservatively partial.
*Source: operators/transform.py*
## Import Surface
- top-level: `from simplecadapi import scale_rsolid`
## Description
Scale a solid along the current coordinate system's axes about a center.
The three factors must be finite and nonzero. A uniform scale preserves
analytic curves and surfaces; a nonuniform scale uses the CAD kernel's
general affine transform. The source solid stays unchanged. The operation
is recorded as ``make_scale_rsolid`` for graph replay; topology tag lineage
is conservatively partial.
## Parameters
### solid
- **Description**: The solid to scale.
### factors
- **Description**: Scale factors along the x, y and z axes of the current coordinate system; finite and nonzero.
### center
- **Description**: The fixed point of the scaling, in current coordinate-system coordinates.
## Returns
The scaled solid.
## Raises
- **ValueError**: A factor is zero or not finite, or the kernel could not scale the solid.
@@ -1,12 +1,51 @@
# sweep_multisection_rsolid
## API Definition
```python
def sweep_multisection_rsolid(profiles: Sequence[Face | Wire], path: Wire,
is_frenet: bool = False, binormal: Sequence[float] | Wire | None = None) -> Solid
def sweep_multisection_rsolid(profiles: Sequence[Face | Wire], path: Wire, is_frenet: bool = False, binormal: Sequence[float] | Wire | None = None) -> Solid
```
Sweep through at least two ordered sections along a continuous path. Face
sections supply their outer wire, matching build123d's multi-section sweep
contract. Binormal is an optional direction or auxiliary spine. The kernel
must produce one valid solid. Every section and path is recorded as an input
of `make_sweep_multisection_rsolid`, so model JSON preserves the construction.
*Source: operators/features.py*
## Import Surface
- top-level: `from simplecadapi import sweep_multisection_rsolid`
## Description
Sweep through explicit ordered sections along a continuous path.
At least two ordered sections are needed. Face sections supply their outer
wire, matching build123d's multi-section sweep contract. ``binormal`` is an
optional direction vector or an auxiliary spine. The kernel must produce
one valid solid. Every section and the path are recorded as inputs of
``make_sweep_multisection_rsolid``, so model JSON preserves the
construction.
## Parameters
### profiles
- **Description**: Ordered section faces or wires (at least two).
### path
- **Description**: The continuous path wire.
### is_frenet
- **Description**: Use the Frenet frame along the path.
### binormal
- **Description**: A direction, or an auxiliary spine wire, that fixes the section orientation.
## Returns
The swept solid.
## Raises
- **TypeError**: A section is neither a Face nor a Wire.
- **ValueError**: Fewer than two sections, a zero ``binormal`` direction, or the kernel could not make a solid.
@@ -1,10 +1,40 @@
# transform_rsolid
## API Definition
```python
def transform_rsolid(solid: Solid, matrix: Sequence[Sequence[float]]) -> Solid
```
Apply a finite nonsingular 4x4 affine matrix in the current coordinate system,
including shear, reflection and nonuniform scale. Reject perspective and
singular matrices. Input geometry stays unchanged. Records a replayable
`make_transform_rsolid` operation; topology tag lineage is partial.
*Source: operators/transform.py*
## Import Surface
- top-level: `from simplecadapi import transform_rsolid`
## Description
Apply a finite nonsingular 4x4 affine matrix in the current coordinate system.
The matrix may include shear, reflection and nonuniform scale. Perspective
matrices and singular maps cannot define a solid and are rejected. The
input geometry stays unchanged. The operation is recorded as
``make_transform_rsolid`` for graph replay; topology tag lineage is partial.
## Parameters
### solid
- **Description**: The solid to transform.
### matrix
- **Description**: A 4x4 affine matrix (row-major, last row ``0 0 0 1``), finite and nonsingular, in current coordinate-system coordinates.
## Returns
The transformed solid.
## Raises
- **ValueError**: The matrix is not a finite 4x4 affine matrix, is singular or a perspective map, or the kernel could not transform the solid.
+27
View File
@@ -0,0 +1,27 @@
# 2.2.6.post2 Update Notes
No change in what the SDK computes. Eight operators moved to the module of their family, and
the API reference they are documented in is now generated for all of them.
## Operators live with their family
| operator | now in |
|---|---|
| `scale_rsolid`, `transform_rsolid` | `operators/transform.py` (next to `translate_shape`, `rotate_shape`) |
| `boolean_rsolidlist` | `operators/boolean.py` (next to `union_rsolid`, `cut_rsolid`) |
| `offset_rsolid`, `draft_rsolid`, `extrude_taper_rsolid`, `extrude_until_rsolid`, `sweep_multisection_rsolid` | `operators/features.py` (next to `extrude_rsolid`, `shell_rsolid`, `sweep_rsolid`) |
`from simplecadapi import scale_rsolid` (and every other name) works as before. Code that
imported them from the modules they were first written in, `simplecadapi.operators.deformation`,
`draft`, `section_features` or `limited_extrusion`, still works and gets a `DeprecationWarning`
naming the new place; import from `simplecadapi` instead.
## The API reference is generated for every operator
The documentation generator kept its own hand-written list of source files and public
functions, and nobody had added those four modules to it. The docs of the eight operators above
were therefore written by hand, and the generator deleted them whenever it ran, while
`boolean_rsolidlist` had none. Now `operators/` is discovered, a function the package exports is
public, and what the hand-written docs said (examples, error conditions, how the operation is
replayed) is in the docstrings, so it is in the generated docs. Tests fail if a public operator
has no doc, or if the committed docs differ from what the generator writes.
+22
View File
@@ -0,0 +1,22 @@
# 2.2.6.post2 更新说明
SDK 的计算结果没有变化。八个算子搬进了各自所属家族的模块,并且它们所在的 API 参考现在全部由生成器生成。
## 算子放在自己家族的模块里
| 算子 | 现在在 |
|---|---|
| `scale_rsolid`、`transform_rsolid` | `operators/transform.py`(和 `translate_shape`、`rotate_shape` 在一起) |
| `boolean_rsolidlist` | `operators/boolean.py`(和 `union_rsolid`、`cut_rsolid` 在一起) |
| `offset_rsolid`、`draft_rsolid`、`extrude_taper_rsolid`、`extrude_until_rsolid`、`sweep_multisection_rsolid` | `operators/features.py`(和 `extrude_rsolid`、`shell_rsolid`、`sweep_rsolid` 在一起) |
`from simplecadapi import scale_rsolid`(以及其他所有名字)用法不变。原先从它们最初所在的模块
`simplecadapi.operators.deformation`、`draft`、`section_features`、`limited_extrusion` 导入的代码仍然可用,
会得到一条指出新位置的 `DeprecationWarning`;请改为从 `simplecadapi` 导入。
## 每个算子的 API 参考都由生成器生成
文档生成器自己维护一份手写的源文件和公开函数清单,没人把那四个模块加进去。于是上面八个算子的文档是手写的,
生成器每次运行都会把它们删掉,`boolean_rsolidlist` 则根本没有文档。现在 `operators/` 自动发现,包导出的函数就是公开 API,
手写文档里的内容(示例、错误条件、操作如何回放)已经进了 docstring,也就进了生成的文档。
公开算子缺文档、或已提交的文档与生成器输出不一致,测试都会失败。
+1 -1
View File
@@ -1,6 +1,6 @@
[project]
name = "simplecadapi"
version = "2.2.6.post1"
version = "2.2.6.post2"
description = "A simplified OCP-native CAD modeling Python API"
readme = "README.md"
license = { file = "LICENSE" }
+17 -12
View File
@@ -69,10 +69,15 @@ from .core import (
get_current_cs,
)
from .errors import SimpleCADError
from .operators.deformation import scale_rsolid, offset_rsolid, transform_rsolid, boolean_rsolidlist
from .operators.section_features import extrude_taper_rsolid, sweep_multisection_rsolid
from .operators.limited_extrusion import extrude_until_rsolid
from .operators.draft import draft_rsolid
from .operators.boolean import boolean_rsolidlist
from .operators.features import (
draft_rsolid,
extrude_taper_rsolid,
extrude_until_rsolid,
offset_rsolid,
sweep_multisection_rsolid,
)
from .operators.transform import scale_rsolid, transform_rsolid
from .params.expr import (
Const,
DimensionTolerance,
@@ -437,14 +442,6 @@ def notebook_id() -> str:
__all__ = [
"scale_rsolid",
"boolean_rsolidlist",
"transform_rsolid",
"offset_rsolid",
"extrude_taper_rsolid",
"sweep_multisection_rsolid",
"extrude_until_rsolid",
"draft_rsolid",
"exporter",
# 核心类
"CoordinateSystem",
@@ -585,12 +582,19 @@ __all__ = [
# 变换操作
"mirror_shape",
"rotate_shape",
"scale_rsolid",
"transform_rsolid",
"translate_shape",
# 3D操作
"draft_rsolid",
"extrude_rsolid",
"extrude_taper_rsolid",
"extrude_until_rsolid",
"helical_sweep_rsolid",
"loft_rsolid",
"offset_rsolid",
"revolve_rsolid",
"sweep_multisection_rsolid",
"sweep_rsolid",
"twisted_sweep_rsolid",
# 标签和选择
@@ -601,6 +605,7 @@ __all__ = [
"select_edges_by_tag",
"select_faces_by_tag",
# 布尔运算
"boolean_rsolidlist",
"cut_rsolid",
"make_2d_cut_rface",
"intersect_rsolid",
+1 -9
View File
@@ -16,7 +16,7 @@ keep observing the executed binding.
import sys as _sys
from types import ModuleType as _ModuleType
from . import _support, geometry, transform, boolean, product, sketch, selection, features, deformation, section_features, limited_extrusion, draft
from . import _support, geometry, transform, boolean, product, sketch, selection, features
from ._support import *
from .geometry import *
from .transform import *
@@ -25,10 +25,6 @@ from .product import *
from .sketch import *
from .selection import *
from .features import *
from .deformation import *
from .section_features import *
from .limited_extrusion import *
from .draft import *
_IMPLEMENTATION_MODULES = (
_support,
@@ -39,10 +35,6 @@ _IMPLEMENTATION_MODULES = (
sketch,
selection,
features,
deformation,
section_features,
limited_extrusion,
draft,
)
__all__ = tuple(
+30
View File
@@ -42,6 +42,8 @@ from ..errors import (
suppress_vendor_deprecation_warnings()
from OCP.BRepCheck import BRepCheck_Analyzer
from OCP.BRepGProp import BRepGProp
from OCP.GProp import GProp_GProps
from OCP.BRepBuilderAPI import BRepBuilderAPI_MakeVertex
@@ -2250,4 +2252,32 @@ def _apply_tag_rselection(
_EXPORTABLE_TYPES = (Compound, Solid, Shell, Face, Wire, Edge, Vertex)
def _finite_vector(value: Sequence[float], name: str) -> tuple[float, float, float]:
values = tuple(float(v) for v in evaluate_value(value))
if len(values) != 3 or not all(math.isfinite(v) for v in values):
raise ValueError(f"{name} must contain three finite numbers")
return values
def _finish(source: Solid, wrapped, op: str, params: dict, inputs: list) -> Solid:
solids = solids_of(wrapped)
if len(solids) != 1:
raise ValueError(f"{op} must produce exactly one solid, got {len(solids)}")
result = Solid(solids[0])
props = GProp_GProps()
BRepGProp.VolumePropertiesGK_s(result.wrapped, props, 1e-9, True, True)
if props.Mass() < 0:
result.wrapped.Reverse()
if not BRepCheck_Analyzer(result.wrapped).IsValid():
raise ValueError(f"{op} produced invalid geometry")
result._metadata = source._metadata.copy()
# These builders do not yet provide a complete face-history channel.
_attach_lineage_from_source(source, result, derivation="continuation", op=op, coverage="partial")
_ensure_geo_selection_input_nodes(inputs)
params = {**params, "input_refs": _serialize_shape_refs(inputs)}
record_operation_if_active(op=op, params=params, outputs=result,
input_shapes=inputs, context=_current_context_metadata())
return result
__all__ = tuple(name for name in globals() if not name.startswith("__"))
+59
View File
@@ -696,4 +696,63 @@ def make_2d_intersect_rface(face_a: Face, face_b: Face) -> Face:
error=e,
)
def boolean_rsolidlist(
left: Sequence[Solid],
right: Sequence[Solid],
operation: str,
) -> list[Solid]:
"""Apply a set boolean to two body groups, retaining every result solid.
Members of each group are a geometric set. Unlike single-solid booleans,
a cut or intersection may return several solids or an empty list.
Topology lineage is partial; the ordered inputs and all output slots are
recorded so downstream features can replay the same geometry.
Args:
left: The first group of solids.
right: The second group of solids.
operation: ``"cut"``, ``"intersect"`` or ``"union"``.
Returns:
The result solids, possibly several or none.
Raises:
TypeError: A group contains something that is not a Solid.
ValueError: ``operation`` is unknown, or a member is invalid or empty.
"""
from ..kernel.ocp_booleans import cut_shapes, common_shapes, fuse_shapes
from ..kernel.ocp_export import make_compound_always
lhs, rhs = list(left), list(right)
if operation not in {"cut", "intersect", "union"}:
raise ValueError("operation must be cut, intersect or union")
inputs = [*lhs, *rhs]
if any(not isinstance(body, Solid) for body in inputs):
raise TypeError("boolean groups must contain Solid values")
if any(body.wrapped.IsNull() or not BRepCheck_Analyzer(body.wrapped).IsValid() for body in inputs):
raise ValueError("boolean groups must contain valid nonempty topology")
if operation == "union":
shape = fuse_shapes([body.wrapped for body in inputs]) if inputs else None
elif not lhs or (operation == "intersect" and not rhs):
shape = None
elif operation == "cut":
shape = cut_shapes(make_compound_always([body.wrapped for body in lhs]),
[body.wrapped for body in rhs])
else:
shape = common_shapes([make_compound_always([body.wrapped for body in group])
for group in (lhs, rhs)])
if shape is not None and not BRepCheck_Analyzer(shape).IsValid():
raise ValueError("set boolean produced invalid topology")
result = [Solid(solid) for solid in solids_of(shape)] if shape is not None else []
for body in result:
for source in inputs:
_attach_lineage_from_source(source, body, derivation="continuation",
op="make_boolean_rsolidlist", coverage="partial")
_ensure_geo_selection_input_nodes(inputs)
record_operation_if_active(op="make_boolean_rsolidlist",
params={"operation": operation, "left_count": len(lhs), "right_count": len(rhs),
"input_refs": _serialize_shape_refs(inputs)}, outputs=result,
input_shapes=inputs, context=_current_context_metadata())
return result
__all__ = tuple(name for name in globals() if not name.startswith("__"))
+25 -212
View File
@@ -1,217 +1,30 @@
"""Recorded scaling and signed offsets for CAD source translation."""
"""Moved: the operators this module held live in the module of their family (``_MOVED``).
Kept so that ``from simplecadapi.operators.deformation import <name>`` keeps working;
import from the package root instead, ``from simplecadapi import <name>``.
"""
from __future__ import annotations
import math
from typing import Sequence
import warnings
from importlib import import_module
import numpy as np
from OCP.BRepBuilderAPI import BRepBuilderAPI_Copy, BRepBuilderAPI_GTransform, BRepBuilderAPI_Transform
from OCP.BRepCheck import BRepCheck_Analyzer
from OCP.BRepGProp import BRepGProp
from OCP.BRepOffsetAPI import BRepOffsetAPI_MakeThickSolid
from OCP.GeomAbs import GeomAbs_Arc, GeomAbs_Intersection
from OCP.GProp import GProp_GProps
from OCP.TopTools import TopTools_ListOfShape
from OCP.gp import gp_GTrsf, gp_Pnt, gp_Trsf
from ._support import (
Solid, Face, ShapeSelector, ScalarLike, evaluate_scalar, evaluate_value,
get_current_cs, solids_of, record_operation_if_active,
_attach_lineage_from_source, _current_context_metadata,
_ensure_geo_selection_node_ids, _resolve_selector_or_shapes,
_serialize_shape_refs,
_ensure_geo_selection_input_nodes,
)
_MOVED = {
"scale_rsolid": "transform",
"transform_rsolid": "transform",
"offset_rsolid": "features",
"boolean_rsolidlist": "boolean",
}
def _finite_vector(value: Sequence[float], name: str) -> tuple[float, float, float]:
values = tuple(float(v) for v in evaluate_value(value))
if len(values) != 3 or not all(math.isfinite(v) for v in values):
raise ValueError(f"{name} must contain three finite numbers")
return values
def _finish(source: Solid, wrapped, op: str, params: dict, inputs: list) -> Solid:
solids = solids_of(wrapped)
if len(solids) != 1:
raise ValueError(f"{op} must produce exactly one solid, got {len(solids)}")
result = Solid(solids[0])
props = GProp_GProps()
BRepGProp.VolumePropertiesGK_s(result.wrapped, props, 1e-9, True, True)
if props.Mass() < 0:
result.wrapped.Reverse()
if not BRepCheck_Analyzer(result.wrapped).IsValid():
raise ValueError(f"{op} produced invalid geometry")
result._metadata = source._metadata.copy()
# These builders do not yet provide a complete face-history channel.
_attach_lineage_from_source(source, result, derivation="continuation", op=op, coverage="partial")
_ensure_geo_selection_input_nodes(inputs)
params = {**params, "input_refs": _serialize_shape_refs(inputs)}
record_operation_if_active(op=op, params=params, outputs=result,
input_shapes=inputs, context=_current_context_metadata())
return result
def scale_rsolid(
solid: Solid,
factors: Sequence[float],
center: Sequence[float] = (0, 0, 0),
) -> Solid:
"""Scale along current coordinate-system axes about an explicit center.
Every factor must be finite and nonzero. A uniform scale preserves analytic
geometry; a nonuniform scale converts curves/surfaces where the kernel needs
it. The input is unchanged and this operation is recorded for graph replay.
"""
values = _finite_vector(factors, "factors")
center_value = _finite_vector(center, "center")
if any(v == 0 for v in values):
raise ValueError("scale factors must be nonzero")
cs = get_current_cs()
global_center = cs.transform_point(np.array(center_value))
if values[0] == values[1] == values[2]:
transform = gp_Trsf()
transform.SetScale(gp_Pnt(*global_center), values[0])
builder = BRepBuilderAPI_Transform(solid.wrapped, transform, True)
else:
basis = np.column_stack([cs.transform_vector(np.eye(3)[i]) for i in range(3)])
matrix = basis @ np.diag(values) @ basis.T
translation = global_center - matrix @ global_center
transform = gp_GTrsf()
for row in range(3):
for col in range(3):
transform.SetValue(row + 1, col + 1, float(matrix[row, col]))
transform.SetValue(row + 1, 4, float(translation[row]))
# GTransform's copy flag copies topology, but can retain shared curve
# geometry from boolean/fillet history. Isolate that geometry first:
# otherwise OCCT 7.9 can produce invalid p-curves and crash its checker.
copied = BRepBuilderAPI_Copy(solid.wrapped, True, False).Shape()
builder = BRepBuilderAPI_GTransform(copied, transform, True)
builder.Build()
if not builder.IsDone():
raise ValueError("kernel could not scale the solid")
return _finish(solid, builder.Shape(), "make_scale_rsolid",
{"factors": factors, "center": center}, [solid])
def transform_rsolid(solid: Solid, matrix: Sequence[Sequence[float]]) -> Solid:
"""Apply a finite nonsingular 4x4 affine matrix in the current frame.
General affine transformations include shear and reflection. Perspective
matrices and singular maps cannot define a solid and are rejected.
"""
values = np.asarray(evaluate_value(matrix), dtype=float)
if values.shape != (4, 4) or not np.isfinite(values).all():
raise ValueError("matrix must be a finite 4x4 affine matrix")
if not np.allclose(values[3], (0, 0, 0, 1), rtol=0, atol=1e-12):
raise ValueError("perspective transforms cannot define an affine solid")
if abs(float(np.linalg.det(values[:3, :3]))) < 1e-14:
raise ValueError("matrix must be nonsingular")
cs = get_current_cs()
basis = np.column_stack([cs.transform_vector(np.eye(3)[i]) for i in range(3)])
origin = cs.transform_point(np.zeros(3))
linear = basis @ values[:3, :3] @ basis.T
translation = origin + basis @ values[:3, 3] - linear @ origin
transform = gp_GTrsf()
for row in range(3):
for col in range(3):
transform.SetValue(row + 1, col + 1, float(linear[row, col]))
transform.SetValue(row + 1, 4, float(translation[row]))
copied = BRepBuilderAPI_Copy(solid.wrapped, True, False).Shape()
builder = BRepBuilderAPI_GTransform(copied, transform, True)
builder.Build()
if not builder.IsDone():
raise ValueError("kernel could not transform the solid")
return _finish(solid, builder.Shape(), "make_transform_rsolid", {"matrix": matrix}, [solid])
def offset_rsolid(
solid: Solid,
amount: ScalarLike,
openings: Sequence[Face] | ShapeSelector = (),
*,
tolerance: float = 1e-4,
kind: str = "ARC",
) -> Solid:
"""Offset a solid outward (positive) or inward (negative).
Selected openings form an open shell. Empty openings produce the closed
offset solid. This is distinct from shell_rsolid's positive inward wall
thickness, and supports both signs and ARC/INTERSECTION joins explicitly.
"""
distance = evaluate_scalar(amount)
if not math.isfinite(distance) or distance == 0:
raise ValueError("amount must be finite and nonzero")
if not math.isfinite(tolerance) or tolerance <= 0:
raise ValueError("tolerance must be finite and positive")
joins = {"ARC": GeomAbs_Arc, "INTERSECTION": GeomAbs_Intersection}
if kind not in joins:
raise ValueError("kind must be ARC or INTERSECTION")
faces = list(_resolve_selector_or_shapes(solid, openings))
if any(not isinstance(face, Face) for face in faces):
raise ValueError("openings must select faces")
selected_ids = _ensure_geo_selection_node_ids(solid, faces)
face_list = TopTools_ListOfShape()
for face in faces:
face_list.Append(face.wrapped)
builder = BRepOffsetAPI_MakeThickSolid()
builder.MakeThickSolidByJoin(solid.wrapped, face_list, distance, tolerance,
Intersection=True, RemoveIntEdges=True, Join=joins[kind])
builder.Build()
if not builder.IsDone():
raise ValueError("kernel could not offset the solid")
params = {"amount": amount, "tolerance": tolerance, "kind": kind,
"removed_face_count": len(faces), "selected_faces": _serialize_shape_refs(faces)}
if selected_ids:
params["selected_face_node_ids"] = selected_ids
return _finish(solid, builder.Shape(), "make_offset_rsolid", params, [solid, *faces])
def boolean_rsolidlist(
left: Sequence[Solid],
right: Sequence[Solid],
operation: str,
) -> list[Solid]:
"""Apply a set boolean to two body groups, retaining every result solid.
Members of each group are a geometric set. Unlike single-solid booleans,
a cut or intersection may return several solids or an empty list.
Topology lineage is partial; the ordered inputs and all output slots are
recorded so downstream features can replay the same geometry.
"""
from ..kernel.ocp_booleans import cut_shapes, common_shapes, fuse_shapes
from ..kernel.ocp_export import make_compound_always
lhs, rhs = list(left), list(right)
if operation not in {"cut", "intersect", "union"}:
raise ValueError("operation must be cut, intersect or union")
inputs = [*lhs, *rhs]
if any(not isinstance(body, Solid) for body in inputs):
raise TypeError("boolean groups must contain Solid values")
if any(body.wrapped.IsNull() or not BRepCheck_Analyzer(body.wrapped).IsValid() for body in inputs):
raise ValueError("boolean groups must contain valid nonempty topology")
if operation == "union":
shape = fuse_shapes([body.wrapped for body in inputs]) if inputs else None
elif not lhs or (operation == "intersect" and not rhs):
shape = None
elif operation == "cut":
shape = cut_shapes(make_compound_always([body.wrapped for body in lhs]),
[body.wrapped for body in rhs])
else:
shape = common_shapes([make_compound_always([body.wrapped for body in group])
for group in (lhs, rhs)])
if shape is not None and not BRepCheck_Analyzer(shape).IsValid():
raise ValueError("set boolean produced invalid topology")
result = [Solid(solid) for solid in solids_of(shape)] if shape is not None else []
for body in result:
for source in inputs:
_attach_lineage_from_source(source, body, derivation="continuation",
op="make_boolean_rsolidlist", coverage="partial")
_ensure_geo_selection_input_nodes(inputs)
record_operation_if_active(op="make_boolean_rsolidlist",
params={"operation": operation, "left_count": len(lhs), "right_count": len(rhs),
"input_refs": _serialize_shape_refs(inputs)}, outputs=result,
input_shapes=inputs, context=_current_context_metadata())
return result
__all__ = ("scale_rsolid", "offset_rsolid", "transform_rsolid", "boolean_rsolidlist")
def __getattr__(name: str):
family = _MOVED.get(name)
if family is None:
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
warnings.warn(
f"{__name__}.{name} moved to simplecadapi.operators.{family}; "
f"import it from simplecadapi instead (from simplecadapi import {name})",
DeprecationWarning,
stacklevel=2,
)
return getattr(import_module(f"simplecadapi.operators.{family}"), name)
+22 -78
View File
@@ -1,83 +1,27 @@
"""Draft selected analytic solid faces around a recorded neutral plane."""
"""Moved: the operators this module held live in the module of their family (``_MOVED``).
Kept so that ``from simplecadapi.operators.draft import <name>`` keeps working;
import from the package root instead, ``from simplecadapi import <name>``.
"""
from __future__ import annotations
import math
from typing import Sequence
import warnings
from importlib import import_module
import numpy as np
from OCP.BRepAdaptor import BRepAdaptor_Surface
from OCP.BRepOffsetAPI import BRepOffsetAPI_DraftAngle
from OCP.GeomAbs import GeomAbs_Plane, GeomAbs_Cylinder, GeomAbs_Cone
from OCP.gp import gp_Dir, gp_Pln, gp_Pnt
from ._support import (
Face, Solid, ShapeSelector, ScalarLike, evaluate_scalar, get_current_cs,
_resolve_selector_or_shapes, _ensure_geo_selection_node_ids, _serialize_shape_refs,
)
from .deformation import _finish, _finite_vector
_MOVED = {
"draft_rsolid": "features",
}
def draft_rsolid(
solid: Solid,
faces_to_draft: Sequence[Face] | ShapeSelector,
angle: ScalarLike,
plane_origin: Sequence[float] = (0, 0, 0),
plane_normal: Sequence[float] = (0, 0, 1),
) -> Solid:
"""Draft planar, cylindrical or conical faces by a signed angle in degrees.
The neutral plane fixes the unchanged section. Its origin and normal are in
current coordinate-system coordinates. Face selection is checked against
the input body and retained as graph inputs for strict replay. The original
solid is preserved. Other surface families are explicitly rejected.
"""
if not isinstance(solid, Solid):
raise TypeError("solid must be a Solid")
degrees = float(evaluate_scalar(angle))
if not math.isfinite(degrees) or abs(degrees) >= 90:
raise ValueError("angle must be finite and strictly between -90 and 90 degrees")
origin = _finite_vector(plane_origin, "plane_origin")
normal = _finite_vector(plane_normal, "plane_normal")
cs = get_current_cs()
global_origin = cs.transform_point(np.asarray(origin))
global_normal = cs.transform_vector(np.asarray(normal))
magnitude = float(np.linalg.norm(global_normal))
if magnitude <= 1e-14:
raise ValueError("plane_normal must be nonzero")
global_normal = global_normal / magnitude
selected = list(_resolve_selector_or_shapes(solid, faces_to_draft))
if not selected:
raise ValueError("draft requires at least one selected face")
original_faces = solid._iter_faces()
for face in selected:
if not isinstance(face, Face):
raise ValueError("faces_to_draft must select only Face objects")
if not any(face.wrapped.IsSame(other.wrapped) for other in original_faces):
raise ValueError("selected draft faces must belong to the input solid")
if BRepAdaptor_Surface(face.wrapped).GetType() not in {GeomAbs_Plane, GeomAbs_Cylinder, GeomAbs_Cone}:
raise ValueError("draft supports only planar, cylindrical, and conical faces")
# Remove repeated references without changing the ordered face selection.
selected = list({face.topo_id: face for face in selected}.values())
selected_ids = _ensure_geo_selection_node_ids(solid, selected)
if degrees == 0:
shape = solid.wrapped
else:
direction = gp_Dir(*global_normal)
plane = gp_Pln(gp_Pnt(*global_origin), direction)
builder = BRepOffsetAPI_DraftAngle(solid.wrapped)
for face in selected:
builder.Add(face.wrapped, direction, math.radians(degrees), plane, True)
if not builder.AddDone():
raise ValueError("kernel could not add the requested draft angle to a selected face")
builder.Build()
if not builder.IsDone():
raise ValueError("kernel could not build the drafted solid")
shape = builder.Shape()
params = {"angle": angle, "plane_origin": plane_origin, "plane_normal": plane_normal,
"selected_face_count": len(selected), "selected_faces": _serialize_shape_refs(selected)}
if selected_ids:
params["selected_face_node_ids"] = selected_ids
return _finish(solid, shape, "make_draft_rsolid", params, [solid, *selected])
__all__ = ("draft_rsolid",)
def __getattr__(name: str):
family = _MOVED.get(name)
if family is None:
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
warnings.warn(
f"{__name__}.{name} moved to simplecadapi.operators.{family}; "
f"import it from simplecadapi instead (from simplecadapi import {name})",
DeprecationWarning,
stacklevel=2,
)
return getattr(import_module(f"simplecadapi.operators.{family}"), name)
+514
View File
@@ -11,6 +11,23 @@ from ._diagnostics import (
raise_open_wire_failure,
render_failure_evidence,
)
from ..kernel.ocp_properties import center_of_mass, distance, volume
from ..kernel.ocp_topology import faces_of
from OCP.BRepAdaptor import BRepAdaptor_Surface
from OCP.BRepAlgoAPI import BRepAlgoAPI_Common, BRepAlgoAPI_Cut, BRepAlgoAPI_Splitter
from OCP.BRepBuilderAPI import BRepBuilderAPI_Sewing, BRepBuilderAPI_Transform
from OCP.BRepGProp import BRepGProp, BRepGProp_Face
from OCP.BRepOffsetAPI import BRepOffsetAPI_DraftAngle, BRepOffsetAPI_MakeOffset, BRepOffsetAPI_MakePipeShell, BRepOffsetAPI_MakeThickSolid, BRepOffsetAPI_ThruSections
from OCP.BRepPrimAPI import BRepPrimAPI_MakeHalfSpace, BRepPrimAPI_MakePrism
from OCP.BRepTools import BRepTools
from OCP.GProp import GProp_GProps
from OCP.GeomAbs import GeomAbs_Arc, GeomAbs_Cone, GeomAbs_Cylinder, GeomAbs_Intersection, GeomAbs_Plane
from OCP.LocOpe import LocOpe_DPrism
from OCP.TopAbs import TopAbs_COMPOUND, TopAbs_FACE, TopAbs_SHELL, TopAbs_WIRE
from OCP.TopExp import TopExp_Explorer
from OCP.TopTools import TopTools_ListOfShape
from OCP.TopoDS import TopoDS_Iterator
from OCP.gp import gp_Pln, gp_Trsf, gp_Vec
from ._support import *
from .geometry import (
_default_plane_x_direction,
@@ -1377,4 +1394,501 @@ def helical_sweep_rsolid(
error=e,
)
def offset_rsolid(
solid: Solid,
amount: ScalarLike,
openings: Sequence[Face] | ShapeSelector = (),
*,
tolerance: float = 1e-4,
kind: str = "ARC",
) -> Solid:
"""Offset a solid outward (positive) or inward (negative).
The amount must be finite and nonzero. Faces passed as ``openings`` form an
open shell; with no openings the result is the closed offset solid. The
join ``kind`` is ``ARC`` or ``INTERSECTION``. Invalid kernel results raise
an error. The operation is recorded as ``make_offset_rsolid`` with explicit
face selections; topology tag lineage is conservatively partial.
``shell_rsolid`` keeps its own contract (a positive inward wall thickness);
this one supports both signs.
Args:
solid: The solid to offset.
amount: Offset distance; positive outward, negative inward.
openings: Faces of ``solid`` (or a QL selector) left open.
tolerance: Kernel tolerance of the offset.
kind: Join type, ``"ARC"`` or ``"INTERSECTION"``.
Returns:
The offset solid.
Raises:
ValueError: ``amount`` is zero or not finite, ``tolerance`` is not
finite and positive, ``kind`` is unknown, ``openings`` do not select
faces, or the kernel produced an invalid result.
"""
distance = evaluate_scalar(amount)
if not math.isfinite(distance) or distance == 0:
raise ValueError("amount must be finite and nonzero")
if not math.isfinite(tolerance) or tolerance <= 0:
raise ValueError("tolerance must be finite and positive")
joins = {"ARC": GeomAbs_Arc, "INTERSECTION": GeomAbs_Intersection}
if kind not in joins:
raise ValueError("kind must be ARC or INTERSECTION")
faces = list(_resolve_selector_or_shapes(solid, openings))
if any(not isinstance(face, Face) for face in faces):
raise ValueError("openings must select faces")
selected_ids = _ensure_geo_selection_node_ids(solid, faces)
face_list = TopTools_ListOfShape()
for face in faces:
face_list.Append(face.wrapped)
builder = BRepOffsetAPI_MakeThickSolid()
builder.MakeThickSolidByJoin(solid.wrapped, face_list, distance, tolerance,
Intersection=True, RemoveIntEdges=True, Join=joins[kind])
builder.Build()
if not builder.IsDone():
raise ValueError("kernel could not offset the solid")
params = {"amount": amount, "tolerance": tolerance, "kind": kind,
"removed_face_count": len(faces), "selected_faces": _serialize_shape_refs(faces)}
if selected_ids:
params["selected_face_node_ids"] = selected_ids
return _finish(solid, builder.Shape(), "make_offset_rsolid", params, [solid, *faces])
def draft_rsolid(
solid: Solid,
faces_to_draft: Sequence[Face] | ShapeSelector,
angle: ScalarLike,
plane_origin: Sequence[float] = (0, 0, 0),
plane_normal: Sequence[float] = (0, 0, 1),
) -> Solid:
"""Draft planar, cylindrical or conical faces by a signed angle in degrees.
The neutral plane fixes the unchanged section: the selected faces lean
toward or away from it. Its origin and normal are in current
coordinate-system coordinates. Face selection is checked against the input
body and retained as graph inputs for strict replay. The input solid is
preserved, the output must be one valid solid, and a zero angle records an
unchanged result. Other surface families are explicitly rejected.
The operation is recorded as ``make_draft_rsolid``; the body and selected
faces are ordered inputs, and the angle, neutral plane and face selection
nodes are parameters, so model JSON replay is strict.
Args:
solid: The body to draft.
faces_to_draft: Faces of ``solid``, or a QL selector that picks them.
angle: Draft angle in degrees, strictly between -90 and 90.
plane_origin: A point of the neutral plane.
plane_normal: Normal of the neutral plane; must be nonzero.
Returns:
The drafted solid.
Raises:
TypeError: ``solid`` is not a Solid.
ValueError: Empty selection, a selection that is not made of faces of
``solid``, an unsupported surface family, a zero plane normal, or
a nonfinite or out-of-range angle.
Examples:
import simplecadapi as scad
from simplecadapi import ql
body = scad.make_box_rsolid(10, 10, 10)
right = ql.faces().where(ql.prop("geom.normal.x", ">", 0.9)).exactly(1)
drafted = scad.draft_rsolid(body, right, angle=10)
"""
if not isinstance(solid, Solid):
raise TypeError("solid must be a Solid")
degrees = float(evaluate_scalar(angle))
if not math.isfinite(degrees) or abs(degrees) >= 90:
raise ValueError("angle must be finite and strictly between -90 and 90 degrees")
origin = _finite_vector(plane_origin, "plane_origin")
normal = _finite_vector(plane_normal, "plane_normal")
cs = get_current_cs()
global_origin = cs.transform_point(np.asarray(origin))
global_normal = cs.transform_vector(np.asarray(normal))
magnitude = float(np.linalg.norm(global_normal))
if magnitude <= 1e-14:
raise ValueError("plane_normal must be nonzero")
global_normal = global_normal / magnitude
selected = list(_resolve_selector_or_shapes(solid, faces_to_draft))
if not selected:
raise ValueError("draft requires at least one selected face")
original_faces = solid._iter_faces()
for face in selected:
if not isinstance(face, Face):
raise ValueError("faces_to_draft must select only Face objects")
if not any(face.wrapped.IsSame(other.wrapped) for other in original_faces):
raise ValueError("selected draft faces must belong to the input solid")
if BRepAdaptor_Surface(face.wrapped).GetType() not in {GeomAbs_Plane, GeomAbs_Cylinder, GeomAbs_Cone}:
raise ValueError("draft supports only planar, cylindrical, and conical faces")
# Remove repeated references without changing the ordered face selection.
selected = list({face.topo_id: face for face in selected}.values())
selected_ids = _ensure_geo_selection_node_ids(solid, selected)
if degrees == 0:
shape = solid.wrapped
else:
direction = gp_Dir(*global_normal)
plane = gp_Pln(gp_Pnt(*global_origin), direction)
builder = BRepOffsetAPI_DraftAngle(solid.wrapped)
for face in selected:
builder.Add(face.wrapped, direction, math.radians(degrees), plane, True)
if not builder.AddDone():
raise ValueError("kernel could not add the requested draft angle to a selected face")
builder.Build()
if not builder.IsDone():
raise ValueError("kernel could not build the drafted solid")
shape = builder.Shape()
params = {"angle": angle, "plane_origin": plane_origin, "plane_normal": plane_normal,
"selected_face_count": len(selected), "selected_faces": _serialize_shape_refs(selected)}
if selected_ids:
params["selected_face_node_ids"] = selected_ids
return _finish(solid, shape, "make_draft_rsolid", params, [solid, *selected])
def extrude_taper_rsolid(
profile: Face,
vector: Sequence[float],
taper: float,
flip_inner: bool = True,
) -> Solid:
"""Extrude a planar sketch face by a vector, with a taper in degrees.
The vector is nonzero and in current coordinate-system coordinates. The
finite taper angle lies strictly between -90 and 90; a positive taper
shrinks the outer section, and inner loops taper the opposite way when
``flip_inner`` is true. An analytic draft prism is used where applicable
and exact offset sections with lofts otherwise. Collapsed loops and invalid
topology raise errors. The operation is recorded as
``make_extrude_taper_rsolid`` for replay.
Args:
profile: The planar face to extrude.
vector: Extrusion vector (nonzero).
taper: Taper angle in degrees, strictly between -90 and 90.
flip_inner: Taper inner loops in the opposite direction.
Returns:
The tapered solid.
Raises:
ValueError: A zero vector, an out-of-range taper, a nonplanar profile,
collapsed loops or an invalid result.
"""
values = _finite_vector(vector, "vector")
angle = float(evaluate_scalar(taper))
if not math.isfinite(angle) or abs(angle) >= 90:
raise ValueError("taper must be finite and between -90 and 90 degrees")
displacement = get_current_cs().transform_vector(np.asarray(values))
length = float(np.linalg.norm(displacement))
if length <= 1e-12:
raise ValueError("extrusion vector must be nonzero")
surface = BRepAdaptor_Surface(profile.wrapped, True)
if surface.GetType() != GeomAbs_Plane:
raise ValueError("taper extrusion requires a planar profile")
normal = np.asarray(tuple(profile.get_normal_at()), dtype=float)
outer = BRepTools.OuterWire_s(profile.wrapped)
wires = [outer]
explorer = TopExp_Explorer(profile.wrapped, TopAbs_WIRE)
while explorer.More():
wire = TopoDS.Wire_s(explorer.Current())
if not wire.IsSame(outer):
wires.append(wire)
explorer.Next()
if angle == 0:
shape = BRepPrimAPI_MakePrism(profile.wrapped, gp_Vec(*displacement)).Shape()
elif np.linalg.norm(displacement / length - normal) < 1e-8 and normal[2] > 0 and len(wires) == 1 and angle > 0:
shape = LocOpe_DPrism(profile.wrapped, length / math.cos(math.radians(angle)), math.radians(angle)).Shape()
else:
# Offset in the profile plane before translating the final section.
move = gp_Trsf()
move.SetTranslation(gp_Vec(*displacement))
solids = []
for i, wire in enumerate(wires):
# Face inner wires wind opposite to the outer boundary. Normalize
# their winding before applying the signed 2-D offset so that
# flip_inner controls geometry rather than kernel wire orientation.
if i:
wire = TopoDS.Wire_s(wire.Reversed())
offset = -length * math.tan(math.radians(angle)) * (-1 if i and flip_inner else 1)
builder = BRepOffsetAPI_MakeOffset(wire, GeomAbs_Intersection, False)
builder.Perform(offset)
if not builder.IsDone():
raise ValueError("taper collapses a profile loop")
offset_shape = builder.Shape()
exp = TopExp_Explorer(offset_shape, TopAbs_WIRE)
found = []
while exp.More():
found.append(TopoDS.Wire_s(exp.Current()))
exp.Next()
if len(found) != 1:
raise ValueError("taper changes loop connectivity")
moved = BRepBuilderAPI_Transform(found[0], move, True).Shape()
loft = BRepOffsetAPI_ThruSections(True, False)
loft.AddWire(wire)
loft.AddWire(TopoDS.Wire_s(moved))
loft.Build()
if not loft.IsDone():
raise ValueError("kernel could not build tapered sections")
solids.append(loft.Shape())
shape = solids[0]
for tool in solids[1:]:
cut = BRepAlgoAPI_Cut(shape, tool)
cut.Build()
if not cut.IsDone():
raise ValueError("kernel could not subtract tapered inner loop")
shape = cut.Shape()
return _finish(profile, shape, "make_extrude_taper_rsolid",
{"vector": vector, "taper": taper, "flip_inner": flip_inner}, [profile])
def sweep_multisection_rsolid(
profiles: Sequence[Face | Wire],
path: Wire,
is_frenet: bool = False,
binormal: Sequence[float] | Wire | None = None,
) -> Solid:
"""Sweep through explicit ordered sections along a continuous path.
At least two ordered sections are needed. Face sections supply their outer
wire, matching build123d's multi-section sweep contract. ``binormal`` is an
optional direction vector or an auxiliary spine. The kernel must produce
one valid solid. Every section and the path are recorded as inputs of
``make_sweep_multisection_rsolid``, so model JSON preserves the
construction.
Args:
profiles: Ordered section faces or wires (at least two).
path: The continuous path wire.
is_frenet: Use the Frenet frame along the path.
binormal: A direction, or an auxiliary spine wire, that fixes the
section orientation.
Returns:
The swept solid.
Raises:
TypeError: A section is neither a Face nor a Wire.
ValueError: Fewer than two sections, a zero ``binormal`` direction, or
the kernel could not make a solid.
"""
sections = list(profiles)
if len(sections) < 2:
raise ValueError("multi-section sweep requires at least two sections")
builder = BRepOffsetAPI_MakePipeShell(path.wrapped)
rotate = False
if isinstance(binormal, Wire):
builder.SetMode(binormal.wrapped, True)
elif binormal is not None:
values = _finite_vector(binormal, "binormal")
direction = get_current_cs().transform_vector(np.asarray(values))
if np.linalg.norm(direction) < 1e-12:
raise ValueError("binormal direction must be nonzero")
builder.SetMode(gp_Dir(*direction))
rotate = True
else:
builder.SetMode(bool(is_frenet))
for section in sections:
if not isinstance(section, (Face, Wire)):
raise TypeError("sections must be Face or Wire")
wire = BRepTools.OuterWire_s(section.wrapped) if isinstance(section, Face) else section.wrapped
builder.Add(wire, False, rotate)
builder.Build()
if not builder.IsDone() or not builder.MakeSolid():
raise ValueError("kernel could not make a solid multi-section sweep")
inputs = [*sections, path]
params = {"profile_count": len(sections), "is_frenet": bool(is_frenet), "binormal": None}
if isinstance(binormal, Wire):
inputs.append(binormal)
params["binormal_is_wire"] = True
elif binormal is not None:
params["binormal"] = binormal
return _finish(sections[0], builder.Shape(), "make_sweep_multisection_rsolid", params, inputs)
def _top_level(shape):
if shape.ShapeType() != TopAbs_COMPOUND:
return [shape]
output = []
iterator = TopoDS_Iterator(shape)
while iterator.More():
output.extend(_top_level(iterator.Value()))
iterator.Next()
return output
def _crosses_direction(face, axis):
"""Ignore side walls tangent to the extrusion, including coincident walls."""
u0, u1, v0, v1 = BRepTools.UVBounds_s(face)
properties = BRepGProp_Face(face)
for u in (.25, .5, .75):
for v in (.25, .5, .75):
point, normal = gp_Pnt(), gp_Vec()
properties.Normal(u0 + u * (u1-u0), v0 + v * (v1-v0), point, normal)
length = normal.Magnitude()
if length > 1e-14 and abs(normal.X()*axis[0] + normal.Y()*axis[1] + normal.Z()*axis[2]) / length > 1e-8:
return True
return False
def _contact_surfaces(target, prism, axis):
common = BRepAlgoAPI_Common(target, prism)
common.Build()
if not common.IsDone() or not faces_of(common.Shape()):
raise ValueError("No intersection: extrusion does not contact target")
history = common.History()
modified = []
intersection_faces = faces_of(common.Shape())
for face in faces_of(target):
affected = list(history.Modified(face))
if affected:
modified.extend(TopoDS.Face_s(item) for item in affected if item.ShapeType() == TopAbs_FACE)
elif not history.IsRemoved(face) and any(item.IsSame(face) for item in intersection_faces):
# A whole target may lie inside the temporary prism, in which case
# unchanged boundary faces are still genuine contact surfaces.
modified.append(face)
if not modified:
raise ValueError("No target boundary surfaces found in extrusion intersection")
sewing = BRepBuilderAPI_Sewing(1e-6)
for face in modified:
if _crosses_direction(face, axis):
sewing.Add(face)
sewing.Perform()
surfaces = _top_level(sewing.SewedShape())
if not surfaces or any(part.ShapeType() not in {TopAbs_FACE, TopAbs_SHELL} for part in surfaces):
raise ValueError("Kernel could not sew target contact surfaces")
return surfaces
def _split_on_surface(prism, surface, keep_top):
arguments, tools = TopTools_ListOfShape(), TopTools_ListOfShape()
arguments.Append(prism)
tools.Append(surface)
splitter = BRepAlgoAPI_Splitter()
splitter.SetArguments(arguments)
splitter.SetTools(tools)
splitter.Build()
if not splitter.IsDone():
raise ValueError("Kernel could not split extrusion on target surface")
reference_face = TopoDS.Face_s(surface) if surface.ShapeType() == TopAbs_FACE else faces_of(surface)[0]
u0, u1, v0, v1 = BRepTools.UVBounds_s(reference_face)
point, normal = gp_Pnt(), gp_Vec()
BRepGProp_Face(reference_face).Normal((u0+u1)/2, (v0+v1)/2, point, normal)
if normal.Magnitude() <= 1e-14:
raise ValueError("Undefined normal on termination surface")
normal.Normalize()
reference = point.Translated(normal)
if surface.ShapeType() == TopAbs_FACE:
halfspace = BRepPrimAPI_MakeHalfSpace(TopoDS.Face_s(surface), reference).Solid()
else:
halfspace = BRepPrimAPI_MakeHalfSpace(TopoDS.Shell_s(surface), reference).Solid()
candidates = []
for part in solids_of(splitter.Shape()):
common = BRepAlgoAPI_Common(part, halfspace)
common.Build()
if not common.IsDone():
raise ValueError("Kernel could not classify the termination side")
properties = GProp_GProps()
BRepGProp.LinearProperties_s(common.Shape(), properties)
is_top = properties.Mass() >= 1e-6
if is_top == keep_top:
candidates.append(part)
return candidates
def extrude_until_rsolid(
profile: Face,
target: Solid | Sequence[Solid],
direction: Sequence[float] = (0, 0, 1),
until: str = "NEXT",
) -> Solid:
"""Extrude a planar face until a target surface, including curved surfaces.
The direction is interpreted in the current coordinate system and
normalized before construction. ``until`` selects the termination:
``NEXT`` (forward, nearest intersecting target surface), ``LAST`` (forward,
farthest), ``PREVIOUS`` (reverse, nearest) and ``FIRST`` (reverse,
farthest). The temporary prism is intersected with the target, the target's
boundary faces are taken from kernel history and sewn into surfaces, and
the prism is split on the selected one. Bounding boxes only size the
temporary prism; they do not define the termination surface, and side
walls parallel to the direction do not join separate near and far limits.
Targets must cover the profile at the requested contact: an uncovered,
open or disconnected output is rejected, as are a missing contact, an
invalid mode, a zero or nonfinite direction and an empty target sequence.
Inputs are preserved. The operation is recorded as
``make_extrude_until_rsolid``; its ordered inputs are the profile followed
by every target solid and its parameters keep ``direction``, ``until`` and
``target_count``, so a changed target is recomputed on replay (no final
BRep is embedded).
Args:
profile: The planar face to extrude.
target: A solid, or a sequence of solids, that bounds the extrusion.
direction: Extrusion direction in current coordinate-system
coordinates.
until: ``"NEXT"``, ``"LAST"``, ``"PREVIOUS"`` or ``"FIRST"``.
Returns:
One valid solid.
Raises:
TypeError: ``profile`` is not a Face, or ``target`` is not a Solid or
a sequence of Solid.
ValueError: No target, no contact, insufficient coverage, a bad mode
or direction, or an invalid kernel result.
Examples:
import simplecadapi as scad
profile = scad.make_rectangle_rface(2, 2)
ceiling = scad.make_box_rsolid(10, 10, 2, bottom_face_center=(0, 0, 5))
near = scad.extrude_until_rsolid(profile, ceiling, until="NEXT") # volume 20
far = scad.extrude_until_rsolid(profile, ceiling, until="LAST") # volume 28
sphere = scad.make_sphere_rsolid(5, center=(0, 0, 10))
curved = scad.extrude_until_rsolid(profile, sphere)
"""
if not isinstance(profile, Face):
raise TypeError("profile must be a Face")
targets = [target] if isinstance(target, Solid) else list(target)
if not targets:
raise ValueError("target must contain at least one Solid")
if any(not isinstance(item, Solid) for item in targets):
raise TypeError("target must be a Solid or a sequence of Solid")
mode = str(getattr(until, "name", until)).upper()
if mode not in {"NEXT", "LAST", "PREVIOUS", "FIRST"}:
raise ValueError("until must be NEXT, LAST, PREVIOUS, or FIRST")
values = _finite_vector(direction, "direction")
global_direction = get_current_cs().transform_vector(np.asarray(values))
magnitude = float(np.linalg.norm(global_direction))
if not math.isfinite(magnitude) or magnitude <= 1e-14:
raise ValueError("direction must be a finite nonzero vector")
axis = global_direction / magnitude
if mode in {"PREVIOUS", "FIRST"}:
axis = -axis
bound_target = make_compound_always([item.wrapped for item in targets])
box = bounding_box(make_compound_always([profile.wrapped, bound_target]))
length = math.sqrt((box.xmax-box.xmin)**2 + (box.ymax-box.ymin)**2 + (box.zmax-box.zmin)**2)
if length <= 1e-12:
raise ValueError("Degenerate profile and target bounds")
prism = BRepPrimAPI_MakePrism(profile.wrapped, gp_Vec(*(axis * length))).Shape()
surfaces = sorted(_contact_surfaces(bound_target, prism, axis), key=lambda part: distance(part, profile.wrapped))
nearest = mode in {"NEXT", "PREVIOUS"}
surface = surfaces[0] if nearest else surfaces[-1]
candidates = _split_on_surface(prism, surface, keep_top=nearest)
if not candidates:
raise ValueError("Extrusion produced no solid on the requested side of the target")
origin = np.asarray(tuple(center_of_mass(profile.wrapped)))
chosen = min(candidates, key=lambda part: np.dot(np.asarray(tuple(center_of_mass(part))) - origin, axis))
if abs(volume(chosen) - volume(prism)) <= max(1e-8, abs(volume(prism))*1e-9):
raise ValueError("Target termination surface does not completely cover the extrusion profile")
if volume(chosen) <= 1e-12 or not BRepCheck_Analyzer(chosen).IsValid():
raise ValueError("Target surface did not completely cover a valid limited extrusion")
result = _finish(profile, chosen, "make_extrude_until_rsolid",
{"direction": direction, "until": mode, "target_count": len(targets)}, [profile, *targets])
result._apply_tag("solid.extrusion", propagate=False)
return result
__all__ = tuple(name for name in globals() if not name.startswith("__"))
+20 -173
View File
@@ -1,180 +1,27 @@
"""Recorded extrusion terminated by a real target face or curved shell.
"""Moved: the operators this module held live in the module of their family (``_MOVED``).
The construction follows the surface-history approach used by build123d:
intersect a long prism, sew the affected target faces, order contact surfaces,
and split by the selected surface. Bounding boxes only bound the temporary
prism; they never define the termination surface.
Kept so that ``from simplecadapi.operators.limited_extrusion import <name>`` keeps working;
import from the package root instead, ``from simplecadapi import <name>``.
"""
from __future__ import annotations
import math
from typing import Sequence
import warnings
from importlib import import_module
import numpy as np
from OCP.BRepAlgoAPI import BRepAlgoAPI_Common, BRepAlgoAPI_Splitter
from OCP.BRepBuilderAPI import BRepBuilderAPI_Sewing
from OCP.BRepCheck import BRepCheck_Analyzer
from OCP.BRepGProp import BRepGProp, BRepGProp_Face
from OCP.BRepPrimAPI import BRepPrimAPI_MakeHalfSpace, BRepPrimAPI_MakePrism
from OCP.BRepTools import BRepTools
from OCP.GProp import GProp_GProps
from OCP.TopAbs import TopAbs_COMPOUND, TopAbs_FACE, TopAbs_SHELL
from OCP.TopoDS import TopoDS, TopoDS_Iterator
from OCP.TopTools import TopTools_ListOfShape
from OCP.gp import gp_Pnt, gp_Vec
from ..kernel.ocp_booleans import solids_of
from ..kernel.ocp_export import make_compound_always
from ..kernel.ocp_properties import bounding_box, center_of_mass, distance, volume
from ..kernel.ocp_topology import faces_of
from ._support import Face, Solid, evaluate_value, get_current_cs
from .deformation import _finish, _finite_vector
_MOVED = {
"extrude_until_rsolid": "features",
}
def _top_level(shape):
if shape.ShapeType() != TopAbs_COMPOUND:
return [shape]
output = []
iterator = TopoDS_Iterator(shape)
while iterator.More():
output.extend(_top_level(iterator.Value()))
iterator.Next()
return output
def _crosses_direction(face, axis):
"""Ignore side walls tangent to the extrusion, including coincident walls."""
u0, u1, v0, v1 = BRepTools.UVBounds_s(face)
properties = BRepGProp_Face(face)
for u in (.25, .5, .75):
for v in (.25, .5, .75):
point, normal = gp_Pnt(), gp_Vec()
properties.Normal(u0 + u * (u1-u0), v0 + v * (v1-v0), point, normal)
length = normal.Magnitude()
if length > 1e-14 and abs(normal.X()*axis[0] + normal.Y()*axis[1] + normal.Z()*axis[2]) / length > 1e-8:
return True
return False
def _contact_surfaces(target, prism, axis):
common = BRepAlgoAPI_Common(target, prism)
common.Build()
if not common.IsDone() or not faces_of(common.Shape()):
raise ValueError("No intersection: extrusion does not contact target")
history = common.History()
modified = []
intersection_faces = faces_of(common.Shape())
for face in faces_of(target):
affected = list(history.Modified(face))
if affected:
modified.extend(TopoDS.Face_s(item) for item in affected if item.ShapeType() == TopAbs_FACE)
elif not history.IsRemoved(face) and any(item.IsSame(face) for item in intersection_faces):
# A whole target may lie inside the temporary prism, in which case
# unchanged boundary faces are still genuine contact surfaces.
modified.append(face)
if not modified:
raise ValueError("No target boundary surfaces found in extrusion intersection")
sewing = BRepBuilderAPI_Sewing(1e-6)
for face in modified:
if _crosses_direction(face, axis):
sewing.Add(face)
sewing.Perform()
surfaces = _top_level(sewing.SewedShape())
if not surfaces or any(part.ShapeType() not in {TopAbs_FACE, TopAbs_SHELL} for part in surfaces):
raise ValueError("Kernel could not sew target contact surfaces")
return surfaces
def _split_on_surface(prism, surface, keep_top):
arguments, tools = TopTools_ListOfShape(), TopTools_ListOfShape()
arguments.Append(prism)
tools.Append(surface)
splitter = BRepAlgoAPI_Splitter()
splitter.SetArguments(arguments)
splitter.SetTools(tools)
splitter.Build()
if not splitter.IsDone():
raise ValueError("Kernel could not split extrusion on target surface")
reference_face = TopoDS.Face_s(surface) if surface.ShapeType() == TopAbs_FACE else faces_of(surface)[0]
u0, u1, v0, v1 = BRepTools.UVBounds_s(reference_face)
point, normal = gp_Pnt(), gp_Vec()
BRepGProp_Face(reference_face).Normal((u0+u1)/2, (v0+v1)/2, point, normal)
if normal.Magnitude() <= 1e-14:
raise ValueError("Undefined normal on termination surface")
normal.Normalize()
reference = point.Translated(normal)
if surface.ShapeType() == TopAbs_FACE:
halfspace = BRepPrimAPI_MakeHalfSpace(TopoDS.Face_s(surface), reference).Solid()
else:
halfspace = BRepPrimAPI_MakeHalfSpace(TopoDS.Shell_s(surface), reference).Solid()
candidates = []
for part in solids_of(splitter.Shape()):
common = BRepAlgoAPI_Common(part, halfspace)
common.Build()
if not common.IsDone():
raise ValueError("Kernel could not classify the termination side")
properties = GProp_GProps()
BRepGProp.LinearProperties_s(common.Shape(), properties)
is_top = properties.Mass() >= 1e-6
if is_top == keep_top:
candidates.append(part)
return candidates
def extrude_until_rsolid(
profile: Face,
target: Solid | Sequence[Solid],
direction: Sequence[float] = (0, 0, 1),
until: str = "NEXT",
) -> Solid:
"""Extrude a planar face until a target surface, including curved surfaces.
NEXT and LAST select the nearest and farthest forward contact. PREVIOUS
and FIRST reverse the direction and select the nearest and farthest contact
behind the profile. Target surfaces must cover the profile at the contact;
an uncovered/open or disconnected output is rejected. Every target remains
a graph input, so changes to target geometry replay this feature correctly.
"""
if not isinstance(profile, Face):
raise TypeError("profile must be a Face")
targets = [target] if isinstance(target, Solid) else list(target)
if not targets:
raise ValueError("target must contain at least one Solid")
if any(not isinstance(item, Solid) for item in targets):
raise TypeError("target must be a Solid or a sequence of Solid")
mode = str(getattr(until, "name", until)).upper()
if mode not in {"NEXT", "LAST", "PREVIOUS", "FIRST"}:
raise ValueError("until must be NEXT, LAST, PREVIOUS, or FIRST")
values = _finite_vector(direction, "direction")
global_direction = get_current_cs().transform_vector(np.asarray(values))
magnitude = float(np.linalg.norm(global_direction))
if not math.isfinite(magnitude) or magnitude <= 1e-14:
raise ValueError("direction must be a finite nonzero vector")
axis = global_direction / magnitude
if mode in {"PREVIOUS", "FIRST"}:
axis = -axis
bound_target = make_compound_always([item.wrapped for item in targets])
box = bounding_box(make_compound_always([profile.wrapped, bound_target]))
length = math.sqrt((box.xmax-box.xmin)**2 + (box.ymax-box.ymin)**2 + (box.zmax-box.zmin)**2)
if length <= 1e-12:
raise ValueError("Degenerate profile and target bounds")
prism = BRepPrimAPI_MakePrism(profile.wrapped, gp_Vec(*(axis * length))).Shape()
surfaces = sorted(_contact_surfaces(bound_target, prism, axis), key=lambda part: distance(part, profile.wrapped))
nearest = mode in {"NEXT", "PREVIOUS"}
surface = surfaces[0] if nearest else surfaces[-1]
candidates = _split_on_surface(prism, surface, keep_top=nearest)
if not candidates:
raise ValueError("Extrusion produced no solid on the requested side of the target")
origin = np.asarray(tuple(center_of_mass(profile.wrapped)))
chosen = min(candidates, key=lambda part: np.dot(np.asarray(tuple(center_of_mass(part))) - origin, axis))
if abs(volume(chosen) - volume(prism)) <= max(1e-8, abs(volume(prism))*1e-9):
raise ValueError("Target termination surface does not completely cover the extrusion profile")
if volume(chosen) <= 1e-12 or not BRepCheck_Analyzer(chosen).IsValid():
raise ValueError("Target surface did not completely cover a valid limited extrusion")
result = _finish(profile, chosen, "make_extrude_until_rsolid",
{"direction": direction, "until": mode, "target_count": len(targets)}, [profile, *targets])
result._apply_tag("solid.extrusion", propagate=False)
return result
__all__ = ("extrude_until_rsolid",)
def __getattr__(name: str):
family = _MOVED.get(name)
if family is None:
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
warnings.warn(
f"{__name__}.{name} moved to simplecadapi.operators.{family}; "
f"import it from simplecadapi instead (from simplecadapi import {name})",
DeprecationWarning,
stacklevel=2,
)
return getattr(import_module(f"simplecadapi.operators.{family}"), name)
+23 -145
View File
@@ -1,150 +1,28 @@
"""Recorded tapered extrusions and sweeps with multiple explicit sections."""
"""Moved: the operators this module held live in the module of their family (``_MOVED``).
Kept so that ``from simplecadapi.operators.section_features import <name>`` keeps working;
import from the package root instead, ``from simplecadapi import <name>``.
"""
from __future__ import annotations
import math
from typing import Sequence
import warnings
from importlib import import_module
import numpy as np
from OCP.BRepAdaptor import BRepAdaptor_Surface
from OCP.BRepAlgoAPI import BRepAlgoAPI_Cut
from OCP.BRepBuilderAPI import BRepBuilderAPI_Transform
from OCP.BRepOffsetAPI import BRepOffsetAPI_MakeOffset, BRepOffsetAPI_MakePipeShell, BRepOffsetAPI_ThruSections
from OCP.BRepPrimAPI import BRepPrimAPI_MakePrism
from OCP.BRepTools import BRepTools
from OCP.GeomAbs import GeomAbs_Intersection, GeomAbs_Plane
from OCP.LocOpe import LocOpe_DPrism
from OCP.TopAbs import TopAbs_WIRE
from OCP.TopExp import TopExp_Explorer
from OCP.TopoDS import TopoDS
from OCP.gp import gp_Dir, gp_Trsf, gp_Vec
from ._support import Face, Wire, Solid, evaluate_scalar, get_current_cs
from .deformation import _finish, _finite_vector
_MOVED = {
"extrude_taper_rsolid": "features",
"sweep_multisection_rsolid": "features",
}
def extrude_taper_rsolid(
profile: Face,
vector: Sequence[float],
taper: float,
flip_inner: bool = True,
) -> Solid:
"""Extrude a planar face by a vector, with a taper in degrees.
Positive taper shrinks the outer section. Inner loops optionally taper in
the opposite direction. Analytic draft prisms are retained where valid;
other orientations/holes use exact offset wire sections and solid lofts.
"""
values = _finite_vector(vector, "vector")
angle = float(evaluate_scalar(taper))
if not math.isfinite(angle) or abs(angle) >= 90:
raise ValueError("taper must be finite and between -90 and 90 degrees")
displacement = get_current_cs().transform_vector(np.asarray(values))
length = float(np.linalg.norm(displacement))
if length <= 1e-12:
raise ValueError("extrusion vector must be nonzero")
surface = BRepAdaptor_Surface(profile.wrapped, True)
if surface.GetType() != GeomAbs_Plane:
raise ValueError("taper extrusion requires a planar profile")
normal = np.asarray(tuple(profile.get_normal_at()), dtype=float)
outer = BRepTools.OuterWire_s(profile.wrapped)
wires = [outer]
explorer = TopExp_Explorer(profile.wrapped, TopAbs_WIRE)
while explorer.More():
wire = TopoDS.Wire_s(explorer.Current())
if not wire.IsSame(outer):
wires.append(wire)
explorer.Next()
if angle == 0:
shape = BRepPrimAPI_MakePrism(profile.wrapped, gp_Vec(*displacement)).Shape()
elif np.linalg.norm(displacement / length - normal) < 1e-8 and normal[2] > 0 and len(wires) == 1 and angle > 0:
shape = LocOpe_DPrism(profile.wrapped, length / math.cos(math.radians(angle)), math.radians(angle)).Shape()
else:
# Offset in the profile plane before translating the final section.
move = gp_Trsf()
move.SetTranslation(gp_Vec(*displacement))
solids = []
for i, wire in enumerate(wires):
# Face inner wires wind opposite to the outer boundary. Normalize
# their winding before applying the signed 2-D offset so that
# flip_inner controls geometry rather than kernel wire orientation.
if i:
wire = TopoDS.Wire_s(wire.Reversed())
offset = -length * math.tan(math.radians(angle)) * (-1 if i and flip_inner else 1)
builder = BRepOffsetAPI_MakeOffset(wire, GeomAbs_Intersection, False)
builder.Perform(offset)
if not builder.IsDone():
raise ValueError("taper collapses a profile loop")
offset_shape = builder.Shape()
exp = TopExp_Explorer(offset_shape, TopAbs_WIRE)
found = []
while exp.More():
found.append(TopoDS.Wire_s(exp.Current()))
exp.Next()
if len(found) != 1:
raise ValueError("taper changes loop connectivity")
moved = BRepBuilderAPI_Transform(found[0], move, True).Shape()
loft = BRepOffsetAPI_ThruSections(True, False)
loft.AddWire(wire)
loft.AddWire(TopoDS.Wire_s(moved))
loft.Build()
if not loft.IsDone():
raise ValueError("kernel could not build tapered sections")
solids.append(loft.Shape())
shape = solids[0]
for tool in solids[1:]:
cut = BRepAlgoAPI_Cut(shape, tool)
cut.Build()
if not cut.IsDone():
raise ValueError("kernel could not subtract tapered inner loop")
shape = cut.Shape()
return _finish(profile, shape, "make_extrude_taper_rsolid",
{"vector": vector, "taper": taper, "flip_inner": flip_inner}, [profile])
def sweep_multisection_rsolid(
profiles: Sequence[Face | Wire],
path: Wire,
is_frenet: bool = False,
binormal: Sequence[float] | Wire | None = None,
) -> Solid:
"""Sweep through explicit ordered section wires along a continuous path.
Face sections use their outer boundary, as in build123d's multi-section
pipe contract. Binormal may be a direction vector or auxiliary spine.
Each supplied section and path remains a graph input for replay.
"""
sections = list(profiles)
if len(sections) < 2:
raise ValueError("multi-section sweep requires at least two sections")
builder = BRepOffsetAPI_MakePipeShell(path.wrapped)
rotate = False
if isinstance(binormal, Wire):
builder.SetMode(binormal.wrapped, True)
elif binormal is not None:
values = _finite_vector(binormal, "binormal")
direction = get_current_cs().transform_vector(np.asarray(values))
if np.linalg.norm(direction) < 1e-12:
raise ValueError("binormal direction must be nonzero")
builder.SetMode(gp_Dir(*direction))
rotate = True
else:
builder.SetMode(bool(is_frenet))
for section in sections:
if not isinstance(section, (Face, Wire)):
raise TypeError("sections must be Face or Wire")
wire = BRepTools.OuterWire_s(section.wrapped) if isinstance(section, Face) else section.wrapped
builder.Add(wire, False, rotate)
builder.Build()
if not builder.IsDone() or not builder.MakeSolid():
raise ValueError("kernel could not make a solid multi-section sweep")
inputs = [*sections, path]
params = {"profile_count": len(sections), "is_frenet": bool(is_frenet), "binormal": None}
if isinstance(binormal, Wire):
inputs.append(binormal)
params["binormal_is_wire"] = True
elif binormal is not None:
params["binormal"] = binormal
return _finish(sections[0], builder.Shape(), "make_sweep_multisection_rsolid", params, inputs)
__all__ = ("extrude_taper_rsolid", "sweep_multisection_rsolid")
def __getattr__(name: str):
family = _MOVED.get(name)
if family is None:
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
warnings.warn(
f"{__name__}.{name} moved to simplecadapi.operators.{family}; "
f"import it from simplecadapi instead (from simplecadapi import {name})",
DeprecationWarning,
stacklevel=2,
)
return getattr(import_module(f"simplecadapi.operators.{family}"), name)
+105
View File
@@ -2,6 +2,8 @@
from __future__ import annotations
from OCP.BRepBuilderAPI import BRepBuilderAPI_Copy, BRepBuilderAPI_GTransform, BRepBuilderAPI_Transform
from OCP.gp import gp_GTrsf, gp_Trsf
from ._support import *
def translate_shape(shape: AnyShape, vector: Tuple[float, float, float]) -> AnyShape:
@@ -420,4 +422,107 @@ def mirror_shape(
error=e,
)
def scale_rsolid(
solid: Solid,
factors: Sequence[float],
center: Sequence[float] = (0, 0, 0),
) -> Solid:
"""Scale a solid along the current coordinate system's axes about a center.
The three factors must be finite and nonzero. A uniform scale preserves
analytic curves and surfaces; a nonuniform scale uses the CAD kernel's
general affine transform. The source solid stays unchanged. The operation
is recorded as ``make_scale_rsolid`` for graph replay; topology tag lineage
is conservatively partial.
Args:
solid: The solid to scale.
factors: Scale factors along the x, y and z axes of the current
coordinate system; finite and nonzero.
center: The fixed point of the scaling, in current coordinate-system
coordinates.
Returns:
The scaled solid.
Raises:
ValueError: A factor is zero or not finite, or the kernel could not
scale the solid.
"""
values = _finite_vector(factors, "factors")
center_value = _finite_vector(center, "center")
if any(v == 0 for v in values):
raise ValueError("scale factors must be nonzero")
cs = get_current_cs()
global_center = cs.transform_point(np.array(center_value))
if values[0] == values[1] == values[2]:
transform = gp_Trsf()
transform.SetScale(gp_Pnt(*global_center), values[0])
builder = BRepBuilderAPI_Transform(solid.wrapped, transform, True)
else:
basis = np.column_stack([cs.transform_vector(np.eye(3)[i]) for i in range(3)])
matrix = basis @ np.diag(values) @ basis.T
translation = global_center - matrix @ global_center
transform = gp_GTrsf()
for row in range(3):
for col in range(3):
transform.SetValue(row + 1, col + 1, float(matrix[row, col]))
transform.SetValue(row + 1, 4, float(translation[row]))
# GTransform's copy flag copies topology, but can retain shared curve
# geometry from boolean/fillet history. Isolate that geometry first:
# otherwise OCCT 7.9 can produce invalid p-curves and crash its checker.
copied = BRepBuilderAPI_Copy(solid.wrapped, True, False).Shape()
builder = BRepBuilderAPI_GTransform(copied, transform, True)
builder.Build()
if not builder.IsDone():
raise ValueError("kernel could not scale the solid")
return _finish(solid, builder.Shape(), "make_scale_rsolid",
{"factors": factors, "center": center}, [solid])
def transform_rsolid(solid: Solid, matrix: Sequence[Sequence[float]]) -> Solid:
"""Apply a finite nonsingular 4x4 affine matrix in the current coordinate system.
The matrix may include shear, reflection and nonuniform scale. Perspective
matrices and singular maps cannot define a solid and are rejected. The
input geometry stays unchanged. The operation is recorded as
``make_transform_rsolid`` for graph replay; topology tag lineage is partial.
Args:
solid: The solid to transform.
matrix: A 4x4 affine matrix (row-major, last row ``0 0 0 1``), finite
and nonsingular, in current coordinate-system coordinates.
Returns:
The transformed solid.
Raises:
ValueError: The matrix is not a finite 4x4 affine matrix, is singular
or a perspective map, or the kernel could not transform the solid.
"""
values = np.asarray(evaluate_value(matrix), dtype=float)
if values.shape != (4, 4) or not np.isfinite(values).all():
raise ValueError("matrix must be a finite 4x4 affine matrix")
if not np.allclose(values[3], (0, 0, 0, 1), rtol=0, atol=1e-12):
raise ValueError("perspective transforms cannot define an affine solid")
if abs(float(np.linalg.det(values[:3, :3]))) < 1e-14:
raise ValueError("matrix must be nonsingular")
cs = get_current_cs()
basis = np.column_stack([cs.transform_vector(np.eye(3)[i]) for i in range(3)])
origin = cs.transform_point(np.zeros(3))
linear = basis @ values[:3, :3] @ basis.T
translation = origin + basis @ values[:3, 3] - linear @ origin
transform = gp_GTrsf()
for row in range(3):
for col in range(3):
transform.SetValue(row + 1, col + 1, float(linear[row, col]))
transform.SetValue(row + 1, 4, float(translation[row]))
copied = BRepBuilderAPI_Copy(solid.wrapped, True, False).Shape()
builder = BRepBuilderAPI_GTransform(copied, transform, True)
builder.Build()
if not builder.IsDone():
raise ValueError("kernel could not transform the solid")
return _finish(solid, builder.Shape(), "make_transform_rsolid", {"matrix": matrix}, [solid])
__all__ = tuple(name for name in globals() if not name.startswith("__"))
+52
View File
@@ -682,3 +682,55 @@ def _private_helper():
if __name__ == "__main__":
unittest.main()
class TestPublicApiIsDocumented(unittest.TestCase):
"""Whatever the package exports has a doc, and the docs are what the
generator writes: a new module cannot be left out of the generator's
list, and a docstring cannot change without the docs following."""
ROOT = Path(__file__).resolve().parents[1]
PACKAGE = ROOT / "src/simplecadapi"
DOCS = ROOT / "docs/skill/references/docs/api"
def test_every_operators_module_is_scanned(self):
scanned = {path.resolve() for path in auto_docs_gen._default_source_files(self.PACKAGE)}
for path in sorted((self.PACKAGE / "operators").glob("*.py")):
if path.name.startswith("_"):
continue
self.assertIn(path.resolve(), scanned, f"{path.name} is not documented by the generator")
def test_every_public_operator_function_has_its_doc(self):
import inspect
import simplecadapi
missing = []
for name in simplecadapi.__all__:
obj = getattr(simplecadapi, name, None)
# an alias (cut = cut_rsolid) is documented under its real name
if not inspect.isfunction(obj) or obj.__name__ != name:
continue
source = Path(inspect.getsourcefile(obj)).resolve()
if (self.PACKAGE / "operators") not in source.parents or source.name.startswith("_"):
continue
if not (self.DOCS / f"{name}.md").is_file():
missing.append(name)
self.assertEqual(missing, [])
def test_the_committed_docs_are_what_the_generator_writes(self):
with tempfile.TemporaryDirectory() as tmp_dir:
out = Path(tmp_dir) / "api"
generator = auto_docs_gen.APIDocumentGenerator(
source_files=auto_docs_gen._resolve_source_files(None),
output_dirs=[out],
clean_stale=True,
quiet=True,
)
generator.extract_apis()
generator.generate_markdown_docs()
generated = {path.name: path.read_text(encoding="utf-8") for path in out.glob("*.md")}
committed = {path.name: path.read_text(encoding="utf-8") for path in self.DOCS.glob("*.md")}
self.assertEqual(sorted(set(generated) ^ set(committed)), [], "files differ; run tools/auto_docs_gen.py")
stale = sorted(name for name in committed if committed[name] != generated[name])
self.assertEqual(stale, [], "docs out of date; run tools/auto_docs_gen.py")
+1 -1
View File
@@ -6,7 +6,7 @@ from OCP.BRepCheck import BRepCheck_Analyzer
import simplecadapi as s
from simplecadapi import ql
from simplecadapi.operators.draft import draft_rsolid
from simplecadapi import draft_rsolid
from simplecadapi.recording.graph import GraphSession
+1 -1
View File
@@ -8,7 +8,7 @@ from OCP.BRepAlgoAPI import BRepAlgoAPI_Cut
import simplecadapi as s
from simplecadapi.kernel.ocp_booleans import solids_of
from simplecadapi.kernel.ocp_properties import center_of_mass, volume
from simplecadapi.operators.limited_extrusion import extrude_until_rsolid
from simplecadapi import extrude_until_rsolid
from simplecadapi.recording.graph import GraphSession
+63
View File
@@ -0,0 +1,63 @@
"""Where the operators live.
An operator is implemented in the module of its family (transforms next to
``translate_shape``, booleans next to ``union_rsolid``, features next to
``extrude_rsolid``). The one-feature modules the converters' operators were
first written in remain as thin aliases of the new places: old imports keep
working and say where to import from instead.
"""
from __future__ import annotations
import importlib
import warnings
import pytest
import simplecadapi
HOME = {
"scale_rsolid": "transform",
"transform_rsolid": "transform",
"boolean_rsolidlist": "boolean",
"offset_rsolid": "features",
"draft_rsolid": "features",
"extrude_taper_rsolid": "features",
"extrude_until_rsolid": "features",
"sweep_multisection_rsolid": "features",
}
OLD = {
"deformation": ["scale_rsolid", "transform_rsolid", "offset_rsolid", "boolean_rsolidlist"],
"draft": ["draft_rsolid"],
"section_features": ["extrude_taper_rsolid", "sweep_multisection_rsolid"],
"limited_extrusion": ["extrude_until_rsolid"],
}
@pytest.mark.parametrize("name,module", sorted(HOME.items()))
def test_an_operator_is_implemented_in_the_module_of_its_family(name, module):
assert getattr(simplecadapi, name).__module__ == f"simplecadapi.operators.{module}"
@pytest.mark.parametrize("old,names", sorted(OLD.items()))
def test_the_old_module_paths_still_work_and_point_to_the_new_place(old, names):
module = importlib.import_module(f"simplecadapi.operators.{old}")
for name in names:
with warnings.catch_warnings(record=True) as caught:
warnings.simplefilter("always")
found = getattr(module, name)
assert found is getattr(simplecadapi, name)
assert any(issubclass(w.category, DeprecationWarning) and HOME[name] in str(w.message) for w in caught), name
def test_a_name_that_never_existed_is_still_an_attribute_error():
module = importlib.import_module("simplecadapi.operators.deformation")
with pytest.raises(AttributeError):
module.no_such_operator
def test_the_package_root_exports_each_once():
assert len(simplecadapi.__all__) == len(set(simplecadapi.__all__))
for name in HOME:
assert name in simplecadapi.__all__
+12
View File
@@ -191,6 +191,15 @@ def _package_root_from(module_file: Path | str | None = None) -> Path:
def _default_source_files(package_root: Path) -> List[Path]:
source_files = [package_root / name for name in DEFAULT_SOURCE_FILENAMES]
# Every operators module is part of the API surface: found, not listed, so
# a new one cannot be left out (four were, and their docs went stale).
listed = set(source_files)
operators_root = package_root / "operators"
source_files.extend(
path
for path in sorted(operators_root.glob("*.py"))
if not path.name.startswith("_") and path not in listed
)
translator_root = package_root / "translator"
for backend_dir in sorted(translator_root.glob("*_translator")):
source_files.extend([backend_dir / "api.py", backend_dir / "translator.py"])
@@ -393,6 +402,9 @@ class APIDocumentGenerator:
return False
if module_name in FULL_PUBLIC_FUNCTION_MODULES:
return True
if module_name.startswith("operators/") and exported_names:
# a module nobody listed: what the package exports is the API
return name in exported_names
if _translator_backend_name(module_name) is not None:
return True
if module_name.startswith("inspect/brep/"):
Generated
+1 -1
View File
@@ -3237,7 +3237,7 @@ wheels = [
[[package]]
name = "simplecadapi"
version = "2.2.6.post1"
version = "2.2.6.post2"
source = { editable = "." }
dependencies = [
{ name = "cadquery-ocp" },