Split

Status: Implemented

Split cuts one or more existing solids with a plane — a world base plane, a datum, or a planar face — or with the analytic carrier surface of a curved face (cylinder, cone, sphere, torus). Each cut body is replaced by up to two pieces.

Walkthrough

Recorded from the running app by BREP_mcp/tests/videos/split.json; regenerate every walkthrough with ./build.sh docs-videos.

Inputs

• solids – multiple reference_selection (SOLID, default []). All resolved solids are cut by the same tool.
• plane – options, default XY: XY, YZ, or XZ, through the world origin unless offset moves it. Ignored when planeRef resolves.
• offset – number, default 0. Shifts the cut plane along its normal (origin + normal·offset).
• planeRef – single reference_selection (FACE or PLANE, default null) that overrides the base plane.
• keep – options, default BOTH: BOTH, ABOVE (the +normal side) or BELOW (the −normal side).
• id – string, default null. Optional identifier for the history entry.

Behaviour

• Every selected solid is cut by the same tool:
  • a planar face reference cuts by that face's plane, shifted along the face normal by offset;
  • a datum or construction plane reference cuts by its frame origin and z-axis normal, shifted by offset;
  • a curved analytic face reference cuts by that face's carrier surface — and on this path offset is ignored;
  • with no planeRef, the named base plane is used. Its normal is the axis perpendicular to it: XY → +Z, YZ → +X, XZ → +Y.

Watch the XZ sign. Split's own XZ base plane has normal +Y, while the XZ plane a Datium or a Plane registers has normal −Y. So ABOVE means the +Y side when you use Split's plane dropdown, and the −Y side when you point planeRef at a datum's XZ plane. XY and YZ agree between the two.

• Each source body is consumed. Surviving pieces are named {featureId}:{solidName}:A for the ABOVE / +normal / outside piece and {featureId}:{solidName}:B for the BELOW / −normal / inside piece. With keep = BOTH, A is added first.
• Each piece's copy of the source face and edge names is suffixed ({featureId}:A / {featureId}:B) to keep them unique, whether or not the sibling piece is kept.

Limitations

• A plane or surface that does not divide a body is an error (plane does not intersect the solid for a plane, tool surface does not divide the solid for a curved one), not a silent no-op or a degenerate piece.
• A planeRef face whose carrier is a general (non-quadric) surface of revolution is rejected by the kernel.
• Setting keep so that no piece survives fails loudly (keep excluded every piece) rather than deleting the body.
• A solids name that does not resolve is recorded as unresolved and skipped, not an error. A planeRef name that does not resolve makes the whole feature a no-op.

Where to find it

Offered in the Modeling and All workbenches. Type code SPL.