ScadPy

Programmatic CAD in Pure Python. — Documentation

ScadPy is a parametric modeling library for Python. Define 2D shapes and 3D solids with a fluent, chainable API: boolean operations, extrusions, fillets, patterns and topology queries. Export to STL, DXF, SVG or render interactively.

Built on Shapely for 2D geometry, trimesh for 3D meshes and NumPy for topology queries (vertex coordinates, edge normals, ring types and more). If you know OpenSCAD, the approach will feel familiar.

Installation

pip install scadpy

Requirements: Python ≥ 3.12.

Quick examples

# 2D — chamfered mounting plate
from scadpy import rectangle, circle, text
import numpy as np

PLATE_WIDTH   = 80
PLATE_HEIGHT  = 50
PLATE_THICKNESS = 10
HOLE_RADIUS   = 4
HOLE_MARGIN   = 10
CHAMFER_SIZE  = 8

base  = rectangle([PLATE_WIDTH, PLATE_HEIGHT])
plate = base.chamfer(CHAMFER_SIZE)

for position, normal in zip(base.vertex_coordinates, base.vertex_normals):
    hole_center = position - HOLE_MARGIN * np.sqrt(2) * normal
    plate -= circle(HOLE_RADIUS).translate(hole_center)

plate.to_screen()

# 3D — extruded mounting plate with label (continues from above)
TEXT_THICKNESS = 2

extruded_plate = plate.linear_extrude(PLATE_THICKNESS)
label = text("ScadPy", size=15).linear_extrude(TEXT_THICKNESS)
extruded_plate |= label.translate(z(PLATE_THICKNESS))
extruded_plate.to_screen()

# 3D — parametric ball bearing
from scadpy import circle, rectangle, sphere, x, y, GRAY, ORANGE

BALL_RADIUS    = 3
RACE_RADIUS    = 15
NB_BALLS       = 11
CLEARANCE      = 0.1
RING_HEIGHT    = 7
RACE_THICKNESS = 10

groove  = circle(BALL_RADIUS + CLEARANCE) | rectangle([BALL_RADIUS, RING_HEIGHT])
race    = rectangle([RACE_THICKNESS, RING_HEIGHT]) - groove
bearing = race.radial_extrude(axis=y(), pivot=x(RACE_RADIUS)).color(GRAY)
ball    = sphere(BALL_RADIUS).color(ORANGE)
bearing += ball.radial_pattern(count=NB_BALLS, axis=y(), pivot=x(RACE_RADIUS))

bearing.to_screen()

# 3D — dice
from scadpy import cuboid, sphere, x, y, z

SIZE = 20
dice = cuboid(SIZE)
pip  = sphere(SIZE / 12).translate(z(SIZE / 2))

one   = pip
two   = pip.translate([SIZE / 4, SIZE / 4, 0]) + pip.translate([-SIZE / 4, -SIZE / 4, 0])
three = one + two
four  = two + two.rotate(90, z())
five  = one + four
six   = four + pip.translate(x(SIZE / 4)) + pip.translate(x(-SIZE / 4))

dice -= (
    one
    + two.rotate(90, x())
    + three.rotate(90, y())
    + four.rotate(-90, y())
    + five.rotate(-90, x())
    + six.rotate(-180, x())
)

dice.to_screen()

# 3D — storage box
from scadpy import square, x, z

SIZE_OUTER      = 20
SIZE_INNER      = 18
FILLET          = 1
BASE_HEIGHT     = 10
CUT_HEIGHT      = 8
CAP_HEIGHT_OUTER = 1.5
CAP_HEIGHT_INNER = 3
CAP_OFFSET_X    = 25
CUT_OFFSET_Z    = 2

outer_base = square(SIZE_OUTER).fillet(FILLET).linear_extrude(BASE_HEIGHT)
inner_cut  = square(SIZE_INNER).linear_extrude(CUT_HEIGHT).translate(z(CUT_OFFSET_Z))
base       = outer_base - inner_cut

cap_outer = square(SIZE_OUTER).fillet(FILLET).linear_extrude(CAP_HEIGHT_OUTER)
cap_inner = square(SIZE_INNER).linear_extrude(CAP_HEIGHT_INNER)
cap       = (cap_outer | cap_inner).translate(x(CAP_OFFSET_X))

storage_box = base + cap
storage_box.to_screen()

AI integration

ScadPy ships a machine-readable skill file (ai-skills.txt) that lets AI assistants understand the full API without reading source code — signatures, descriptions, parameters, return types, and usage examples, extracted directly from the source.

Cheat sheet

Parameters shown in # comments are optional, with their default values.

2D — Shape

from scadpy import *

# primitives
circle(radius=3)                                # segment_count=64
polygon(points=[(-2, -2), (2, -2), (0, 2)])
rectangle(size=[6, 3])
Shape.from_dxf("file.dxf")
Shape.from_svg("file.svg")
square(size=4)

# boolean operations
s = square(size=4);  c = circle(radius=3)
s | c    # union
s - c    # difference
s & c    # intersection
s ^ c    # symmetric difference
s + c    # concat (no merge)

