Documentation / generated/freecad-operations.md
Core 11629ae · View or edit Markdown on GitHub ↗

Freecad operation reference

Generated from the current declarations. Do not edit this file by hand.

All routes support shared document/value expressions and finite analytic studies through the framework runtime. Lengths use millimetres. All outputs must be one valid positive-volume solid. See CAD and mesh workflows for native and tessellated output limits.

Index#

body, box, chamfer, circle, common, cone, cut, cylinder, extrude, fillet, fuse, importSTEP, loft, multiFuse, pad, pocket, polygon, readSTEP, rectangle, revolve, sphere, torus

body#

Create the native PartDesign container for one mechanical part and its feature history.

Common mistakes and assumptions:

• A Body is a container, not a solid output. This slice supports one Body at the world origin, one first Pad and a linear Pocket chain.

Native binding: PartDesign::Body. Output kind: ["body"].

Inputs: none.

Options: none.

box#

Creates a native Part::Box: an axis-aligned rectangular solid whose minimum corner sits at origin and which extends length along +X, width along +Y and height along +Z, in millimetres. Choose it for plates, stock blanks and rectangular cut tools. It has no rotation option; for a block in another orientation extrude a rectangle or polygon along the required direction. Schemaxis always assigns all four settings (defaults: a 10 mm cube at the world origin), and the feature stays editable in the published FCStd. In batch parts, parameters plus drive can retain supported length relationships in a native VarSet instead of materialising only the current number.

Common mistakes and assumptions:

• origin is the minimum corner, not the centre: to centre a 20 mm wide box on x = 0, set origin x to -10.
• As a cut tool, let the box overshoot the faces it should pass through; coincident faces make booleans fragile.
• Recorded native qualification for this route covers an analytic box and a height variant (qualification.json box-baseline and box-variant); it does not qualify every boolean that uses a box.

Native binding: Part::Box. Output kind: ["solid"].

Inputs: none.

chamfer#

Bevels selected edges of an existing solid with one equal distance on both adjoining faces (native Part::Chamfer) and produces a solid. Edge selection works exactly as for fillet: one-based indices of the base solid or a geometric selector with an exact expected count. Choose it for lead-in bevels and broken edges where a flat face is wanted instead of a round.

Common mistakes and assumptions:

• The default edges [1] is just the first edge of the base topology; choose edges deliberately.
• Oversized or intersecting chamfers fail native checks; planning only checks that indices exist.
• Covered by an analytic-volume acceptance fixture (all twelve edges of a block); not exhaustively qualified.

Native binding: Part::Chamfer. Output kind: ["solid"].

circle#

Creates a circular sketch profile centred on origin in the XY, XZ or YZ plane, built as a fully constrained Sketcher sketch with a constraint named radius. Choose it as a section for loft (for example two circles of different radii for a tapered duct) or to extrude a round bar along any direction; for a plain cylinder, cylinder needs no profile node. Optional inputs.body places this sketch in an origin-based PartDesign Body for Pad/Pocket history. Named dimensions can use persistent parameters and drive in batch runs. Optional centre gives signed [x,y] coordinates and named centreX/centreY constraints instead of coincidence at the origin.

Common mistakes and assumptions:

• A profile cannot be the output node.
• Loft sections must sit at different positions: offset the second circle with origin along the plane normal.

Native binding: Sketcher::SketchObject. Output kind: ["profile"].

common#

Keeps only the volume shared by two solids (native Part::Common, an intersection). Choose it to trim a part to an envelope, or to build shapes such as a lens from two spheres. The operands must overlap with positive volume; disjoint or merely touching solids leave nothing, which fails native validity even for an intermediate node.

Common mistakes and assumptions:

• The intersection does not depend on which operand is base or tool.
• Covered by an analytic-volume acceptance fixture (two half-overlapping boxes, 3000 mm³); not exhaustively qualified.

Native binding: Part::Common. Output kind: ["solid"].

Options: none.

cone#

