Cadquery

CadQuery リファレンス

CadQuery — OpenCascade ベースの Python 製パラメトリック 3D CAD モデリングライブラリ。 スクリプトとして CAD モデルを記述でき、Workplane / Sketch / Assembly といった抽象レイヤー上で 制約ベースの設計を可能にする。STEP / DXF / STL / glTF など多様な業界標準フォーマットの入出力に対応。 公式ドキュメント (cadquery.readthedocs.io) の全 20 ページを 14 カテゴリに構造化。

ディレクトリ構造

.claude/skills/cadquery/
├── SKILL.md                                  ← このファイル（エントリーポイント）
└── references/
    ├── getting-started/README.md             ← 入門索引（5 ページ）
    ├── workplane/README.md                   ← Workplane page 索引（9 ページ）
    ├── sketch/README.md                      ← Sketch page 索引（2 ページ）
    ├── assemblies/README.md                  ← Assemblies page 索引（4 ページ）
    ├── free-function/README.md               ← Free Function API 索引（9 ページ）
    ├── visualization/README.md               ← Visualization 索引（5 ページ）
    ├── file-io/README.md                     ← File I/O 索引（15 ページ）
    ├── examples/README.md                    ← Examples 索引（9 ページ / 33 例カバー）
    ├── api/README.md                         ← API Reference + Cheatsheet 索引（14 ページ）
    ├── selectors/README.md                   ← Selectors Reference 索引（8 ページ）
    ├── classes/README.md                     ← Class Summary 索引（4 ページ）
    ├── cqgi/README.md                        ← CQGI 索引（7 ページ）
    ├── extending/README.md                   ← Plugin/拡張ガイド索引（10 ページ）
    └── misc/README.md                        ← Citing 索引（1 ページ）

探索手順

1. ユーザーのタスクに最も関連するカテゴリを特定する 2. そのカテゴリの README.md を読む 3. README.md 内の一覧から必要な個別ファイルを選んで読む 4. 必要に応じて関連ページのリンクを辿る

カテゴリ → README.md マッピング

Assemblies

Classes and methods for combining Workplane and Shape objects into hierarchical, constraint-solved assemblies.

Method Summary

Signature / Usage

import cadquery as cq

# Build an assembly
assy = (
    cq.Assembly()
    .add(cq.Workplane("XY").box(1, 1, 1), name="base", color=cq.Color("red"))
    .add(cq.Workplane("XY").sphere(0.5), name="ball",
         loc=cq.Location((0, 0, 1)))
)

# Constraint-based assembly
assy = (
    cq.Assembly()
    .add(cq.Workplane("XY").box(2, 2, 1), name="bottom")
    .add(cq.Workplane("XY").box(1, 1, 1), name="top")
    .constrain("bottom@faces@>Z", "top@faces@<Z", "Plane")
    .solve()
)

assy.save("assembly.step")

Options / Props

Assembly(obj, loc, name, color, material, metadata)

Assembly.add(obj, loc, name, color, material, metadata)

Assembly.save(path, exportType, mode, tolerance, angularTolerance)

Assembly.constrain(q1, q2, kind, param)

Assembly.solve(verbosity)

Constraint Types

Constraint Query String Syntax

Format: "<name>@<type>@<selector>"

• <name>: Assembly component name (or "" for root)
• <type>: faces, edges, vertices
• <selector>: Any valid selector string (e.g. >Z, <X, \|Y)

Example: "pin@faces@>Z" — the topmost face of the component named "pin"

Color Usage

# Named colors
cq.Color("red")
cq.Color("green")
cq.Color("blue")

# RGBA
cq.Color(0.8, 0.2, 0.1, 1.0)

Notes

• Assembly.solve() must be called after all constraints are defined to compute final positions.
• Component names must be unique within an assembly.
• The constraint system uses a 6-DOF solver; under-constrained assemblies will have remaining degrees of freedom.
• Location objects can be created with cq.Location(cq.Vector(x, y, z)) or cq.Location((x, y, z)).
• STEP export preserves assembly hierarchy; STL/GLTF flatten geometry.

Related

• File Management and Export
• Stack and Selector Methods
• Selectors

CadQuery Cheatsheet

Quick-reference for CadQuery's most commonly used operations, selectors, and patterns.

3D Construction

Primitives

Additive Operations

Subtractive Operations

Boolean Operations

Use combine parameter shorthand on creation methods:

• combine="a" — add (union)
• combine="s" — subtract
• combine="i" — intersect

Edge Modifications

2D Construction

Shapes

Positioning

Lines and Arcs

Arrays

Sketch API

Basic Shapes

Sketch Refinement

Import / Export

Supported formats: STEP, STL, AMF, SVG, VRML, GLTF, TJS

Assemblies

assy = (
    cq.Assembly()
    .add(part1, name="base", color=cq.Color("red"))
    .add(part2, name="lid",  loc=cq.Location((0, 0, 10)))
    .constrain("base@faces@>Z", "lid@faces@<Z", "Plane")
    .solve()
)
assy.save("assembly.step")

BREP Topology

Selector String Reference

Axis Symbols

Axes: X, Y, Z, XY, YZ, XZ, or custom >(1,1,0)

Face Selector Examples

Edge Selector Examples

Vertex Selector Examples

Combining Selectors

Workplane Positioning

Named Planes

Core Classes

Related

• Workplane 2D Operations
• Workplane 3D Operations
• Selectors
• Assemblies

File Management and Export

Importing and exporting CAD files in CadQuery. Supports STEP, STL, DXF, SVG, AMF, VRML, GLTF, and more.

Method Summary

Signature / Usage

