Subtractive Pipe¶

In one sentence: Sweep a closed 2-D profile sketch along a path curve to cut a channel or groove whose cross-section follows that path.

Overview¶

Workbench: Part Design · Menu: Part Design → Subtractive Features → Subtractive Pipe
Toolbar: Part Design Modeling Features · Shortcut: none

Subtractive Pipe takes the same two inputs as Additive Pipe — a profile sketch and a path (spine) — but subtracts the resulting swept solid from the active Body instead of adding to it. The result is a channel, groove, or hollow tunnel whose cross-section follows the chosen path from one end to the other. All parameters are identical to Additive Pipe; only the Boolean operation (cut vs. fuse) differs.

Intuition¶

Think of a router bit moving along a curved guide. The bit has a specific shape (the profile), and the guide controls where the bit travels (the path). Whatever shape the bit has, the groove left in the workpiece mirrors that shape all the way along the guide's length.

The profile sketch defines the shape of the cross-section being removed. The spine defines the route it travels. The two are independent: a circular profile on a straight spine carves a cylindrical bore; the same circular profile on a curved spine carves a bent tunnel.

Because the profile is dragged along the spine starting at one end, the sketch does not need to be drawn on the spine. FreeCAD positions it correctly as long as the profile's origin lies on or near the spine's start point.

When to use it¶

You need to cut a channel, conduit, or wiring duct that follows a curved route through a part.
You are machining a curved slot or groove whose cross-section must remain constant along its length.
You want to model a fluid passage, pipe recess, or cable raceway inside a housing.
You need the cut to morph between two cross-section shapes along the path (use Multisection transform mode — see Parameters).
The path is assembled from multiple joined edges, and you want a single operation to cut along all of them as one continuous route.

When NOT to use it¶

The cut has a constant cross-section and a straight path — use Pocket; it is simpler and less prone to failure.
The cut revolves around a central axis — use Groove, which handles axisymmetric cuts.
The profiles at the start and end are different and there is no explicit spine — use Subtractive Loft, which blends between sections without requiring a spine sketch.
The path is a helix — use Subtractive Helix, which generates the helical path automatically.
You want to add material — use Additive Pipe.

Step-by-step walkthrough¶

Prerequisites: An active Body with at least one existing solid feature to cut into. You will need two sketches: a profile (cross-section shape) and a spine (the path). Both must belong to the Body before you start.

Create the profile sketch. Draw and fully constrain the cross-section shape on any plane or datum plane. The profile must be a single closed wire (or multiple nested closed wires for a hollow section). Close the Sketcher task panel.
Create the spine sketch. Draw the path curve on a different plane. The spine can be an open or closed wire; it must be one continuous, connected wire — disconnected edges will cause a failure. Close the Sketcher task panel.
Activate Part Design → Subtractive Features → Subtractive Pipe. The task panel opens with three collapsible sections: Pipe Parameters, Section Orientation, and Section Transformation.
Set the Profile. In Pipe Parameters, click Object next to the Profile field, then click the profile sketch in the model tree or viewport.
Set the Path. Under Path to Sweep Along, click Object, then click the spine sketch. Alternatively, click Add edge to pick individual edges from any geometry in the Body instead of using a whole sketch.
Set Corner transition if the spine has sharp corners:
- Transformed (default) — the profile rotates to match the tangent at each corner; may produce self-intersecting geometry at tight bends.
- Right corner — the pipe makes a mitre-cut join at each corner.
- Round corner — the pipe is rounded at each corner.
Adjust Orientation mode in Section Orientation if needed (see Parameters). Leave it on Standard for most channels.
Click OK. FreeCAD sweeps the profile along the path and subtracts the result from the Body.

Tip

If the spine is a sketch, select the entire sketch in the model tree as the path. If the spine is made of edges on an existing solid face, use Add edge to select them individually.

Parameters¶

The task panel is divided into three sections. All parameters are identical to Additive Pipe.

Pipe Parameters¶

Parameter	Type	Default	Description
Profile	Object link	—	The sketch (or face/wire sub-element) whose outline is swept. Must be a closed profile to form a solid cut.
Corner transition	Dropdown	Transformed	How the sweep behaves at kinks in the spine: `Transformed` (shear), `Right corner` (mitre), `Round corner` (fillet). See deep dive below.
Path to Sweep Along	Object link + edge list	—	The spine object (typically a sketch) or a list of individual edges that form the path. Edges must form one connected, non-branching wire.
Add edge / Remove edge	Buttons	—	Toggle selection mode to add or remove individual edges from the edge list.

Section Orientation¶

Controls how the profile is rotated as it travels along the path.

