Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
10 KiB
NURBS editing in a GUI: what the SDK can and cannot do today
Status: research, 2026-11-04, branch wip/types-surface-sketch (cut from feat/gui-modeling). Nothing here is
implemented; the last section lists the C++ operations a Plasticity-level editor would need.
Two ways into OpenCASCADE from Python
- Public SDK operations (
*_r<kind>insimplecadapi,simplecadapi.surface). They are recorded in the graph, replay, carry tags and appear insimplecadapi.catalog. A GUI or agent can only rely on these. - The private OCP-compat layer
simplecadapi._cpp.occt.*(src/cpp/bindings/python/occt/bind_occt_{core,query,algo}.cpp), reached from a shape throughShape.wrapped(bind_topo.cpp,bind_common). It mirrors part of OCP for the internal Python layers (inspect, translators). It is not recorded, not replayable and not documented. Edits made through it are invisible to the graph and have no way back into topology.
Legend: public = a recorded SDK op; private = only through _cpp.occt; internal = used inside the C++ kernel, not
exposed; absent = not linked anywhere.
Capability by capability
| Capability | Status | Evidence |
|---|---|---|
| Read poles / weights / knots / multiplicities / degree of an existing Edge | public (read-only) | inspect_shape_rbrepinspection (src/simplecadapi/inspect/brep/inspect.py, _edge_parameters); native _bspline_curve_of(edge) (bind_sdk_compat.cpp, bspline_curve_dict) |
| Same for a Face | public (read-only) | inspect.py _surface_parameters (poles, weights, knots, mults of a B-spline surface) |
| Read through OCCT objects | private | Geom_BSplineCurve / Geom_BSplineSurface / Bezier bound in bind_occt_query.cpp (Poles, Weights, Knots, Multiplicities, Degree, UDegree/VDegree); BRep_Tool.Curve_s/Surface_s/CurveOnSurface_s in bind_occt_core.cpp |
| Write a pole / weight / knot of an existing curve | private only | bind_occt_query.cpp: Geom_BSplineCurve.SetPole/SetWeight/SetKnot(s)/IncreaseMultiplicity, Bezier SetPole/SetWeight |
| Write a pole / weight of an existing surface | private only | Geom_BSplineSurface.SetPole/SetWeight, Geom_BezierSurface.SetPole/SetWeight (bind_occt_query.cpp) |
| Rebuild an Edge/Face after such an edit | absent | no op rebuilds topology from a modified Geom_*; the modified handle is shared with the original shape (mutation in place, unrecorded) |
| Degree elevation | private only | Geom_BSplineCurve.IncreaseDegree, Geom_BSplineSurface.IncreaseDegree (bind_occt_query.cpp) |
| Knot insertion / removal | private, curves only | Geom_BSplineCurve.InsertKnot/RemoveKnot (bind_occt_query.cpp); no InsertUKnot/RemoveUKnot for surfaces |
| Fit a surface through a point grid | public | fit_point_grid_rface (src/cpp/src/surface/fitter.cpp, GeomAPI_PointsToBSplineSurface, smoothing weights) |
| Interpolate a curve through points | public | make_interpolated_spline_redge/rwire, make_periodic_spline_rwire (src/cpp/src/kernel/curves.cpp, GeomAPI_Interpolate) |
| Approximate a curve (least squares, tolerance) | absent | GeomAPI_PointsToBSpline is not linked |
| Refit / simplify an existing curve or face, convert to NURBS | private / absent | GeomConvert.CurveToBSplineCurve_s/SurfaceToBSplineSurface_s private (bind_occt_query.cpp); BRepBuilderAPI_NurbsConvert, ShapeCustom, BSplineRestriction, Approx_* absent |
| G0/G1/G2 boundary conditions when filling | public | make_surface_patch_rface, fill_holes_rshell with SurfaceBoundary(edge, continuity="C0"/"G1"/"G2", support=face) -> BRepOffsetAPI_MakeFilling (fitter.cpp, order_of) |
| Continuity analysis between two faces (G0/G1/G2 deviation along an edge) | absent (one internal probe) | LocalAnalysis, GeomLProp not linked; dihedral angle along an edge is internal (src/cpp/src/ops/features/probes.cpp) |
| Gordon / ruled / loft / Bezier surfaces | public | make_gordon_surface_rface (gordon.cpp), make_ruled_surface_rface, loft_rshell / loft_rsolid, make_bezier_surface_rface (faces_from_data.cpp), sweeps (sweep_rsolid, sweep_multisection_rsolid, ...) |
| Blend surface between two faces (free, not a solid edge) | absent | only fillet_rsolid / chamfer_rsolid on solid edges (BRepFilletAPI_*, semantic/tracking_blends.cpp); no GeomFill_* / BRepBlend |
| Offset a surface | absent | offset_rsolid / shell_rsolid are solid-only (ops/features/offsets.cpp, MakeThickSolid); no Geom_OffsetSurface, no face offset |
| Extend a surface | absent | no GeomLib::ExtendSurfByLength, no ShapeExtend |
| Trim a surface by curves | public | trim_surface_rface(carrier, outer, holes) (src/cpp/src/surface/trim.cpp: projects the wire, checks pcurves with GeomLib_CheckCurveOnSurface, BRepAlgoAPI_Common) |
| Split a face by a curve | absent (internal splitter) | BRepAlgoAPI_Splitter only inside extrude_until; no BRepFeat_SplitShape |
| Untrim / read the trimming loops in UV | internal | pcurves read in trim.cpp via BRep_Tool::CurveOnSurface; no op returns them |
| Curve on surface (edge from a 2D curve on a face) | absent | BRepBuilderAPI_MakeEdge(Geom2d_Curve, Surface) not bound/used (MakeEdge takes 3D curves only, bind_occt_algo.cpp) |
| Project a point onto a surface | internal / private | GeomAPI_ProjectPointOnSurf in trim.cpp, ShapeAnalysis_Surface in probes.cpp; private binding in bind_occt_query.cpp |
| Project a curve onto a surface | absent | BRepProj_Projection not linked; project_rsketch only projects onto a sketch plane (src/cpp/src/sketch/project.cpp) |
| Isocurves (U/V iso lines) | private | Geom_Surface.UIso/VIso (bind_occt_query.cpp); used inside the guided-loft recipe (bind_sdk_compat.cpp); no op |
| Evaluate a curve / surface (point, derivatives, curvature) | private (sampling public) | Edge.sample(count) public (bind_ops_geometry.cpp); D0..DN, BRepLProp_SLProps curvatures private; no curve curvature (CLProps), no curvature comb |
| Sketch B-splines with poles / knots / weights | public | add_bspline_rsketch(..., control_points, degree, knots, multiplicities, weights, periodic) (bind_sketch.cpp); 3D make_spline_redge/rwire (bind_ops_geometry.cpp) |
| Editor hooks for control-point editing | absent | src/simplecadapi/editor only maps bspline_curve/surface to the BSPLINE selection filter (editor/selection.py) |
OCCT classes already linked: Geom_BSplineCurve/Surface, Geom_Bezier*, GeomAPI_Interpolate, GeomAPI_PointsToBSplineSurface, BRepOffsetAPI_MakeFilling, ThruSections, MakePipeShell, MakeThickSolid, MakeOffset (wires), BRepFill, BRepFilletAPI, GeomConvert, GeomAPI_ProjectPointOnSurf, ShapeAnalysis_Surface/FreeBounds, GeomLib_CheckCurveOnSurface, BRepAlgoAPI_Common/Splitter, BRepLProp_SLProps, Geom2d_*, BRepExtrema.
Not linked: GeomPlate, GeomFill, LocalAnalysis, GeomLProp, Geom_OffsetSurface, GeomLib::ExtendSurfByLength, ShapeExtend, ShapeCustom, BRepBuilderAPI_NurbsConvert, BRepFeat_SplitShape, BRepProj_Projection, GeomAPI_PointsToBSpline, Approx_*.
What this means for a GUI
The SDK can build every common freeform surface from data a GUI collects (control nets, curve networks, boundary
patches with G1/G2 supports, trims), and it can read the NURBS data of a result. It cannot edit an existing curve
or surface as a recorded operation: every edit a Plasticity-style control-point drag implies (move pole, set weight,
insert knot, elevate degree) exists only as unrecorded mutation through the private OCCT layer, and nothing rebuilds the
Edge/Face from the modified geometry. The editor must therefore keep the control net itself and re-run a constructor op
(make_spline_redge, make_bezier_surface_rface) on every drag, which loses the identity and tags of downstream topology
and has no answer for imported or derived (fillet, Gordon, filling) surfaces.
Operations that would be needed (C++ kernel ops, recorded, catalog-typed)
Read:
inspect_curve_rnurbs(edge)/inspect_surface_rnurbs(face)- degree, poles (Sequence[Point3]/ grid), weights, knots, multiplicities, periodic/rational flags, parameter range; converts non-B-spline geometry on request (GeomConvert). Today's data sits ininspect_shape_rbrepinspection; it needs to be a first-class typed value.evaluate_curve_rframe(edge, t)/evaluate_surface_rframe(face, u, v)- point, derivatives, normal, curvatures (GeomLProp_CLProps/SLProps), for curvature combs and zebra-like checks.measure_continuity_rcontinuity(face_a, face_b, edge, samples)- G0 gap, G1 angle, G2 curvature deviation (LocalAnalysis_SurfaceContinuity).
Edit (each returns a new Edge/Face, recorded, lineage preserved for tags):
4. edit_curve_poles_redge(edge, poles=..., weights=...) and edit_surface_poles_rface(face, poles=..., weights=...)
- replace some or all poles/weights, keep the trim (re-project the face's trim loops).
insert_knot_redge/insert_knot_rface(face, u=|v=, multiplicity),remove_knot_*(tolerance-checked).elevate_degree_redge/elevate_degree_rface(face, u_degree, v_degree).rebuild_curve_redge(edge, degree, pole_count | tolerance)/rebuild_surface_rface(face, u_count, v_count, degree)(GeomAPI_PointsToBSpline(Surface),Approx_*) andconvert_to_nurbs_rshape(BRepBuilderAPI_NurbsConvert).
Build:
8. blend_surface_rface(edge_a, face_a, edge_b, face_b, continuity="G1"|"G2") (GeomFill / GeomPlate).
9. offset_surface_rface(face, distance) (BRepOffsetAPI_MakeOffsetShape on a face, Geom_OffsetSurface) and
extend_surface_rface(face, edge, length, continuity) (GeomLib::ExtendSurfByLength).
10. split_face_rfacelist(face, tools) (BRepFeat_SplitShape / BRepAlgoAPI_Splitter), untrim_surface_rface(face).
11. make_curve_on_surface_redge(face, uv_points | Geom2d spec) and project_curve_onto_face_redge(edge, face, direction=None) (BRepProj_Projection, BRepAlgo_NormalProjection).
12. make_isocurve_redge(face, u=|v=) (UIso/VIso + trim to the face).
Most important gaps, in order: (a) recorded edits of an existing curve/surface (4-6) - without them control-point editing is a rebuild-from-scratch hack; (b) continuity measurement and blend surfaces (3, 8) - the core of class-A style surfacing; (c) offset/extend/split of faces (9, 10) - routine surface workflow steps that have no op at all.