import cadquery as cq
from cadquery import exporters, importers

# Import a STEP file
result = importers.importStep("model.step")

# Export to STEP
exporters.export(result, "output.step")

# Export to STL with tolerance
exporters.export(result, "output.stl", tolerance=0.01, angularTolerance=0.1)

# Export to SVG
result.exportSvg("output.svg")

# Import DXF
profile = importers.importDXF("profile.dxf", tol=1e-6)

Options / Props

exporters.export(w, fname, exportType, tolerance, angularTolerance, opt)

importers.importDXF(filename, tol, exclude, include)

Workplane.toSvg(opts)

DxfDocument(approx, tolerance)

Supported Export Formats

Notes

• exporters.export() auto-detects the format from the file extension when exportType is None.
• Lower tolerance values produce finer STL/AMF meshes but larger files and slower export.
• importers.importStep() returns a Workplane with the imported shape on the stack.
• DXF import creates wire/face geometry from 2D DXF entities; 3D DXF is not supported.

Related

• Workplane Initialization
• Assemblies

Iteration Methods

Methods for applying a function to each item on the CadQuery stack.

Method Summary

Signature / Usage

import cadquery as cq

# Use each() to apply a custom operation at every stack point
def make_pillar(loc):
    return cq.Workplane("XY").circle(0.25).extrude(2).val().located(loc)

result = (
    cq.Workplane("XY")
    .rarray(2, 2, 3, 3)
    .each(make_pillar, combine=True)
)

# eachpoint: callback receives translated location objects
def make_pin(loc):
    return cq.Workplane("XY").circle(0.1).extrude(1).val().located(loc)

result = (
    cq.Workplane("XY")
    .rarray(1, 1, 4, 4)
    .eachpoint(make_pin, useLocalCoordinates=True, combine=True)
)

Options / Props

Workplane.each(callback, useLocalCoordinates, combine, clean)

Workplane.eachpoint(arg, useLocalCoordinates, combine, clean)

Notes

• each() is suited for operating on existing shapes; eachpoint() is better when generating new geometry at each location.
• The callback must return a Shape (or Compound), not a Workplane.
• Use .val() inside the callback to extract the Shape from a Workplane builder.
• useLocalCoordinates=True transforms coordinates into the workplane frame, enabling consistent relative placement.

Related

• Stack and Selector Methods
• 2D Operations
• 3D Operations (Requiring 2D Workplane)

CadQuery API Reference

Selectors

Selector classes and string syntax for filtering CadQuery geometry (faces, edges, vertices, etc.).

String Selector Syntax

Selectors can be passed as strings directly to .faces(), .edges(), .vertices(), etc.

Axis Modifiers

Axis References

X, Y, Z, XY, YZ, XZ — or a custom vector >(1, 1, 0)

Combining Selectors

Selector Classes

Signature / Usage

import cadquery as cq
from cadquery.selectors import NearestToPointSelector, AreaNthSelector

# String selector - top face
result = cq.Workplane("XY").box(4, 4, 4).faces(">Z")

# Select largest face
result = cq.Workplane("XY").box(4, 4, 2).faces(AreaNthSelector(-1))

# Combine string selectors
result = cq.Workplane("XY").box(4, 4, 4).edges("|Z and >Y")

# Use NearestToPointSelector
result = (
    cq.Workplane("XY")
    .box(4, 4, 4)
    .faces(NearestToPointSelector((0, 0, 2)))
)

Face Filtering Examples

Edge Filtering Examples

TypeSelector Types

Notes

• DirectionNthSelector and CenterNthSelector use zero-based index n; negative indices count from the end.
• BoxSelector(boundingbox=False) tests whether the object's center is inside the box; boundingbox=True tests whether the bounding box intersects.
• For non-planar faces, direction-based selectors are evaluated at the center of mass.
• Combining selectors via string syntax is often clearer than nesting AndSelector/SumSelector objects.

Related

• Stack and Selector Methods
• Cheatsheet

Sketching with Edges and Constraints

Edge-based sketch construction with geometric constraint support in CadQuery.

Method Summary

Signature / Usage

import cadquery as cq

# Edge-based workflow with constraints
result = (
    cq.Workplane("XY")
    .sketch()
    .segment((0, 0), (1, 0), tag="bottom")
    .segment((1, 0), (1, 1), tag="right")
    .segment((1, 1), (0, 1), tag="top")
    .close()
    .assemble(mode="a")
    .finalize()
    .extrude(0.5)
)

Options / Props

Sketch.edge(val, tag, forConstruction)

Sketch.segment(p1, p2, tag, forConstruction)

Sketch.arc(p1, p2, p3, tag, forConstruction)

Sketch.spline(pts, tangents, periodic, tag, forConstruction)

Sketch.constrain(tag1, tag2, constraint, arg)

Notes

• Edges must form a closed loop before calling Sketch.assemble() to build a face.
• Sketch.close() is a convenience shortcut that adds the final segment to close the loop.
• Sketch.solve() must be called after adding all constraints to update geometry positions.
• Construction edges (forConstruction=True) are used as references for constraints but are not part of the resulting face.
• Constraints are solved using a 2D constraint solver; over- or under-constrained sketches will raise an error.

Related

• Sketch Initialization
• Sketch Selection
• Sketching with Faces

Sketching with Faces

Face-based sketch construction API — create closed-face primitives, arrays, and perform local modifications within a CadQuery sketch.

Method Summary

Signature / Usage

import cadquery as cq