Creates a native Part::Cone: a solid of revolution with radius1 at the base circle (centred at origin) and radius2 at the top circle, height along axis. radius2 = 0 gives a pointed cone; otherwise it is a frustum. Choose it for countersink tools, nozzles and tapers between two circles; use loft for transitions between non-circular sections.

Common mistakes and assumptions:

• radius1 must be greater than 0, so the apex can only be at the top; to point the cone the other way, reverse axis and move origin.
• Equal radii make FreeCAD 1.1 build a cylinder instead of a cone.
• Covered by the analytic-volume acceptance fixture (cone along +X, verification/2026-09-19-adaptor-expansion.json); not exhaustively qualified.

Native binding: Part::Cone. Output kind: ["solid"].

Inputs: none.

cut#

Subtracts the tool solid from the base solid (native Part::Cut) and produces a solid linked to both inputs, so editing an operand in FreeCAD recomputes the result. Choose it for holes, slots and pockets; position the hole by the tool's own options. Use common to keep only the overlap, and fuse or multiFuse to add material.

Common mistakes and assumptions:

• base and tool are not interchangeable: swapping them keeps the tool minus the base.
• Planning only checks that both inputs are earlier solids; a tool that misses the base or touches it only on a face can still fail or leave an unchanged part. Check the volume with a measurement.
• Native evidence: the bracket and flange gallery examples (verification/2026-09-19-freecad-gallery.json); booleans are not exhaustively qualified.

Native binding: Part::Cut. Output kind: ["solid"].

Options: none.

cylinder#

Creates a native Part::Cylinder whose base circle is centred at origin and which extends height along axis. Choose it for pins, bosses and round bars, and above all as the tool for a round hole in cut. Unlike circle + extrude it needs no separate profile node; the axis may point in any direction. In batch parts, parameters plus drive can retain supported length relationships in a native VarSet instead of materialising only the current number.

Common mistakes and assumptions:

• radius is half the hole diameter.
• For a through-hole, start the tool below the part and make it longer than the part is thick (the bracket example uses origin z = -1 and height 10 for an 8 mm plate).
• A zero axis vector fails planning with INVALID_AXIS.

Native binding: Part::Cylinder. Output kind: ["solid"].

Inputs: none.

extrude#

Sweeps a closed profile (polygon, rectangle or circle) a fixed length along a direction to make a prism-like solid (native Part::Extrusion with Solid enabled, a custom direction, one-sided, no taper). The solid stays linked to its profile, so editing the sketch in FreeCAD updates it. A direction that is not perpendicular to the profile gives an oblique prism. Use revolve for solids of revolution and loft to change section along the way. In batch parts, parameters plus drive can retain supported length relationships in a native VarSet instead of materialising only the current number.

Common mistakes and assumptions:

• direction defaults to +Z, which lies inside XZ and YZ sketch planes; set it to the plane normal for such profiles.
• The input must be a profile node; extruding a solid fails with TYPE_MISMATCH.
• Covered by an analytic-volume acceptance fixture (an L-shaped polygon, 5400 mm³); not exhaustively qualified.

Native binding: Part::Extrusion. Output kind: ["solid"].

fillet#

Rounds selected edges of an existing solid with one constant radius (native Part::Fillet) and produces a solid. Select edges either by one-based index in the base solid's topology or, preferably, with a geometric selector (where + expect) that Schemaxis resolves again for every design variant and rechecks after reopening. Apply it late in the feature tree, after booleans, as the FreeCAD documentation advises; use chamfer for a flat bevel.

Common mistakes and assumptions:

• The default edges [1] is just the first edge of the base topology; always choose edges deliberately (inspect the base node with schemaxis inspect --node).
• A radius too large for the adjacent faces makes FreeCAD fail the fillet; planning cannot detect this.
• A selector must match exactly expect edges; otherwise the run fails (EMPTY_SELECTION, AMBIGUOUS_SELECTION or SELECTION_COUNT_MISMATCH) instead of rounding other edges.

Native binding: Part::Fillet. Output kind: ["solid"].

fuse#

