Skip to content

Object Properties and Inspection

These functions and properties let you inspect and extract data from solid objects.

size

Get the bounding box dimensions of an object.

Syntax:

obj.size
size(obj)

Returns: A vector [width, height, depth] for 3D objects or [width, height] for 2D objects. Both 2D and 3D results support vector arithmetic (e.g. obj.size * 2).

Examples:

from pythonscad import *

c = cube([10, 20, 30])
print(c.size)  # [10.0, 20.0, 30.0]

s = square([10, 20])
print(s.size)       # [10.0, 20.0]
print(s.size * 2)   # [20.0, 40.0]

position

Get the minimum corner coordinates of the bounding box.

Syntax:

obj.position
position(obj)

Returns: A vector [x, y, z] for 3D objects or [x, y] for 2D objects, representing the minimum corner of the bounding box. Both support vector arithmetic, so e.g. obj.translate(obj.position * -1) recenters 2D or 3D objects alike.

Examples:

from pythonscad import *

c = cube(10).translate([5, 5, 5])
print(c.position)  # [5.0, 5.0, 5.0]

s = square(10).translate([3, 4])
print(s.position)                  # [3.0, 4.0]
s.translate(s.position * -1).show()  # back to the origin

bbox

Get the bounding box as a solid object.

Syntax:

obj.bbox
bbox(obj)

Returns: A cube (3D) or square (2D) representing the bounding box of the object.

Examples:

from pythonscad import *

s = sphere(10)
s.bbox.color("red", alpha=0.3).show()
s.show()

mesh

Extract the mesh data (vertices and triangles) from a solid.

Syntax:

obj.mesh(triangulate=True, color=False)
mesh(obj, triangulate=True, color=False)

Parameters:

Parameter Type Default Description
obj solid — The object to extract mesh from
triangulate bool True Triangulate faces
color bool False Include color data

Returns: A tuple (points, triangles) where points is a list of [x, y, z] coordinates and triangles is a list of vertex index lists.

Examples:

from pythonscad import *

c = cube(10)
pts, tris = c.mesh()

# Modify vertices and reconstruct
for pt in pts:
    if pt[2] > 5:
        pt[0] += 3
polyhedron(pts, tris).show()

faces

Get a list of face solids from an object. Each face is a 2D solid with a matrix property indicating its orientation in 3D space.

Syntax:

obj.faces(triangulate=False)
faces(obj, triangulate=False)

Parameters:

Parameter Type Default Description
obj solid — The object to extract faces from
triangulate bool False Return triangulated faces

Returns: A list of 2D solid objects, each with a .matrix attribute (4x4 transformation matrix showing the face's position and orientation).

Examples:

from pythonscad import *

core = sphere(r=2)
face_list = core.faces()

flower = core
for f in face_list:
    flower |= f.linear_extrude(height=4)
flower.show()

edges

Get a list of edge solids from a face or 2D object.

Syntax:

obj.edges()
edges(obj)

Returns: A list of edge solids, each with a .matrix attribute.

Examples:

from pythonscad import *

sq = square(10)
edge_list = sq.edges()
print(len(edge_list))

inside

Check whether a given point is inside an object (2D or 3D).

Syntax:

obj.inside(point)
inside(obj, point)

Parameters:

Parameter Type Description
obj solid The 2D or 3D object to test against
point [x, y] or [x, y, z] Point to test. Use 2 components for 2D objects; use 3 for 3D. Missing components default to 0. Extra components beyond the object dimension are ignored for 2D.

Returns: True if the point is classified as inside, False otherwise.

  • 2D: Points in the interior or on the boundary (edge or vertex) return True.
  • 3D: Uses a ray-crossing test; points exactly on the surface are not guaranteed to return True.

Examples:

from pythonscad import *

c = cube(10)
print(c.inside([5, 5, 5]))   # True
print(c.inside([15, 5, 5]))  # False

s = square(10, center=True)
print(s.inside([0, 0]))      # True (interior)
print(s.inside([5, 0]))      # True (on edge)
print(s.inside([5, 5]))      # True (on vertex)
print(s.inside([10, 10]))    # False

children

Get the child nodes of a compound solid as a tuple.

Syntax:

obj.children()
children(obj)

Returns: A tuple of child solid objects.

Examples:

from pythonscad import *

u = union(cube(5), sphere(3))
parts = u.children()
print(len(parts))  # 2

c

Read the RGBA color of the root color() wrapper on a solid.

Syntax:

obj.c      # attribute access
obj["c"]   # mapping protocol

Returns: (r, g, b, a) as a tuple of floats in [0, 1] when the outermost node is a color() wrapper, None otherwise.

Examples:

from pythonscad import *

c = cube(10).color("Red")
print(c.c)          # (1.0, 0.0, 0.0, 1.0)
print(c["c"])       # (1.0, 0.0, 0.0, 1.0)  — mapping protocol

print(cube(10).c)   # None — no color wrapper

u = cube(1).color("Red") | sphere(2).color("Blue")
print(u.c)            # None — union is the root, not a ColorNode
print(u.children()[0].c)  # (1.0, 0.0, 0.0, 1.0)
print(u.children()[1].c)  # (0.0, 0.0, 1.0, 1.0)

To set or change a color, use color().

See also: color()


Dynamic Attributes

Solid objects support dynamic attribute access for node-specific data. These attributes are available through both dot notation (obj.attr) and subscript notation (obj["attr"]). These attributes cannot only be read, but also overwritten.

Built-in dynamic attributes

Attribute Available on Description
points polygon nodes Read/write access to polygon vertex coordinates
paths polygon nodes Read/write access to polygon paths
faces polyhedron nodes Read access to face indices
matrix face/edge solids 4x4 transformation matrix showing orientation in space

Custom attributes

You can store arbitrary data on any solid:

from pythonscad import *

c = cube(10)
c["name"] = "my cube"
c.material = "PLA"

print(c["name"])     # "my cube"
print(c.material)    # "PLA"

See Object Model for more details on attribute access.