result = (
    cq.Workplane("XY")
    .sketch()
    .rect(4, 2)                        # outer rectangle face
    .rarray(1.5, 0.75, 2, 2)           # 2x2 grid of locations
    .circle(0.25, mode="s")            # subtract circles at each location
    .reset()
    .vertices()
    .fillet(0.25)
    .finalize()
    .extrude(0.5)
)

Options / Props

Common mode parameter

Sketch.rect(w, h, angle, mode, tag)

Sketch.rarray(xs, ys, nx, ny)

Sketch.parray(r, a1, da, n, rotate)

Sketch.distribute(n, start, stop, rotate)

Sketch.offset(d, mode, tag)

Notes

• Array methods (rarray, parray, distribute, push) set the current location context; subsequent face-creation calls are placed at each location.
• mode="s" is the primary way to create holes/cutouts within a sketch.
• Sketch.clean() removes leftover internal wires that can interfere with extrusion.
• Sketch.hull() wraps all selected geometry in a convex hull face.

Related

• Sketch Initialization
• Sketch Selection
• Sketching with Edges and Constraints

Sketch Initialization

Methods and classes for creating and initializing 2D sketch objects in CadQuery.

Method Summary

Signature / Usage

import cadquery as cq

# Create a sketch via Workplane
result = (
    cq.Workplane("XY")
    .sketch()
    .circle(1)
    .finalize()
    .extrude(1)
)

# Import DXF into a sketch
sketch = cq.Sketch().importDXF("profile.dxf")

Options / Props

Sketch(parent, locs, obj)

Sketch.importDXF(filename, tol, exclude, include)

Sketch.located(loc)

Notes

• Sketch.finalize() must be called to return control to the parent Workplane after sketch operations.
• Sketch.copy() / Sketch.located() / Sketch.moved() produce shallow copies suitable for reuse in arrays.
• Use Workplane.sketch() as the primary entry point when building sketches within a fluent chain.

Related

• Sketch Selection
• Sketching with Faces
• Sketching with Edges and Constraints

Sketch Selection

Methods for selecting, tagging, and manipulating elements within a CadQuery sketch.

Method Summary

Signature / Usage

import cadquery as cq

result = (
    cq.Workplane("XY")
    .sketch()
    .circle(2).tag("outer")
    .circle(1).tag("inner")
    .select("outer")          # re-select the outer circle
    .faces()                  # work with face selection
    .finalize()
)

Options / Props

Sketch.tag(tag)

Sketch.select(*tags)

Sketch.faces(s, tag) / Sketch.edges(s, tag) / Sketch.vertices(s, tag)

Notes

• Tags survive subsequent operations and can be referenced at any later point in the sketch chain.
• Sketch.reset() restores selection to "all objects" — useful before starting a new selection sequence.
• Sketch.delete() permanently removes the selected geometry from the sketch; use with care.
• All three geometry-type selectors (faces, edges, vertices) accept the same s and tag arguments.

Related

• Sketch Initialization
• Sketching with Faces
• Sketching with Edges and Constraints

Stack and Selector Methods

Methods for navigating, querying, and modifying the object stack and selecting geometry on a CadQuery Workplane.

Method Summary

Stack Navigation

Geometry Selectors

Signature / Usage

import cadquery as cq

result = (
    cq.Workplane("XY")
    .box(4, 4, 4)
    .faces(">Z")          # select top face
    .workplane()          # new workplane on that face
    .circle(1)
    .cutBlind(2)
)

# Stack navigation
box = cq.Workplane("XY").box(2, 2, 2)
print(box.size())         # 1
print(type(box.val()))    # <class 'cadquery.occ_impl.shapes.Solid'>

# Traverse parent chain
child = box.faces(">Z")
parent = child.end()       # returns to the box workplane

Options / Props

Geometry selector methods (faces, edges, vertices, wires, solids, shells, compounds)

Workplane.end(n)

Workplane.item(i)

Workplane.add(obj)

Notes

• val() returns the first raw Shape; vals() returns all raw shapes as a list. Both skip non-shape items.
• all() returns a list of Workplane objects wrapping each stack item individually.
• Selector strings follow CadQuery's string syntax (see Selectors).
• Chaining .faces(">Z").workplane() is the standard pattern for placing features on a specific face.
• end() is essential in fluent chains: after a .faces() selector, call .end() to return to the parent solid context.

Related

• Selectors
• Workplane Initialization
• Iteration Methods

2D Operations

2D drawing and construction methods on a CadQuery Workplane, used to build wire profiles for subsequent 3D operations.

Method Summary

Signature / Usage

import cadquery as cq

# Draw a closed profile and extrude
result = (
    cq.Workplane("XY")
    .moveTo(0, 0)
    .lineTo(2, 0)
    .lineTo(2, 1)
    .lineTo(0, 1)
    .close()
    .extrude(0.5)
)

# Rectangular array of circles
result = (
    cq.Workplane("XY")
    .rarray(1.5, 1.5, 3, 3)
    .circle(0.25)
    .extrude(1)
)

Options / Props

Workplane.rect(xLen, yLen, centered, forConstruction)

Workplane.spline(listOfXYTuple, tangents, periodic, ...)

Workplane.rarray(xSpacing, ySpacing, xCount, yCount, center)

Workplane.polarArray(radius, startAngle, angle, count, fill, rotate)

Notes

• All coordinate arguments are in the local workplane coordinate system.
• forConstruction=True creates geometry visible for reference but excluded from faces and wires.
• Drawing methods accumulate "pending edges"; call close() or wire() to consolidate them before 3D operations.
• mirrorX() / mirrorY() operate on all pending edges and are useful to draw half a profile.

Related

• Workplane Initialization
• 3D Operations (Requiring 2D Workplane)
• Stack and Selector Methods