Unites two solids into one (native Part::Fuse), for example a boss on a plate or the two legs of a bracket. The operands must overlap or share a face: separate pieces give a result with two solids, which cannot be the output. Use multiFuse to unite three or more solids in one feature, with optional refinement.

Common mistakes and assumptions:

• Disjoint operands produce two solids; as the output this fails with INVALID_GEOMETRY.
• Schemaxis does not set Refine on fuse (or cut and common); FreeCAD 1.1 takes it from the installation's Part/Boolean RefineModel preference (true unless changed), so edge numbering for index-based finishing can differ between installations. multiFuse sets refine explicitly.

Native binding: Part::Fuse. Output kind: ["solid"].

Options: none.

importSTEP#

Bring one external STEP solid (for example a supplier part) into the model with explicit units, axis orientation and placement, check it against facts you declare from its drawing or datasheet, optionally merge coplanar faces, and continue with ordinary cuts, fillets, measurements and checked STEP, STL and FCStd publications.

Common mistakes and assumptions:

• Imported geometry has no sketches, parameters or feature history; edit it by placement or later features.
• Declared facts are checked on the exact solid; they are not a guarantee of identity or orientation for symmetric parts.
• Live preview does not support importSTEP; use a batch run.
• Runs made before hardened export verification report RERUN_REQUIRED instead of verified.

Native binding: Part::Feature. Output kind: ["solid"].

Inputs: none.

loft#

Builds a solid that blends through two or more closed profiles in the listed order (native Part::Loft with Solid on and Closed off), for tapered ducts, nozzles and transitions such as round-to-square. Each section must be a profile node at a distinct position, usually offset along a common normal with origin. ruled chooses straight-line or smooth surfaces between sections.

Common mistakes and assumptions:

• Section order is the sweep order; listing sections out of positional order gives a twisted or self-intersecting result.
• Planning cannot check that sections are compatible (for example a circle and a rectangle); native lofting can still fail.
• Native test evidence: two ruled circles (radius 20 and 10, 30 mm apart) loft to the analytic frustum volume 7000π mm³; other section combinations are not qualified.

Native binding: Part::Loft. Output kind: ["solid"].

multiFuse#

Unites 2 to 32 solids in one native Part::MultiFuse feature, for example a frame of overlapping bars or a cluster of bosses, instead of a chain of fuse nodes. The union must still be one connected solid. With refine true (the Schemaxis default) FreeCAD merges face fragments that lie on the same surface, giving cleaner topology for later finishing.

Common mistakes and assumptions:

• Any solid that does not touch the others leaves a second solid; as the output this fails with INVALID_GEOMETRY.
• refine changes edge numbering; inspect the result before writing index-based fillet or chamfer edges.
• Native test evidence: three overlapping 10 mm boxes unite to 2000 mm³; not exhaustively qualified.

Native binding: Part::MultiFuse. Output kind: ["solid"].

pad#

Turn an owned constrained sketch into the first solid of its Body, extruded along +Z.

Common mistakes and assumptions:

• Requires an earlier Body and a profile owned by that Body. The first Pad has no native BaseFeature; length may use a persistent driver.

Native binding: PartDesign::Pad. Output kind: ["solid"].

pocket#

Cut a through hole from the current Body tip using an unused sketch in the same Body.

Common mistakes and assumptions:

• The XY sketch cuts along +Z through all stock. Fixed depth and other side modes are unsupported. Select the final solid tip as output.

Native binding: PartDesign::Pocket. Output kind: ["solid"].

polygon#

Creates a closed, straight-sided sketch profile (Sketcher::SketchObject) from ordered 2D vertices on the XY, XZ or YZ plane. It produces a profile, not a solid: feed it to extrude, revolve or loft. Choose it for L-sections, trapezoids and other outlines; use rectangle or circle for those shapes, since they are fully dimension-constrained in FreeCAD. Schemaxis closes the outline and rejects repeated vertices, zero area and self-intersection before FreeCAD runs.

Common mistakes and assumptions:

• A profile cannot be the output node; it fails with TYPE_MISMATCH.
• Schemaxis adds no sketch constraints to a polygon, so in FreeCAD its vertices are free geometry rather than named dimensions.
• Choose plane before writing points: the same [u, v] values land on different world axes on each plane.

