diff --git a/docs/skill/references/docs/api/README.md b/docs/skill/references/docs/api/README.md index 7f17bb0d..84d951e7 100644 --- a/docs/skill/references/docs/api/README.md +++ b/docs/skill/references/docs/api/README.md @@ -414,6 +414,7 @@ This index includes generated docs for the public SimpleCAD API surface, includi - [insert_curve_knot_redge](insert_curve_knot_redge.md) *(from operators/geometry.py)* `top-level` - [insert_spline_anchor_rsketch](insert_spline_anchor_rsketch.md) *(from operators/sketch.py)* `top-level` - [insert_surface_knot_rface](insert_surface_knot_rface.md) *(from operators/geometry.py)* `top-level` +- [inset_face_rsolid](inset_face_rsolid.md) *(from operators/features.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` diff --git a/docs/skill/references/docs/api/inset_face_rsolid.md b/docs/skill/references/docs/api/inset_face_rsolid.md new file mode 100644 index 00000000..22246a86 --- /dev/null +++ b/docs/skill/references/docs/api/inset_face_rsolid.md @@ -0,0 +1,65 @@ +# inset_face_rsolid + +## API Definition + +```python +def inset_face_rsolid(solid, face, distance) +``` + +*Source: operators/features.py* + +## Import Surface + +- top-level: `from simplecadapi import inset_face_rsolid` + +## Description + +Imprint the loops of one planar face moved a distance inside it. + +The outline of the face (and the outline of each of its holes) is offset in +the face's plane by ``distance`` towards the inside, and the offset loops are +imprinted on the solid: the face becomes an inner face and the ring around it +(a ring around each hole too). The solid keeps its shape and volume; it only +has one face more, which the next operation can pull out, push in or open, so +steps, bosses and walls are built by insetting and pulling again. + +The operation is recorded as ``make_inset_face_rsolid``; the body and the face +are ordered inputs and the distance is a parameter, so model JSON replay is +strict. The split pieces are fragments of the face (element references and +tags follow them as a split) and carry the kernel roles ``inset.inner`` and +``inset.ring``, so ``scad.ref.face(..., role="inset.inner")`` names the inner +face whatever the face was. + +## Parameters + +### solid + +- **Description**: The body whose face is inset. + +### face + +- **Description**: One planar face of ``solid``, or a QL selector that picks exactly one. + +### distance + +- **Description**: How far inside the face the loops run, in mm; positive. + +## Returns + +The same solid with the face split in its inner face and ring. + +## Raises + +- **TypeError**: ``solid`` is not a Solid. +- **ValueError**: Not exactly one face, a face of another solid, a curved face, a non-positive distance, or a distance at which nothing of the face is left inside the loops. + +## Examples + +```python +import simplecadapi as scad +ql = scad.ql +box = scad.make_box_rsolid(40, 30, 20) +top = ql.faces().where(ql.prop("geom.center.z", ">=", 19.9)).exactly(1) +inset = scad.inset_face_rsolid(box, top, 3) +inner = scad.ref.face("", "make_inset_face_rsolid", role="inset.inner").one(inset) +``` diff --git a/docs/skill/references/domains/part-modeling.md b/docs/skill/references/domains/part-modeling.md index 7f5e8988..ade12e1e 100644 --- a/docs/skill/references/domains/part-modeling.md +++ b/docs/skill/references/domains/part-modeling.md @@ -72,6 +72,9 @@ consult their own documentation before the first call. `twisted_sweep_rsolid` (supports inner-wire profiles), `helical_sweep_rsolid`, `loft_rsolid`, `loft_rshell`, `shell_rsolid`. - Detail: `fillet_rsolid`, `chamfer_rsolid`. +- Face loops: `inset_face_rsolid(solid, face, distance)` imprints a planar face's loops moved inside it (the + shape is unchanged; the face splits into roles `inset.inner` and `inset.ring`). Pull or push the inner face + next (`extrude_rsolid(profile=inner, ...)` joined or cut) to build steps, bosses and walls without a sketch. ## Boolean discipline diff --git a/editor-web/src/components/OperationPanel.tsx b/editor-web/src/components/OperationPanel.tsx index 8a69c2d6..fea3d37d 100644 --- a/editor-web/src/components/OperationPanel.tsx +++ b/editor-web/src/components/OperationPanel.tsx @@ -56,7 +56,7 @@ export function OperationPanel({ if (event.key === "Escape") { event.preventDefault(); drop.current(); - } else if (event.key === "Enter" && !event.shiftKey && !(event.target as HTMLElement | null)?.closest("textarea, .cm-editor")) { + } else if (event.key === "Enter" && !event.shiftKey && !(event.target instanceof Element && event.target.closest("textarea, .cm-editor"))) { event.preventDefault(); // let a number box commit its value first window.setTimeout(() => keep.current(), 0); diff --git a/editor-web/src/i18n/locales/zh-CN.json b/editor-web/src/i18n/locales/zh-CN.json index 37be20a1..4dd86720 100644 --- a/editor-web/src/i18n/locales/zh-CN.json +++ b/editor-web/src/i18n/locales/zh-CN.json @@ -339,12 +339,16 @@ "Holes": "孔", "Hollow the body, opening the picked faces.": "把实体挖空,并打开所选的面。", "How the new solid meets the body so far: join it, cut it out, keep only what they share, or (when there is no body yet) start it.": "新实体与已有实体的关系:合并、切除、只保留公共部分,或(还没有实体时)作为起始实体。", + "Imprint the loops of one planar face moved a distance inside it, splitting the face in an inner face and a ring.": "把一个平面的轮廓向内偏移一段距离并印刻,将面分成内面和外圈。", + "Imprint the outline of a flat face moved inside it: the face splits into an inner face (pull it out or push it in next) and the ring around it.": "把平面的轮廓向内偏移并印刻到实体上:面被分成内面(之后可拉出或压入)和外圈。", "Inner wires": "内线框", "Insert a U or V knot into a face's B-spline surface at ``parameter`` (strictly inside the surface's domain in that direction).": "在面的 B 样条曲面的 ``parameter`` 处插入一个 U 或 V 节点(必须严格位于该方向的参数域内部)。", "Insert a cell here": "在此插入单元", "Insert a knot into an edge's B-spline curve at ``parameter`` (strictly inside the edge's parameter range).": "在边的 B 样条曲线的 ``parameter`` 处插入节点(必须严格位于边的参数范围内部)。", "Insert curve knot": "插入曲线节点", "Insert surface knot": "插入曲面节点", + "Inset": "内缩", + "Inset face": "内缩面", "Intersect": "相交", "Is frenet": "Frenet 标架", "Join": "合并", diff --git a/editor-web/src/lib/commands.ts b/editor-web/src/lib/commands.ts index 46850fd3..dd54e477 100644 --- a/editor-web/src/lib/commands.ts +++ b/editor-web/src/lib/commands.ts @@ -102,6 +102,7 @@ export const CONTEXT_ACTIONS: Record boolean> = { extrude_face_join: (c) => c.faces === 1 && c.planarFaces === 1 && c.edges === 0 && c.sketches === 0, extrude_face_cut: (c) => c.faces === 1 && c.planarFaces === 1 && c.edges === 0 && c.sketches === 0, shell: (c) => c.faces >= 1 && c.edges === 0 && c.sketches === 0, + inset_face: (c) => c.faces === 1 && c.planarFaces === 1 && c.edges === 0 && c.sketches === 0, fillet: (c) => c.edges >= 1 && c.sketches === 0, chamfer: (c) => c.edges >= 1 && c.sketches === 0, extrude_sketch: (c) => c.sketches === 1, @@ -235,6 +237,7 @@ const SYNONYMS: Record = { fillet: ["round", "rounded", "radius", "edge"], chamfer: ["bevel", "edge"], shell: ["hollow", "thin", "wall"], + inset_face: ["offset", "outline", "loop", "imprint", "step", "boss", "inset"], linear_pattern: ["array", "copies", "repeat", "row"], radial_pattern: ["array", "circular", "polar", "copies", "repeat"], mirror: ["flip", "symmetry", "reflect"], diff --git a/src/cpp/bindings/python/bind_ops_features.cpp b/src/cpp/bindings/python/bind_ops_features.cpp index dbfc7e27..969fa1d8 100644 --- a/src/cpp/bindings/python/bind_ops_features.cpp +++ b/src/cpp/bindings/python/bind_ops_features.cpp @@ -446,6 +446,15 @@ void bind_derived(py::module_& m) { py::arg("plane_normal") = unit_z(), "Draft planar, cylindrical or conical faces by a signed angle in degrees about a neutral plane."); + m.def( + "inset_face_rsolid", + [](const Solid& solid, const FacesOrQuery& face, const Length& distance) { + const FaceSelection selection = selection_from(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) { diff --git a/src/cpp/include/scad/ops/features/blends.hpp b/src/cpp/include/scad/ops/features/blends.hpp index 6208595c..58c1918f 100644 --- a/src/cpp/include/scad/ops/features/blends.hpp +++ b/src/cpp/include/scad/ops/features/blends.hpp @@ -52,4 +52,8 @@ Solid offset_rsolid(const Solid& solid, const Scalar& amount, const FaceSelectio Solid draft_rsolid(const Solid& solid, const FaceSelection& faces_to_draft, const Scalar& angle, const Scalar3& plane_origin = scalar3(0, 0, 0), const Scalar3& plane_normal = scalar3(0, 0, 1)); +// Imprint the loops of one planar face moved `distance` inside it: the face becomes an inner face (role inset.inner) +// and the ring around it (inset.ring); the solid is the same shape. Recorded as make_inset_face_rsolid. +Solid inset_face_rsolid(const Solid& solid, const FaceSelection& face, const Scalar& distance); + } // namespace scad diff --git a/src/cpp/src/ops/features/executors.cpp b/src/cpp/src/ops/features/executors.cpp index 6a547999..d3dcd53d 100644 --- a/src/cpp/src/ops/features/executors.cpp +++ b/src/cpp/src/ops/features/executors.cpp @@ -138,6 +138,9 @@ void register_blends(reactive::ExecutorRegistry& registry) { return one(draft_rsolid(Solid(input(in, 0)), rest(in, 1, in.size()), number(p, "angle"), point(p, "plane_origin"), point(p, "plane_normal"))); }); + registry.add("make_inset_face_rsolid", [](Params p, Inputs in, const ScalarValues&) { + return one(inset_face_rsolid(Solid(input(in, 0)), rest(in, 1, in.size()), number(p, "distance"))); + }); } // ---- booleans ----------------------------------------------------------------------------------- diff --git a/src/cpp/src/ops/features/offsets.cpp b/src/cpp/src/ops/features/offsets.cpp index 6227464f..334badf8 100644 --- a/src/cpp/src/ops/features/offsets.cpp +++ b/src/cpp/src/ops/features/offsets.cpp @@ -1,12 +1,17 @@ -// offset_rsolid, draft_rsolid (operators/features.py). +// offset_rsolid, draft_rsolid, inset_face_rsolid (operators/features.py). #include #include +#include +#include #include #include #include #include #include +#include +#include #include +#include #include #include @@ -15,6 +20,7 @@ #include "internal.hpp" #include "scad/core/tolerance.hpp" #include "scad/kernel/convert.hpp" +#include "scad/kernel/topology.hpp" #include "scad/ops/features/blends.hpp" #include "scad/semantic/tracking.hpp" @@ -135,4 +141,126 @@ Solid draft_rsolid(const Solid& solid, const FaceSelection& faces_to_draft, cons return finish_solid(solid, built, std::move(rec).take(), std::move(delta)); } +namespace { + +// A kernel-proven role of one face of the result (as the surface operations record theirs). +TopoRoleEntry face_role(const TopoDS_Shape& face, const char* role, const char* method) { + TopoRoleEntry entry; + entry.ref.kind = Kind::Face; + entry.ref.topo_id = kernel_topo_id(face); + entry.role = role; + entry.metadata = Value::object(); + entry.metadata.set("coverage", "complete"); + entry.metadata.set("status", "proven"); + entry.metadata.set("evidence_kind", "kernel_operation_role"); + entry.metadata.set("evidence_method", method); + return entry; +} + +// The role written on the face itself as well (its `track` metadata): what the output-role selectors and the replay +// check read. +void stamp_face_role(Solid& result, const TopoDS_Shape& piece, const char* role) { + for (Face face : result.faces()) { + if (!face.wrapped().IsSame(piece)) + continue; + Value track = face.get_metadata("track", Value::object()); + if (!track.is_object()) + track = Value::object(); + Value roles = Value::array(); + roles.push_back(std::string(role)); + track.set("op", "make_inset_face_rsolid"); + track.set("topo_id", kernel_topo_id(piece)); + track.set("kind", "FACE"); + track.set("coverage", "complete"); + track.set("status", "proven"); + track.set("result_roles", std::move(roles)); + face.set_metadata("track", std::move(track)); + } +} + +} // namespace + +Solid inset_face_rsolid(const Solid& solid, const FaceSelection& face, const Scalar& distance) { + const double inset = evaluate_finite(distance); + if (!std::isfinite(inset) || inset <= 0) + throw ValueError("distance must be finite and positive: how far inside the face the loop runs"); + const std::vector resolved = face.resolve(solid); + if (resolved.size() != 1) + throw ValueError("inset_face takes exactly one face, got " + std::to_string(resolved.size())); + const Face target = resolved.front(); + const std::vector own_faces = solid.faces(); + if (std::none_of(own_faces.begin(), own_faces.end(), [&](const Face& f) { return f.wrapped().IsSame(target.wrapped()); })) + throw ValueError("the face must belong to the input solid"); + const TopoDS_Face source = TopoDS::Face(target.wrapped()); + if (occt_guard([&] { return BRepAdaptor_Surface(source).GetType(); }) != GeomAbs_Plane) + throw ValueError("inset_face needs a planar face"); + + BRepTools_History history; + std::vector inner, ring; + const TopoDS_Shape built = occt_guard([&]() -> TopoDS_Shape { + // every loop of the face (its outline and its holes) moved inside it by `inset`, in its plane + BRepOffsetAPI_MakeOffset offsetter(source, GeomAbs_Intersection); + offsetter.Perform(-inset); + if (!offsetter.IsDone()) + throw ValueError("the inset does not fit in the face: the loop collapses at this distance"); + const std::vector loops = kernel::wires_of(offsetter.Shape()); + if (loops.empty()) + throw ValueError("the inset does not fit in the face: nothing is left inside it at this distance"); + BRepFeat_SplitShape splitter(solid.wrapped()); + for (const TopoDS_Wire& loop : loops) + splitter.Add(loop, source); + splitter.Build(); + if (!splitter.IsDone()) + throw ValueError("kernel could not imprint the inset loop on the face"); + TopTools_ListOfShape input; + input.Append(solid.wrapped()); + history = BRepTools_History(input, splitter); + // the piece bounded by the offset loops alone is the inner face; a piece that keeps an edge of the face's own + // outline is the ring + TopTools_IndexedMapOfShape outline; + TopExp::MapShapes(source, TopAbs_EDGE, outline); + TopTools_IndexedMapOfShape kept; + for (int i = 1; i <= outline.Extent(); ++i) { + const TopTools_ListOfShape& images = history.Modified(outline(i)); + if (images.IsEmpty() && !history.IsRemoved(outline(i))) + kept.Add(outline(i)); + for (TopTools_ListIteratorOfListOfShape it(images); it.More(); it.Next()) + kept.Add(it.Value()); + } + for (TopTools_ListIteratorOfListOfShape it(history.Modified(source)); it.More(); it.Next()) { + TopTools_IndexedMapOfShape edges; + TopExp::MapShapes(it.Value(), TopAbs_EDGE, edges); + bool touches = false; + for (int i = 1; i <= edges.Extent() && !touches; ++i) + touches = kept.Contains(edges(i)); + (touches ? ring : inner).push_back(it.Value()); + } + if (inner.empty() || ring.empty()) + throw ValueError("the inset loop did not split the face"); + return splitter.Shape(); + }); + + FeatureRecord rec("make_inset_face_rsolid"); + rec.scalar("distance", distance); + rec.param("selected_face_count", Value(static_cast(1))); + if (rec.recording()) { + const PickParams picks = capture_picks(solid, std::vector{target}, solid.faces(), /*refs_first=*/false); + picks.apply_refs(rec, "selected_faces"); + picks.apply_ids(rec, "selected_face_node_ids", {}); + } + rec.input(solid, "body").inputs(std::vector{target}, "face"); + // the face is split in two pieces (fragments of it); the kernel says which is which + TopoDelta delta = modification_delta(history, solid.wrapped(), built, "fragment"); + for (const TopoDS_Shape& piece : inner) + delta.roles.push_back(face_role(piece, "inset.inner", "OffsetLoopInterior")); + for (const TopoDS_Shape& piece : ring) + delta.roles.push_back(face_role(piece, "inset.ring", "OffsetLoopExterior")); + Solid result = finish_solid(solid, built, std::move(rec).take(), std::move(delta)); + for (const TopoDS_Shape& piece : inner) + stamp_face_role(result, piece, "inset.inner"); + for (const TopoDS_Shape& piece : ring) + stamp_face_role(result, piece, "inset.ring"); + return result; +} + } // namespace scad diff --git a/src/simplecadapi/__init__.py b/src/simplecadapi/__init__.py index 3e41db85..11a9253a 100644 --- a/src/simplecadapi/__init__.py +++ b/src/simplecadapi/__init__.py @@ -184,6 +184,7 @@ from simplecadapi._cpp import ( cut_rsolid, cut_rsolid_list, draft_rsolid, + inset_face_rsolid, extrude_rsolid, extrude_taper_rsolid, extrude_until_rsolid, @@ -727,6 +728,7 @@ __all__ = [ "translate_shape", # 3D operations "draft_rsolid", + "inset_face_rsolid", "extrude_rsolid", "extrude_taper_rsolid", "extrude_until_rsolid", diff --git a/src/simplecadapi/_cpp/_native/__init__.pyi b/src/simplecadapi/_cpp/_native/__init__.pyi index 0ce990cc..0f86ddc4 100644 --- a/src/simplecadapi/_cpp/_native/__init__.pyi +++ b/src/simplecadapi/_cpp/_native/__init__.pyi @@ -40,6 +40,7 @@ from simplecadapi.operators.boolean import make_2d_union_rface from simplecadapi.operators.boolean import union_rsolid from simplecadapi.operators.features import chamfer_rsolid from simplecadapi.operators.features import draft_rsolid +from simplecadapi.operators.features import inset_face_rsolid from simplecadapi.operators.features import extrude_rsolid from simplecadapi.operators.features import extrude_taper_rsolid from simplecadapi.operators.features import extrude_until_rsolid @@ -346,7 +347,7 @@ import numpy.typing import simplecadapi.core import simplecadapi.params.units import typing -__all__: list[str] = ['ANGLE', 'AREA', 'AnyShape', 'Assembly', 'BSplineFitResult', 'BlendDiagnosis', 'Body', 'BooleanDiagnosis', 'CM', 'CUBIC_CM', 'CUBIC_FOOT', 'CUBIC_INCH', 'CUBIC_M', 'CUBIC_MM', 'Component', 'Compound', 'Connector', 'ConnectorAnchor', 'ConnectorRef', 'Const', 'Constraint', 'ConstraintReport', 'ConstraintResidual', 'CoordinateSystem', 'DEGREE', 'DIMENSIONLESS', 'Dimension', 'DimensionTolerance', 'Edge', 'ExecutorRegistry', 'Expr', 'ExprBase', 'ExpressionGraph', 'FOOT', 'Face', 'FrameGraph', 'FrameNode', 'GeometryRef', 'GraphSession', 'INCH', 'LENGTH', 'LineageDerivation', 'LineagePolicy', 'M', 'MM', 'Material', 'Mesh', 'NodeFailure', 'ONE', 'OperationGraph', 'OperationNode', 'PERCENT', 'Part', 'Placement', 'PublicConnectorRef', 'RADIAN', 'RecomputeReport', 'RenderFrame', 'RenderPanel', 'RenderScene', 'SQUARE_CM', 'SQUARE_FOOT', 'SQUARE_INCH', 'SQUARE_M', 'SQUARE_MM', 'ScalarLimit', 'SemanticDelta', 'SemanticRef', 'Shell', 'SimpleWorkplane', 'Sketch', 'SketchConstraint', 'SketchConstraintDiagnostic', 'SketchEntity', 'SketchRef', 'SketchSolveResult', 'SketchSolverBackend', 'SketchSolverOptions', 'Solid', 'StaleLineageError', 'SurfaceBoundary', 'SurfaceFillingSettings', 'TagAttachment', 'TagBinding', 'TagBindingScope', 'TagCertainty', 'TagEvidence', 'TagEvidenceKind', 'TagLifecycle', 'TagLineageWitness', 'TagPolicy', 'TagProducer', 'TagProducerKind', 'TagPropagation', 'TagScope', 'TagTarget', 'TagTargetKind', 'TopologyPropagation', 'TrackingPolicy', 'Unit', 'UnitValidationError', 'VOLUME', 'Var', 'Vec3', 'Vertex', 'WORLD_CS', 'Wire', 'Workplane', 'acos', 'add_arc_rsketch', 'add_belt_constraint_rassembly', 'add_bspline_rsketch', 'add_circle_rsketch', 'add_component_rassembly', 'add_connector_rpart', 'add_ellipse_rsketch', 'add_fixed_constraint_rassembly', 'add_gear_constraint_rassembly', 'add_line_rsketch', 'add_point_rsketch', 'add_prismatic_constraint_rassembly', 'add_rack_pinion_constraint_rassembly', 'add_revolute_constraint_rassembly', 'apply_tag', 'apply_tag_rselection', 'asin', 'assert_blend_volume_monotonic', 'assign_material_rpart', 'atan', 'atan2', 'boolean_rsolidlist', 'canonical_brep_bytes', 'canonical_bytes', 'canonical_hash', 'canonical_unit_for_dimension', 'canonicalize_params', 'chamfer_corner_rsketch', 'chamfer_rsolid', 'clone_semantic_view', 'const', 'constrain_angle_rsketch', 'constrain_coincident_rsketch', 'constrain_collinear_rsketch', 'constrain_concentric_rsketch', 'constrain_connect_rsketch', 'constrain_diameter_rsketch', 'constrain_distance_rsketch', 'constrain_distance_x_rsketch', 'constrain_distance_y_rsketch', 'constrain_equal_length_rsketch', 'constrain_equal_radius_rsketch', 'constrain_fix_rsketch', 'constrain_horizontal_rsketch', 'constrain_length_rsketch', 'constrain_line_distance_rsketch', 'constrain_major_radius_rsketch', 'constrain_midpoint_points_rsketch', 'constrain_midpoint_rsketch', 'constrain_minor_radius_rsketch', 'constrain_mirror_rsketch', 'constrain_normal_rsketch', 'constrain_parallel_rsketch', 'constrain_perpendicular_rsketch', 'constrain_point_on_rsketch', 'constrain_points_horizontal_rsketch', 'constrain_points_vertical_rsketch', 'constrain_radius_rsketch', 'constrain_symmetric_rsketch', 'constrain_tangent_rsketch', 'constrain_vertical_rsketch', 'constraint_reports_match', 'convert_spline_to_anchors_rsketch', 'convert_to_bspline_redge', 'convert_to_bspline_rface', 'convert_value', 'cos', 'create_angle_arc', 'create_angle_arc_wire', 'create_arc', 'create_arc_wire', 'create_box', 'create_circle_edge', 'create_circle_face', 'create_circle_wire', 'create_cylinder', 'create_face_from_wire', 'create_face_from_wires', 'create_helix', 'create_helix_wire', 'create_interpolated_spline', 'create_interpolated_spline_wire', 'create_line', 'create_periodic_spline_wire', 'create_point', 'create_polyline_wire', 'create_rectangle_face', 'create_rectangle_wire', 'create_segment', 'create_segment_wire', 'create_sphere', 'create_spline', 'create_spline_wire', 'create_wire_from_edges', 'current_tracking_policy', 'cut_rsolid', 'cut_rsolid_list', 'deserialize_shape', 'diagnose_blend_failure', 'diagnose_boolean_failure', 'diff_sketch_rsketchdiff', 'draft_rsolid', 'elevate_curve_degree_redge', 'elevate_surface_degree_rface', 'evaluate_scalar', 'evaluate_value', 'explain_tag', 'explode_rassembly', 'export_brep', 'export_glb', 'export_obj', 'export_step', 'export_step_assembly', 'export_stl', 'expression_uses_units', 'extend_rsketch', 'extrude_rsolid', 'extrude_taper_rsolid', 'extrude_until_rsolid', 'fill_holes_rshell', 'fillet_corner_rsketch', 'fillet_rsolid', 'find_registered_node', 'fit_cubic_bspline_control_points', 'fit_point_grid_rface', 'forget_graph_nodes', 'free_boundaries_rwirelist', 'from_brep', 'get_active_session', 'get_current_cs', 'get_current_frame_source', 'get_default_sketch_solver_backend', 'get_sketch_entity_rsketchref', 'get_sketch_point_rsketchref', 'get_sketch_solver_backend', 'get_unit', 'global_executor_registry', 'ground_component_rassembly', 'helical_sweep_rsolid', 'identity_placement_rplacement', 'import_brep', 'import_step', 'import_stl', 'import_stl_shape', 'infer_dimension', 'insert_curve_knot_redge', 'insert_spline_anchor_rsketch', 'insert_surface_knot_rface', 'inspect_assembly_constraints', 'inspect_assembly_constraints_rconstraintreport', 'inspect_curve_rcurvedata', 'inspect_sketch_rsketchcrossings', 'inspect_sketch_rsketchprofiles', 'inspect_sketch_rsketchresult', 'inspect_surface_rsurfacedata', 'intersect_rsolid', 'isolated_recording', 'lift_scalar', 'linear_pattern_rsolidlist', 'list_tag_splits', 'list_tags', 'load_brep_region_rshell', 'load_brep_region_rsolid', 'loft_rshell', 'loft_rsolid', 'make_2d_cut_rface', 'make_2d_intersect_rface', 'make_2d_union_rface', 'make_angle_arc_redge', 'make_angle_arc_rwire', 'make_assembly_rassembly', 'make_bezier_surface_rface', 'make_box_rsolid', 'make_circle_redge', 'make_circle_rface', 'make_circle_rwire', 'make_compound_from_assembly_rcompound', 'make_cone_rsolid', 'make_connector_ref_rconnectorref', 'make_cylinder_rsolid', 'make_cylindrical_surface_rface', 'make_edge_connector_rconnector', 'make_ellipse_redge', 'make_ellipse_rface', 'make_ellipse_rwire', 'make_face_connector_rconnector', 'make_face_from_sketch_rface', 'make_face_from_wire_rface', 'make_face_from_wires_rface', 'make_faces_from_sketch_rfacelist', 'make_gordon_surface_rface', 'make_helix_redge', 'make_helix_rwire', 'make_interpolated_spline_redge', 'make_interpolated_spline_rwire', 'make_line_redge', 'make_material_rmaterial', 'make_param_spec', 'make_part_rpart', 'make_periodic_spline_rwire', 'make_placement_connector_rconnector', 'make_placement_rplacement', 'make_point_rvertex', 'make_polyline_rwire', 'make_rectangle_rface', 'make_rectangle_rwire', 'make_ruled_surface_rface', 'make_scalar_limit_rscalarlimit', 'make_segment_redge', 'make_segment_rwire', 'make_sketch_rsketch', 'make_solid_from_shell_rsolid', 'make_sphere_rsolid', 'make_spline_redge', 'make_spline_rwire', 'make_surface_patch_rface', 'make_three_point_arc_redge', 'make_three_point_arc_rwire', 'make_vertex_connector_rconnector', 'make_wire_from_edges_rwire', 'make_wire_from_sketch_rwire', 'make_workplane_from_axis_rworkplane', 'make_workplane_from_face_rworkplane', 'make_workplane_from_points_rworkplane', 'make_workplane_midplane_rworkplane', 'make_workplane_normal_to_curve_rworkplane', 'make_workplane_offset_rworkplane', 'make_workplane_rworkplane', 'math', 'measure_constraint_residual_rconstraintresidual', 'mesh', 'mirror_shape', 'move_curve_poles_redge', 'move_surface_poles_rface', 'offset_rsolid', 'parse_ui_comment', 'place_component_rassembly', 'project_rsketch', 'ql', 'radial_pattern_rsolidlist', 'raise_loft_failure_if_diagnosed', 'rebuild_curve_redge', 'rebuild_surface_rface', 'record_operation_if_active', 'recording_active', 'referenced_expressions', 'register_executor', 'register_graph_nodes', 'register_node', 'register_sketch_solver_backend', 'remove_spline_anchor_rsketch', 'render_auto_view', 'render_default_threads', 'render_edge_polylines', 'render_scene', 'render_view_preset', 'resolve_connector', 'resolve_connector_placement', 'resolve_connector_ref_placement', 'resolve_item_connector', 'resolve_item_connector_placement', 'revolve_rsolid', 'rotate_shape', 'same_node_content', 'sample_curve_rcurvature', 'sample_surface_risocurves', 'scale_rsolid', 'select_edges_by_tag', 'select_faces_by_tag', 'serialize_shape', 'set_body_appearance_rpart', 'set_curve_poles_redge', 'set_curve_weights_redge', 'set_default_sketch_solver_backend', 'set_producer_version', 'set_public_connector_rassembly', 'set_surface_poles_rface', 'set_surface_weights_rface', 'sew_faces_rshell', 'shell_rsolid', 'sin', 'sketch_solver_backend', 'solve_assembly_constraints', 'solve_assembly_constraints_rassembly', 'sqrt', 'std', 'step_bytes', 'surface', 'suspend_graph_recording', 'sweep_multisection_rsolid', 'sweep_rsolid', 'tagging', 'tan', 'tessellate_solid', 'tracking_policy_scope', 'transform_rsolid', 'translate_shape', 'trim_rsketch', 'trim_surface_rface', 'twisted_sweep_rsolid', 'unground_component_rassembly', 'union_rsolid', 'unit_from_payload', 'unit_to_payload', 'upstream_closure', 'use_coordinate_system', 'var'] +__all__: list[str] = ['ANGLE', 'AREA', 'AnyShape', 'Assembly', 'BSplineFitResult', 'BlendDiagnosis', 'Body', 'BooleanDiagnosis', 'CM', 'CUBIC_CM', 'CUBIC_FOOT', 'CUBIC_INCH', 'CUBIC_M', 'CUBIC_MM', 'Component', 'Compound', 'Connector', 'ConnectorAnchor', 'ConnectorRef', 'Const', 'Constraint', 'ConstraintReport', 'ConstraintResidual', 'CoordinateSystem', 'DEGREE', 'DIMENSIONLESS', 'Dimension', 'DimensionTolerance', 'Edge', 'ExecutorRegistry', 'Expr', 'ExprBase', 'ExpressionGraph', 'FOOT', 'Face', 'FrameGraph', 'FrameNode', 'GeometryRef', 'GraphSession', 'INCH', 'LENGTH', 'LineageDerivation', 'LineagePolicy', 'M', 'MM', 'Material', 'Mesh', 'NodeFailure', 'ONE', 'OperationGraph', 'OperationNode', 'PERCENT', 'Part', 'Placement', 'PublicConnectorRef', 'RADIAN', 'RecomputeReport', 'RenderFrame', 'RenderPanel', 'RenderScene', 'SQUARE_CM', 'SQUARE_FOOT', 'SQUARE_INCH', 'SQUARE_M', 'SQUARE_MM', 'ScalarLimit', 'SemanticDelta', 'SemanticRef', 'Shell', 'SimpleWorkplane', 'Sketch', 'SketchConstraint', 'SketchConstraintDiagnostic', 'SketchEntity', 'SketchRef', 'SketchSolveResult', 'SketchSolverBackend', 'SketchSolverOptions', 'Solid', 'StaleLineageError', 'SurfaceBoundary', 'SurfaceFillingSettings', 'TagAttachment', 'TagBinding', 'TagBindingScope', 'TagCertainty', 'TagEvidence', 'TagEvidenceKind', 'TagLifecycle', 'TagLineageWitness', 'TagPolicy', 'TagProducer', 'TagProducerKind', 'TagPropagation', 'TagScope', 'TagTarget', 'TagTargetKind', 'TopologyPropagation', 'TrackingPolicy', 'Unit', 'UnitValidationError', 'VOLUME', 'Var', 'Vec3', 'Vertex', 'WORLD_CS', 'Wire', 'Workplane', 'acos', 'add_arc_rsketch', 'add_belt_constraint_rassembly', 'add_bspline_rsketch', 'add_circle_rsketch', 'add_component_rassembly', 'add_connector_rpart', 'add_ellipse_rsketch', 'add_fixed_constraint_rassembly', 'add_gear_constraint_rassembly', 'add_line_rsketch', 'add_point_rsketch', 'add_prismatic_constraint_rassembly', 'add_rack_pinion_constraint_rassembly', 'add_revolute_constraint_rassembly', 'apply_tag', 'apply_tag_rselection', 'asin', 'assert_blend_volume_monotonic', 'assign_material_rpart', 'atan', 'atan2', 'boolean_rsolidlist', 'canonical_brep_bytes', 'canonical_bytes', 'canonical_hash', 'canonical_unit_for_dimension', 'canonicalize_params', 'chamfer_corner_rsketch', 'chamfer_rsolid', 'clone_semantic_view', 'const', 'constrain_angle_rsketch', 'constrain_coincident_rsketch', 'constrain_collinear_rsketch', 'constrain_concentric_rsketch', 'constrain_connect_rsketch', 'constrain_diameter_rsketch', 'constrain_distance_rsketch', 'constrain_distance_x_rsketch', 'constrain_distance_y_rsketch', 'constrain_equal_length_rsketch', 'constrain_equal_radius_rsketch', 'constrain_fix_rsketch', 'constrain_horizontal_rsketch', 'constrain_length_rsketch', 'constrain_line_distance_rsketch', 'constrain_major_radius_rsketch', 'constrain_midpoint_points_rsketch', 'constrain_midpoint_rsketch', 'constrain_minor_radius_rsketch', 'constrain_mirror_rsketch', 'constrain_normal_rsketch', 'constrain_parallel_rsketch', 'constrain_perpendicular_rsketch', 'constrain_point_on_rsketch', 'constrain_points_horizontal_rsketch', 'constrain_points_vertical_rsketch', 'constrain_radius_rsketch', 'constrain_symmetric_rsketch', 'constrain_tangent_rsketch', 'constrain_vertical_rsketch', 'constraint_reports_match', 'convert_spline_to_anchors_rsketch', 'convert_to_bspline_redge', 'convert_to_bspline_rface', 'convert_value', 'cos', 'create_angle_arc', 'create_angle_arc_wire', 'create_arc', 'create_arc_wire', 'create_box', 'create_circle_edge', 'create_circle_face', 'create_circle_wire', 'create_cylinder', 'create_face_from_wire', 'create_face_from_wires', 'create_helix', 'create_helix_wire', 'create_interpolated_spline', 'create_interpolated_spline_wire', 'create_line', 'create_periodic_spline_wire', 'create_point', 'create_polyline_wire', 'create_rectangle_face', 'create_rectangle_wire', 'create_segment', 'create_segment_wire', 'create_sphere', 'create_spline', 'create_spline_wire', 'create_wire_from_edges', 'current_tracking_policy', 'cut_rsolid', 'cut_rsolid_list', 'deserialize_shape', 'diagnose_blend_failure', 'diagnose_boolean_failure', 'diff_sketch_rsketchdiff', 'draft_rsolid', 'inset_face_rsolid', 'elevate_curve_degree_redge', 'elevate_surface_degree_rface', 'evaluate_scalar', 'evaluate_value', 'explain_tag', 'explode_rassembly', 'export_brep', 'export_glb', 'export_obj', 'export_step', 'export_step_assembly', 'export_stl', 'expression_uses_units', 'extend_rsketch', 'extrude_rsolid', 'extrude_taper_rsolid', 'extrude_until_rsolid', 'fill_holes_rshell', 'fillet_corner_rsketch', 'fillet_rsolid', 'find_registered_node', 'fit_cubic_bspline_control_points', 'fit_point_grid_rface', 'forget_graph_nodes', 'free_boundaries_rwirelist', 'from_brep', 'get_active_session', 'get_current_cs', 'get_current_frame_source', 'get_default_sketch_solver_backend', 'get_sketch_entity_rsketchref', 'get_sketch_point_rsketchref', 'get_sketch_solver_backend', 'get_unit', 'global_executor_registry', 'ground_component_rassembly', 'helical_sweep_rsolid', 'identity_placement_rplacement', 'import_brep', 'import_step', 'import_stl', 'import_stl_shape', 'infer_dimension', 'insert_curve_knot_redge', 'insert_spline_anchor_rsketch', 'insert_surface_knot_rface', 'inspect_assembly_constraints', 'inspect_assembly_constraints_rconstraintreport', 'inspect_curve_rcurvedata', 'inspect_sketch_rsketchcrossings', 'inspect_sketch_rsketchprofiles', 'inspect_sketch_rsketchresult', 'inspect_surface_rsurfacedata', 'intersect_rsolid', 'isolated_recording', 'lift_scalar', 'linear_pattern_rsolidlist', 'list_tag_splits', 'list_tags', 'load_brep_region_rshell', 'load_brep_region_rsolid', 'loft_rshell', 'loft_rsolid', 'make_2d_cut_rface', 'make_2d_intersect_rface', 'make_2d_union_rface', 'make_angle_arc_redge', 'make_angle_arc_rwire', 'make_assembly_rassembly', 'make_bezier_surface_rface', 'make_box_rsolid', 'make_circle_redge', 'make_circle_rface', 'make_circle_rwire', 'make_compound_from_assembly_rcompound', 'make_cone_rsolid', 'make_connector_ref_rconnectorref', 'make_cylinder_rsolid', 'make_cylindrical_surface_rface', 'make_edge_connector_rconnector', 'make_ellipse_redge', 'make_ellipse_rface', 'make_ellipse_rwire', 'make_face_connector_rconnector', 'make_face_from_sketch_rface', 'make_face_from_wire_rface', 'make_face_from_wires_rface', 'make_faces_from_sketch_rfacelist', 'make_gordon_surface_rface', 'make_helix_redge', 'make_helix_rwire', 'make_interpolated_spline_redge', 'make_interpolated_spline_rwire', 'make_line_redge', 'make_material_rmaterial', 'make_param_spec', 'make_part_rpart', 'make_periodic_spline_rwire', 'make_placement_connector_rconnector', 'make_placement_rplacement', 'make_point_rvertex', 'make_polyline_rwire', 'make_rectangle_rface', 'make_rectangle_rwire', 'make_ruled_surface_rface', 'make_scalar_limit_rscalarlimit', 'make_segment_redge', 'make_segment_rwire', 'make_sketch_rsketch', 'make_solid_from_shell_rsolid', 'make_sphere_rsolid', 'make_spline_redge', 'make_spline_rwire', 'make_surface_patch_rface', 'make_three_point_arc_redge', 'make_three_point_arc_rwire', 'make_vertex_connector_rconnector', 'make_wire_from_edges_rwire', 'make_wire_from_sketch_rwire', 'make_workplane_from_axis_rworkplane', 'make_workplane_from_face_rworkplane', 'make_workplane_from_points_rworkplane', 'make_workplane_midplane_rworkplane', 'make_workplane_normal_to_curve_rworkplane', 'make_workplane_offset_rworkplane', 'make_workplane_rworkplane', 'math', 'measure_constraint_residual_rconstraintresidual', 'mesh', 'mirror_shape', 'move_curve_poles_redge', 'move_surface_poles_rface', 'offset_rsolid', 'parse_ui_comment', 'place_component_rassembly', 'project_rsketch', 'ql', 'radial_pattern_rsolidlist', 'raise_loft_failure_if_diagnosed', 'rebuild_curve_redge', 'rebuild_surface_rface', 'record_operation_if_active', 'recording_active', 'referenced_expressions', 'register_executor', 'register_graph_nodes', 'register_node', 'register_sketch_solver_backend', 'remove_spline_anchor_rsketch', 'render_auto_view', 'render_default_threads', 'render_edge_polylines', 'render_scene', 'render_view_preset', 'resolve_connector', 'resolve_connector_placement', 'resolve_connector_ref_placement', 'resolve_item_connector', 'resolve_item_connector_placement', 'revolve_rsolid', 'rotate_shape', 'same_node_content', 'sample_curve_rcurvature', 'sample_surface_risocurves', 'scale_rsolid', 'select_edges_by_tag', 'select_faces_by_tag', 'serialize_shape', 'set_body_appearance_rpart', 'set_curve_poles_redge', 'set_curve_weights_redge', 'set_default_sketch_solver_backend', 'set_producer_version', 'set_public_connector_rassembly', 'set_surface_poles_rface', 'set_surface_weights_rface', 'sew_faces_rshell', 'shell_rsolid', 'sin', 'sketch_solver_backend', 'solve_assembly_constraints', 'solve_assembly_constraints_rassembly', 'sqrt', 'std', 'step_bytes', 'surface', 'suspend_graph_recording', 'sweep_multisection_rsolid', 'sweep_rsolid', 'tagging', 'tan', 'tessellate_solid', 'tracking_policy_scope', 'transform_rsolid', 'translate_shape', 'trim_rsketch', 'trim_surface_rface', 'twisted_sweep_rsolid', 'unground_component_rassembly', 'union_rsolid', 'unit_from_payload', 'unit_to_payload', 'upstream_closure', 'use_coordinate_system', 'var'] class AnyShape: """ Tag mixin that provides tagging support for geometry objects. diff --git a/src/simplecadapi/_glue/docstrings.json b/src/simplecadapi/_glue/docstrings.json index c2bb6593..d6bb5565 100644 --- a/src/simplecadapi/_glue/docstrings.json +++ b/src/simplecadapi/_glue/docstrings.json @@ -377,5 +377,6 @@ "make_workplane_midplane_rworkplane": "Create the workplane halfway between two parallel planar faces (a symmetry plane).\n\nnormal and x come from ``face_a``; origin = the middle between the centre of ``face_a`` and its projection onto the\nplane of ``face_b``.\n\nRecorded: the node takes the inputs as ordered references, so a model-JSON replay builds the frame again from the\ngeometry as it is then, and a sketch on the workplane (``plane=wp``) or an operation inside ``with wp:`` follows it.\n\nArgs:\n face_a: A planar Face; it gives the normal and x.\n face_b: A planar Face parallel to it.\n\nReturns:\n SimpleWorkplane: a frame in world coordinates (``origin``, ``normal``, ``x_dir``, ``y_dir``, ``plane``) that is\n also a context manager: ``with wp:`` makes it the current coordinate system, ``make_sketch_rsketch(plane=wp)``\n draws on it. It is a value: enter it again in later code, pickle it (the notebook cell cache does).\n\nRaises:\n SimpleCADError: A face is not planar or the faces are not parallel.\n\nUsage:\n ``mid = scad.make_workplane_midplane_rworkplane(left_wall, right_wall)``; mirror or sketch on it.\n", "make_workplane_normal_to_curve_rworkplane": "Create a workplane normal to a curve: the plane of a sweep profile.\n\norigin = the point at ``at`` (a fraction of the curve's length: 0 = start, 1 = end); normal = the direction of\ntravel there; x = ``x_dir`` projected onto the plane, or global Z made square to the normal (global X when the\ntangent is near Z).\n\nRecorded: the node takes the inputs as ordered references, so a model-JSON replay builds the frame again from the\ngeometry as it is then, and a sketch on the workplane (``plane=wp``) or an operation inside ``with wp:`` follows it.\n\nArgs:\n curve: An Edge or a Wire (the sweep path).\n at: The fraction of the length, in [0, 1].\n x_dir: The direction of x, projected onto the plane.\n\nReturns:\n SimpleWorkplane: a frame in world coordinates (``origin``, ``normal``, ``x_dir``, ``y_dir``, ``plane``) that is\n also a context manager: ``with wp:`` makes it the current coordinate system, ``make_sketch_rsketch(plane=wp)``\n draws on it. It is a value: enter it again in later code, pickle it (the notebook cell cache does).\n\nRaises:\n SimpleCADError: ``at`` is outside [0, 1], the curve has no length, or ``x_dir`` is along the tangent.\n\nUsage:\n ``start = scad.make_workplane_normal_to_curve_rworkplane(path, 0)``;\n ``profile = ... make_sketch_rsketch(\"profile\", plane=start) ...``; ``sweep_rsolid(profile, path)``.\n", "list_tag_splits": "The tagged entities that the operations behind a shape split into pieces.\n\nA tag follows its entity the way a reference does: while the entity stays one entity it keeps the tag; when an\noperation splits it (a slot cut across a tagged face, a cut through a tagged body), the tag does not go to every\npiece. Each piece carries ``.split1`` .. ``.split`` instead, numbered as the operation recorded them (by\ncentre, then size), and ``ql.tag(\"\")`` finds none of them. Name the pieces you mean with tags of your own after the\nsplit, or select them with ``ql.tag(\".split1\")`` / ``ql.tag(\".*\")``.\n\nArgs:\n shape: A shape made in a recording session (its history is read).\n\nReturns:\n list[dict]: One row per split, upstream first: ``tag`` (the tag the entity had), ``into`` (the tags of the pieces,\n in piece order), ``node_id`` and ``op`` (the operation that split it), ``source_topo_id`` and ``pieces``\n (``output_slot``, ``kind``, ``topo_id`` of each piece in that operation's output). Empty for a shape without\n recorded history.\n\nExamples:\n >>> top = scad.apply_tag_rselection(box, scad.ql.faces().where(scad.ql.prop(\"geom.center.z\", \">=\", 9.9)), \"mount.top\")\n >>> halves = scad.cut_rsolid(top, slot) # the slot splits the top face (and the body)\n >>> [row[\"into\"] for row in scad.list_tag_splits(halves[0])]\n [['mount.top.split1', 'mount.top.split2']]", - "make_workplane_offset_rworkplane": "Create a workplane moved and turned relative to a workplane or a named plane.\n\nThe editor's move and turn handles write this operation: a plane placed by hand on a base, without any model geometry.\n\nArgs:\n base: The plane it is placed on: a workplane value (made by a ``make_workplane_*_rworkplane`` operation, recorded\n as this node's input so the new plane follows it when it moves) or a named plane ``\"XY\"`` / ``\"XZ\"`` / ``\"YZ\"``\n (axes as sketches read them).\n offset: How far the origin moves, ``(dx, dy, dz)`` along the base's own x, y and normal.\n rx, ry, rz: Turns in degrees about the base's own axes, applied in that order, each about the axis as the previous\n turn left it (R = Rx(rx) Ry(ry) Rz(rz) in the base's frame).\n\nReturns:\n SimpleWorkplane: The new frame. Use it as a sketch plane (``plane=wp``) or as a context (``with wp:``).\n\nExamples:\n >>> wp = scad.make_workplane_offset_rworkplane(\"XY\", offset=(0, 0, 20), rx=30)\n >>> lid = scad.make_workplane_offset_rworkplane(wp, offset=(0, 0, 5)) # follows wp" -} + "make_workplane_offset_rworkplane": "Create a workplane moved and turned relative to a workplane or a named plane.\n\nThe editor's move and turn handles write this operation: a plane placed by hand on a base, without any model geometry.\n\nArgs:\n base: The plane it is placed on: a workplane value (made by a ``make_workplane_*_rworkplane`` operation, recorded\n as this node's input so the new plane follows it when it moves) or a named plane ``\"XY\"`` / ``\"XZ\"`` / ``\"YZ\"``\n (axes as sketches read them).\n offset: How far the origin moves, ``(dx, dy, dz)`` along the base's own x, y and normal.\n rx, ry, rz: Turns in degrees about the base's own axes, applied in that order, each about the axis as the previous\n turn left it (R = Rx(rx) Ry(ry) Rz(rz) in the base's frame).\n\nReturns:\n SimpleWorkplane: The new frame. Use it as a sketch plane (``plane=wp``) or as a context (``with wp:``).\n\nExamples:\n >>> wp = scad.make_workplane_offset_rworkplane(\"XY\", offset=(0, 0, 20), rx=30)\n >>> lid = scad.make_workplane_offset_rworkplane(wp, offset=(0, 0, 5)) # follows wp", + "inset_face_rsolid": "Imprint the loops of one planar face moved a distance inside it.\n\nThe outline of the face (and the outline of each of its holes) is offset in\nthe face's plane by ``distance`` towards the inside, and the offset loops are\nimprinted on the solid: the face becomes an inner face and the ring around it\n(a ring around each hole too). The solid keeps its shape and volume; it only\nhas one face more, which the next operation can pull out, push in or open, so\nsteps, bosses and walls are built by insetting and pulling again.\n\nThe operation is recorded as ``make_inset_face_rsolid``; the body and the face\nare ordered inputs and the distance is a parameter, so model JSON replay is\nstrict. The split pieces are fragments of the face (element references and\ntags follow them as a split) and carry the kernel roles ``inset.inner`` and\n``inset.ring``, so ``scad.ref.face(..., role=\"inset.inner\")`` names the inner\nface whatever the face was.\n\nArgs:\n solid: The body whose face is inset.\n face: One planar face of ``solid``, or a QL selector that picks exactly one.\n distance: How far inside the face the loops run, in mm; positive.\n\nReturns:\n The same solid with the face split in its inner face and ring.\n\nRaises:\n TypeError: ``solid`` is not a Solid.\n ValueError: Not exactly one face, a face of another solid, a curved\n face, a non-positive distance, or a distance at which nothing of the\n face is left inside the loops.\n\nExamples:\n import simplecadapi as scad\n ql = scad.ql\n box = scad.make_box_rsolid(40, 30, 20)\n top = ql.faces().where(ql.prop(\"geom.center.z\", \">=\", 19.9)).exactly(1)\n inset = scad.inset_face_rsolid(box, top, 3)\n inner = scad.ref.face(\"\", \"make_inset_face_rsolid\", role=\"inset.inner\").one(inset)\n" +} \ No newline at end of file diff --git a/src/simplecadapi/_glue/modules.json b/src/simplecadapi/_glue/modules.json index 1a26882f..a3e525ac 100644 --- a/src/simplecadapi/_glue/modules.json +++ b/src/simplecadapi/_glue/modules.json @@ -196,6 +196,7 @@ "diff_sketch_rsketchdiff": "simplecadapi.operators.sketch", "distance": "simplecadapi.kernel.ocp_properties", "draft_rsolid": "simplecadapi.operators.features", +"inset_face_rsolid": "simplecadapi.operators.features", "edges": "simplecadapi.ql", "edges_of": "simplecadapi.kernel.ocp_topology", "evaluate_scalar": "simplecadapi.params.expr", diff --git a/src/simplecadapi/_glue/tables.py b/src/simplecadapi/_glue/tables.py index 36de32d4..d731bd2d 100644 --- a/src/simplecadapi/_glue/tables.py +++ b/src/simplecadapi/_glue/tables.py @@ -186,6 +186,7 @@ _OPERATION_OUTPUT_ROLE_CARDINALITY: Dict[str, Tuple[Tuple[str, str], ...]] = { ("revolution.side", "many"), ), _OP_MAKE_FILLET_RSOLID: (("fillet.patch", "many"),), + "make_inset_face_rsolid": (("inset.inner", "one"), ("inset.ring", "many")), _OP_MAKE_CHAMFER_RSOLID: (("chamfer.patch", "many"),), _OP_MAKE_SHELL_RSOLID: ( ("shell.body_face", "many"), diff --git a/src/simplecadapi/editor/features.py b/src/simplecadapi/editor/features.py index 3ab36271..adcc60be 100644 --- a/src/simplecadapi/editor/features.py +++ b/src/simplecadapi/editor/features.py @@ -536,6 +536,10 @@ def _chamfer(c: Context) -> list[str]: return [*c.recipe("edges", "tip"), f"{c.slug} = scad.chamfer_rsolid(solid={c.body('body')}, edges={c.selection('edges')}, distance={c.var('distance')})"] +def _inset_face(c: Context) -> list[str]: + return [*c.recipe("face", "tip"), f"{c.slug} = scad.inset_face_rsolid(solid={c.body('body')}, face={c.selection('face')}, distance={c.var('distance')})"] + + def _shell(c: Context) -> list[str]: return [ *c.recipe("faces", "tip"), @@ -679,6 +683,10 @@ SPECS: tuple[Spec, ...] = ( Spec("extrude_face", "Extrude face", "Features", "build", "solid", "Push a flat face of the body out (or into it) along its normal, without a sketch.", (_BODY(), Slot("face", "Face", "select", entity="face", single=True, help="Pick one flat face of the body."), _enum("direction", "Direction", _FACE_DIRECTIONS, "normal"), _signed("distance", "Distance", 10.0, min=0.001)), _extrude_face), + Spec("inset_face", "Inset face", "Features", "modifier", "solid", + "Imprint the outline of a flat face moved inside it: the face splits into an inner face (pull it out or push it in next) and the ring around it.", + (_BODY(), Slot("face", "Face", "select", entity="face", single=True, help="Pick one flat face of the body."), + _length("distance", "Inset", 1.0)), _inset_face), Spec("fillet", "Fillet", "Features", "modifier", "solid", "Round the picked edges.", (_BODY(), Slot("edges", "Edges", "select", entity="edge"), _length("radius", "Radius", 0.5)), _fillet), Spec("chamfer", "Chamfer", "Features", "modifier", "solid", "Bevel the picked edges.", diff --git a/src/simplecadapi/operators/__init__.py b/src/simplecadapi/operators/__init__.py index 8f6b3b3e..9a5d3b78 100644 --- a/src/simplecadapi/operators/__init__.py +++ b/src/simplecadapi/operators/__init__.py @@ -28,6 +28,7 @@ from simplecadapi._cpp import ( diagnose_blend_failure, diagnose_boolean_failure, draft_rsolid, + inset_face_rsolid, extrude_rsolid, extrude_taper_rsolid, extrude_until_rsolid, @@ -318,6 +319,7 @@ __all__ = [ "diagnostics_dir", "diff_sketch_rsketchdiff", "draft_rsolid", + "inset_face_rsolid", "elevate_curve_degree_redge", "elevate_surface_degree_rface", "explain_tag", diff --git a/src/simplecadapi/operators/features.py b/src/simplecadapi/operators/features.py index 95584fc5..10739017 100644 --- a/src/simplecadapi/operators/features.py +++ b/src/simplecadapi/operators/features.py @@ -20,6 +20,7 @@ from simplecadapi._cpp import ( chamfer_rsolid, diagnose_blend_failure, draft_rsolid, + inset_face_rsolid, extrude_rsolid, extrude_taper_rsolid, extrude_until_rsolid, @@ -56,6 +57,7 @@ __all__ = [ "chamfer_rsolid", "diagnose_blend_failure", "draft_rsolid", + "inset_face_rsolid", "extrude_rsolid", "extrude_taper_rsolid", "extrude_until_rsolid", diff --git a/src/simplecadapi/recording/serializer.py b/src/simplecadapi/recording/serializer.py index 50e871aa..597e3ea1 100644 --- a/src/simplecadapi/recording/serializer.py +++ b/src/simplecadapi/recording/serializer.py @@ -471,6 +471,7 @@ PUBLIC_API_COVERAGE: Dict[str, Dict[str, str]] = { "sweep_multisection_rsolid": {"status": "replayable", "op": "make_sweep_multisection_rsolid"}, "extrude_until_rsolid": {"status": "replayable", "op": "make_extrude_until_rsolid"}, "draft_rsolid": {"status": "replayable", "op": "make_draft_rsolid"}, + "inset_face_rsolid": {"status": "replayable", "op": "make_inset_face_rsolid"}, "mirror_shape": {"status": "replayable", "op": "make_mirror_rshape"}, "extrude_rsolid": {"status": "replayable", "op": "make_extrude_rsolid"}, "revolve_rsolid": {"status": "replayable", "op": "make_revolve_rsolid"}, @@ -703,6 +704,7 @@ CANONICAL_CORE_OP_SET: Tuple[str, ...] = ( "make_sweep_multisection_rsolid", "make_extrude_until_rsolid", "make_draft_rsolid", + "make_inset_face_rsolid", "make_mirror_rshape", "make_cut_rsolid", "make_cut_rsolid_list", @@ -4557,6 +4559,19 @@ def _execute_graph( _store_outputs(node, result) continue + if op_name == "make_inset_face_rsolid": + ctx.require_params(node.node_id, op_name, params, ("distance", "selected_face_count")) + values = _input_outputs(ctx, outputs, node, 0) + if values: + solid = values[0] + faces = _resolve_feature_selection(ctx, node=node, solid=solid, + params=params, kind="face", outputs=outputs) + if ctx.strict and len(faces) != params["selected_face_count"]: + ctx.fail(f"Graph node '{node.node_id}' expected {params['selected_face_count']} inset face, got {len(faces)}") + result = ops.inset_face_rsolid(solid=solid, face=faces, distance=params["distance"]) + _store_outputs(node, result) + continue + if op_name == "make_extrude_until_rsolid": ctx.require_params(node.node_id, op_name, params, ("direction", "until", "target_count")) count = int(params["target_count"]) diff --git a/test/test_inset_face.py b/test/test_inset_face.py new file mode 100644 index 00000000..05aa3a72 --- /dev/null +++ b/test/test_inset_face.py @@ -0,0 +1,68 @@ +"""inset_face_rsolid: a planar face's loops moved inside it are imprinted; the face splits into its inner face and ring.""" + +import pytest +from simplecadapi._cpp.occt.BRepCheck import BRepCheck_Analyzer + +import simplecadapi as s +from simplecadapi import ql +from simplecadapi.recording.graph import GraphSession + +TOP = ql.faces().where(ql.prop("geom.center.z", ">=", 19.9)).where(ql.prop("geom.type", "==", "PLANE")).exactly(1) + + +def _top_pieces(body): + return sorted((face for face in body._iter_faces() if abs(face.get_center().z - 20) < 1e-6 and face._geom_type() == "PLANE"), key=lambda f: f.get_area()) + + +def test_the_face_splits_into_its_inner_face_and_ring_and_the_shape_stays(): + box = s.make_box_rsolid(40, 30, 20) + inset = s.inset_face_rsolid(box, TOP, 3) + assert len(inset._iter_faces()) == 7 + assert inset.get_volume() == pytest.approx(box.get_volume()) + assert [round(face.get_area(), 6) for face in _top_pieces(inset)] == [384, 816] # the ring, then 34 x 24 inside + assert BRepCheck_Analyzer(inset.wrapped).IsValid() + + +def test_a_hole_of_the_face_gets_its_own_ring(): + holed = s.cut_rsolid(s.make_box_rsolid(40, 30, 20), s.make_cylinder_rsolid(4, 50, (0, 0, -5))) + inset = s.inset_face_rsolid(holed, TOP, 2) + areas = [face.get_area() for face in _top_pieces(inset)] + assert areas[0] == pytest.approx(3.14159265 * (6**2 - 4**2), rel=1e-6) # around the hole + assert sum(areas) == pytest.approx(40 * 30 - 3.14159265 * 16, rel=1e-6) + + +def test_the_pieces_carry_kernel_roles_that_name_them_after_a_parameter_change(): + with GraphSession(): + inset = s.inset_face_rsolid(s.make_box_rsolid(40, 30, 20), TOP, 3) + inner = s.ref.face("", "make_inset_face_rsolid", role="inset.inner") + ring = s.ref.face("", "make_inset_face_rsolid", role="inset.ring") + assert inner.one(inset).get_area() == pytest.approx(816) + assert ring.one(inset).get_area() == pytest.approx(384) + assert s.ref.of(inner.one(inset), inset) == inner.__class__.from_dict({**inner.to_dict(), "guard": s.ref.of(inner.one(inset), inset).guard}) + # pull the inner face out: a boss, built on the piece the role names + boss = s.union_rsolid(inset, s.extrude_rsolid(profile=inner.one(inset), direction=(0, 0, 1), distance=5)) + assert boss.get_volume() == pytest.approx(24000 + 816 * 5) + + +def test_the_operation_is_recorded_and_replays(): + with GraphSession() as session: + result = s.inset_face_rsolid(s.make_box_rsolid(40, 30, 20), TOP, 3) + session.capture_result(value=result) + node = next(node for node in session.graph.nodes if node.op == "make_inset_face_rsolid") + assert node.params["distance"] == 3 + assert node.params["selected_face_count"] == 1 + assert len(node.inputs) == 2 + replayed = s.replay_model_json(s.export_model_json(session))[0] + assert len(replayed._iter_faces()) == 7 + + +def test_what_it_refuses(): + box = s.make_box_rsolid(40, 30, 20) + with pytest.raises(ValueError, match="positive"): + s.inset_face_rsolid(box, TOP, 0) + with pytest.raises(ValueError, match="does not fit"): + s.inset_face_rsolid(box, TOP, 20) + with pytest.raises(ValueError, match="exactly one"): + s.inset_face_rsolid(box, ql.faces(), 1) + with pytest.raises(ValueError, match="planar"): + s.inset_face_rsolid(s.make_cylinder_rsolid(5, 10), ql.faces().where(ql.prop("geom.type", "==", "CYLINDER")).exactly(1), 1) diff --git a/test/test_operator_layout.py b/test/test_operator_layout.py index f89ac891..4b80b1f6 100644 --- a/test/test_operator_layout.py +++ b/test/test_operator_layout.py @@ -22,6 +22,7 @@ HOME = { "boolean_rsolidlist": "boolean", "offset_rsolid": "features", "draft_rsolid": "features", + "inset_face_rsolid": "features", "extrude_taper_rsolid": "features", "extrude_until_rsolid": "features", "sweep_multisection_rsolid": "features", diff --git a/test/test_serialization.py b/test/test_serialization.py index a93a47f8..4f0a906c 100644 --- a/test/test_serialization.py +++ b/test/test_serialization.py @@ -381,6 +381,7 @@ class TestCoverageMatrix(unittest.TestCase): "make_sweep_multisection_rsolid", "make_extrude_until_rsolid", "make_draft_rsolid", + "make_inset_face_rsolid", "make_boolean_rsolidlist", "make_cut_rsolid_list", "make_mirror_rshape",