3D Operations (Not Requiring 2D Workplane)

3D modification operations that work directly on selected solid geometry without requiring a 2D sketch profile.

Method Summary

Signature / Usage

import cadquery as cq

# Fillet all edges of a box
result = (
    cq.Workplane("XY")
    .box(4, 4, 4)
    .edges("|Z")
    .fillet(0.5)
)

# Shell a box (remove top face)
result = (
    cq.Workplane("XY")
    .box(4, 4, 4)
    .faces(">Z")
    .shell(0.2)
)

# Mirror a shape
result = (
    cq.Workplane("XY")
    .box(2, 2, 2)
    .translate((3, 0, 0))
    .mirror("YZ")
)

Options / Props

Workplane.shell(thickness, kind)

Workplane.fillet(radius)

Workplane.chamfer(length, length2)

Workplane.split(keepTop, keepBottom, keepBoth)

Workplane.rotate(axisStartPoint, axisEndPoint, angleDegrees)

Workplane.mirror(mirrorPlane, basePointVector, union)

Notes

• fillet() and chamfer() operate on the selected edges (set with .edges() prior to the call). Without prior selection, all edges are affected.
• shell() removes the selected faces to create openings; without a selection it attempts to shell with no opening.
• split() uses the active workplane as the cutting plane.
• translate() and rotate() create new objects; they do not modify in-place.
• mirror(union=True) automatically unions the mirrored copy back into the original solid.

Related

• 3D Operations (Requiring 2D Workplane)
• Stack and Selector Methods
• Selectors

3D Operations (Requiring 2D Workplane)

3D solid creation and Boolean operations that use an active 2D workplane profile in CadQuery.

Method Summary

Signature / Usage

import cadquery as cq

# Extrude a rectangle
result = cq.Workplane("XY").rect(4, 2).extrude(1)

# Revolve a profile
result = (
    cq.Workplane("XZ")
    .lineTo(2, 0)
    .lineTo(2, 3)
    .lineTo(0, 3)
    .close()
    .revolve(360, (0, 0, 0), (0, 1, 0))
)

# Loft between two profiles
result = (
    cq.Workplane("XY")
    .rect(4, 4)
    .workplane(offset=5)
    .circle(1)
    .loft()
)

Options / Props

Workplane.extrude(until, combine, clean, both, taper)

Workplane.hole(diameter, depth, clean)

Workplane.cboreHole(diameter, cboreDiameter, cboreDepth, depth, clean)

Workplane.sweep(path, multisection, ...)

Workplane.revolve(angleDegrees, axisStart, axisEnd, combine, clean)

Notes

• extrude(until="next") and extrude(until="last") use face topology to determine depth automatically.
• Boolean operations (cut, union, intersect) accept either a Workplane or Shape argument.
• combine=True (default) merges the new solid with the existing one on the stack; combine=False leaves separate solids.
• clean=True (default) calls Solid.clean() to heal the result, which can be slow for complex geometry.
• loft() requires at least two wire profiles on the stack (created with workplane() calls between them).

Related

• 2D Operations
• 3D Operations (Not Requiring 2D Workplane)
• Workplane Initialization

Initialization (Workplane)

Creating new Workplanes and starting object chains in CadQuery.

Method Summary

Signature / Usage

import cadquery as cq

# Named plane
wp = cq.Workplane("XY")
wp = cq.Workplane("YZ")
wp = cq.Workplane("XZ")
wp = cq.Workplane("front")
wp = cq.Workplane("back")
wp = cq.Workplane("top")
wp = cq.Workplane("bottom")
wp = cq.Workplane("left")
wp = cq.Workplane("right")

# Custom plane with origin offset
wp = cq.Workplane("XY", origin=(0, 0, 10))

# Workplane from an existing Plane object
plane = cq.Plane(origin=(0, 0, 5), xDir=(1, 0, 0), normal=(0, 0, 1))
wp = cq.Workplane(plane)

Options / Props

Workplane(inPlane, origin, obj)

Named Planes Reference

Notes

• The Workplane is the primary entry point for all CadQuery fluent API operations.
• Operations are performed in the local 2D coordinate system of the active workplane.
• Use Workplane.workplane() (stack method) to create a new workplane offset from an existing face or plane after initial construction.
• All coordinates passed to 2D drawing methods are relative to the active workplane origin and axes.

Related

• 2D Operations
• 3D Operations (Requiring 2D Workplane)
• Stack and Selector Methods

Assembly Colors

cq.Color assigns display colors to assembly parts. Accepts RGBA tuples or named color strings.

Signature / Usage

import cadquery as cq

# Named color
cq.Color("black")
cq.Color("yellow")
cq.Color("green")

# RGBA tuple (values 0.0–1.0; alpha controls transparency)
cq.Color(0, 0, 1, 0.2)   # semi-transparent blue
cq.Color(1, 0, 0, 1.0)   # opaque red

# Used in Assembly.add()
assy.add(shape, name="part", color=cq.Color("steelblue"))
assy.add(panel, name="panel", color=cq.Color(0, 0, 1, 0.2))

Options / Props

cq.Color(r, g, b, a=1.0) or cq.Color(name)

Notes

• Over 700 named colors are available (OCCT X11 color set).
• Common names: "red", "green", "blue", "black", "white", "yellow", "gray", "steelblue", "orange", "cyan", "magenta", "gold", "pink", "violet", "brown", "coral", "ivory", "khaki", "lavender", "salmon", "silver", "tan", "teal", "turquoise".
• Gray variants are available as "gray0" through "gray99".
• Color is a display property only; it does not affect geometry or solver behavior.