Parameter	Type	Default	Description
Orientation mode	Dropdown	Standard	How the profile rotates as it travels the path: Standard / Fixed / Frenet / Auxiliary / Binormal. See deep dive below.
Curvilinear equivalence	Checkbox	On	(Auxiliary mode only) Distribute orientation points by arc length rather than parallel projection.
Auxiliary spine	Object link + edge list	—	(Auxiliary mode only) A secondary path that drives the profile's roll angle.
X / Y / Z	Float	0.0	(Binormal mode only) The fixed binormal vector components.

Orientation mode in depth¶

The Orientation mode dropdown controls how the profile rotates about the spine axis as it travels along the path. The spine tells the profile where to go; the orientation mode tells it which way to face at each point along the journey.

Standard (default)¶

Intuition: Like threading a needle onto a curved wire and letting it find its own least-twisted resting orientation — the profile tilts to follow the path but never spins more than necessary.

Technically, FreeCAD uses the Darboux frame with minimum-rotation transport (sometimes called "parallel transport"). The total accumulated twist from start to end is minimised.

Use this mode when: - You want the most natural result with no explicit configuration - The spine is a flat 2-D curve (Standard and Frenet give identical results for planar paths) - No deliberate twist or roll is needed in the swept solid

Watch out for: On highly curved 3-D spines, Standard can still accumulate a visible twist. If the finished solid looks rotated at one end, try Frenet or Auxiliary to diagnose whether the path curvature is causing it.

Fixed¶

Intuition: Like carrying a tray of drinks level through a winding corridor — the profile keeps its original world-space orientation no matter how the path turns and dips.

The profile's X, Y, Z axes in world space are frozen at their initial values and never rotate throughout the sweep. The cross-section always faces the same compass direction.

Use this mode when: - The profile must maintain an absolute world orientation regardless of the path (e.g. a sign bracket that must always face front, or a slide channel that must stay horizontal) - You intentionally want the ends of the sweep to not be perpendicular to the path

Watch out for: On curved paths, a profile that cannot tilt to stay tangent to the path will quickly twist and self-intersect. Fixed is practical only for paths with minimal curvature, or when the profile is small enough that the mismatch does not cause self-intersection.

Frenet¶

Intuition: Like a roller-coaster car whose "up" arrow always points toward the inside of the current curve — the profile tips inward on bends, following the local curvature of the path.

Technically this uses the classical Frenet–Serret frame: the profile normal follows the principal curvature normal of the path. On a tightly curved section the profile leans steeply; on a nearly-straight section the lean is almost zero.

Use this mode when: - You want the profile normal to track the path curvature rather than minimise overall rotation - A mathematically defined curve requires Frenet-frame behaviour specifically - Standard produces unexpected rotation and you need a different algorithm to compare

Watch out for: On nearly-straight sections (very low curvature), the Frenet normal is mathematically undefined and can abruptly flip 180° — the classical Frenet "flip" problem, which produces a sudden twist in the solid. Avoid Frenet for any spine that includes straight or near-straight segments.

Auxiliary¶

Intuition: Like tracing both strands of a twisted rope to define its twist — you draw a second guide spine alongside the main path, and FreeCAD reads the angular relationship between them to determine exactly how much the profile should roll at every point.

This mode gives you the most control: any twist behaviour you can express as a second curve can be encoded.

Use this mode when: - You need a deliberately twisted sweep (propeller blade, twisted square column, helical channel with a specific roll profile) - Standard and Frenet both produce unwanted rotation and manual control is needed - The twist must geometrically match another piece of the design

Sub-parameters active in Auxiliary mode:

Sub-parameter	Type	Default	Description
Auxiliary spine	Object link + edge list	—	The guide path that drives roll. Should span the full length of the primary spine.
Curvilinear equivalence	Checkbox	On	On: distribute orientation points by arc length (natural, recommended). Off: parallel projection — can produce bunching on spines of unequal length.

Watch out for: The auxiliary spine must span the same range as the primary spine. Mismatched start/end points prevent the orientation mapping from being computed and produce an error.

Binormal¶

Intuition: Like a satellite dish on a moving arm — no matter which way the arm points, the dish always faces a fixed direction you specify (north, vertical, toward a wall).

You provide an X/Y/Z vector; the profile's out-of-plane axis (the binormal) is locked parallel to that vector throughout the entire sweep.

Use this mode when: - One face of the profile must consistently point toward a fixed world direction (not just stay upright, but face a specific direction) - Sweeping along a 3-D path where a functional face must always point toward a mating surface or datum plane

Sub-parameters active in Binormal mode:

Sub-parameter	Type	Default	Description
X / Y / Z	Float	0.0	Components of the fixed binormal vector. FreeCAD normalises it; all three being zero is invalid.

Watch out for: A zero binormal vector (0, 0, 0) causes a recompute failure. Also, if the path tangent becomes exactly parallel to the binormal vector at any point along the spine, the orientation is geometrically undefined there and the sweep will fail.

