3D Primitives
cube
Create a box (rectangular prism) in the first octant. When center is true, the cube is centered at the origin.
Syntax:
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
size |
number or [x, y, z] |
1 |
A single number creates a cube; a list creates a box with those dimensions |
center |
bool or string | False |
True centers on origin; a 3-char string controls per-axis centering |
PythonSCAD extensions:
The center parameter accepts a 3-character string where each character controls centering on one axis (X, Y, Z):
|,0,_, or space: center on this axis<,[,(, or-: align to negative side (default, same ascenter=False)>,],), or+: align to positive side
Examples:
OpenSCAD reference: cube
sphere
Create a sphere centered at the origin.
Syntax:
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
r |
number or function | 1 |
Radius of the sphere, or a Python function f(v) -> radius |
d |
number | — | Diameter (alternative to r; cannot specify both) |
style |
string | "orig" |
Tessellation style: "orig" (latitude rings) or "octa" (subdivided octahedron; poles and equator match cylinder() fragment count) |
fn |
int | — | Number of segments for full circle |
fa |
float | — | Minimum angle per segment |
fs |
float | — | Minimum segment size |
PythonSCAD extensions:
The r parameter can be a Python function that receives a 3D direction vector and returns a radius, creating a deformed sphere:
Examples:
OpenSCAD reference: sphere
cylinder
Create a cylinder or cone centered on the Z axis. The base sits on the XY plane unless center is true.
Syntax:
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
h |
number | 1 |
Height of the cylinder |
r |
number | 1 |
Radius (both top and bottom) |
r1 |
number | — | Bottom radius (for cones) |
r2 |
number | — | Top radius (for cones) |
d |
number | — | Diameter (alternative to r) |
d1 |
number | — | Bottom diameter |
d2 |
number | — | Top diameter |
center |
bool | False |
Center vertically on origin |
angle |
float | 360 |
Arc angle in degrees (PythonSCAD extension) |
fn |
int | — | Number of segments |
fa |
float | — | Minimum angle per segment |
fs |
float | — | Minimum segment size |
PythonSCAD extensions:
The angle parameter creates a partial cylinder (pie/wedge shape):
Examples:
OpenSCAD reference: cylinder
polyhedron
Create a 3D solid from a list of vertices and face indices.
Syntax:
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
points |
list of [x, y, z] |
— | Vertex coordinates |
faces |
list of index lists | — | Each face is a list of vertex indices (counterclockwise when viewed from outside) |
convexity |
int | 2 |
Maximum number of front/back faces a ray can intersect |
triangles |
list | — | Deprecated alias for faces (triangles only) |
colors |
list | — | Per-face colors |
Examples:
from pythonscad import *
pts = [
[0, 0, 0], [10, 0, 0], [10, 10, 0], [0, 10, 0],
[0, 0, 10], [10, 0, 10], [10, 10, 10], [0, 10, 10]
]
faces = [
[0, 1, 2, 3], # bottom
[4, 5, 6, 7], # top
[0, 1, 5, 4], # front
[1, 2, 6, 5], # right
[2, 3, 7, 6], # back
[3, 0, 4, 7], # left
]
polyhedron(pts, faces).show()
You can also reconstruct a solid from its mesh data:
OpenSCAD reference: polyhedron
rounded_cube
Create a cube or box with uniformly rounded edges and corners. This is a PythonSCAD-only helper (not part of upstream OpenSCAD).
The given size is the outer extent of the solid, including the
rounding. You must specify exactly one of r (radius) or d
(diameter); supplying both or neither raises TypeError.
By default, rounded_cube() is positioned like cube(size), with its minimum
corner at the origin. center=False and center=None both keep that behavior;
set center=True to center the generated shape's bounding box on the origin.
Syntax:
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
size |
number or [x, y, z] |
— | Outer edge length for a cube, or outer box dimensions |
r |
number | — | Rounding radius. Cannot be used with d |
d |
number | — | Rounding diameter. Cannot be used with r |
center |
bool or None |
False |
If True, center the generated shape's bounding box on the origin. If False or None, place it in the positive octant |
fn |
int | — | Number of segments for the rounding sphere |
fa |
float | — | Minimum angle per rounding-sphere segment |
fs |
float | — | Minimum rounding-sphere segment size |
Examples:
patch
Build a triangulated surface stitched onto one outer boundary ring and zero or more inner boundary rings ("holes"), optionally displaced along its normal and optionally curved via per-ring tangents. This is a PythonSCAD-only extension (not part of upstream OpenSCAD).
Together with concat(), patch() gives you a second way to build a
manifold solid, alongside ordinary CSG. Rather than combining primitives
with boolean operations, you describe the object's surface directly: each
patch() call builds one wall, panel, or bridge as a mesh whose boundary
points line up exactly with its neighbors, and concat() stitches those
pieces into a single watertight object.
Syntax:
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
outer |
list of [x, y, z] points, or a 2D shape |
— | The outer boundary ring |
holes |
list of rings (each a list of points or a 2D shape) | None |
Zero or more inner boundary rings to cut out of the surface |
proj |
function (point) -> [u, v] |
None |
How to flatten the boundary into a 2D domain for triangulation. Left as None, patch() picks automatically — see Automatic behavior below |
grid_spacing_uv |
number | 1.0 |
Target spacing between interior mesh points, in the flattened domain's own units. Smaller values give a finer mesh at higher cost |
displacement |
function (point) -> number |
None |
A bump/texture function evaluated at each interior point and applied along the local surface normal. Boundary points are never displaced, so neighboring patch()/concat() calls still line up exactly |
use_tangents |
bool | False |
Bows the surface using each ring's own plane normal as a tangent, instead of a flat interpolation between rings. See use_tangents below |
Automatic behavior:
outer and each entry of holes is a closed ring of points (or a 2D
shape, converted to one). patch() recognizes three shapes of input
automatically, with no need to say which one you're building:
- Panel with cutouts —
outerand the holes lie roughly in one plane. The plane is found automatically and the interior is filled in, with the holes cut out. - Tube wall —
outerand one hole ("the tube partner") sit far apart along a shared axis, like one ring of a vase wall. Any further holes (e.g. mounting holes drilled through the wall, at any angle) get their own real 2D shape regardless of orientation, instead of collapsing to a line under a plain top-down view. - Bridge between two separate rings — when
outerand a single hole are two rings that don't nest inside one another (e.g. two side ports that a handle needs to arc between),patch()connects them directly, point by point, along a curve built from each point's own position and (if supplied) tangent.
use_tangents:
use_tangents=True uses a ring's own plane normal as its tangent — "the
surface should leave this ring perpendicular to the shape's own plane."
This is correct for a ring that is genuinely a side port (a hole drilled
straight through a wall, or a handle mount), but not for an ordinary
tapered profile: two unrotated circles forming a cone both have plane
normals pointing straight up, which is not the direction the cone's wall
actually travels, and would bow an otherwise straight wall into a bulge.
Leave this at the default (False) unless a ring is genuinely meant to be
left at a right angle to its own plane.
Examples:
Performance:
patch()'s cost scales with the number of boundary and interior mesh
points, controlled by grid_spacing_uv: halving it roughly quadruples the
point and triangle count. Prefer the coarsest grid_spacing_uv that still
looks acceptable before reaching for other tuning.