Related

• tutorial.md

Constraints

Constraint types available for Assembly.constrain(). Each defines a cost function that solve() minimizes.

Signature / Usage

# String-selector form
assy.constrain("part1@faces@>Z", "part2@faces@<Z", "Plane")
assy.constrain("part1@faces@<X", "part2@faces@<X", "Axis", param=0)

# Shape-object form (for BoxSelector or custom selectors)
assy.constrain("part1", part1.faces(">Z").val(), "part2", part2.faces("<Z").val(), "Axis")

# Single-object constraints (Fixed family)
assy.constrain("part1", "Fixed")
assy.constrain("part1@faces@>Z", "FixedAxis", (1, 0, 0))
assy.constrain("part1", "FixedPoint", (0, 0, 5))
assy.constrain("part1", "FixedRotation", (45, 0, 90))

Constraint Types

Two-object constraints

Single-object constraints

Notes

• The string selector syntax is "partName@subtype@directionSelector" (e.g., "left@faces@<Z") or "partName?tagName" for tagged shapes.
• "Plane" is equivalent to applying "Point" + "Axis" together and is the most common mating constraint.
• Only Face, circular Edge, and non-circular Edge are valid for "Axis"; other types raise ValueError.
• Systems can be underconstrained (solver may not move unconstrained parts) or overconstrained (solver finds best fit).

Related

• tutorial.md
• locations.md

Object Locations

cq.Location specifies translation and rotation when adding parts to an assembly.

Signature / Usage

import cadquery as cq

cone = cq.Solid.makeCone(1, 0, 2)

assy = cq.Assembly()
# Add with explicit location: translation tuple, axis tuple, angle (degrees)
assy.add(
    cone,
    loc=cq.Location((0, 0, 0), (1, 0, 0), 180),
    name="cone0",
    color=cq.Color("green"),
)
# Add at default location (origin, no rotation)
assy.add(cone, name="cone1", color=cq.Color("blue"))

show_object(assy)

cq.Location(translation, axis, angle)

Notes

• Locations set via loc= in .add() are overwritten by solve() when constraints are present.
• In underconstrained systems the solver may not move an object that doesn't contribute to any cost function; its initial location is then preserved.
• For complicated assemblies, supplying approximately correct initial locations can reduce solver computation time.
• Use constraints + solve() as the preferred alternative to manually computing locations.

Related

• tutorial.md
• constraints.md

Assemblies

Assembly Tutorial

Step-by-step guide to building a multi-part assembly using cq.Assembly, constraints, and solve().

Signature / Usage

import cadquery as cq

# Instantiate an assembly and add parts
assy = (
    cq.Assembly()
    .add(shape_or_workplane, name="part_name", color=cq.Color("black"), loc=cq.Location(...))
    .add(...)
)

# Define constraints between parts
assy.constrain("part1@faces@>Z", "part2@faces@<Z", "Plane")
assy.constrain("part1@faces@<X", "part2@faces@<X", "Axis")

# Run the constraint solver
assy.solve()

# Export
assy.export("result.step")  # STEP format
assy.export("result.xml")   # OCCT XML format

Options / Props

Assembly() constructor

.add(obj, ...)

.constrain(selector1, selector2, kind, param=...)

Notes

• Tagged faces (rv.faces(">X").tag("X")) can be referenced with "part?tag" syntax.
• solve() overwrites initial locations set with loc=; initial locations only influence convergence in underconstrained or multi-solution systems.
• Shape objects can be passed directly instead of string selectors: .constrain("p1", shape1, "p2", shape2, "Axis") — use .val() to extract a single Shape from a Workplane.

Related

• locations.md
• constraints.md
• colors.md

Core Classes

CadQuery's four primary objects for 2D/3D modeling and assembly.

---

Sketch

A 2D sketch object for constructing planar geometry using edges, constraints, and faces.

Signature / Usage

import cadquery as cq

result = (
    cq.Workplane("XY")
    .placeSketch(
        cq.Sketch()
        .rect(2, 2)
        .circle(0.5, mode="s")
    )
    .extrude(1)
)

Constructor

cadquery.Sketch(parent=None, locs=None, obj=None)

In practice, cq.Sketch() is typically instantiated with no arguments and populated via method chaining.

Key Methods

Notes

• Most methods return self for fluent chaining.
• mode parameter controls how geometry is added: 'a' (add), 's' (subtract), 'i' (intersect), 'c' (construction).
• Use finalize() to return to the parent Workplane after building a sketch.
• solve() must be called after constrain() to compute positions.

Related

• topological.md

---

Workplane

Defines a coordinate system in 3D space from which 2D and 3D modeling operations are performed. The central class of the CadQuery fluent API.

Signature / Usage

import cadquery as cq

result = (
    cq.Workplane("XY")
    .box(10, 10, 5)
    .faces(">Z")
    .workplane()
    .hole(2)
)

Constructor

cadquery.Workplane(
    inPlane: str | Plane | Face = "XY",
    origin: tuple | Vector = (0, 0, 0),
    obj: Shape | None = None
)

Key Methods

Selection

2D Sketching

3D Modeling

Boolean Operations

Navigation & Stack

Export

Notes

• Almost all methods return a new Workplane to enable method chaining.
• The string plane name "XY" selects a named plane; "front", "top", "right" are aliases.
• selector arguments accept either a string (parsed by StringSyntaxSelector) or a Selector instance.
• combine=True automatically fuses results into the existing solid on the stack.

Related

• selectors.md

---

Assembly

Nested assembly of shapes, sub-assemblies, and relative positioning constraints.

Signature / Usage

import cadquery as cq

