Files
make-cad/src/cpp/bindings/python/bind_ops_features.cpp
T
Ni Jingzhe 35a4e5efa9 fix(kernel): cut and intersect unify what they leave split, and a blend never returns an invalid solid (#88)
DECISION: three changes, in this order of importance, each independent of the others.
(1) a fillet or chamfer whose result OCCT calls invalid is an error; (2) cut_rsolid, cut_rsolid_list and
intersect_rsolid unify the same-domain faces and edges of their result by default, with `clean=False` to keep the raw
result, as union already does; (3) the diagnosis names split faces instead of blaming the radius. No compatibility
shim for records made before `clean` existed: replay requires the parameter, like every other recorded one.

PROBLEM (reproduced on the issue's two cases, current dev build on Windows, OCCT 7.9.3)
A cut through the side of a box with a cylinder splits the cylinder wall along the cylinder's parametric seam into two
faces, and the top edge of the notch into a long and a short arc. union unified (ShapeUpgrade_UnifySameDomain) and cut
did not. OCCT then fillets that top edge wrongly:
- case A: BRepCheck-invalid solid, volume 28305.59 (should be 29604.46), no error at all: `fillet_rsolid` checked only
  IsDone and volume > 0;
- case B: refusal, and the diagnosis said "the radius exceeds the 2.5 mm of face room" - the half of the wall the seam cut
  off - so the advised radius was not the limit.
Same geometry, other libraries: CadQuery and build123d clean after a boolean by default and give 29604.46 / 29811.31.

(1) THE EXIT CHECK IS THE MOST IMPORTANT
`assert_blend_valid`, next to the volume check in `finish_blend` (fillet and chamfer): BRepCheck_Analyzer on the result;
invalid while the input was valid is a BlendValidityViolation, which leads the error message ("the kernel returned broken
geometry"), like the existing volume violation. Not raised when the input was already invalid (an imported solid is not
the blend's fault). It turns "wrong volume found three operations later" into an error at the operation that caused it,
whatever else is or is not done about cleaning.

(2) CLEAN BY DEFAULT, WITH THE HISTORY FOLLOWING
SDK booleans go through `tracked_cut` / `tracked_intersect`, which ask the kernel's history what became of every face
(that is how tags and lineage survive), so cleaning only the shape would break tracking. `BooleanOptions::clean` makes
`run_boolean` unify the result, merge the unifier's history into the boolean's, and follow the section edges through it;
the section-edge following was lifted out of `fuse_shapes_with_history` into one helper both use (fuse behaves as
before). The unified shape replaces the result only when it has the same number of solids and is valid whenever the raw
result was; otherwise the raw result stands. FreeCAD and build123d fall back the same way, and replicad's unconditional
SimplifyResult has been seen to invalidate results (BarbourSmith/Abundance#1934), so the fallback is not decoration.
`clean` is a keyword of the three functions (default True), recorded as params.clean like union's. C++ `cut_shapes`,
`common_shapes` and `tracked_*` keep `clean=false` as their default so other callers (diagnosis, set booleans, std
parts) are unchanged.
Not done on purpose: OCCT's own SimplifyResult(true, true) that the issue suggests: the explicit unifier already gives
the same merge and history, with a fallback we control.

REPLAY: NO LEGACY BRANCH (owner's rule: do not keep old formats alive)
`flag(p, "clean")` and `ctx.require_params(..., "clean")` fail on a graph recorded before this change, as they do for
any missing parameter. Such a graph has to be recorded again.

(3) THE DIAGNOSIS
`classify_split_faces`, before the face-room probe: unify the solid, carry the selected edges over with the unifier's
history, blend again with the same size; if that works the split faces are the cause, and the message says so and how to
fix it (clean=True, or union_rsolid(clean=True)). The room probe stays for a radius that really is too large (test:
radius 50 on the cleaned case is still reported as too large).

EVIDENCE
- Both cases now give valid fillets with volumes 29604.46 and 29811.31, equal to CadQuery's.
- clean=False: A raises "not a valid solid" (it was returned), B raises "faces ... split on a surface ... clean=True".
- test/test_boolean_clean.py (10 tests): face counts 8 against 9, volume unchanged by cleaning, cut_list and intersect,
  both cases, both clean=False diagnoses, a really-too-large radius, `clean` recorded, replay giving 8 / 9 faces.
- A random sample, 120 cases of the issue's recipe (box minus 2-4 vertical boxes/cylinders on a grid, top edges, r 1-3),
  both modes: 240 results, none invalid and returned (clean=True 84 valid / 36 errors, clean=False 83 / 37).
- Full Python suite on this machine: 2674 passed; 22 failed and 9 errors, none touching booleans (Windows paths,
  encodings, file locks, addon and shell integration, missing OCP, a math-library last digit in test_tolerance).

NOT DONE / NOT KNOWN
- The C++ unit tests (ctest) were not built or run here (SCAD_BUILD_TESTS is off for the wheel build). CutOptions::clean
  defaults to true, so a C++ test that compares a cut's topology may need its expectation updated: CI will say.
- The issue's 16000-case run was not repeated, only the small sample above; it shows that no invalid result is
  returned, not the 0.4% rate of the issue (there is no old binary here to compare with).
- A stored artifact or fingerprint of a model with a cut that left split faces changes: the faces are fewer. That is the
  point of the change; rebuild such models.
- Unifying can still make a later blend worse on rare inputs (the issue saw 6 segfaults after unify in other libraries
  too); here the unify is inside the boolean, so a crash would show in the boolean.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-12 03:31:21 +08:00

818 lines
40 KiB
C++

// Python bindings for the "ops_features" area: the operators of operators/{features,boolean,
// transform}.py under the Python names, argument names and defaults (keyword-only where
// Python is keyword-only).
//
// The GIL is released around the kernel work, except while a ql selector is being resolved
// (a property resolver registered from Python is called back from there).
#include "bindings.hpp"
#include <TopAbs_ShapeEnum.hxx>
#include <TopExp_Explorer.hxx>
#include <optional>
#include <string>
#include <vector>
#include "scad/core/tolerance.hpp"
#include "scad/core/error.hpp"
#include "scad/ops/features/features.hpp"
#include "scad/ql/ql.hpp"
#include "scad/reactive/registry.hpp"
namespace {
using namespace scad;
using scad::pybind::Angle;
using scad::pybind::AnyOf;
using scad::pybind::Choice;
using scad::pybind::Count;
using scad::pybind::Direction3;
using scad::pybind::DirectionVec;
using scad::pybind::Length;
using scad::pybind::PlainQuantity;
using scad::pybind::Point3;
using scad::pybind::Vector3;
// ---- what the signatures say ------------------------------------------------------------------------------------
// The parameters below that the binding reads as a Python object (and checks itself, with its own errors) print these.
// SCAD_SIGNATURE_NAME and the vocabulary are in semantic_types.hpp; these name what the operations here accept.
#define SCAD_SIGNATURE_TEXT(Tag, text) SCAD_SIGNATURE_NAME(Tag, pybind11::detail::const_name(text))
SCAD_SIGNATURE_TEXT(EdgesTag,
"collections.abc.Iterable[simplecadapi._cpp._native.Edge] | "
"simplecadapi._cpp._native.ql.ShapeSelector");
SCAD_SIGNATURE_TEXT(FacesTag,
"collections.abc.Iterable[simplecadapi._cpp._native.Face] | "
"simplecadapi._cpp._native.ql.ShapeSelector");
SCAD_SIGNATURE_TEXT(LoftSectionsTag,
"collections.abc.Iterable[simplecadapi._cpp._native.Wire | simplecadapi._cpp._native.Vertex]");
SCAD_SIGNATURE_TEXT(SweepSectionsTag,
"collections.abc.Iterable[simplecadapi._cpp._native.Face | simplecadapi._cpp._native.Wire]");
SCAD_SIGNATURE_TEXT(ShapesTag, "collections.abc.Iterable[simplecadapi._cpp._native.Shape]");
SCAD_SIGNATURE_TEXT(SolidsTag, "collections.abc.Iterable[simplecadapi._cpp._native.Solid]");
SCAD_SIGNATURE_TEXT(TargetTag,
"simplecadapi._cpp._native.Solid | collections.abc.Iterable[simplecadapi._cpp._native.Solid]");
SCAD_SIGNATURE_TEXT(FaceOperandTag, "simplecadapi._cpp._native.Face");
SCAD_SIGNATURE_TEXT(BinormalTag, "simplecadapi._cpp._native.Wire | simplecadapi.types.Direction3 | None");
SCAD_SIGNATURE_TEXT(FactorsTag, "collections.abc.Sequence[float | Expr]");
// A TrackingPolicy member or its value.
SCAD_SIGNATURE_TEXT(PolicyTag, "typing.Literal['full', 'graph'] | simplecadapi._cpp.TrackingPolicy");
// The name of the mode, or an enum member with that name (build123d's Until).
SCAD_SIGNATURE_TEXT(UntilTag, "typing.Literal['NEXT', 'LAST', 'PREVIOUS', 'FIRST'] | enum.Enum");
SCAD_SIGNATURE_TEXT(HandednessTag, "typing.Literal['Right', 'Left']");
// cut_rsolid: what a cut that splits the body gives (every piece, or an error), and what it returns.
SCAD_SIGNATURE_TEXT(OnSplitTag, "typing.Literal['pieces', 'error']");
SCAD_SIGNATURE_TEXT(SolidOrPiecesTag, "simplecadapi._cpp._native.Solid | list[simplecadapi._cpp._native.Solid]");
SCAD_SIGNATURE_TEXT(OffsetKindTag, "typing.Literal['ARC', 'INTERSECTION']");
SCAD_SIGNATURE_TEXT(SetOperationTag, "typing.Literal['cut', 'intersect', 'union']");
#undef SCAD_SIGNATURE_NAME
using EdgesOrQuery = AnyOf<EdgesTag>;
using FacesOrQuery = AnyOf<FacesTag>;
using PointArg = AnyOf<scad::pybind::PointTag>; // checked by vector_arg
using DirectionArg = AnyOf<scad::pybind::DirectionTag>; // checked by vector_arg
using VectorArg = AnyOf<scad::pybind::VectorTag>; // checked by vector_arg
using Policy = AnyOf<PolicyTag>;
using Handedness = Choice<HandednessTag>;
// ---- conversions ---------------------------------------------------------------------------------------------
py::object shape_to_py(const Shape& s) {
switch (s.kind()) {
case Kind::Vertex:
return py::cast(Vertex(s));
case Kind::Edge:
return py::cast(Edge(s));
case Kind::Wire:
return py::cast(Wire(s));
case Kind::Face:
return py::cast(Face(s));
case Kind::Shell:
return py::cast(Shell(s));
case Kind::Solid:
return py::cast(Solid(s));
case Kind::Compound:
return py::cast(Compound(s));
}
return py::none();
}
py::list shapes_to_py(const std::vector<Shape>& shapes) {
py::list out;
for (const Shape& shape : shapes)
out.append(shape_to_py(shape));
return out;
}
py::list solids_to_py(const std::vector<Solid>& solids) {
py::list out;
for (const Solid& solid : solids)
out.append(py::cast(solid));
return out;
}
// A blend (fillet, chamfer) on the pieces of a split cut, the list `cut_rsolid` returns: each piece gets the picked
// edges that lie on it, a piece with none is kept as it is, and the result is the pieces in their order. A selector is
// resolved on every piece without its cardinality, which is then checked against the edges found on all of them.
template <class Blend>
py::list blend_pieces(const py::object& pieces_arg, const py::object& edges, const char* op, const Blend& blend) {
std::vector<Solid> pieces;
for (const py::handle item : pieces_arg) {
if (!py::isinstance<Solid>(item))
throw TypeError(std::string(op) +
": solid must be a Solid, or the list of Solid pieces of a cut that split a body");
pieces.push_back(item.cast<Solid>());
}
if (pieces.empty())
throw ValueError(std::string(op) + ": no solid to work on (an empty list of pieces)");
std::vector<std::vector<Edge>> per(pieces.size());
std::size_t total = 0;
if (py::isinstance<ql::ShapeSelector>(edges)) {
py::dict data = edges.attr("to_dict")();
const py::object card = data.attr("pop")("cardinality", py::none());
const ql::ShapeSelector open = edges.get_type().attr("from_dict")(data).cast<ql::ShapeSelector>();
for (std::size_t i = 0; i < pieces.size(); ++i) {
for (const Shape& shape : open.resolve(pieces[i]))
per[i].emplace_back(shape);
total += per[i].size();
}
if (!card.is_none()) {
const py::dict bound = card.cast<py::dict>();
const auto read = [&bound](const char* key) -> std::optional<std::size_t> {
return bound.contains(key) && !bound[key].is_none() ? std::optional(bound[key].cast<std::size_t>())
: std::nullopt;
};
const auto exactly = read("exactly");
const auto least = read("at_least");
const auto most = read("at_most");
if ((exactly && total != *exactly) || (least && total < *least) || (most && total > *most)) {
throw ValueError(std::string(op) + ": the edge selector expected " + py::str(card).cast<std::string>() +
" edge(s) on the pieces of the split body, found " + std::to_string(total));
}
}
} else {
for (const py::handle item : edges) {
if (!py::isinstance<Edge>(item))
throw TypeError(std::string(op) + ": expected an Edge or a QL selector");
const Edge edge = item.cast<Edge>();
bool placed = false;
for (std::size_t i = 0; i < pieces.size() && !placed; ++i) {
for (TopExp_Explorer it(pieces[i].wrapped(), TopAbs_EDGE); it.More() && !placed; it.Next()) {
if (it.Current().IsSame(edge.wrapped())) {
per[i].push_back(edge);
placed = true;
}
}
}
if (!placed)
throw ValueError(std::string(op) + ": an edge is not on any piece of the split body");
++total;
}
}
if (total == 0)
throw ValueError(std::string(op) + ": no edge to work on in any piece of the split body");
py::list out;
for (std::size_t i = 0; i < pieces.size(); ++i)
out.append(per[i].empty() ? py::cast(pieces[i]) : py::cast(blend(pieces[i], EdgeSelection(per[i]))));
return out;
}
// A list of shapes of one kind, or a ql selector that finds them.
template <class T>
Selection<T> selection_from(const py::object& value) {
if (py::isinstance<ql::ShapeSelector>(value))
return Selection<T>(value.cast<const ql::ShapeSelector&>());
std::vector<T> items;
for (const py::handle item : value) {
if (!py::isinstance<T>(item)) {
throw TypeError(std::string("expected a ") + std::string(kind_name(T::kKind)) + " or a QL selector");
}
items.push_back(item.cast<T>());
}
return Selection<T>(std::move(items));
}
// A 3-vector argument that Python validates itself: any sequence of numbers, ValueError unless it
// holds exactly three.
Scalar3 vector_arg(const py::object& value, const char* name) {
const std::string message = std::string(name) + " must contain three finite numbers";
if ((py::isinstance<py::str>(value) || py::isinstance<py::bytes>(value)) || !py::hasattr(value, "__len__") ||
!py::hasattr(value, "__getitem__"))
throw ValueError(message);
const py::sequence items = py::reinterpret_borrow<py::sequence>(value);
if (items.size() != 3)
throw ValueError(message);
Scalar3 out;
for (std::size_t i = 0; i < 3; ++i)
out[i] = items[i].cast<Scalar>();
return out;
}
std::vector<Shape> shape_list(const py::object& value, const char* complaint) {
std::vector<Shape> out;
for (const py::handle item : value) {
if (!py::isinstance<Shape>(item))
throw TypeError(complaint);
out.push_back(item.cast<Shape>());
}
return out;
}
// An operator that takes `tracking_policy`: the enum member or its string value.
std::string policy_text(const py::object& value) {
if (py::isinstance<py::str>(value))
return value.cast<std::string>();
if (py::hasattr(value, "value"))
return py::str(value.attr("value")).cast<std::string>();
return py::str(value).cast<std::string>();
}
// Runs `body` with the GIL released unless `keep_gil`. An exception leaves with the GIL back.
template <class F>
auto unlocked(bool keep_gil, F&& body) {
std::optional<py::gil_scoped_release> release;
if (!keep_gil)
release.emplace();
return body();
}
py::tuple unit_z() {
return py::make_tuple(0, 0, 1);
}
py::tuple origin() {
return py::make_tuple(0, 0, 0);
}
// ---- sweeps of a profile ------------------------------------------------------------------------------------
SweepTags sweep_tags(OptionalString tag_prefix, OptionalString result_tag, OptionalString start, OptionalString end,
OptionalString side) {
return {std::move(tag_prefix), std::move(result_tag), std::move(start), std::move(end), std::move(side)};
}
void bind_extrusion(py::module_& m) {
m.def(
"extrude_rsolid",
[](const Shape& profile, const Direction3& direction, const Length& distance, OptionalString tag_prefix,
OptionalString result_tag, OptionalString start_face_tag, OptionalString end_face_tag,
OptionalString side_faces_tag) {
const SweepTags tags = sweep_tags(std::move(tag_prefix), std::move(result_tag), std::move(start_face_tag),
std::move(end_face_tag), std::move(side_faces_tag));
return unlocked(false, [&] { return extrude_rsolid(profile, direction, distance, tags); });
},
py::arg("profile"), py::arg("direction"), py::arg("distance"), py::kw_only(), py::arg("tag_prefix") = py::none(),
py::arg("result_tag") = py::none(), py::arg("start_face_tag") = py::none(), py::arg("end_face_tag") = py::none(),
py::arg("side_faces_tag") = py::none(), "Create a solid by extruding a profile, with optional role-based tags.");
m.def(
"revolve_rsolid",
[](const Shape& profile, const Direction3& axis, const Angle& angle, const Point3& origin,
OptionalString tag_prefix, OptionalString result_tag, OptionalString start_face_tag,
OptionalString end_face_tag, OptionalString side_faces_tag) {
const SweepTags tags = sweep_tags(std::move(tag_prefix), std::move(result_tag), std::move(start_face_tag),
std::move(end_face_tag), std::move(side_faces_tag));
return unlocked(false, [&] { return revolve_rsolid(profile, axis, angle, origin, tags); });
},
py::arg("profile"), py::arg("axis") = unit_z(), py::arg("angle") = 360, py::arg("origin") = origin(),
py::kw_only(), py::arg("tag_prefix") = py::none(), py::arg("result_tag") = py::none(),
py::arg("start_face_tag") = py::none(), py::arg("end_face_tag") = py::none(),
py::arg("side_faces_tag") = py::none(), "Create a revolved solid, with optional kernel-role-based tags.");
}
// ---- local features ------------------------------------------------------------------------------------------
void bind_blends(py::module_& m) {
m.def(
"fillet_rsolid",
[](const AnyOf<SolidOrPiecesTag>& solid, const EdgesOrQuery& edges, const Length& radius,
OptionalString result_tag, OptionalString generated_faces_tag) -> AnyOf<SolidOrPiecesTag> {
const BlendTags tags{std::move(result_tag), std::move(generated_faces_tag)};
if (!py::isinstance<Solid>(solid.value)) {
return {
blend_pieces(solid.value, edges, "fillet_rsolid", [&](const Solid& piece, const EdgeSelection& picked) {
return fillet_rsolid(piece, picked, radius, tags);
})};
}
const Solid body = solid.value.cast<Solid>();
const EdgeSelection selection = selection_from<Edge>(edges);
return {
py::cast(unlocked(selection.is_selector(), [&] { return fillet_rsolid(body, selection, radius, tags); }))};
},
py::arg("solid"), py::arg("edges"), py::arg("radius"), py::kw_only(), py::arg("result_tag") = py::none(),
py::arg("generated_faces_tag") = py::none(),
"Apply fillets, with optional tagging of kernel-proven patch faces.");
m.def(
"chamfer_rsolid",
[](const AnyOf<SolidOrPiecesTag>& solid, const EdgesOrQuery& edges, const Length& distance,
std::optional<PlainQuantity<scad::pybind::AngleTag>> angle, std::optional<DirectionVec> reference_direction,
OptionalString result_tag, OptionalString generated_faces_tag) -> AnyOf<SolidOrPiecesTag> {
const ChamferOptions options{angle ? std::optional<double>(*angle) : std::nullopt,
reference_direction ? std::optional<Vec3>(*reference_direction) : std::nullopt,
{std::move(result_tag), std::move(generated_faces_tag)}};
if (!py::isinstance<Solid>(solid.value)) {
return {
blend_pieces(solid.value, edges, "chamfer_rsolid", [&](const Solid& piece, const EdgeSelection& picked) {
return chamfer_rsolid(piece, picked, distance, options);
})};
}
const Solid body = solid.value.cast<Solid>();
const EdgeSelection selection = selection_from<Edge>(edges);
return {py::cast(
unlocked(selection.is_selector(), [&] { return chamfer_rsolid(body, selection, distance, options); }))};
},
py::arg("solid"), py::arg("edges"), py::arg("distance"), py::kw_only(), py::arg("angle") = py::none(),
py::arg("reference_direction") = py::none(), py::arg("result_tag") = py::none(),
py::arg("generated_faces_tag") = py::none(),
"Apply chamfers, with optional tagging of kernel-proven patch faces.\n\nWithout ``angle`` the chamfer is "
"symmetric. "
"With ``angle`` (degrees between the chamfer face and the reference face) the second leg is "
"``distance * tan(angle)``; ``reference_direction`` picks the reference face per edge.");
m.def(
"shell_rsolid",
[](const Solid& solid, const FacesOrQuery& faces_to_remove, const Length& thickness, OptionalString result_tag,
OptionalString body_faces_tag, OptionalString offset_faces_tag, OptionalString closing_faces_tag,
OptionalString wall_edges_tag) {
const FaceSelection selection = selection_from<Face>(faces_to_remove);
const ShellTags tags{std::move(result_tag), std::move(body_faces_tag), std::move(offset_faces_tag),
std::move(closing_faces_tag), std::move(wall_edges_tag)};
return unlocked(selection.is_selector(), [&] { return shell_rsolid(solid, selection, thickness, tags); });
},
py::arg("solid"), py::arg("faces_to_remove"), py::arg("thickness"), py::kw_only(),
py::arg("result_tag") = py::none(), py::arg("body_faces_tag") = py::none(),
py::arg("offset_faces_tag") = py::none(), py::arg("closing_faces_tag") = py::none(),
py::arg("wall_edges_tag") = py::none(), "Shell a solid, with optional kernel-role-based face tags.");
}
// ---- sweeps through sections ---------------------------------------------------------------------------------
void bind_sweeps(py::module_& m) {
m.def(
"loft_rsolid",
[](const AnyOf<LoftSectionsTag>& profiles, bool ruled, const Policy& tracking_policy, OptionalString tag_prefix,
OptionalString result_tag, OptionalString start_face_tag, OptionalString end_face_tag,
OptionalString side_faces_tag) {
const std::vector<Shape> sections =
shape_list(profiles, "loft_rsolid sections must contain only Wire or Vertex objects");
const LoftOptions options{policy_text(tracking_policy),
sweep_tags(std::move(tag_prefix), std::move(result_tag), std::move(start_face_tag),
std::move(end_face_tag), std::move(side_faces_tag))};
return unlocked(false, [&] { return loft_rsolid(sections, ruled, options); });
},
py::arg("profiles"), py::arg("ruled") = false, py::kw_only(), py::arg("tracking_policy") = "full",
py::arg("tag_prefix") = py::none(), py::arg("result_tag") = py::none(), py::arg("start_face_tag") = py::none(),
py::arg("end_face_tag") = py::none(), py::arg("side_faces_tag") = py::none(),
"Create a lofted solid, with optional kernel-role-based tags.");
m.def(
"sweep_rsolid",
[](const Face& profile, const Wire& path, bool is_frenet, OptionalString tag_prefix, OptionalString result_tag,
OptionalString start_face_tag, OptionalString end_face_tag, OptionalString side_faces_tag) {
const SweepTags tags = sweep_tags(std::move(tag_prefix), std::move(result_tag), std::move(start_face_tag),
std::move(end_face_tag), std::move(side_faces_tag));
return unlocked(false, [&] { return sweep_rsolid(profile, path, is_frenet, tags); });
},
py::arg("profile"), py::arg("path"), py::arg("is_frenet") = false, py::kw_only(),
py::arg("tag_prefix") = py::none(), py::arg("result_tag") = py::none(), py::arg("start_face_tag") = py::none(),
py::arg("end_face_tag") = py::none(), py::arg("side_faces_tag") = py::none(),
"Create a swept solid, with optional kernel-role-based tags.");
m.def(
"twisted_sweep_rsolid",
[](const Shape& profile, const Length& distance, const Angle& twist_angle, const Direction3& axis,
const Point3& origin, const Length& guide_radius, OptionalString tag_prefix, OptionalString result_tag,
OptionalString start_face_tag, OptionalString end_face_tag, OptionalString side_faces_tag) {
const TwistedSweepOptions options{
guide_radius, sweep_tags(std::move(tag_prefix), std::move(result_tag), std::move(start_face_tag),
std::move(end_face_tag), std::move(side_faces_tag))};
return unlocked(false,
[&] { return twisted_sweep_rsolid(profile, distance, twist_angle, axis, origin, options); });
},
py::arg("profile"), py::arg("distance"), py::arg("twist_angle"), py::arg("axis") = unit_z(),
py::arg("origin") = origin(), py::kw_only(), py::arg("guide_radius") = 1.0, py::arg("tag_prefix") = py::none(),
py::arg("result_tag") = py::none(), py::arg("start_face_tag") = py::none(), py::arg("end_face_tag") = py::none(),
py::arg("side_faces_tag") = py::none(),
"Sweep a planar profile along a straight axis with linear rotation (twist_angle in degrees).");
m.def(
"helical_sweep_rsolid",
[](const Wire& profile, const Length& pitch, const Length& height, const Length& radius, const Point3& center,
const Direction3& dir, const Handedness& handedness) {
return unlocked(
false, [&] { return helical_sweep_rsolid(profile, pitch, height, radius, center, dir, handedness.value); });
},
py::arg("profile"), py::arg("pitch"), py::arg("height"), py::arg("radius"), py::arg("center") = origin(),
py::arg("dir") = unit_z(), py::kw_only(), py::arg("handedness") = "Right",
"Create a solid by sweeping a profile along a helical path.");
m.def(
"sweep_multisection_rsolid",
[](const AnyOf<SweepSectionsTag>& profiles, const Wire& path, bool is_frenet,
const AnyOf<BinormalTag>& binormal_arg) {
const py::object& binormal = binormal_arg;
const std::vector<Shape> sections = shape_list(profiles, "sections must be Face or Wire");
std::optional<Binormal> aux;
if (py::isinstance<Wire>(binormal) || py::isinstance<Edge>(binormal)) // an edge: the wire of that one edge
aux = Binormal(binormal.cast<Wire>());
else if (!binormal.is_none())
aux = Binormal(vector_arg(binormal, "binormal"));
return unlocked(false, [&] { return sweep_multisection_rsolid(sections, path, is_frenet, aux); });
},
py::arg("profiles"), py::arg("path"), py::arg("is_frenet") = false, py::arg("binormal") = py::none(),
"Sweep through explicit ordered sections along a continuous path.");
}
// ---- derived solids ---------------------------------------------------------------------------------------------
void bind_derived(py::module_& m) {
m.def(
"offset_rsolid",
[](const Solid& solid, const Length& amount, const FacesOrQuery& openings, double tolerance,
const Choice<OffsetKindTag>& kind) {
const FaceSelection selection = selection_from<Face>(openings);
return unlocked(selection.is_selector(),
[&] { return offset_rsolid(solid, amount, selection, {tolerance, kind}); });
},
py::arg("solid"), py::arg("amount"), py::arg("openings") = py::tuple(), py::kw_only(),
py::arg("tolerance") = tol::kOffsetTolerance, py::arg("kind") = "ARC",
"Offset a solid outward (positive) or inward (negative).");
m.def(
"draft_rsolid",
[](const Solid& solid, const FacesOrQuery& faces_to_draft, const Angle& angle, const PointArg& plane_origin,
const DirectionArg& plane_normal) {
const FaceSelection selection = selection_from<Face>(faces_to_draft);
const Scalar3 origin_value = vector_arg(plane_origin, "plane_origin"),
normal_value = vector_arg(plane_normal, "plane_normal");
return unlocked(selection.is_selector(),
[&] { return draft_rsolid(solid, selection, angle, origin_value, normal_value); });
},
py::arg("solid"), py::arg("faces_to_draft"), py::arg("angle"), py::arg("plane_origin") = origin(),
py::arg("plane_normal") = unit_z(),
"Draft planar, cylindrical or conical faces by a signed angle in degrees about a neutral plane.");
m.def(
"press_pull_rsolid",
[](const Solid& solid, const FacesOrQuery& face, const Length& distance) {
const FaceSelection selection = selection_from<Face>(face);
return unlocked(selection.is_selector(), [&] { return press_pull_rsolid(solid, selection, distance); });
},
py::arg("solid"), py::arg("face"), py::arg("distance"),
"Pull one planar face out along its outward normal (positive distance) or press it in (negative).");
m.def(
"inset_face_rsolid",
[](const Solid& solid, const FacesOrQuery& face, const Length& distance) {
const FaceSelection selection = selection_from<Face>(face);
return unlocked(selection.is_selector(), [&] { return inset_face_rsolid(solid, selection, distance); });
},
py::arg("solid"), py::arg("face"), py::arg("distance"),
"Imprint the loops of one planar face moved a distance inside it, splitting the face in an inner face and a "
"ring.");
m.def(
"extrude_taper_rsolid",
[](const Face& profile, const VectorArg& vector, const Angle& taper, bool flip_inner) {
const Scalar3 direction = vector_arg(vector, "vector");
return unlocked(false, [&] { return extrude_taper_rsolid(profile, direction, taper, flip_inner); });
},
py::arg("profile"), py::arg("vector"), py::arg("taper"), py::arg("flip_inner") = true,
"Extrude a planar sketch face by a vector, with a taper in degrees.");
m.def(
"extrude_until_rsolid",
[](const Face& profile, const AnyOf<TargetTag>& target_arg, const DirectionArg& direction,
const AnyOf<UntilTag>& until_arg) {
const py::object& target = target_arg;
const py::object& until = until_arg;
std::vector<Solid> targets;
if (py::isinstance<Solid>(target)) {
targets.push_back(target.cast<Solid>());
} else {
for (const py::handle item : target) {
if (!py::isinstance<Solid>(item))
throw TypeError("target must be a Solid or a sequence of Solid");
targets.push_back(item.cast<Solid>());
}
}
const Scalar3 axis = vector_arg(direction, "direction");
const std::string mode = py::str(py::hasattr(until, "name") ? until.attr("name") : until).cast<std::string>();
return unlocked(false, [&] { return extrude_until_rsolid(profile, targets, axis, mode); });
},
py::arg("profile"), py::arg("target"), py::arg("direction") = unit_z(), py::arg("until") = "NEXT",
"Extrude a planar face until a target surface, including curved surfaces.");
m.def(
"scale_rsolid",
[](const Solid& solid, const AnyOf<FactorsTag>& factors, const PointArg& center) {
const Scalar3 scale = vector_arg(factors, "factors"), about = vector_arg(center, "center");
return unlocked(false, [&] { return scale_rsolid(solid, scale, about); });
},
py::arg("solid"), py::arg("factors"), py::arg("center") = origin(),
"Scale a solid along the current coordinate system's axes about a center.");
m.def(
"transform_rsolid",
[](const Solid& solid, const std::vector<std::vector<Scalar>>& matrix) {
return unlocked(false, [&] { return transform_rsolid(solid, matrix); });
},
py::arg("solid"), py::arg("matrix"),
"Apply a finite nonsingular 4x4 affine matrix in the current coordinate system.");
}
// ---- tracking policy and the failure diagnoses ------------------------------------------------------------------
// `with tracking_policy_scope(TrackingPolicy.GRAPH): ...`
class PolicyScope {
public:
explicit PolicyScope(TrackingPolicy policy) : policy_(policy) {}
PolicyScope& enter() {
scope_.emplace(policy_);
return *this;
}
void exit() { scope_.reset(); }
private:
TrackingPolicy policy_;
std::optional<TrackingPolicyScope> scope_;
};
void bind_tracking_policy(py::module_& m) {
py::list members;
members.append(py::make_tuple("FULL", "full"));
members.append(py::make_tuple("GRAPH", "graph"));
py::dict kwargs;
kwargs["type"] = py::module_::import("builtins").attr("str");
kwargs["module"] = "simplecadapi._cpp";
m.attr("TrackingPolicy") = py::module_::import("enum").attr("Enum")("TrackingPolicy", members, **kwargs);
py::class_<PolicyScope, std::shared_ptr<PolicyScope>>(m, "_TrackingPolicyScope")
.def("__enter__",
[](const std::shared_ptr<PolicyScope>& scope) {
scope->enter();
return scope;
})
.def("__exit__", [](PolicyScope& scope, const py::args&) { scope.exit(); });
m.def(
"tracking_policy_scope",
[](const Policy& policy) {
const std::string text = policy_text(policy);
if (text == "full")
return std::make_shared<PolicyScope>(TrackingPolicy::Full);
if (text == "graph")
return std::make_shared<PolicyScope>(TrackingPolicy::Graph);
throw ValueError("'" + text + "' is not a valid TrackingPolicy");
},
py::arg("policy"), "Run a block with graph-only or full topology tracking.");
m.def("current_tracking_policy", [] { return std::string(to_string(current_tracking_policy())); });
}
py::list measurements_to_py(const std::vector<ErrorMeasurement>& measurements) {
py::list out;
for (const ErrorMeasurement& item : measurements) {
py::dict entry;
entry["name"] = item.name;
if (const auto* number = std::get_if<double>(&item.value))
entry["value"] = *number;
else {
const auto& v = std::get<std::array<double, 3>>(item.value);
entry["value"] = py::make_tuple(v[0], v[1], v[2]);
}
entry["unit"] = item.unit;
out.append(entry);
}
return out;
}
template <class Diagnosis>
void bind_diagnosis(py::module_& m, const char* name) {
py::class_<Diagnosis>(m, name)
.def_readonly("failure_kind", &Diagnosis::failure_kind)
.def_readonly("what_happened", &Diagnosis::what_happened)
.def_readonly("possible_causes", &Diagnosis::possible_causes)
.def_readonly("repair", &Diagnosis::repair)
.def_property_readonly("measurements", [](const Diagnosis& d) { return measurements_to_py(d.measurements); });
}
void bind_diagnostics(py::module_& m) {
bind_diagnosis<BlendDiagnosis>(m, "BlendDiagnosis");
bind_diagnosis<BooleanDiagnosis>(m, "BooleanDiagnosis");
m.def(
"diagnose_blend_failure",
[](const Solid& solid, const py::list& edges, double size_value, const std::string& operation_kind,
const py::object& retry_single) {
std::vector<Edge> items;
for (const py::handle item : edges)
items.push_back(item.cast<Edge>());
BlendRetry retry;
if (!retry_single.is_none())
retry = [&](const Edge& edge) { return py::bool_(retry_single(py::cast(edge))).cast<bool>(); };
return diagnose_blend_failure(solid, items, size_value, operation_kind, retry);
},
py::arg("solid"), py::arg("edges"), py::kw_only(), py::arg("size_value"), py::arg("operation_kind"),
py::arg("retry_single") = py::none(), "Classify a fillet/chamfer failure; None when no probe explains it.");
m.def(
"assert_blend_volume_monotonic",
[](const Solid& source, const Solid& result, const std::string&, const std::string& operation_kind,
std::optional<double> size_value, const py::list& edges) {
std::vector<Edge> items;
for (const py::handle item : edges)
items.push_back(item.cast<Edge>());
assert_blend_volume_monotonic(source, result, operation_kind, size_value, items);
},
py::arg("source"), py::arg("result"), py::kw_only(), py::arg("operation"), py::arg("operation_kind"),
py::arg("size_value"), py::arg("edges"),
"Raise when an all-convex blend returned more material than it was given.");
m.def(
"diagnose_boolean_failure",
[](const py::list& operands, std::optional<double> effective_tol, const std::string& operation_kind) {
std::vector<Solid> solids;
for (const py::handle item : operands)
solids.push_back(item.cast<Solid>());
return diagnose_boolean_failure(solids, effective_tol, operation_kind);
},
py::arg("operands"), py::kw_only(), py::arg("effective_tol"), py::arg("operation_kind") = "union",
"Classify a boolean failure from its operands; None when none explains it.");
m.def(
"raise_loft_failure_if_diagnosed",
[](const AnyOf<ShapesTag>& sections, const std::string& operation) {
raise_loft_failure_if_diagnosed(shape_list(sections, "loft sections must be shapes"), operation);
},
py::arg("sections"), py::arg("operation"), "Explain a failed loft from its sections, when they do.");
}
// ---- booleans ------------------------------------------------------------------------------------------------
// The Solids of `args`, nested lists and tuples flattened; anything else is the operator's own error.
void flatten_solids(const py::handle& value, std::string_view operation, std::vector<Solid>& out) {
if (py::isinstance<Solid>(value)) {
out.push_back(value.cast<Solid>());
} else if (py::isinstance<py::list>(value) || py::isinstance<py::tuple>(value)) {
for (const py::handle item : value)
flatten_solids(item, operation, out);
} else {
reject_boolean_operand(operation);
}
}
std::vector<Solid> flattened(const py::args& args, std::string_view operation) {
std::vector<Solid> out;
for (const py::handle item : args)
flatten_solids(item, operation, out);
return out;
}
std::vector<Solid> solid_group(const py::object& group) {
std::vector<Solid> out;
for (const py::handle item : group) {
if (!py::isinstance<Solid>(item))
throw TypeError("boolean groups must contain Solid values");
out.push_back(item.cast<Solid>());
}
return out;
}
void bind_booleans(py::module_& m) {
m.def(
"union_rsolid",
[](const py::args& solids, bool clean, bool glue, std::optional<double> tol, const Policy& tracking_policy) {
const std::vector<Solid> operands = flattened(solids, "union_rsolid");
const UnionOptions options{clean, glue, tol, policy_text(tracking_policy)};
return unlocked(false, [&] { return union_rsolid(operands, options); });
},
py::kw_only(), py::arg("clean") = true, py::arg("glue") = false, py::arg("tol") = py::none(),
py::arg("tracking_policy") = "full", "Compute the boolean union and return one manifold solid.");
m.def(
"cut_rsolid",
[](const py::args& solids, bool skip_non_intersecting, const Policy& tracking_policy,
const Choice<OnSplitTag>& on_split, bool clean) -> AnyOf<SolidOrPiecesTag> {
const std::vector<Solid> operands = flattened(solids, "cut_rsolid");
CutOptions options{skip_non_intersecting, policy_text(tracking_policy)};
options.clean = clean;
if (on_split.value == "error")
return {py::cast(unlocked(false, [&] { return cut_rsolid(operands, options); }))};
if (on_split.value != "pieces")
throw scad::ValueError("on_split must be 'pieces' or 'error'");
CutOutcome outcome = unlocked(false, [&] { return cut_rsolid_keep_split(operands, options); });
if (outcome.solid)
return {py::cast(*outcome.solid)};
return {solids_to_py(outcome.pieces)}; // the cut split the body: every piece, ordered by centroid
},
py::kw_only(), py::arg("skip_non_intersecting") = true, py::arg("tracking_policy") = "full",
py::arg("on_split") = "pieces", py::arg("clean") = true,
"Compute the boolean difference of solids: the first is the base, the rest are subtracted in order.");
m.def(
"cut_rsolid_list",
[](const py::args& solids, bool skip_non_intersecting, const Policy& tracking_policy, bool clean) {
const std::vector<Solid> operands = flattened(solids, "cut_rsolid_list");
CutOptions options{skip_non_intersecting, policy_text(tracking_policy)};
options.clean = clean;
return solids_to_py(unlocked(false, [&] { return cut_rsolid_list(operands, options); }));
},
py::kw_only(), py::arg("skip_non_intersecting") = true, py::arg("tracking_policy") = "full",
py::arg("clean") = true,
"Compute the boolean difference of solids and keep every piece: a cut that splits the body returns each part, "
"and one that consumes the body returns an empty list.");
m.def(
"intersect_rsolid",
[](const py::args& solids, bool clean) {
const std::vector<Solid> operands = flattened(solids, "intersect_rsolid");
return unlocked(false, [&] { return intersect_rsolid(operands, clean); });
},
py::kw_only(), py::arg("clean") = true, "Compute the boolean intersection of solids.");
m.def(
"boolean_rsolidlist",
[](const AnyOf<SolidsTag>& left, const AnyOf<SolidsTag>& right, const Choice<SetOperationTag>& operation_arg) {
const std::string& operation = operation_arg;
if (operation != "cut" && operation != "intersect" && operation != "union") {
throw ValueError("operation must be cut, intersect or union");
}
const std::vector<Solid> lhs = solid_group(left), rhs = solid_group(right);
return solids_to_py(unlocked(false, [&] { return boolean_rsolidlist(lhs, rhs, operation); }));
},
py::arg("left"), py::arg("right"), py::arg("operation"),
"Apply a set boolean to two body groups, retaining every result solid.");
const auto bind_2d = [&m](const char* name, Face (*fn)(const Shape&, const Shape&), const char* first,
const char* second, const char* doc) {
m.def(
name,
[fn, name, first, second](const AnyOf<FaceOperandTag>& a_arg, const AnyOf<FaceOperandTag>& b_arg) {
const py::object& a = a_arg;
const py::object& b = b_arg;
if (!py::isinstance<Shape>(a))
reject_face_operand(name, first);
if (!py::isinstance<Shape>(b))
reject_face_operand(name, second);
const Shape& left = a.cast<const Shape&>();
const Shape& right = b.cast<const Shape&>();
return unlocked(false, [&] { return fn(left, right); });
},
py::arg(first), py::arg(second), doc);
};
bind_2d("make_2d_cut_rface", &make_2d_cut_rface, "body", "tool", "Subtract one 2D face from another.");
bind_2d("make_2d_union_rface", &make_2d_union_rface, "face_a", "face_b",
"Compute the boolean union of two 2D faces.");
bind_2d("make_2d_intersect_rface", &make_2d_intersect_rface, "face_a", "face_b",
"Compute the boolean intersection of two 2D faces.");
}
// ---- transforms and patterns ----------------------------------------------------------------------------------
void bind_transforms(py::module_& m) {
m.def(
"translate_shape",
[](const Shape& shape, const Vector3& vector) {
return shape_to_py(unlocked(false, [&] { return translate_shape(shape, vector); }));
},
py::arg("shape"), py::arg("vector"), "Translate a shape by an offset vector.");
m.def(
"rotate_shape",
[](const Shape& shape, const Angle& angle, const Direction3& axis, const Point3& origin) {
return shape_to_py(unlocked(false, [&] { return rotate_shape(shape, angle, axis, origin); }));
},
py::arg("shape"), py::arg("angle"), py::arg("axis") = unit_z(), py::arg("origin") = origin(),
"Rotate a shape around an axis.");
m.def(
"mirror_shape",
[](const Shape& shape, const Point3& plane_origin, const Direction3& plane_normal) {
return shape_to_py(unlocked(false, [&] { return mirror_shape(shape, plane_origin, plane_normal); }));
},
py::arg("shape"), py::arg("plane_origin"), py::arg("plane_normal"), "Mirror a shape across a plane.");
m.def(
"linear_pattern_rsolidlist",
[](const Shape& shape, const Direction3& direction, const Count& count, const Length& spacing) {
return shapes_to_py(
unlocked(false, [&] { return linear_pattern_rsolidlist(shape, direction, count, spacing); }));
},
py::arg("shape"), py::arg("direction"), py::arg("count"), py::arg("spacing"),
"Create a linear pattern of solids.");
m.def(
"radial_pattern_rsolidlist",
[](const Shape& shape, const Point3& center, const Direction3& axis, const Count& count,
const Angle& total_rotation_angle) {
return shapes_to_py(unlocked(
false, [&] { return radial_pattern_rsolidlist(shape, center, axis, count, total_rotation_angle); }));
},
py::arg("shape"), py::arg("center"), py::arg("axis"), py::arg("count"), py::arg("total_rotation_angle"),
"Create a radial pattern of solids.");
}
} // namespace
void bind_ops_features(py::module_& m) {
bind_extrusion(m);
bind_blends(m);
bind_booleans(m);
bind_transforms(m);
bind_sweeps(m);
bind_derived(m);
bind_tracking_policy(m);
bind_diagnostics(m);
register_features_executors(reactive::ExecutorRegistry::global());
}