modeling-app/docs/kcl-std/functions/std-solid-subtract.md

title, subtitle, excerpt, layout

title	subtitle	excerpt	layout
subtract	Function in std::solid	Subtract removes tool solids from base solids, leaving the remaining material.	manual

Subtract removes tool solids from base solids, leaving the remaining material.

subtract(
  @solids: [Solid; 1+],
  tools: [Solid],
  tolerance?: number(Length),
): [Solid; 1+]

Performs a bool subtraction operation, removing the volume of one or more tool solids from one or more base solids. The result is a new solid representing the material that remains after all tool solids have been cut away. This function is essential for machining simulations, cavity creation, and complex multi-body part modeling.

Arguments

Name	Type	Description	Required
solids	[Solid; 1+]	The solids to use as the base to subtract from.	Yes
tools	[Solid]	The solids to subtract.	Yes
tolerance	number(Length)	The tolerance to use for the subtraction operation.	No

Returns

[Solid; 1+]

Examples

// Subtract a cylinder from a cube using the stdlib functions.

fn cube(center, size) {
    return startSketchOn(XY)
        |> startProfile(at = [center[0] - size, center[1] - size])
        |> line(endAbsolute = [center[0] + size, center[1] - size])
        |> line(endAbsolute = [center[0] + size, center[1] + size])
        |> line(endAbsolute = [center[0] - size, center[1] + size])
        |> close()
        |> extrude(length = 10)
}

part001 = cube(center = [0, 0], size = 10)
part002 = cube(center = [7, 3], size = 5)
    |> translate(z = 1)

subtractedPart = subtract([part001], tools=[part002])

// Subtract a cylinder from a cube using operators.
// NOTE: This will not work when using codemods through the UI.
// Codemods will generate the stdlib function call instead.

fn cube(center, size) {
    return startSketchOn(XY)
        |> startProfile(at = [center[0] - size, center[1] - size])
        |> line(endAbsolute = [center[0] + size, center[1] - size])
        |> line(endAbsolute = [center[0] + size, center[1] + size])
        |> line(endAbsolute = [center[0] - size, center[1] + size])
        |> close()
        |> extrude(length = 10)
}

part001 = cube(center = [0, 0], size = 10)
part002 = cube(center = [7, 3], size = 5)
    |> translate(z = 1)

// This is the equivalent of: subtract([part001], tools=[part002])
subtractedPart = part001 - part002