assy = (
    cq.Assembly()
    .add(cq.Workplane("XY").box(1, 1, 1), name="box")
    .add(cq.Workplane("XY").sphere(0.5), name="ball", loc=cq.Location((0, 0, 1.5)))
)
assy.save("assembly.step")

Constructor

cadquery.Assembly(
    obj: Shape | Workplane | None = None,
    loc: Location | None = None,
    name: str | None = None,
    color: Color | None = None,
    material: Material | None = None,
    metadata: Dict[str, Any] | None = None
)

Key Methods

Properties

Notes

• Constraint kinds include "Plane", "Point", "Axis", "Fixed" among others.
• solve() must be called before toCompound() or save() when constraints are used.
• Assembly name values must be unique within the hierarchy.
• Sub-assemblies can be nested arbitrarily deep via repeated add() calls.

Related

• geometry.md

---

Constraint

An alias for ConstraintSpec, used internally by Assembly.constrain() to define positional relationships between components.

Signature / Usage

# Constraints are added via Assembly.constrain(), not instantiated directly:
assy.constrain("box?top_face", "ball?bottom_face", "Plane")
assy.solve()

Notes

• Constraint is an alias of ConstraintSpec — direct instantiation is rarely needed.
• Constraints are resolved by calling Assembly.solve().
• The query strings passed to Assembly.constrain() use the form "<name>?<selector>".

Related

• core.md — Assembly

Geometry Classes

Geometric primitives and spatial data structures used throughout CadQuery.

---

Vector

A 3-dimensional vector supporting standard mathematical operations.

Signature / Usage

import cadquery as cq

v = cq.Vector(1, 0, 0)
n = v.normalized()
p = v.projectToPlane(cq.Vector(0, 0, 1))

Constructor

cadquery.Vector(x: float = 0, y: float = 0, z: float = 0)
cadquery.Vector(v: tuple | list)          # From 2- or 3-tuple
cadquery.Vector(v: gp_Vec | gp_Pnt | ...)  # From OCC object

Key Methods

Properties

Notes

• Supports +, -, *, /, == operators.
• Interoperable with Python tuples: most CadQuery methods accept (x, y, z) tuples in place of Vector.

---

Matrix

A 4×4 homogeneous transformation matrix for 3D affine transforms.

Signature / Usage

import cadquery as cq

m = cq.Matrix()
row = m[0]          # Access row as list
t = m.transposed_list()

Constructor

cadquery.Matrix()

Matrices are typically constructed by CadQuery internally (e.g., from Plane or Location objects).

Key Methods

Notes

• Wraps OpenCASCADE's gp_Trsf / gp_Mat objects.
• Pickle-serializable via __getstate__ / __setstate__.

---

Plane

A 2D coordinate system embedded in 3D space, defined by an origin, X direction, and normal.

Signature / Usage

import cadquery as cq

# Named planes
xy = cq.Plane.named("XY")
xz = cq.Plane.named("XZ")

# Custom plane
p = cq.Plane(origin=(0, 0, 5), xDir=(1, 0, 0), normal=(0, 0, 1))

# Coordinate conversion
world_pt = p.toWorldCoords((1, 2))
local_pt = p.toLocalCoords(cq.Vector(1, 2, 5))

Constructor

cadquery.Plane(
    origin: Vector | tuple,
    xDir: Vector | tuple = (1, 0, 0),
    normal: Vector | tuple = (0, 0, 1)
)

Key Methods

Properties

Notes

• Named planes: "XY", "YZ", "XZ", "front", "back", "left", "right", "top", "bottom".
• Supports == and != for comparison; hashable for use in sets/dicts.

---

Location

A position and orientation in 3D space (translation + rotation).

Signature / Usage

import cadquery as cq

# From a translation vector
loc = cq.Location((1, 2, 3))

# From a plane (sets orientation)
loc = cq.Location(cq.Plane.XY)

# From vector + rotation axis + angle
loc = cq.Location(cq.Vector(0, 0, 10), cq.Vector(0, 0, 1), 45)

t = loc.toTuple()  # ((x,y,z), (rx,ry,rz))

Constructor

cadquery.Location(t: Any)

Accepts: (x,y,z) tuple, Vector, Plane, OCC TopLoc_Location, or (translation, rotation) tuple.

Key Methods

Notes

• Location supports * operator for composition and **-1 for inversion.
• Used extensively in Assembly and Sketch for positioning.
• Pickle-serializable.

---

BoundBox

An axis-aligned bounding box for shapes or point sets.

Signature / Usage

import cadquery as cq

shape = cq.Workplane("XY").box(10, 5, 3).val()
bb = shape.BoundingBox()
print(bb.xmin, bb.xmax, bb.ymin, bb.ymax, bb.zmin, bb.zmax)

Constructor

cadquery.BoundBox(bb: Bnd_Box)

Typically obtained from Shape.BoundingBox(), not constructed directly.

Key Methods

Properties

---

Color

An RGBA color wrapper around OpenCASCADE's Quantity_ColorRGBA.

Signature / Usage

import cadquery as cq

c1 = cq.Color("red")               # Named color
c2 = cq.Color(1.0, 0.5, 0.0)       # RGB, alpha=0
c3 = cq.Color(0.0, 1.0, 0.0, 0.5)  # RGBA
rgba = c2.toTuple()                 # (1.0, 0.5, 0.0, 0.0)

Constructor

cadquery.Color(name: str)
cadquery.Color(r: float, g: float, b: float, a: float = 0, srgb: bool = True)

Key Methods

Notes

• Supports == and is hashable.
• Alpha convention: 0 = fully opaque, 1 = fully transparent (OCC convention).

