surface edits: sub-entity tags follow without a session; stubs, API pages, graph spec, skill page

The edits finish through finalize_tracked with the entries of the rebuild's history (modification_history, the
entries next to modification_delta), so tags on the face and its edges follow with or without a recorder, as for the
tracked solid ops. Stubs regenerated (pybind11-stubgen 2.5.5), API pages generated by tools/auto_docs_gen.py, the
graph JSON spec lists the 14 recorded ops and their params/delta, and the skill gains
references/domains/curve-surface-editing.md (read, convert, edit, check; trimming; tags), linked from
part-modeling.md and references/README.md. CHANGELOG under Unreleased.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
NiJingzhe
2026-11-04 11:21:36 +08:00
parent 9df1d77917
commit f021b33489
31 changed files with 540 additions and 17 deletions
+12
View File
@@ -6,6 +6,18 @@ user-facing notes live in [`docs/updates/`](docs/updates/) (English and
## Unreleased
### Added
- Editing existing curves and surfaces as recorded operations (the SDK half of NURBS control-point editing):
`inspect_curve_rcurvedata` / `inspect_surface_rsurfacedata` read degree, poles, weights, knots and trimming;
`set_*_poles`, `move_*_poles`, `set_*_weights`, `insert_*_knot`, `elevate_*_degree` (curves `_redge`, surfaces
`_rface`), `convert_to_bspline_redge/rface` (the explicit step for lines, circles, planes, cylinders) and
`rebuild_curve_redge/rface` return a new shape, record a topology delta (tags and references follow the face and
its edges) and replay from model JSON. A trimmed face keeps its trimming. `sample_curve_rcurvature` and
`sample_surface_risocurves` give an editor a curvature comb and clipped isocurves.
### Fixed
- A stable reference into a face or shell body (no solid) resolves; it raised `cannot resolve QL selector scope`.
## 2.2.7 — 2026-10-30
### Fixed
+1
View File
@@ -54,6 +54,7 @@ Stage and role pages of the long workflows:
| --- | --- |
| `domains/addon-development.md` | you create, publish, install, update or remove a SimpleCADAPI addon (`sca-addon.toml`), or decide whether a capability is an addon or SDK work. |
| `domains/assembly-and-product.md` | the deliverable has more than one physical part, repeated instances, nested subassemblies, motion semantics, or a `.scadpkg` package (details under "Use when"). |
| `domains/curve-surface-editing.md` | an existing Edge or Face must be reshaped by its control points, weights, knots or degree, refitted, or sampled for a curvature comb / isocurves. |
| `domains/drawing-inspection-evidence.md` | a section view of the drawing must be verified against the rebuilt model, a DIM ledger row needs its `measurement_contract`, or the roundtrip evidence (annotations, reviews, coverage) is built or checked. |
| `domains/drawing-inspection.md` | a vector-PDF engineering drawing must be parsed into tiered evidence, or a rebuilt model is read back for the roundtrip. |
| `domains/editor-collaboration.md` | a person has the code-first editor open (`sca edit`) and you edit the same notebooks (a selection, a cell reference or a tuned value arrives). |
+18
View File
@@ -383,8 +383,12 @@ 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`
- [convert_to_bspline_redge](convert_to_bspline_redge.md) *(from operators/geometry.py)* `top-level`
- [convert_to_bspline_rface](convert_to_bspline_rface.md) *(from operators/geometry.py)* `top-level`
- [diff_sketch_rsketchdiff](diff_sketch_rsketchdiff.md) *(from operators/sketch.py)* `top-level`
- [draft_rsolid](draft_rsolid.md) *(from operators/features.py)* `top-level`
- [elevate_curve_degree_redge](elevate_curve_degree_redge.md) *(from operators/geometry.py)* `top-level`
- [elevate_surface_degree_rface](elevate_surface_degree_rface.md) *(from operators/geometry.py)* `top-level`
- [explain_tag](explain_tag.md) *(from operators/selection.py)* `top-level`
- [explode_rassembly](explode_rassembly.md) *(from operators/product.py)* `top-level`
- [extend_rsketch](extend_rsketch.md) *(from operators/sketch.py)* `top-level`
@@ -396,11 +400,15 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- [get_sketch_point_rsketchref](get_sketch_point_rsketchref.md) *(from operators/sketch.py)* `top-level`
- [ground_component_rassembly](ground_component_rassembly.md) *(from operators/product.py)* `top-level`
- [identity_placement_rplacement](identity_placement_rplacement.md) *(from operators/product.py)* `top-level`
- [insert_curve_knot_redge](insert_curve_knot_redge.md) *(from operators/geometry.py)* `top-level`
- [insert_surface_knot_rface](insert_surface_knot_rface.md) *(from operators/geometry.py)* `top-level`
- [inspect_assembly_constraints_rconstraintreport](inspect_assembly_constraints_rconstraintreport.md) *(from operators/product.py)* `top-level`
- [inspect_body_overlaps_rlist](inspect_body_overlaps_rlist.md) *(from operators/product.py)* `top-level`
- [inspect_curve_rcurvedata](inspect_curve_rcurvedata.md) *(from operators/geometry.py)* `top-level`
- [inspect_sketch_rsketchcrossings](inspect_sketch_rsketchcrossings.md) *(from operators/sketch.py)* `top-level`
- [inspect_sketch_rsketchprofiles](inspect_sketch_rsketchprofiles.md) *(from operators/sketch.py)* `top-level`
- [inspect_sketch_rsketchresult](inspect_sketch_rsketchresult.md) *(from operators/sketch.py)* `top-level`
- [inspect_surface_rsurfacedata](inspect_surface_rsurfacedata.md) *(from operators/geometry.py)* `top-level`
- [key](key.md) *(from ql.py)* `submodule:ql`
- [linear_pattern_rsolidlist](linear_pattern_rsolidlist.md) *(from operators/transform.py)* `top-level`
- [load_brep_region_rshell](load_brep_region_rshell.md) *(from operators/geometry.py)* `top-level`
@@ -408,6 +416,8 @@ 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`
- [measure_part_mass_rmassreport](measure_part_mass_rmassreport.md) *(from operators/product.py)* `top-level`
- [meta](meta.md) *(from ql.py)* `submodule:ql`
- [move_curve_poles_redge](move_curve_poles_redge.md) *(from operators/geometry.py)* `top-level`
- [move_surface_poles_rface](move_surface_poles_rface.md) *(from operators/geometry.py)* `top-level`
- [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`
@@ -421,11 +431,19 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- [project_rsketch](project_rsketch.md) *(from operators/sketch.py)* `top-level`
- [prop](prop.md) *(from ql.py)* `submodule:ql`
- [radial_pattern_rsolidlist](radial_pattern_rsolidlist.md) *(from operators/transform.py)* `top-level`
- [rebuild_curve_redge](rebuild_curve_redge.md) *(from operators/geometry.py)* `top-level`
- [rebuild_surface_rface](rebuild_surface_rface.md) *(from operators/geometry.py)* `top-level`
- [register_property_resolver](register_property_resolver.md) *(from ql.py)* `submodule:ql`
- [render_screenshot_rpath](render_screenshot_rpath.md) *(from operators/features.py)* `top-level`
- [sample_curve_rcurvature](sample_curve_rcurvature.md) *(from operators/geometry.py)* `top-level`
- [sample_surface_risocurves](sample_surface_risocurves.md) *(from operators/geometry.py)* `top-level`
- [scale_rsolid](scale_rsolid.md) *(from operators/transform.py)* `top-level`
- [select](select.md) *(from ql.py)* `submodule:ql`
- [set_curve_poles_redge](set_curve_poles_redge.md) *(from operators/geometry.py)* `top-level`
- [set_curve_weights_redge](set_curve_weights_redge.md) *(from operators/geometry.py)* `top-level`
- [set_public_connector_rassembly](set_public_connector_rassembly.md) *(from operators/product.py)* `top-level`
- [set_surface_poles_rface](set_surface_poles_rface.md) *(from operators/geometry.py)* `top-level`
- [set_surface_weights_rface](set_surface_weights_rface.md) *(from operators/geometry.py)* `top-level`
- [sew_faces_rshell](sew_faces_rshell.md) *(from operators/geometry.py)* `top-level`
- [shells](shells.md) *(from ql.py)* `submodule:ql`
- [solve_assembly_constraints_rassembly](solve_assembly_constraints_rassembly.md) *(from operators/product.py)* `top-level`
@@ -0,0 +1,19 @@
# convert_to_bspline_redge
## API Definition
```python
def convert_to_bspline_redge(edge, *, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import convert_to_bspline_redge`
## Description
Convert an edge's curve to a B-spline, so the curve edits can work on it.
The explicit, recorded step for analytic edges (a line becomes a degree-1 B-spline, a circle or arc a rational quadratic); the shape does not change, its parameter range may. Returns a new Edge; the input is not changed. Recorded: the Edge continues in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# convert_to_bspline_rface
## API Definition
```python
def convert_to_bspline_rface(face, *, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import convert_to_bspline_rface`
## Description
Convert a face's surface (and its boundary curves) to B-splines, so the surface edits can work on it.
The explicit, recorded step for analytic faces (planes, cylinders, cones, spheres, ...); the shape and the trimming do not change, the (u, v) parametrisation may. Returns a new Face; the input is not changed. Recorded: the Face and its boundary edges continue in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# elevate_curve_degree_redge
## API Definition
```python
def elevate_curve_degree_redge(edge, degree, *, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import elevate_curve_degree_redge`
## Description
Raise the degree of an edge's B-spline curve to ``degree``.
The shape does not change; poles are added. Only B-spline and Bezier curves are edited; a line, circle or other analytic edge is refused with a message naming ``convert_to_bspline_redge``, the explicit conversion step. Returns a new Edge; the input is not changed. Recorded: the Edge continues in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# elevate_surface_degree_rface
## API Definition
```python
def elevate_surface_degree_rface(face, u_degree=None, v_degree=None, *, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import elevate_surface_degree_rface`
## Description
Raise the U and/or V degree of a face's B-spline surface.
Give ``u_degree``, ``v_degree`` or both; a degree that is given is at least the current one and one of them is higher. The shape does not change; poles are added. The face keeps its trimming exactly: its boundary loops stay where they are in the surface's (u, v) space and the 3D boundary edges are recomputed on the edited surface. Only B-spline and Bezier surfaces are edited; a plane, cylinder or other analytic face is refused with a message naming ``convert_to_bspline_rface``, the explicit conversion step. Returns a new Face; the input is not changed. Recorded: the Face and its boundary edges continue in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# insert_curve_knot_redge
## API Definition
```python
def insert_curve_knot_redge(edge, parameter, multiplicity=1, *, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import insert_curve_knot_redge`
## Description
Insert a knot into an edge's B-spline curve at ``parameter`` (strictly inside the edge's parameter range).
The shape does not change; the curve gains ``multiplicity`` poles near that parameter, for finer local editing. The knot's total multiplicity may not exceed the degree. Only B-spline and Bezier curves are edited; a line, circle or other analytic edge is refused with a message naming ``convert_to_bspline_redge``, the explicit conversion step. Returns a new Edge; the input is not changed. Recorded: the Edge continues in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# insert_surface_knot_rface
## API Definition
```python
def insert_surface_knot_rface(face, direction, parameter, multiplicity=1, *, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import insert_surface_knot_rface`
## Description
Insert a U or V knot into a face's B-spline surface at ``parameter`` (strictly inside the surface's domain in that direction).
The shape does not change; the pole grid gains ``multiplicity`` rows (``"U"``) or columns (``"V"``). The face keeps its trimming exactly: its boundary loops stay where they are in the surface's (u, v) space and the 3D boundary edges are recomputed on the edited surface. Only B-spline and Bezier surfaces are edited; a plane, cylinder or other analytic face is refused with a message naming ``convert_to_bspline_rface``, the explicit conversion step. Returns a new Face; the input is not changed. Recorded: the Face and its boundary edges continue in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# inspect_curve_rcurvedata
## API Definition
```python
def inspect_curve_rcurvedata(edge)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import inspect_curve_rcurvedata`
## Description
Read the NURBS data of an edge's curve: what the curve edits work on.
Returns ``{type, analytic, editable, conversion, degree, poles, weights, knots, multiplicities, periodic, rational, closed, domain, reversed, parameter_range}``. ``poles`` are points in the current coordinate system, indices are 0-based (the ``moves`` of ``move_curve_poles_redge``); ``parameter_range`` is the edge's own range (where ``insert_curve_knot_redge`` may insert). For a line, circle or other analytic curve ``editable`` is false, ``conversion`` is ``"convert_to_bspline_redge"`` and the data is what that conversion would produce. Not recorded in the graph.
@@ -0,0 +1,19 @@
# inspect_surface_rsurfacedata
## API Definition
```python
def inspect_surface_rsurfacedata(face)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import inspect_surface_rsurfacedata`
## Description
Read the NURBS data of a face's surface: what the surface edits work on.
Returns ``{type, analytic, editable, conversion, u_degree, v_degree, poles, weights, u_knots, v_knots, u_multiplicities, v_multiplicities, u_periodic, v_periodic, rational, domain, reversed, trimmed, uv_bounds}``. ``poles`` is a grid of rows along U, each row running along V (as ``make_bezier_surface_rface`` takes it), in the current coordinate system; indices are 0-based ``(row, column)``. ``domain`` is the surface's ``[u1, u2, v1, v2]``, ``uv_bounds`` the face's; ``trimmed`` says whether the face is bounded by anything but the surface's own domain. For a plane, cylinder or other analytic surface ``editable`` is false, ``conversion`` is ``"convert_to_bspline_rface"`` and the data is what that conversion would produce. Not recorded in the graph.
@@ -0,0 +1,19 @@
# move_curve_poles_redge
## API Definition
```python
def move_curve_poles_redge(edge, moves, *, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import move_curve_poles_redge`
## Description
Move some poles of an edge's B-spline curve: ``moves`` maps a 0-based pole index to its new position.
The sparse form of ``set_curve_poles_redge`` (what a control-point drag records). Only B-spline and Bezier curves are edited; a line, circle or other analytic edge is refused with a message naming ``convert_to_bspline_redge``, the explicit conversion step. Returns a new Edge; the input is not changed. Recorded: the Edge continues in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# move_surface_poles_rface
## API Definition
```python
def move_surface_poles_rface(face, moves, *, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import move_surface_poles_rface`
## Description
Move some poles of a face's B-spline surface: ``moves`` maps a 0-based ``(row, column)`` to the pole's new position.
The sparse form of ``set_surface_poles_rface`` (what a control-point drag records). The face keeps its trimming exactly: its boundary loops stay where they are in the surface's (u, v) space and the 3D boundary edges are recomputed on the edited surface. Only B-spline and Bezier surfaces are edited; a plane, cylinder or other analytic face is refused with a message naming ``convert_to_bspline_rface``, the explicit conversion step. Returns a new Face; the input is not changed. Recorded: the Face and its boundary edges continue in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# rebuild_curve_redge
## API Definition
```python
def rebuild_curve_redge(edge, degree=3, pole_count=None, *, tolerance=0.001, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import rebuild_curve_redge`
## Description
Refit an edge's curve as a B-spline of ``degree`` with ``pole_count`` poles, or with the fewest poles that keep within ``tolerance``.
A least-squares fit with uniform clamped knots in the edge's own parameter range; the end points are kept. Works on any edge, analytic ones too (the result is a B-spline). Returns a new Edge; the input is not changed. Recorded: the Edge continues in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# rebuild_surface_rface
## API Definition
```python
def rebuild_surface_rface(face, u_degree=3, v_degree=3, u_pole_count=None, v_pole_count=None, *, tolerance=0.001, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import rebuild_surface_rface`
## Description
Refit a face's surface as a B-spline of the given degrees and pole counts, or with the fewest poles that keep within ``tolerance``.
Give both pole counts or neither. A least-squares fit in the face's own (u, v) parametrisation (over the surface's domain for a B-spline, over the face's bounds otherwise), so the face keeps its trimming. Works on any face. Returns a new Face; the input is not changed. Recorded: the Face and its boundary edges continue in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# sample_curve_rcurvature
## API Definition
```python
def sample_curve_rcurvature(edge, count=64)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import sample_curve_rcurvature`
## Description
Sample an edge for a curvature comb: ``count`` points evenly in its parameter range.
Returns ``{parameters, points, tangents, normals, curvatures, max_curvature}`` in the current coordinate system; a normal points to the centre of curvature and is zero where the curve is straight. Not recorded in the graph.
@@ -0,0 +1,19 @@
# sample_surface_risocurves
## API Definition
```python
def sample_surface_risocurves(face, u_count=5, v_count=5, samples=48)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import sample_surface_risocurves`
## Description
Sample isocurves of a face, clipped to its trimming.
``u_count`` lines of constant u and ``v_count`` of constant v, evenly inside the face's (u, v) bounds, each sampled at ``samples`` points. Returns ``{u: [{parameter, segments}], v: [...], uv_bounds}``; ``segments`` are the runs of points that lie on the face. Not recorded in the graph.
@@ -0,0 +1,19 @@
# set_curve_poles_redge
## API Definition
```python
def set_curve_poles_redge(edge, poles, *, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import set_curve_poles_redge`
## Description
Set every pole of an edge's B-spline curve.
``poles`` lists exactly as many points as the curve has poles (``inspect_curve_rcurvedata``), in order, in the current coordinate system. Degree, knots and weights stay. Only B-spline and Bezier curves are edited; a line, circle or other analytic edge is refused with a message naming ``convert_to_bspline_redge``, the explicit conversion step. Returns a new Edge; the input is not changed. Recorded: the Edge continues in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# set_curve_weights_redge
## API Definition
```python
def set_curve_weights_redge(edge, weights, *, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import set_curve_weights_redge`
## Description
Set the weights of an edge's B-spline curve: one positive value per pole.
A weight above 1 pulls the curve toward its pole; any weight other than 1 makes the curve rational. Only B-spline and Bezier curves are edited; a line, circle or other analytic edge is refused with a message naming ``convert_to_bspline_redge``, the explicit conversion step. Returns a new Edge; the input is not changed. Recorded: the Edge continues in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# set_surface_poles_rface
## API Definition
```python
def set_surface_poles_rface(face, poles, *, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import set_surface_poles_rface`
## Description
Set every pole of a face's B-spline surface.
``poles`` is the full grid (rows along U, each row along V), the same size as ``inspect_surface_rsurfacedata`` reports, in the current coordinate system. The face keeps its trimming exactly: its boundary loops stay where they are in the surface's (u, v) space and the 3D boundary edges are recomputed on the edited surface. Only B-spline and Bezier surfaces are edited; a plane, cylinder or other analytic face is refused with a message naming ``convert_to_bspline_rface``, the explicit conversion step. Returns a new Face; the input is not changed. Recorded: the Face and its boundary edges continue in the node's history, so tags and references follow.
@@ -0,0 +1,19 @@
# set_surface_weights_rface
## API Definition
```python
def set_surface_weights_rface(face, weights, *, tag_prefix=None)
```
*Source: operators/geometry.py*
## Import Surface
- top-level: `from simplecadapi import set_surface_weights_rface`
## Description
Set the weights of a face's B-spline surface: a grid of positive values, one per pole.
The face keeps its trimming exactly: its boundary loops stay where they are in the surface's (u, v) space and the 3D boundary edges are recomputed on the edited surface. Only B-spline and Bezier surfaces are edited; a plane, cylinder or other analytic face is refused with a message naming ``convert_to_bspline_rface``, the explicit conversion step. Returns a new Face; the input is not changed. Recorded: the Face and its boundary edges continue in the node's history, so tags and references follow.
@@ -912,8 +912,9 @@ fields when their target expression is unitless.
- importer 仍识别冻结的 `2.0` contract,但 `2.0` graph 不得使用
`load_brep_region_rshell`、`load_brep_region_rsolid`、
`make_solid_from_shell_rsolid`、`trim_rsketch`、`extend_rsketch`、
`fillet_corner_rsketch`、`chamfer_corner_rsketch`、`project_rsketch` 或
`explode_rassembly`。
`fillet_corner_rsketch`、`chamfer_corner_rsketch`、`project_rsketch`、
`explode_rassembly` 或曲线/曲面编辑操作(`convert_to_bspline_*`、`set_*_poles_*`、
`move_*_poles_*`、`set_*_weights_*`、`insert_*_knot_*`、`elevate_*_degree_*`、`rebuild_*`)。
- 为兼容早期 `2.0` model payload,importer 将缺失的
`canonical_contract` 视为最小 legacy `{"contract_version": "2.0"}`;
新导出的 model payload 仍必须显式包含完整 contract。
@@ -1063,6 +1064,20 @@ New canonical profile nodes use the `make_*_r*` names listed in `canonical_contr
- `make_gordon_surface_rface`
- `make_surface_patch_rface`
- `trim_surface_rface`
- `convert_to_bspline_redge`
- `convert_to_bspline_rface`
- `set_curve_poles_redge`
- `move_curve_poles_redge`
- `set_curve_weights_redge`
- `insert_curve_knot_redge`
- `elevate_curve_degree_redge`
- `set_surface_poles_rface`
- `move_surface_poles_rface`
- `set_surface_weights_rface`
- `insert_surface_knot_rface`
- `elevate_surface_degree_rface`
- `rebuild_curve_redge`
- `rebuild_surface_rface`
- `make_loft_rshell`
- `sew_faces_rshell`
- `make_solid_from_shell_rsolid`
@@ -1350,6 +1365,19 @@ Notes:
- Params: `assembly_id`, `factor`, `center`, `axis` (3-vectors or `null`), `directions` (component id to 3-vector), `weights` (component id to number)
- `factor` is recorded as a symbolic parameter when it was a `Var` / `Expr`. Constraints are not re-solved; solving the result moves the components back.
#### Curve and surface edits (`*_redge` / `*_rface`)
`convert_to_bspline_redge`, `convert_to_bspline_rface`, `set_curve_poles_redge`, `move_curve_poles_redge`,
`set_curve_weights_redge`, `insert_curve_knot_redge`, `elevate_curve_degree_redge`, `set_surface_poles_rface`,
`move_surface_poles_rface`, `set_surface_weights_rface`, `insert_surface_knot_rface`, `elevate_surface_degree_rface`,
`rebuild_curve_redge`, `rebuild_surface_rface`.
- Inputs: 1 `Edge` (`*_redge`) or 1 `Face` (`*_rface`), named by `params.input_refs` (a pick from a solid becomes a selection node first)
- Outputs: 1 new `Edge` / `Face` (the input is not changed)
- Params (besides `input_refs` and `tag_prefix`): `poles` (list of points / grid of rows along U), `moves` (`[[index, point], ...]` for a curve, `[[row, column, point], ...]` for a surface; indices 0-based), `weights` (list / grid), `parameter`, `multiplicity`, `direction` (`"U"` / `"V"`), `degree`, `u_degree` / `v_degree` (`null` = unchanged for `elevate_surface_degree_rface`), `pole_count` / `u_pole_count` / `v_pole_count` (`null` = from `tolerance`), `tolerance`. Points are in the node's `context` coordinate system.
- `topo_delta`: the face and its edges (an edge: itself) are `MODIFIED`, derivation `continuation`, each with its input entity as parent, so tags and references follow.
- `inspect_curve_rcurvedata`, `inspect_surface_rsurfacedata`, `sample_curve_rcurvature`, `sample_surface_risocurves` are diagnostic: no node.
#### `make_constrain_*_rsketch`
- Inputs: 1 `Sketch`
@@ -0,0 +1,72 @@
# Task Domain: Editing Curves and Surfaces (control points, weights, knots, degree)
Change an existing curve or surface the way a NURBS editor does (drag a pole, weight it, add a knot for local control,
raise the degree), as ordinary recorded operations. Each one returns a NEW Edge or Face; the input is never changed.
**Read when:** an existing Edge or Face must be reshaped by its control points, weights, knots or degree, refitted
(`rebuild_*`), or sampled for a curvature comb / isocurves; or a freeform face built with `make_bezier_surface_rface`,
`fit_point_grid_rface`, `trim_surface_rface`, Gordon or a patch must be adjusted after it was built.
## Use when
- A freeform face or spline edge is close but must be adjusted locally ("lift this corner", "flatten this edge").
- A surface needs more control in one region: insert a knot there, then move the new poles.
- An analytic face or edge (plane, cylinder, line, arc) must become freeform so it can be bent.
## Do not use
- The shape is better rebuilt from its inputs: change the profile / point grid / curve network of the constructor
instead (parametric intent stays in the constructor's arguments).
- A face that is part of a solid must stay part of a closed body: an edit returns a free face (no shell or solid is
rebuilt around it). Sew the edited faces again (`sew_faces_rshell`, `make_solid_from_shell_rsolid`) when needed.
## The loop: read, edit, check
1. `inspect_curve_rcurvedata(edge)` / `inspect_surface_rsurfacedata(face)`: degree(s), `poles`, `weights`, knots,
multiplicities, domain, `editable`, `trimmed`. Pole indices are 0-based; a surface's `poles` are rows along U, each
row along V (the shape `make_bezier_surface_rface` takes). Coordinates are in the current coordinate system.
2. If `editable` is false (`type` is `line`, `circle`, `plane`, `cylinder`, ...), convert explicitly:
`convert_to_bspline_redge` / `convert_to_bspline_rface` (recorded; the shape does not change). The edits refuse
analytic geometry with a message naming the conversion; nothing converts silently.
3. Edit (each recorded, each returns a new shape):
| Goal | Curve (Edge) | Surface (Face) |
| --- | --- | --- |
| Move some poles | `move_curve_poles_redge(e, {1: (x, y, z)})` | `move_surface_poles_rface(f, {(1, 2): (x, y, z)})` |
| Set all poles | `set_curve_poles_redge(e, poles)` | `set_surface_poles_rface(f, grid)` |
| Weights (rational) | `set_curve_weights_redge(e, ws)` | `set_surface_weights_rface(f, ws_grid)` |
| Local control | `insert_curve_knot_redge(e, t, multiplicity=1)` | `insert_surface_knot_rface(f, "U", u)` |
| Smoother / more poles | `elevate_curve_degree_redge(e, 4)` | `elevate_surface_degree_rface(f, u_degree=3)` |
| Refit (degree, pole count or tolerance) | `rebuild_curve_redge(e, 3, 8)` | `rebuild_surface_rface(f, 3, 3, 6, 6)` |
4. Check: `inspect_*` again; `sample_curve_rcurvature(edge, 64)` for a curvature comb (points, normals,
curvatures, `max_curvature`); `sample_surface_risocurves(face, 5, 5)` for isocurves clipped to the trimming.
Knot insertion and degree elevation never change the shape (only the control net). A knot parameter must lie strictly
inside the edge's `parameter_range` / the surface's `domain`; the knot's total multiplicity is at most the degree.
## Trimmed faces
A trimmed face (holes, an outer loop that is not the surface's own boundary) keeps its trimming exactly: the loops stay
where they are in (u, v), and the 3D boundary edges are recomputed on the edited surface. So a hole moves with the
surface as it bends. `rebuild_surface_rface` keeps the parametrisation for the same reason. An edit that makes the
boundary invalid (folds the surface over itself) fails with the operation's error; nothing is returned half-built.
## Tags and references
Every edit records its history: the face and its boundary edges are `modified` (continuation). A tag assigned with
`apply_tag_rselection` on the face or on one of its edges, and a stable reference (`topology.element_ref`), follow the
entity through any chain of edits (with or without a `GraphSession`), and `ql.tag(...)` finds it on the result.
`tag_prefix=` only names the result of the operation it is passed to (`<prefix>.face` / `<prefix>.edge`), as for every
other operation: name the entities that must keep their name with `apply_tag_rselection`.
```python
face = scad.make_bezier_surface_rface(grid)
face = scad.apply_tag_rselection(face, [face], "skin") # a name that follows the face
data = scad.inspect_surface_rsurfacedata(face) # degrees, poles, knots ...
face = scad.insert_surface_knot_rface(face, "U", 0.5) # one more row of poles
face = scad.move_surface_poles_rface(face, {(2, 1): (1.0, 1.0, 2.5)})
assert ql.faces().where(ql.tag("skin")).exactly(1).resolve(face)
```
Read the API page of each operation under `references/docs/api/` before the first call.
@@ -67,6 +67,7 @@ consult their own documentation before the first call.
`make_face_from_wires_rface`, `make_surface_patch_rface`,
`make_ruled_surface_rface`, `make_gordon_surface_rface`,
`make_cylindrical_surface_rface`.
- Editing an existing curve or surface (poles, weights, knots, degree, refit): `domains/curve-surface-editing.md`.
- Features: `extrude_rsolid`, `revolve_rsolid`, `sweep_rsolid`,
`twisted_sweep_rsolid` (supports inner-wire profiles), `helical_sweep_rsolid`,
`loft_rsolid`, `loft_rshell`, `shell_rsolid`.
@@ -161,6 +161,17 @@ TrackedResult tracked_shell(const Solid& solid, const std::vector<Face>& faces_t
TopoDelta modification_delta(const BRepTools_History& history, const TopoDS_Shape& input, const TopoDS_Shape& result,
std::string_view modified_derivation, bool generated_faces_continue = false);
// The same, with the per-entity entries the tag projection reads (finalize_tracked): for a modification whose result
// is finished through the tracked pipeline (the curve / surface edits), so tags of sub-entities follow without a
// recorder too.
struct ModificationHistory {
TopoDelta delta;
DeltaEntries entries;
};
ModificationHistory modification_history(const BRepTools_History& history, const TopoDS_Shape& input,
const TopoDS_Shape& result, std::string_view modified_derivation,
bool generated_faces_continue = false);
// ---------------------------------------------------------------------------
// Booleans (operators: cut_rsolid, union_rsolid, intersect_rsolid)
// ---------------------------------------------------------------------------
+8 -1
View File
@@ -13,6 +13,12 @@ namespace scad {
TopoDelta modification_delta(const BRepTools_History& history, const TopoDS_Shape& input, const TopoDS_Shape& result,
std::string_view modified_derivation, bool generated_faces_continue) {
return modification_history(history, input, result, modified_derivation, generated_faces_continue).delta;
}
ModificationHistory modification_history(const BRepTools_History& history, const TopoDS_Shape& input,
const TopoDS_Shape& result, std::string_view modified_derivation,
bool generated_faces_continue) {
if (!tracking::history_wanted())
return {};
tracking::RetainedHistory source(history);
@@ -43,7 +49,8 @@ TopoDelta modification_delta(const BRepTools_History& history, const TopoDS_Shap
}
}
}
return std::move(delta).finish().delta;
tracking::Finished finished = std::move(delta).finish();
return {std::move(finished.delta), std::move(finished.delta_entries)};
}
} // namespace scad
+6 -5
View File
@@ -24,13 +24,14 @@ T finish(const T& source, const std::string& op, Value params, const TagPrefix&
}
if (single.IsNull())
throw ValueError(std::string("the rebuild produced no ") + what);
TopoDelta delta = modification_delta(history, source.wrapped(), single, "continuation");
ModificationHistory traced = modification_history(history, source.wrapped(), single, "continuation");
params.set("tag_prefix", tag_prefix ? Value(*tag_prefix) : Value());
detail::OperationRecord record{.op = op, .params = std::move(params), .inputs = {{source, what}}};
return detail::finalize_surface_output(
T(single),
detail::EditOutput{
.record = std::move(record), .tag_prefix = tag_prefix, .source = source, .delta = std::move(delta)});
return detail::finalize_surface_output(T(single), detail::EditOutput{.record = std::move(record),
.tag_prefix = tag_prefix,
.source = source,
.delta = std::move(traced.delta),
.entries = std::move(traced.entries)});
}
} // namespace
+2 -6
View File
@@ -277,16 +277,12 @@ namespace {
template <class T>
T finalize_edit(T result, EditOutput output) {
attach_lineage_from_source(output.source, result, LineageDerivation::Continuation, output.record.op, "complete");
result.set_runtime(kCoverageKey, "complete");
if (output.record.labels.empty())
output.record.labels = {"derived", "edit", "surface", std::string(kind_name(result.kind()))};
output.record.ordered_inputs = true;
std::optional<TopoDelta> delta;
if (!output.delta.entries.empty())
delta = std::move(output.delta);
T finalized = finalize_derived<T>(std::move(result),
FinalizeSpec{.record = to_op_record(std::move(output.record), std::move(delta))});
T finalized = finalize_tracked<T>(std::move(result), std::move(output.delta), std::move(output.entries),
FinalizeSpec{.record = to_op_record(std::move(output.record))});
apply_prefix_tag(finalized, output.tag_prefix);
return finalized;
}
+5 -2
View File
@@ -17,6 +17,7 @@
#include "scad/core/scalar.hpp"
#include "scad/core/value.hpp"
#include "scad/semantic/tracked_result.hpp"
#include "scad/surface/operators.hpp"
#include "scad/topo/delta.hpp"
#include "scad/topo/recorder.hpp"
@@ -89,13 +90,15 @@ struct BoundariesOutput {
std::vector<Wire> finalize_surface_output(std::vector<Wire> result, BoundariesOutput output);
// The curve / surface edits (editing/*.cpp): one input Edge or Face, one result of the same kind, built on edited
// geometry. `delta` is the history of the rebuild (modification_delta): the face, its edges continue. The source's
// tags continue onto the result as lineage when nothing is recorded; with a recorder they follow the delta.
// geometry. `delta` / `entries` are the history of the rebuild (modification_history): the face and its edges
// continue, and their tags follow through the tracked pipeline (projected per entity; with a recorder, the tags a
// recorded assignment made follow through the delta in the graph).
struct EditOutput {
OperationRecord record;
TagPrefix tag_prefix;
Shape source;
TopoDelta delta;
DeltaEntries entries;
};
Face finalize_surface_output(Face result, EditOutput output);
Edge finalize_surface_output(Edge result, EditOutput output);
File diff suppressed because one or more lines are too long
+13
View File
@@ -164,6 +164,19 @@ def test_tags_and_references_follow_a_face_and_its_edges_through_edits():
assert len(ql.edges().where(ql.tag("user.curve")).resolve(curve)) == 1
def test_tags_of_the_face_and_its_edges_follow_without_a_recording_session_too():
face = scad.make_bezier_surface_rface(GRID)
(rim,) = ql.edges().where(ql.prop("geom.center.x", "<=", 1e-6)).resolve(face)
face = scad.apply_tag_rselection(scad.apply_tag_rselection(face, [rim], "user.rim"), [face], "user.skin")
edited = scad.elevate_surface_degree_rface(scad.move_surface_poles_rface(face, {(1, 1): (1, 1, 2)}), 3, 3)
assert len(ql.faces().where(ql.tag("user.skin")).resolve(edited)) == 1
(tagged,) = ql.edges().where(ql.tag("user.rim")).resolve(edited)
assert tagged.get_center().x == pytest.approx(0.0)
# a tag_prefix names the result of the operation it is given to (as everywhere in the SDK)
named = scad.insert_surface_knot_rface(face, "U", 0.5, tag_prefix="skin")
assert "skin.face" in named._list_tags()
def test_a_face_picked_from_a_solid_is_converted_edited_and_replayed():
with scad.GraphSession() as session:
box = scad.make_box_rsolid(10, 10, 10)