Corner transition in depth¶

The Corner transition dropdown controls what happens when the spine has sharp kinks — points where two edges meet at an angle rather than blending smoothly. The profile must somehow "navigate" each corner.

Transformed (default)¶

At each kink, the profile is sheared to match the local tangent of the incoming edge. The transition is abrupt — there is no blending radius.

Use this mode when: - The spine has gentle curves where shearing does not cause self-intersection - You want the mathematically simplest result with no added geometry at corners - The spine segments are tangent-continuous (no actual kinks)

Watch out for: At tight bends or very large profiles, the sheared section can self-intersect. FreeCAD will report "Pipe could not be built". Reduce the profile size, increase the bend radius in the spine, or switch to Round corner.

Right corner¶

The sweep makes a sharp mitre cut at each corner — like picture-frame moulding, where two pieces meet at a 45° mitre rather than bending around.

Use this mode when: - You need a crisp architectural corner with no rounding (square conduit, sheet-metal box sections, rectangular hollow sections) - The profile is rectangular and a mitred join is geometrically appropriate

Watch out for: Produces flat triangular corner faces. At very acute corner angles the mitre face becomes large and the resulting topology is complex, which can cause downstream Boolean or fillet operations to fail.

Round corner¶

The corner is smoothed with a fillet arc. The pipe curves gradually around the kink rather than making a sharp turn.

Use this mode when: - The profile is round (pipe, rod, wire) and a smooth bend is physically expected - The spine has tight corners where Transformed produces self-intersection - Modelling real-world tubing, handrails, conduit runs, or bent bar stock

Watch out for: The fillet radius is computed automatically by OCCT from the geometry — you cannot specify it directly. The only way to control the radius is to change the corner angle in the spine sketch or add intermediate tangent points to guide the curvature.

Section Transformation¶

Controls whether the cut profile changes shape along the path.

Parameter	Type	Default	Description
Transform mode	Dropdown	Constant	`Constant`: identical cut profile at every point. `Multisection`: cut profile morphs through intermediate section sketches. See deep dive below.
Add Section / Remove Section	Buttons	—	(Multisection only) Pick additional profile sketches.
Section list	Ordered list	—	(Multisection only) Intermediate sections in path order, top = spine start.

Transform mode in depth¶

The Transform mode dropdown controls whether the profile shape stays constant or morphs along the path.

Constant (default)¶

The identical profile cross-section is used at every point along the path. The swept solid has the same shape from start to finish — like extruding pasta through a die of fixed shape.

Use this mode when: - You are sweeping a uniform cross-section (pipe, rod, channel, rail, wiring duct) - The cross-section is not supposed to change at any point along the spine

Watch out for: Nothing — this is the correct mode for the vast majority of sweeps.

Multisection¶

The profile morphs through a sequence of intermediate section sketches positioned along the spine. The solid is interpolated between the start profile, each intermediate section in path order, and the end of the spine.

Use this mode when: - You need a shape that transitions from one cross-section to another along its length (e.g. round inlet → square outlet on a duct or nozzle) - The transition must pass through specific intermediate cross-sections at defined positions — more controlled than Additive Loft's free-form blending

Sub-parameters active in Multisection mode:

Sub-parameter	Type	Default	Description
Add Section / Remove Section	Buttons	—	Toggle selection mode to add or remove intermediate section sketches from the list.
Section list	Ordered list	—	Sections in path order (top = spine start). Reorder by drag-and-drop.

Watch out for: All intermediate sections must have the same number of closed wires (loops) as the start profile. Only the very last section in the list may be reduced to a single point (which closes the solid to a cone tip or similar). Mismatching wire counts always causes a "Pipe could not be built" failure.

Advanced usage¶

Multisection sweeps¶

In Multisection mode the cut morphs between the start profile and each intermediate section in order. This lets you carve a recess that transitions from a round entry to a rectangular channel:

Draw the start profile (e.g. a circle) positioned at the spine's start.
Draw intermediate section sketches at desired points along the spine, each attached to a datum plane perpendicular to the spine at that point.
In Section Transformation, switch to Multisection and add the intermediate sketches in path order.

All sections must have the same number of closed loops as the start profile. The last section can be a single point to produce a tapered tip.

Spine from existing geometry¶

The spine does not have to be a dedicated sketch. Click Add edge and select edges directly from a face of an existing solid in the Body. This is useful for cutting a groove along the edge profile of an enclosure wall.

Cutting with a closed spine¶

If the spine forms a closed loop (e.g. a circle), the swept cut wraps around and meets itself, producing a torus-shaped cavity. Make sure the profile origin lies on the spine to avoid self-intersecting geometry.