---

Material

Material properties used in Assembly for simulation or export metadata.

Signature / Usage

import cadquery as cq

mat = cq.Material()
mat.name = "steel"
mat.density = 7850.0
mat.densityUnit = "kg/m^3"
mat.description = "Carbon steel"

Constructor

cadquery.Material()

Properties

Key Methods

Notes

• Supports ==, hashing, and pickle serialization.
• Passed to Assembly or Shape metadata; not used for physical simulation by CadQuery itself.

CadQuery Class Reference

Selector Classes

Selectors filter lists of topological objects (vertices, edges, faces, solids, etc.) returned by Workplane selection methods. They can be composed using binary operators.

---

Selector (Abstract Base)

Base class for all selectors. Defines the interface.

Signature / Usage

# Selectors are passed to Workplane selection methods:
result = cq.Workplane("XY").box(1,1,1).faces(cq.selectors.NearestToPointSelector((0,0,1)))

Constructor

cadquery.selectors.Selector()

Key Methods

Notes

• Subclass and override filter() to implement custom selectors.
• Selectors support |, &, -, ! operators for composition (see Binary Selectors).

---

NearestToPointSelector

Selects the single object (vertex, edge, face, or solid) whose center is nearest to a given point.

Constructor

cadquery.selectors.NearestToPointSelector(pnt: tuple | Vector)

Key Methods

Notes

• Returns exactly one object: the closest by center-of-mass distance.

---

BoxSelector

Selects objects whose bounding box center lies within a 3D box defined by two corner points.

Constructor

cadquery.selectors.BoxSelector(
    point0: tuple | Vector,
    point1: tuple | Vector,
    boundingbox: bool = False
)

Key Methods

---

BaseDirSelector

Abstract base class for direction-based selectors.

Constructor

cadquery.selectors.BaseDirSelector(
    vector: Vector | tuple,
    tolerance: float = 0.0001
)

Key Methods

Notes

• Override test(vec) in subclasses to define the directional criterion.

---

DirectionSelector

Selects edges or faces whose normal/direction is aligned with (within tolerance of) the given vector.

Constructor

cadquery.selectors.DirectionSelector(
    vector: Vector | tuple,
    tolerance: float = 0.0001
)

String syntax: "+X", "-Y", "+Z" etc. (positive/negative axis directions).

Notes

• For edges: selects edges parallel to the vector.
• For faces: selects faces whose normal matches the vector.

---

ParallelDirSelector

Selects objects whose direction is parallel (regardless of sign) to the given vector.

Constructor

cadquery.selectors.ParallelDirSelector(
    vector: Vector | tuple,
    tolerance: float = 0.0001
)

String syntax: "|X", "|Y", "|Z".

Notes

• Differs from DirectionSelector in that anti-parallel (180°) also matches.

---

PerpendicularDirSelector

Selects objects whose direction is perpendicular to the given vector.

Constructor

cadquery.selectors.PerpendicularDirSelector(
    vector: Vector | tuple,
    tolerance: float = 0.0001
)

String syntax: "#X", "#Y", "#Z".

---

DirectionMinMaxSelector

Selects the object(s) that are farthest (directionMax=True) or closest (directionMax=False) along a given direction.

Constructor

cadquery.selectors.DirectionMinMaxSelector(
    vector: Vector | tuple,
    directionMax: bool = True,
    tolerance: float = 0.0001
)

String syntax: ">X", ">Y", ">Z" (max); "<X", "<Y", "<Z" (min).

Notes

• Uses center of mass for distance calculation.
• Multiple objects at the same extremal position are all returned.

---

DirectionNthSelector

Selects the Nth group of objects when sorted by their projection onto a direction vector.

Constructor

cadquery.selectors.DirectionNthSelector(
    vector: Vector | tuple,
    n: int,
    directionMax: bool = True,
    tolerance: float = 0.0001
)

String syntax: ">X[0]", "<Z[-1]" etc.

---

TypeSelector

Selects objects of a specific topological type.

Constructor

cadquery.selectors.TypeSelector(typeString: str)

String syntax: "%Plane" (planar faces), "%Line" (linear edges), "%Circle" (circular edges).

---

RadiusNthSelector

Selects the object(s) with the Nth smallest or largest radius among arc/circle edges.

Constructor

cadquery.selectors.RadiusNthSelector(
    n: int,
    directionMax: bool = True,
    tolerance: float = 0.0001
)

Key Methods

---

CenterNthSelector

Selects the Nth object when sorted by the projection of its center onto a given direction.

Constructor

cadquery.selectors.CenterNthSelector(
    vector: Vector | tuple,
    n: int,
    directionMax: bool = True,
    tolerance: float = 0.0001
)

String syntax: ">>X[0]", "<<Z[-1]" etc.

Key Methods

---

LengthNthSelector

Selects the Nth object when sorted by arc length (for edges/wires).

Constructor

cadquery.selectors.LengthNthSelector(
    n: int,
    directionMax: bool = True,
    tolerance: float = 0.0001
)

Key Methods

---

AreaNthSelector

Selects the Nth object when sorted by surface area (for faces).

Constructor

cadquery.selectors.AreaNthSelector(
    n: int,
    directionMax: bool = True,
    tolerance: float = 0.0001
)

Key Methods

---

BinarySelector

Abstract base class for selectors that combine two child selectors.

Constructor

cadquery.selectors.BinarySelector(left: Selector, right: Selector)

Key Methods

---

AndSelector

Returns the intersection of two selectors (objects matching both).

Constructor

cadquery.selectors.AndSelector(left: Selector, right: Selector)