Native binding: Sketcher::SketchObject. Output kind: ["profile"].

Inputs: none.

readSTEP#

Imports one solid from a STEP file as a static Part::Feature so that later nodes can cut, fuse, fillet or measure it, for example to drill a supplier part or to continue from a STEP published by an earlier workflow step. Schemaxis copies the file into the run directory and records its SHA-256 digest; saved verification checks that retained copy, so a moved or exported run still verifies after the original is removed, while a new plan or resume reads the current file. The shape has no feature history, and the file must contain exactly one valid solid. For declared units, orientation, checked facts and refine, use importSTEP.

Common mistakes and assumptions:

• Multi-body or assembly STEP files fail with INVALID_GEOMETRY; export a single solid.
• readSTEP does not check units: FreeCAD silently applies the unit the file assigns and assumes millimetres when none is assigned. Use importSTEP with explicit units and expectations, or check bounds and volume with a measurement.
• Live preview does not support readSTEP (UNSUPPORTED_LIVE_INPUT); use a batch run.
• Changing the source file before verification fails with INPUT_CHANGED.

Native binding: Part::Feature. Output kind: ["solid"].

Inputs: none.

rectangle#

Creates a rectangular sketch profile centred on origin in the XY, XZ or YZ plane. Schemaxis builds it as a fully constrained Sketcher sketch with constraints named width and height, so the dimensions stay editable in FreeCAD and linked extrusions follow them. It is a profile: extrude, revolve or loft it to make a solid; for an axis-aligned block from a corner, box is simpler. Optional inputs.body places this sketch in an origin-based PartDesign Body for Pad/Pocket history. Named dimensions can use persistent parameters and drive in batch runs.

Common mistakes and assumptions:

• A profile cannot be the output node.
• The rectangle is centred on origin, unlike box, whose origin is a corner.
• If the native sketch does not solve fully constrained, the run fails with CONSTRAINT_FAILED.

Native binding: Sketcher::SketchObject. Output kind: ["profile"].

revolve#

Sweeps a closed profile around an axis line to make a solid of revolution such as a ring, flange, bushing or turned part (native Part::Revolution with Solid enabled). The axis is the line through origin along axis. Draw the profile in a plane that contains that axis (for the default Z axis use XZ or YZ) and keep it on one side of the axis.

Common mistakes and assumptions:

• A profile on XY revolved about the default Z axis lies perpendicular to the axis and cannot sweep a volume.
• FreeCAD notes that a profile crossing the rotation axis makes the revolve fail in most cases.
• For revolve, origin is a point on the axis; it does not move the profile.
• Covered by an analytic-volume acceptance fixture (an XZ rectangle revolved to an annulus); not exhaustively qualified.

Native binding: Part::Revolution. Output kind: ["solid"].

sphere#

Creates a native Part::Sphere, a full ball centred at origin. Choose it for ball ends, spherical cavities (cut it from a block) or test solids with the analytic volume 4/3·π·r³. It produces a solid.

Common mistakes and assumptions:

• Schemaxis assigns its own default radius of 10 mm; FreeCAD's native 5 mm default is never used.
• Covered by the eight-fixture analytic-volume acceptance run (verification/2026-09-19-adaptor-expansion.json); not exhaustively qualified.

Native binding: Part::Sphere. Output kind: ["solid"].

Inputs: none.

torus#

Creates a native Part::Torus: a circular tube of radius minorRadius swept around a circular path of radius majorRadius, centred at origin in the plane perpendicular to axis. Choose it for O-rings, handles and ring groove tools (cut a torus from a shaft). Schemaxis requires minorRadius < majorRadius, so the ring always has a central hole.

Common mistakes and assumptions:

• minorRadius equal to or larger than majorRadius fails planning with INVALID_GEOMETRY.
• Covered by the analytic-volume acceptance fixture (2·π²·R·r²); not exhaustively qualified.

Native binding: Part::Torus. Output kind: ["solid"].

Inputs: none.