# transforms
s.chamfer(size=0.8)              # vertex_filter=None, epsilon=1e-8
s.color(color=RED)
s.convexify()                    # part_filter=None
s.fill()                         # part_filter=None
s.fillet(size=0.8)               # vertex_filter=None, segment_count=32, epsilon=1e-8
s.grow(distance=0.5)             # part_filter=None
s.linear_cut(axis=x())          # pivot=0
s.linear_pattern(counts=4, steps=x(3))        # counts=[nx, ny], steps=[sx, sy]
s.linear_slice(thickness=2, direction=x())  # pivot=0, part_filter=None
s.mirror(normal=[1, 0])          # pivot=0
s.pull(distance=1.0)             # pivot=0, vertex_filter=None
s.push(distance=1.0)             # pivot=0, vertex_filter=None
s.radial_pattern(count=6)        # angle=360, pivot=0
s.radial_slice(start=0, end=180) # pivot=0, part_filter=None
s.resize(size=[6, None])         # auto=False, pivot=None, vertex_filter=None
s.rotate(angle=30)               # pivot=0, vertex_filter=None
s.scale(scale=[2, 0.5])          # pivot=0, vertex_filter=None
s.shrink(distance=0.5)           # part_filter=None
s.translate(translation=[2, 1])  # vertex_filter=None

# features
s.bounds                         # [min_x, min_y, max_x, max_y]
s.bounding_box                   # → Shape (rectangle)
s.centroid                       # [cx, cy] — geometric centroid
s.is_empty                       # bool

# topology — coordinates & attributes
s.are_vertices_convex            # (n_vertices,)   — convexity mask
s.directed_edge_directions       # (2*n_edges, 2)
s.edge_lengths                   # (n_edges,)
s.edge_midpoints                 # (n_edges,  2)
s.edge_normals                   # (n_edges,  2)
s.ring_types                     # (n_rings,)  — "exterior"|"interior"
s.vertex_angles                  # (n_vertices,)   — interior angles (°)
s.vertex_coordinates             # (n_vertices, 2)
s.vertex_normals                 # (n_vertices, 2) — outward unit normals

# topology — bridges (*_to_*)
s.directed_edge_to_edge             # directed_edge → edge
s.directed_edge_to_vertex           # directed_edge → [start, end]
s.edge_to_vertex                    # edge          → [start, end]
s.ring_to_part                      # ring          → part
s.vertex_to_incoming_directed_edge  # vertex        → directed_edge
s.vertex_to_outgoing_directed_edge  # vertex        → directed_edge
s.vertex_to_neighbor_vertex       # vertex        → [prev, next]
s.vertex_to_part                    # vertex        → part
s.vertex_to_ring                    # vertex        → ring

# extrusions → Solid
s.linear_extrude(height=3)
s.radial_extrude(axis=y(), pivot=x(5))  # start=0, end=360, segment_count=64
s.path_extrude(path)                    # fillet_segments=None, min_fillet_radius=None, intermediate_sections=None, strategy=None

# sweep strategies (for path_extrude strategy= parameter)
scale_sweep(end=3)                      # start=1.0
rotate_sweep(angle=360)                 # start_angle=0.0
resize_sweep(end_size=[2, 4])           # start_size=None
reverse_sweep(strategy=scale_sweep(3))

# export
s.to_dxf_file("output.dxf")
s.to_html_file("output.html")
s.to_screen()
s.to_svg_file("output.svg")

3D — Solid

from scadpy import *

# primitives
cone(radius=2, height=4)         # segment_count=64
cuboid(size=[4, 3, 2])
cylinder(radius=2, height=4)     # segment_count=64
polyhedron(vertices=vertices, faces=faces)
sphere(radius=3)                 # subdivision_count=4
Solid.from_stl("model.stl")

# boolean operations
a = cuboid(size=[4, 3, 2]);  b = sphere(radius=2)
a | b    # union
a - b    # difference
a & b    # intersection
a ^ b    # symmetric difference
a + b    # concat (no merge)

# transforms
a.color(color=RED)
a.convexify()                    # part_filter=None
a.linear_pattern(counts=4, steps=x(3))        # counts=[nx, ny, nz], steps=[sx, sy, sz]
a.mirror(normal=[1, 0, 0])       # pivot=0
a.pull(distance=1.0)             # pivot=0, vertex_filter=None
a.push(distance=1.0)             # pivot=0, vertex_filter=None
a.radial_pattern(count=6, axis=z())            # angle=360, pivot=0
a.resize(size=[6, None, None])   # auto=False, pivot=None, vertex_filter=None
a.rotate(angle=30, axis=z())    # pivot=0, vertex_filter=None
a.scale(scale=[2, 1, 0.5])       # pivot=0, vertex_filter=None
a.translate(translation=[1, 0, 0])  # vertex_filter=None

# features
a.bounds                         # [min_x, min_y, min_z, max_x, max_y, max_z]
a.bounding_box                   # → Solid (cuboid)
a.centroid                       # [cx, cy, cz] — geometric centroid
a.is_empty                       # bool

# topology — coordinates & bridges (*_to_*)
a.triangle_to_vertex    # triangle → [v0, v1, v2]
a.vertex_coordinates    # (n_vertices,  3)
a.vertex_to_part        # vertex   → part

# export
a.to_html_file("output.html")
a.to_screen()
a.to_stl_file("output.stl")

Roadmap

• Improve documentation
• Richer topology for Shape and Solid
• Richer transformations for Shape and Solid
• Chamfer and fillet on Solid
• New assembly types: PointCloud2d, Wire2d, PointCloud3d, Wire3d
• Better error messages
• More import/export formats

Development

# Create and activate venv
python3 -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e .[dev]

# Run doctests & generate documentation & AI skill file
cd docs && make doctest && make html && make skills

License

See LICENSE.md.