Common mistakes and pitfalls¶

Spine is not connected

Cause: The selected edges or spine sketch contain a gap — the path is two or more disconnected segments.
Fix: Edit the spine sketch to ensure every line or arc shares endpoints with its neighbours, or use Add edge to select only a contiguous sequence of edges.

Pipe could not be built / Result is not a solid

Cause: The profile is too large for the curvature of the path at some point. If the cross-section overhangs the centre of curvature, OCCT cannot form a valid solid to subtract.
Fix: Reduce the profile size, increase the path's bend radius, or switch the Corner transition to Round corner to smooth sharp turns.

Profile sketch is not closed

Cause: The profile sketch has an open wire, which cannot form a solid face to sweep.
Fix: Open the profile sketch, close the gap, and ensure the Sketcher reports zero open edges.

Unexpected profile twist along the path

Cause: The Standard orientation mode can produce a visible twist on certain curved paths, especially when the path has sections of low curvature.
Fix: Try Frenet mode, or use Auxiliary mode with a second guiding spine to take explicit control of the roll angle.

Python API¶

Minimal example¶

import FreeCAD as App
import Part
import Sketcher

doc = App.newDocument()

# Create the body with a solid block to cut into
body = doc.addObject("PartDesign::Body", "Body")

base_sk = doc.addObject("Sketcher::SketchObject", "BaseSketch")
body.addObject(base_sk)
base_sk.addGeometry(
    Part.makePolygon([
        App.Vector(-25, -25, 0), App.Vector(25, -25, 0),
        App.Vector(25, 25, 0), App.Vector(-25, 25, 0),
        App.Vector(-25, -25, 0),
    ])
)
doc.recompute()

pad = doc.addObject("PartDesign::Pad", "Pad")
body.addObject(pad)
pad.Profile = base_sk
pad.Length = 60.0
doc.recompute()

# Profile sketch: a circle of radius 5 mm on the XY plane
profile = doc.addObject("Sketcher::SketchObject", "Profile")
body.addObject(profile)
profile.addGeometry(Part.Circle(App.Vector(0, 0, 0), App.Vector(0, 0, 1), 5), False)
profile.addConstraint(Sketcher.Constraint("Coincident", 0, 3, -1, 1))
doc.recompute()

# Spine sketch: a line 50 mm along Y, on the XZ plane
spine = doc.addObject("Sketcher::SketchObject", "Spine")
body.addObject(spine)
spine.MapMode = "FlatFace"
spine.AttachmentSupport = (doc.XZ_Plane, [""])
doc.recompute()
spine.addGeometry(Part.LineSegment(App.Vector(0, 0, 0), App.Vector(0, 50, 0)), False)
spine.addConstraint(Sketcher.Constraint("Coincident", 0, 1, -1, 1))
doc.recompute()

# Create the Subtractive Pipe
pipe = doc.addObject("PartDesign::SubtractivePipe", "SubtractivePipe")
body.addObject(pipe)
pipe.Profile = profile
pipe.Spine = spine
doc.recompute()

Key properties¶

All properties live in the Sweep property group.

Property	Type	Default	Description
`Profile`	`App::PropertyLinkSub`	—	The profile sketch or sub-element. Inherited from `ProfileBased`.
`Spine`	`App::PropertyLinkSub`	—	The path object and optionally specific sub-edges.
`SpineTangent`	`App::PropertyBool`	`False`	When `True`, tangent-continuous edges adjoining the spine are automatically included in the path.
`AuxiliarySpine`	`App::PropertyLinkSub`	—	Secondary spine used when `Mode` is `"Auxiliary"`.
`AuxiliarySpineTangent`	`App::PropertyBool`	`False`	Include tangent-continuous edges into the auxiliary spine.
`AuxiliaryCurvilinear`	`App::PropertyBool`	`True`	Use curvilinear equivalence when computing orientation from the auxiliary spine.
`Mode`	`App::PropertyEnumeration`	`"Standard"`	Profile orientation mode. Values: `"Standard"`, `"Fixed"`, `"Frenet"`, `"Auxiliary"`, `"Binormal"`.
`Binormal`	`App::PropertyVector`	`(0, 0, 0)`	Fixed binormal vector, used only when `Mode` is `"Binormal"`.
`Transition`	`App::PropertyEnumeration`	`"Transformed"`	Corner behaviour. Values: `"Transformed"`, `"Right corner"`, `"Round corner"`.
`Transformation`	`App::PropertyEnumeration`	`"Constant"`	Section transform mode. Values: `"Constant"`, `"Multisection"`, `"Linear"`, `"S-shape"`, `"Interpolation"`.
`Sections`	`App::PropertyLinkSubList`	`[]`	Intermediate section profiles for Multisection mode, in path order.