String syntax: "<selectorA> and <selectorB>" or "<selectorA> & <selectorB>".

Signature / Usage

import cadquery as cq

result = (
    cq.Workplane("XY").box(1, 1, 1)
    .edges(cq.selectors.AndSelector(
        cq.selectors.ParallelDirSelector((0, 0, 1)),
        cq.selectors.LengthNthSelector(0)
    ))
)

---

SumSelector

Returns the union of two selectors (objects matching either).

Constructor

cadquery.selectors.SumSelector(left: Selector, right: Selector)

String syntax: "<selectorA> or <selectorB>" or "<selectorA> | <selectorB>".

---

SubtractSelector

Returns objects matching the left selector but not the right.

Constructor

cadquery.selectors.SubtractSelector(left: Selector, right: Selector)

String syntax: "<selectorA> exc <selectorB>" or "<selectorA> except <selectorB>".

---

InverseSelector

Returns all objects that do NOT match a given selector.

Constructor

cadquery.selectors.InverseSelector(selector: Selector)

String syntax: "not(<selectorString>)".

Key Methods

---

StringSyntaxSelector

Parses and evaluates a compact string-based selector expression. Used internally by Workplane selection methods when a string argument is provided.

Signature / Usage

import cadquery as cq

# Equivalent pairs — string and explicit selector:
cq.Workplane("XY").box(1,1,1).faces(">Z")
cq.Workplane("XY").box(1,1,1).faces(cq.selectors.StringSyntaxSelector(">Z"))

Constructor

cadquery.selectors.StringSyntaxSelector(selectorString: str)

Key Methods

String Syntax Reference

Direction / alignment tokens

Type tokens

Indexed variants (ordinal selection)

>Z[0]    # farthest (same as >Z)
>Z[-1]   # second-farthest from negative end = second-closest
<Y[1]    # second-closest in Y

Composite operators

Notes

• String selectors are parsed at runtime; invalid tokens raise a ValueError.
• Custom direction vectors can be used: ">(1, 1, 0)".
• Index notation [n] supports negative indices (Python-style).
• StringSyntaxSelector is the default when passing a plain string to faces(), edges(), etc.

Topological Classes

Low-level wrappers around OpenCASCADE topology objects. All inherit from Shape.

---

Shape

Base class for all geometric objects in CadQuery. Wraps a TopoDS_Shape from OpenCASCADE.

Constructor

cadquery.Shape(obj: TopoDS_Shape)

Key Methods

Topology Access

Geometry Queries

Transformations

Boolean Operations

Utilities

Notes

• Shape is not instantiated directly; use the concrete subclasses.
• Transformations return new Shape instances; they do not mutate in-place unless explicitly noted.

---

Vertex

A single point in 3D space.

Constructor

cadquery.Vertex(obj: TopoDS_Shape, forConstruction: bool = False)

Key Methods

Related

• geometry.md — Vector

---

Edge

A trimmed curve that forms the border of a Face. Inherits Mixin1D and Shape.

Constructor

cadquery.Edge(obj: TopoDS_Shape)

Key Methods

Factory / Creation (classmethods)

Instance Methods

Curve analysis methods inherited from Mixin1D are also available.

Notes

• Construction edges (forConstruction=True) do not participate in face/wire building.

Related

• topological.md — Mixin1D

---

Wire

A series of connected, ordered Edges that typically bounds a Face. Inherits Mixin1D and Shape.

Constructor

cadquery.Wire(obj: TopoDS_Shape)

Key Methods

Factory / Creation (classmethods)

Instance Methods

Notes

• A closed wire is required to create a Face.
• assembleEdges automatically orders and joins edges.

---

Face

A bounded surface representing part of the boundary of a solid. Inherits Mixin3D and Shape.

Constructor

cadquery.Face(obj: TopoDS_Shape)

Key Methods

Factory / Creation (classmethods)

Query Methods

Modification Methods

Related

• topological.md — Mixin3D

---

Shell

The outer boundary of a surface, formed from a connected set of Faces.

Constructor

cadquery.Shell(obj: TopoDS_Shape)

Key Methods

Notes

• Shells are rarely created directly; they arise from solid creation operations.

---

Solid

A single closed 3D volume. Inherits Mixin3D and Shape.

Constructor

cadquery.Solid(obj: TopoDS_Shape)

Key Methods

Factory / Creation (classmethods)

Modification (instance methods)

Query

Related

• topological.md — Mixin3D

---

Compound

A collection of disconnected shapes (solids, wires, edges, etc.). Inherits Mixin3D and Shape.

Constructor

cadquery.Compound(obj: TopoDS_Shape)

Key Methods

Notes

• Compound is the result type of most multi-shape operations (e.g., arrays, text).

---

CompSolid

A composite solid — multiple solids sharing boundary faces.

Constructor

cadquery.CompSolid(obj: TopoDS_Shape)

Notes

• CompSolid is rarely used directly in CadQuery; it maps to TopoDS_CompSolid in OpenCASCADE.
• Arises from some import operations on STEP files with shared topology.

---

Mixin1D

Mixin class providing parametric curve analysis methods for 1D shapes (Edge, Wire).

Key Methods

Notes

• mode='length' interprets d as arc length; mode='parameter' interprets it as the raw OCC parameter.
• frame='frenet' uses Frenet frame; frame='corrected' avoids discontinuities on helices.

---

Mixin3D

Mixin class providing post-processing operations for 3D shapes (Face, Shell, Solid, Compound).

Key Methods

Notes

• fillet and chamfer operate on edgeList; pass None to apply to all edges.
• hollow is equivalent to Workplane.shell().