API reference

Everything below is importable from smlibpy directly: from smlibpy import *.

Shapes

Part

Part()

A solid: one or more closed volumes.

Combine parts with + (union), - (difference) and & (intersection). The right-hand side may be a single part or any iterable of parts.

• area (property): Total surface area.
• bbox(): Tight axis-aligned bounding box.
• center(): Center of mass (uniform density).
• chamfer(edges, length): Bevel edges. length is the setback measured along both adjacent faces.
• closest_point(point):
• colored(color): The same body with a display color ("steelblue", "#4682b4" or (r, g, b)).
• cut(*others): Subtract other parts.
• distance_to(other): Minimum distance to a point or to another body.
• draft(faces, angle, neutral_plane):
• edges(seams=False): All edges. Seam edges (where a closed surface such as a cylinder meets itself) are left out unless seams is true.
• export(path, **kwargs): Write the shape to a file; the format follows the extension (step, stl, glb, ...).
• faces(): All faces of this shape.
• fillet(edges, radius, *, continuity=None, fullness=1.0): Round edges.
• fuse(*others): Union with other parts.
• heal(): Repair gaps, tolerances and topology (mostly needed for imported data).
• info(): Counts and measures in one dictionary.
• intersect(*others): Keep only the volume shared with the other parts.
• intersection_curves(other): The curves where this body's surface meets another body's surface.
• is_valid(): True if the part is a closed, manifold solid that encloses a positive volume.
• mass_properties(density=1.0, accuracy=None): Mass, center of mass and inertia tensor for a uniform density.
• mesh(tolerance=None, angle=15.0): Triangulate the shape (see smlibpy.mesh.tessellate).
• mirror(plane=Plane.XZ): A mirrored copy (reflection in plane, a plane or a planar face; by default the XZ plane, which flips Y).
• moved(location): A copy of this shape moved by a location (location * shape).
• named(name): The same body with a name (used by exporters and the viewer).
• offset(distance): Grow (positive) or shrink (negative) the part by distance everywhere.
• on(target): Place this shape, designed around the world XY plane, onto a plane or face.
• outline(plane=Plane.XY): The body's edges projected onto a plane (a 2D drawing view).
• project(curve, direction=(0, 0, -1)): Project a curve onto the body along direction; returns the curves on its faces.
• rotate(axis=Axis.Z, angle=0.0): A copy rotated by angle degrees about axis.
• scale(factor, center=(0, 0, 0)): A scaled copy. factor is a number or per-axis factors (sx, sy, sz), none of them zero (ValueError: that would flatten the shape).
• section(plane=Plane.XY): The cross-section of the part in a plane, as a sketch.
• shell(thickness, openings=None, *, outward=False): Hollow the part out to walls of thickness, removing the openings faces.
• show(**kwargs): Show the shape in the browser viewer (see smlibpy.show).
• silhouette(direction=(0, 0, 1)): Silhouette curves on the body as seen along direction.
• solids(): The separate bodies of this part.
• split(plane, keep='above'): Cut the part with a plane.
• to_nurbs(): A copy whose faces and edges are all NURBS (analytic types converted).
• translate(x=0.0, y=0.0, z=0.0): A copy moved by (x, y, z).
• vertices(): All vertices of this shape.
• volume (property):
• wires(): All wires (closed edge loops of faces, or the shape itself if it is a wire).

Sketch

Sketch()

A planar region (with holes, possibly several pieces) on a plane.

Sketch constructors build in the world XY plane around the origin; place a sketch with .on(plane_or_face), Plane * sketch or Pos(...) * sketch. Combine sketches with +, - and &, then turn them into parts with extrude, revolve, sweep or smlibpy.loft.

• area (property):
• bbox(): Tight axis-aligned bounding box.
• center(): Center of mass (centroid) of the shape.
• closest_point(point):
• colored(color): The same body with a display color ("steelblue", "#4682b4" or (r, g, b)).
• distance_to(other): Minimum distance to a point or to another body.
• edges(seams=False): All edges. Seam edges (where a closed surface such as a cylinder meets itself) are left out unless seams is true.
• export(path, **kwargs): Write the shape to a file; the format follows the extension (step, stl, glb, ...).
• extrude(amount, *, both=False, taper=0.0, direction=None): Extrude the region into a solid.
• faces(): All faces of this shape.
• fillet(radius, vertices=None): Round the corners of the region (between straight edges).
• heal(): Repair gaps, tolerances and topology (mostly needed for imported data).
• info(): Counts and measures in one dictionary.
• intersection_curves(other): The curves where this body's surface meets another body's surface.
• mesh(tolerance=None, angle=15.0): Triangulate the shape (see smlibpy.mesh.tessellate).
• mirror(plane=Plane.XZ): A mirrored copy (reflection in plane, a plane or a planar face; by default the XZ plane, which flips Y).
• moved(location): A copy of this shape moved by a location (location * shape).
• named(name): The same body with a name (used by exporters and the viewer).
• offset(distance, *, round=True): Grow (positive) or shrink (negative) the region; corners are rounded or sharp.
• on(target): Place this shape, designed around the world XY plane, onto a plane or face.
• outline(plane=Plane.XY): The body's edges projected onto a plane (a 2D drawing view).
• plane (property): The sketch plane; extrusions follow its normal.
• project(curve, direction=(0, 0, -1)): Project a curve onto the body along direction; returns the curves on its faces.
• revolve(axis=None, angle=360.0): Revolve the region about an axis in its plane.
• rotate(axis=Axis.Z, angle=0.0): A copy rotated by angle degrees about axis.
• scale(factor, center=(0, 0, 0)): A scaled copy. factor is a number or per-axis factors (sx, sy, sz), none of them zero (ValueError: that would flatten the shape).
• show(**kwargs): Show the shape in the browser viewer (see smlibpy.show).
• silhouette(direction=(0, 0, 1)): Silhouette curves on the body as seen along direction.
• sweep(path, *, sharp_corners=None): Sweep the region along a path. The sketch should sit at the start of the path.
• thicken(thickness, *, both=False): Turn the sheet into a solid of thickness (along the face normals; a negative thickness grows against them). With both the solid is thickness thick in total, half of it to each side of the sheet.
• to_nurbs(): A copy whose faces and edges are all NURBS (analytic types converted).
• translate(x=0.0, y=0.0, z=0.0): A copy moved by (x, y, z).
• vertices(): All vertices of this shape.
• wires(): All wires (closed edge loops of faces, or the shape itself if it is a wire).

Shell

Shell()

A sheet body: one or more faces that do not enclose a volume (surfaces).

• area (property):
• bbox(): Tight axis-aligned bounding box.
• center(): Center of mass (centroid) of the shape.
• closest_point(point):
• colored(color): The same body with a display color ("steelblue", "#4682b4" or (r, g, b)).
• distance_to(other): Minimum distance to a point or to another body.
• edges(seams=False): All edges. Seam edges (where a closed surface such as a cylinder meets itself) are left out unless seams is true.
• export(path, **kwargs): Write the shape to a file; the format follows the extension (step, stl, glb, ...).
• faces(): All faces of this shape.
• heal(): Repair gaps, tolerances and topology (mostly needed for imported data).
• info(): Counts and measures in one dictionary.
• intersection_curves(other): The curves where this body's surface meets another body's surface.
• mesh(tolerance=None, angle=15.0): Triangulate the shape (see smlibpy.mesh.tessellate).
• mirror(plane=Plane.XZ): A mirrored copy (reflection in plane, a plane or a planar face; by default the XZ plane, which flips Y).
• moved(location): A copy of this shape moved by a location (location * shape).
• named(name): The same body with a name (used by exporters and the viewer).
• on(target): Place this shape, designed around the world XY plane, onto a plane or face.
• outline(plane=Plane.XY): The body's edges projected onto a plane (a 2D drawing view).
• project(curve, direction=(0, 0, -1)): Project a curve onto the body along direction; returns the curves on its faces.
• rotate(axis=Axis.Z, angle=0.0): A copy rotated by angle degrees about axis.
• scale(factor, center=(0, 0, 0)): A scaled copy. factor is a number or per-axis factors (sx, sy, sz), none of them zero (ValueError: that would flatten the shape).
• show(**kwargs): Show the shape in the browser viewer (see smlibpy.show).
• silhouette(direction=(0, 0, 1)): Silhouette curves on the body as seen along direction.
• thicken(thickness, *, both=False): Turn the sheet into a solid of thickness (along the face normals; a negative thickness grows against them). With both the solid is thickness thick in total, half of it to each side of the sheet.
• to_nurbs(): A copy whose faces and edges are all NURBS (analytic types converted).
• translate(x=0.0, y=0.0, z=0.0): A copy moved by (x, y, z).
• vertices(): All vertices of this shape.
• wires(): All wires (closed edge loops of faces, or the shape itself if it is a wire).

Face

Face(owner, kface)

A bounded piece of a surface, belonging to a body (a part, shell or sketch).

• area (property):
• axis (property): Axis of a cylinder, cone, sphere, torus or surface of revolution.
• bbox(): Tight axis-aligned bounding box.
• center(): Area centroid. For curved faces it may lie off the face; see interior_point.
• distance_to(point):
• edges(seams=False): The face's edges (seam edges only with seams=True).
• export(path, **kwargs): Write the shape to a file; the format follows the extension (step, stl, glb, ...).
• extrude(amount, **kwargs): Extrude a planar face along its normal (see Sketch.extrude).
• faces(): All faces of this shape.
• geom_type (property): "plane", "cylinder", "cone", "sphere", "torus", "revolution",
• inner_wires():
• interior_point(): A point guaranteed to lie on the face.
• is_planar (property): True for planes and for flat B-spline faces (control points in one plane).
• mesh(tolerance=None, angle=15.0): Triangulate the shape (see smlibpy.mesh.tessellate).
• mirror(plane=Plane.XZ): A mirrored copy (reflection in plane, a plane or a planar face; by default the XZ plane, which flips Y).
• moved(location): A copy of this shape moved by a location (location * shape).
• neighbors(): Faces sharing an edge with this one.
• normal_at(point=None): Outward unit normal at the face point closest to point (default: the center).
• on(target): Place this shape, designed around the world XY plane, onto a plane or face.
• outer_wire():
• owner (property): The body this face belongs to.
• plane (property): The face's plane: origin at its centroid, normal pointing out of the body.
• radius (property): Radius of a cylinder, sphere or cone (at its base), minor radius of a torus.
• rotate(axis=Axis.Z, angle=0.0): A copy rotated by angle degrees about axis.
• scale(factor, center=(0, 0, 0)): A scaled copy. factor is a number or per-axis factors (sx, sy, sz), none of them zero (ValueError: that would flatten the shape).
• show(**kwargs): Show the shape in the browser viewer (see smlibpy.show).
• to_shell(): A sheet body holding a copy of this face.
• to_sketch(): A sketch holding a copy of this (planar) face.
• translate(x=0.0, y=0.0, z=0.0): A copy moved by (x, y, z).
• vertices(): All vertices of this shape.
• wires(): All wires (closed edge loops of faces, or the shape itself if it is a wire).

Edge

Edge()

A bounded curve: a line segment, an arc, a circle, an ellipse or a NURBS curve.

Edges come from bodies (part.edges()) or from curve constructors such as smlibpy.Line, smlibpy.Arc and smlibpy.Spline. Parameters along an edge (point_at(t)) run from 0 at the start to 1 at the end, proportional to arc length.

• arc_center (property): Center of a circular edge.
• bbox(): Tight axis-aligned bounding box.
• center(): The point halfway along the edge (use arc_center for a circle's center).
• convexity (property): "convex" for an outside corner (material angle below 180 degrees), "concave"
• direction (property): Unit direction of a straight edge (start to end).
• distance_to(point):
• edges(): All edges of this shape.
• end (property):
• export(path, **kwargs): Write the shape to a file; the format follows the extension (step, stl, glb, ...).
• faces(): All faces of this shape.
• geom_type (property): "line", "circle" (also arcs), "ellipse", "bspline" or "other".
• intersections(other): Points where this edge crosses another edge.
• is_closed (property):
• is_convex(): True on an outside corner (see convexity).
• is_seam (property): True for the seam of a closed surface (an edge used twice by one face).
• length (property):
• mesh(tolerance=None, angle=15.0): Triangulate the shape (see smlibpy.mesh.tessellate).
• mirror(plane=Plane.XZ): A mirrored copy (reflection in plane, a plane or a planar face; by default the XZ plane, which flips Y).
• moved(location): A copy of this shape moved by a location (location * shape).
• normal (property): Axis direction of a circular edge.
• on(target): Place this shape, designed around the world XY plane, onto a plane or face.
• point_at(t=0.5): Point at fraction t of the edge length (0 = start, 1 = end).
• radius (property): Radius of a circular edge.
• reversed(): The same edge traversed the other way.
• rotate(axis=Axis.Z, angle=0.0): A copy rotated by angle degrees about axis.
• scale(factor, center=(0, 0, 0)): A scaled copy. factor is a number or per-axis factors (sx, sy, sz), none of them zero (ValueError: that would flatten the shape).
• show(**kwargs): Show the shape in the browser viewer (see smlibpy.show).
• start (property):
• tangent_at(t=0.5): Unit tangent at fraction t of the edge length, pointing along the edge.
• translate(x=0.0, y=0.0, z=0.0): A copy moved by (x, y, z).
• vertices(): All vertices of this shape.
• wires(): All wires (closed edge loops of faces, or the shape itself if it is a wire).

Wire

Wire(edges, *, sort=True)

A chain of edges, open or closed. Wire([edge, edge, ...]) orders and orients the edges.

• bbox(): Tight axis-aligned bounding box.
• center(): Length-weighted average of the edge midpoints.
• close(): This wire closed with a straight line from its end to its start.
• distance_to(point):
• edges(): All edges of this shape.
• end (property):
• export(path, **kwargs): Write the shape to a file; the format follows the extension (step, stl, glb, ...).
• faces(): All faces of this shape.
• fillet(radius, vertices=None): Round the corners between straight edges with tangent arcs (planar wires).
• is_closed (property):
• length (property):
• mesh(tolerance=None, angle=15.0): Triangulate the shape (see smlibpy.mesh.tessellate).
• mirror(plane=Plane.XZ): A mirrored copy (reflection in plane, a plane or a planar face; by default the XZ plane, which flips Y).
• moved(location): A copy of this shape moved by a location (location * shape).
• on(target): Place this shape, designed around the world XY plane, onto a plane or face.
• plane(): The plane of a planar wire (normal by the right-hand rule along the wire).
• point_at(t=0.5): Point at fraction t of the total length.
• reversed():
• rotate(axis=Axis.Z, angle=0.0): A copy rotated by angle degrees about axis.
• scale(factor, center=(0, 0, 0)): A scaled copy. factor is a number or per-axis factors (sx, sy, sz), none of them zero (ValueError: that would flatten the shape).
• show(**kwargs): Show the shape in the browser viewer (see smlibpy.show).
• start (property):
• tangent_at(t=0.5):
• to_sketch(): The planar region bounded by this closed wire.
• translate(x=0.0, y=0.0, z=0.0): A copy moved by (x, y, z).
• vertices(): All vertices of this shape.
• wires(): All wires (closed edge loops of faces, or the shape itself if it is a wire).

Vertex

Vertex(x=0.0, y=0.0, z=0.0)

A point. Vertices of bodies come from .vertices(); Vertex(x, y, z) makes one.

• bbox(): Tight axis-aligned bounding box.
• center(): Center of mass (centroid) of the shape.
• distance_to(other):
• edges(): All edges of this shape.
• export(path, **kwargs): Write the shape to a file; the format follows the extension (step, stl, glb, ...).
• faces(): All faces of this shape.
• mesh(tolerance=None, angle=15.0): Triangulate the shape (see smlibpy.mesh.tessellate).
• mirror(plane=Plane.XZ): A mirrored copy (reflection in plane, a plane or a planar face; by default the XZ plane, which flips Y).
• moved(location): A copy of this shape moved by a location (location * shape).
• on(target): Place this shape, designed around the world XY plane, onto a plane or face.
• point (property):
• rotate(axis=Axis.Z, angle=0.0): A copy rotated by angle degrees about axis.
• scale(factor, center=(0, 0, 0)): A scaled copy. factor is a number or per-axis factors (sx, sy, sz), none of them zero (ValueError: that would flatten the shape).
• show(**kwargs): Show the shape in the browser viewer (see smlibpy.show).
• translate(x=0.0, y=0.0, z=0.0): A copy moved by (x, y, z).
• vertices(): All vertices of this shape.
• wires(): All wires (closed edge loops of faces, or the shape itself if it is a wire).
• x (property):
• y (property):
• z (property):

ShapeList

ShapeList(iterable=())

A list of shapes with selection helpers.

Every selector returns a new ShapeList, so selectors chain::

part.edges().parallel_to(Z).max_by(X)
part.faces().planar().facing(-Z)

A one-element list can be used wherever a single shape is expected (sketch.on(part.faces().top())). Use one to require exactly one.

• append(object): Append object to the end of the list.
• at(point, tol=0.0001): Shapes passing through point (vertices at, edges/faces touching it).
• back(): Shapes furthest along +Y.
• bbox():
• bottom(): Lowest shapes (smallest Z).
• center(): Average of the members' centers.
• circles(): Circular edges (full circles and arcs).
• clear(): Remove all items from list.
• concave(): Edges on inside corners (material angle above 180 degrees).
• convex(): Edges on outside corners (material angle below 180 degrees).
• copy(): Return a shallow copy of the list.
• count(value): Return number of occurrences of value.
• cylinders(): Cylindrical faces.
• edges():
• extend(iterable): Extend list by appending elements from the iterable.
• faces():
• facing(direction, max_angle=0.001): Faces whose outward normal points along direction (within max_angle degrees).
• filter(predicate): Keep the shapes for which predicate(shape) is true.
• filter_by(criterion): parallel_to(axis), of_type(name) or filter(predicate), depending on the argument.
• first (property):
• front(): Shapes furthest along -Y.
• group_by(key=Axis.Z, tol=0.0001): Group shapes with equal key (within tol), groups in ascending key order.
• index(value, start=0, stop=9223372036854775807): Return first index of value.
• insert(index, object): Insert object before index.
• largest(): The biggest shape by volume, area or length.
• last (property):
• left(): Shapes furthest along -X.
• lines(): Straight edges (also straight B-spline edges, such as the edges of a chamfer).
• max_by(key=Axis.Z, tol=0.0001): The shapes with the largest key (all of them, if several tie).
• min_by(key=Axis.Z, tol=0.0001): The shapes with the smallest key (all of them, if several tie).
• moved(location):
• nearest(point): The shape whose center is closest to point.
• of_type(*geom_types): Keep shapes of the given geometry types, e.g. "line", "circle", "plane", "cylinder", "bspline".
• on(target): Every shape placed onto a plane or face (see Shape.on).
• one(): The only element; raises if the list does not hold exactly one shape.
• parallel_to(axis): Straight edges along axis, or planar faces whose normal is along axis.
• perpendicular_to(axis): Straight edges perpendicular to axis, or planar faces containing it.
• planar(): Planar faces (also flat B-spline faces).
• pop(index=-1): Remove and return item at index (default last).
• remove(value): Remove first occurrence of value.
• reverse(): Reverse IN PLACE.
• right(): Shapes furthest along +X.
• rotate(axis=Axis.Z, angle=0.0):
• smallest(): The smallest shape by volume, area or length.
• smooth(): Edges where two faces meet tangentially, such as the borders of a fillet.
• sort(*, key=None, reverse=False): Sort the list in ascending order and return None.
• sort_by(key=Axis.Z, reverse=False): Sort by position along an axis, by "length"/"area"/"volume"/"radius", or by any function of a shape.
• sort_by_distance(point, reverse=False):
• top(): Highest shapes (largest Z).
• translate(x=0.0, y=0.0, z=0.0):
• vertices():
• wires():
• within(box): Shapes whose bounding box lies inside box.

Shape

Shape()

Base class of all shapes.

• bbox(): Tight axis-aligned bounding box.
• center(): Center of mass (centroid) of the shape.
• edges(): All edges of this shape.
• export(path, **kwargs): Write the shape to a file; the format follows the extension (step, stl, glb, ...).
• faces(): All faces of this shape.
• mesh(tolerance=None, angle=15.0): Triangulate the shape (see smlibpy.mesh.tessellate).
• mirror(plane=Plane.XZ): A mirrored copy (reflection in plane, a plane or a planar face; by default the XZ plane, which flips Y).
• moved(location): A copy of this shape moved by a location (location * shape).
• on(target): Place this shape, designed around the world XY plane, onto a plane or face.
• rotate(axis=Axis.Z, angle=0.0): A copy rotated by angle degrees about axis.
• scale(factor, center=(0, 0, 0)): A scaled copy. factor is a number or per-axis factors (sx, sy, sz), none of them zero (ValueError: that would flatten the shape).
• show(**kwargs): Show the shape in the browser viewer (see smlibpy.show).
• translate(x=0.0, y=0.0, z=0.0): A copy moved by (x, y, z).
• vertices(): All vertices of this shape.
• wires(): All wires (closed edge loops of faces, or the shape itself if it is a wire).

MassProperties

MassProperties(mass, volume, area, center, inertia, density)

Mass properties of a part.

inertia is the inertia tensor about the center of mass (axes parallel to the world axes); principal_moments and principal_axes are its eigen-decomposition.

• principal_axes (property):
• principal_moments (property):

Geometry

Vector

Vector(*args)

An immutable 3D vector or point.

Vector(1, 2), Vector(1, 2, 3), Vector((1, 2, 3)) and Vector(other) are all accepted. Vectors support +, -, * (by a number), /, unary -, abs() (length), iteration and indexing.

• angle_to(other): Angle to another vector in degrees (0..180).
• any_perpendicular(): A unit vector perpendicular to this one.
• cross(other):
• distance_to(other):
• dot(other):
• is_close(other, tol=1e-06):
• is_parallel(other, angle_tol=0.0001): True if both vectors point along the same line (either sense).
• is_perpendicular(other, angle_tol=0.0001):
• length (property):
• normalized():
• project_to(plane): Orthogonal projection of this point onto a plane.
• rotate(axis, angle): Rotate this point about an axis (through the origin for a plain vector).
• to_tuple():
• x (property):
• y (property):
• z (property):

Axis

Axis(origin=(0, 0, 0), direction=(0, 0, 1))

An infinite line through origin along direction.

Axis.X, Axis.Y and Axis.Z (also exported as X, Y, Z) are the world axes. Axes are used to rotate, revolve, mirror, and to sort or filter shapes.

• at(origin): The same direction through another point.
• direction (property):
• distance_to(point):
• is_parallel(other, angle_tol=0.0001):
• moved(loc):
• origin (property):
• position_along(point): Signed coordinate of point along this axis.
• project(point):
• reversed():

Plane

Plane(origin=(0, 0, 0), x_dir=None, z_dir=(0, 0, 1))

A coordinate system: an origin, an x direction and a normal (z_dir).

Planes are where sketches live and where parts are placed. Named planes: Plane.XY (= Plane.top), Plane.XZ (= Plane.front), Plane.YZ (= Plane.right), plus back, left and bottom. Their local Y axis points up (world +Z) for the side views, so a sketch drawn "upwards" stands up on the front plane.

A planar smlibpy.Face converts to a plane at its center with its outward normal: Plane(face) or face.plane.

• at(origin): The same orientation through another origin.
• contains(point, tol=1e-06):
• distance_to(point): Signed distance of a point above the plane.
• flipped(): The same plane seen from the other side (normal reversed, x kept).
• from_local(point):
• is_coplanar(other, tol=1e-06):
• location (property): The location that maps the world XY plane onto this plane.
• moved(loc):
• normal (property): The plane normal.
• offset(distance): This plane moved distance along its normal.
• origin (property):
• project(point):
• rotated(x=0.0, y=0.0, z=0.0): Rotate about the plane's own X, then Y, then Z axis (degrees).
• shifted(x=0.0, y=0.0, z=0.0): This plane moved within its own coordinates.
• to_local(point):
• x_dir (property):
• y_dir (property):
• z_dir (property): The plane normal.

Location

Location(position=None, rotation=None)

A rigid placement (rotation + translation), stored as a 4x4 matrix.

Build them with Pos and Rot and combine with *. Applying a location to a shape moves the shape: Pos(10, 0, 0) * Rot(z=45) * Box(1, 1, 1) first rotates the box about the world Z axis, then moves it 10 along X.

• about(axis, angle): Rotation by angle degrees about an arbitrary axis.
• inverse():
• matrix (property): The 4x4 homogeneous matrix (column-vector convention).
• plane (property): The XY plane moved by this location.
• position (property):
• rotate_vector(v):
• rotation (property): Rotation as X, Y, Z angles in degrees (applied in that order about world axes).
• x_dir (property):
• y_dir (property):
• z_dir (property):

Pos

Pos(x=0.0, y=0.0, z=0.0)

A translation. Pos(10, 0, 5) or Pos((10, 0, 5)) or Pos(vector).

Rot

Rot(x=0.0, y=0.0, z=0.0)

A rotation in degrees about the world X, then Y, then Z axis.

BoundBox

BoundBox(min, max)

An axis-aligned bounding box.

• center (property):
• contains(point, tol=1e-06):
• diagonal (property):
• of_points(points):
• size (property):
• union(other):

Align

Align(*values)

How a new shape sits relative to the origin along an axis.

MIN puts the shape's lower bound at the origin, CENTER centers it, MAX puts its upper bound at the origin. Constructors take one value for all axes or one per axis: Box(10, 10, 2, align=(Align.CENTER, Align.CENTER, Align.MIN)) stands the box on the XY plane.

Parts

Box

Box(length, width, height, *, align=Align.CENTER)

A box of length (X) by width (Y) by height (Z).

Cylinder

Cylinder(radius, height, *, align=Align.CENTER)

A cylinder along Z.

Cone

Cone(bottom_radius, top_radius, height, *, align=Align.CENTER)

A cone (or frustum) along Z; one of the radii may be zero.

Sphere

Sphere(radius, *, align=Align.CENTER)

A sphere.

Torus

Torus(major_radius, minor_radius, *, align=Align.CENTER)

A torus around Z.

Wedge

Wedge(length, width, height, top_length=0.0, *, align=Align.CENTER)

A ramp: a length (X) by width (Y) base whose high side, height tall, is the face at x = -length/2; the slope runs down towards +X. top_length gives a flat top of that length, measured from the -X end.

Hole

Hole(radius, depth)

A drilling tool: a cylinder from the origin down to -depth.

CounterBoreHole

CounterBoreHole(radius, counter_bore_radius, counter_bore_depth, depth)

A drilling tool with a counterbore at the top.

CounterSinkHole

CounterSinkHole(radius, counter_sink_radius, depth, angle=82.0)

A drilling tool with a conical countersink of included angle at the top.

Sketches

Rectangle

Rectangle(width, height, *, align=Align.CENTER)

A width (X) by height (Y) rectangle.

RoundedRectangle

RoundedRectangle(width, height, radius, *, align=Align.CENTER)

A rectangle with rounded corners.

Circle

Circle(radius, *, align=Align.CENTER)

A disk of radius.

Ellipse

Ellipse(x_radius, y_radius, *, align=Align.CENTER)

An ellipse with semi-axes x_radius and y_radius.

Polygon

Polygon(*points, align=None)

The polygon through the points (closed automatically). Points stay where they are unless align is given.

RegularPolygon

RegularPolygon(radius, sides, *, inscribed=False, rotation=0.0, align=Align.CENTER)

A regular polygon with sides corners.

radius is the distance to the corners, or to the middle of the sides when inscribed is true (handy for hexagons measured across flats: radius = flats / 2).

Slot

Slot(length, width, *, rotation=0.0, align=Align.CENTER)

An obround slot length long overall (round ends included) and width wide.

Trapezoid

Trapezoid(width, height, left_angle, right_angle=None, *, align=Align.CENTER)

A trapezoid with a base of width; the side angles are measured inside the base corners.

make_face

make_face(outer, *holes)

The planar region inside a closed wire, minus the regions inside holes.

Curves

Line

Line(start, end)

A straight edge from start to end.

Polyline

Polyline(*points, close=False)

Straight segments through the points. close=True connects the last point to the first.

PolarLine

PolarLine(start, length, angle, plane=Plane.XY)

A line of length leaving start at angle degrees from the plane's X axis.

CenterArc

CenterArc(center, radius, start_angle, arc_size, plane=Plane.XY)

An arc around center starting at start_angle and spanning arc_size degrees (angles counterclockwise from the plane's X axis; a negative arc_size runs clockwise). CenterArc(c, r, 0, 360) is a full circle.

center is given in plane coordinates.

ThreePointArc

ThreePointArc(start, through, end)

The circular arc from start through through to end.

RadiusArc

RadiusArc(start, end, radius, plane=Plane.XY)

The shorter arc of radius from start to end in plane.

A positive radius bulges to the left of the direction start→end, a negative one to the right.

SagittaArc

SagittaArc(start, end, sagitta, plane=Plane.XY)

An arc from start to end whose middle is sagitta away from the chord (positive to the left of start→end).

TangentArc

TangentArc(start, end, tangent)

An arc from start to end leaving start along tangent.

Spline

Spline(*points, tangents=None, closed=False)

A smooth cubic curve through the points.

Args

• points: Two or more points.
• tangents: Optional (start_tangent, end_tangent) directions; either may be None.
• closed: Make a closed loop (smooth at the join).

Bezier

Bezier(*control_points, weights=None)

A Bézier curve (rational if weights are given) from its control points.

Helix

Helix(pitch, height, radius, *, center=(0, 0, 0), direction=(0, 0, 1), end_radius=None, left_handed=False)

A helix around direction through center.

end_radius makes a conical helix; pitch is the rise per turn.

EllipticalArc

EllipticalArc(center, x_radius, y_radius, start_angle=0.0, end_angle=360.0, plane=Plane.XY)

An ellipse (or elliptical arc) around center in plane.

FilletPolyline

FilletPolyline(*points, radius, close=False)

A polyline whose corners are rounded with radius.

Patterns

Locations

Locations(*items)

A list of locations. Locations((0, 0), (10, 5), ...) takes points, locations, planes, faces (their center planes) or vertices.

• append(object): Append object to the end of the list.
• clear(): Remove all items from list.
• copy(): Return a shallow copy of the list.
• count(value): Return number of occurrences of value.
• extend(iterable): Extend list by appending elements from the iterable.
• index(value, start=0, stop=9223372036854775807): Return first index of value.
• insert(index, object): Insert object before index.
• on(target): The pattern placed onto a plane or face.
• points (property):
• pop(index=-1): Remove and return item at index (default last).
• remove(value): Remove first occurrence of value.
• reverse(): Reverse IN PLACE.
• sort(*, key=None, reverse=False): Sort the list in ascending order and return None.

GridLocations

GridLocations(x_spacing, y_spacing, x_count, y_count, *, centered=True)

A rectangular grid in the XY plane, centered on the origin unless centered=False.

PolarLocations

PolarLocations(radius, count, *, start_angle=0.0, angular_range=360.0, rotate=True)

count locations on a circle of radius in the XY plane.

With rotate the copies turn with the pattern (their X axis points outward). A full circle (angular_range=360) spaces them evenly without repeating the start.

HexLocations

HexLocations(spacing, x_count, y_count, *, centered=True)

A honeycomb pattern: rows spacing apart along X, every other row shifted by half.

Operations

extrude

extrude(profile, amount, *, both=False, taper=0.0, direction=None)

Extrude a sketch, a planar face or a closed wire into a solid (see Sketch.extrude).

An open curve extrudes into a surface (a Shell), along direction or the normal of the curve's plane.

revolve

revolve(profile, axis=None, angle=360.0)

Revolve a sketch about an axis into a solid (see Sketch.revolve).

An open curve revolves into a surface of revolution (a Shell).

loft

loft(sections, *, ruled=False, smooth=True)

A solid through a sequence of cross sections, or a surface through open curves.

Args

• sections: Two or more sections in order: sketches, planar faces or closed wires for a solid; open edges or wires for a surface (a Shell). Sections with holes make a hollow solid; every section needs the same number of holes.
• ruled: Straight transitions between neighbouring sections.
• smooth: With four or more sections, pass through them with a cubic surface (False: quadratic). Three sections always give a quadratic one.

sweep

sweep(profile, path, *, orient=True, translational=False, sharp_corners=None)

Sweep a profile along a path.

The profile is moved so that its center sits at the start of the path and (with orient) turned to face along the path, so profiles can be drawn anywhere, usually in the XY plane::

tube = sweep(Circle(2), Spline((0, 0, 0), (0, 10, 20), (30, 10, 40)))
rail = sweep(Rectangle(4, 2), Helix(pitch=10, height=40, radius=20))

Args

• profile: A sketch (holes allowed), a planar face or a closed wire.
• path: An edge, or a wire of connected edges.
• orient: Turn the profile to be perpendicular to the path at its start.
• translational: Keep the profile's orientation fixed instead of turning it with the path.
• sharp_corners: For paths of several edges: miter the corners of a planar path (default for planar paths); False sweeps each edge on its own and joins the pieces.

fillet

fillet(edges, radius, **kwargs)

Round edges of the part they belong to (see Part.fillet).

chamfer

chamfer(edges, length)

Bevel edges of the part they belong to (see Part.chamfer).

shell

shell(part, thickness, openings=None, *, outward=False)

Hollow out a part (see Part.shell).

offset

offset(shape, distance, **kwargs)

Grow or shrink a part or a sketch by distance.

mirror

mirror(shape, plane=Plane.XZ)

A mirrored copy of a shape.

split

split(part, plane, keep='above')

Cut a part with a plane (see Part.split).

section

section(part, plane=Plane.XY)

Cross-section of a part (see Part.section).

thicken

thicken(surface, thickness)

Turn a face or sheet into a solid of thickness.

Surfaces

surface

surface(points, *, interpolate=True)

A freeform NURBS surface from a grid of points.

Args

• points: Rows of points, points[i][j] (all rows the same length, at least 4 x 4: the surface is bicubic).
• interpolate: Pass through the points (default). False uses them as control points, which gives a smoother surface that only approaches them.

ruled

ruled(a, b)

The ruled surface between two curves (straight lines join matching points).

stitch

stitch(*pieces, tolerance=None)

Sew faces and sheets along their common edges.

Returns a Part when the result encloses a volume, otherwise a Shell. tolerance is the largest gap to close (default: 1e-4 of the model size).

Meshes

Mesh

Mesh(vertices, triangles, normals=None, _poly=None)

An indexed triangle mesh.

Attributes

• vertices: (n, 3) float array of positions.

• triangles: (m, 3) int array of vertex indices (counterclockwise seen from outside).

• normals: optional (m, 3, 3) corner normals (one per triangle corner), used for shading crisp CAD edges.

• area (property):

• bbox():

• center():

• export(path, **kwargs):

• is_closed(): True if every edge of the mesh is shared by exactly two triangles (a watertight mesh).

• triangle_normals (property):

• volume (property): Enclosed volume (meaningful for closed meshes).

tessellate

tessellate(shape, tolerance=None, angle=15.0)

Triangulate a shape.

Args

• shape: A part, sketch, shell or face.
• tolerance: Maximum distance between mesh and exact surface. Default: 0.1 % of the bounding box diagonal.
• angle: Maximum angle (degrees) between neighbouring triangle normals on curved faces.

Files

export

export(shapes, path, **kwargs)

Write shapes to path; the format follows the file extension.

export_step

export_step(shapes, path, *, unit='mm', name=None)

Exact B-rep export to STEP AP214. Names and colors of parts are kept.

export_stl

export_stl(shapes, path, *, tolerance=None, angle=15.0, ascii=False)

Triangle mesh export (binary unless ascii). tolerance is the maximum deviation.

export_glb

export_glb(shapes, path, *, tolerance=None, angle=15.0, edges=True, edge_color='#1f2328')

Binary glTF export with colors, names and (optionally) the B-rep edges as lines.

glTF is Y-up and measured in meters; the model is written Z-up in millimeters as modeled, under a root node that turns it upright and scales it by 0.001, so viewers show it at its real size.

export_gltf

export_gltf(shapes, path, **kwargs)

glTF export with the buffer embedded as a data URI (in meters, like export_glb).

export_obj

export_obj(shapes, path, *, tolerance=None, angle=15.0)

Wavefront OBJ export (one object per part).

save

save(shapes, path, *, ascii=True)

Write a body to SMLib's native .smb format (exact and lossless).

load

load(path)

Read a file, picking the format from the extension: STEP (.step, .stp) and SMLib (.smb) give exact parts, STL a Mesh.

A STEP file with one body gives that part, one with several a ShapeList. A native file that encloses no volume comes back as a Shell.

import_stl

import_stl(path)

Read an STL file (binary or ASCII) as a mesh.

import_step

import_step(path, *, heal=True)

Read the solids and surfaces of a STEP file (AP203, AP214, AP242 B-rep data).

Returns a single smlibpy.Part (or smlibpy.Shell) when the file holds one body, otherwise a smlibpy.ShapeList of them. Lengths are converted to millimeters; assembly placements are applied; names and colors are kept. heal repairs bodies that come out invalid (valid ones are left alone).

Pictures and viewer

render

render(*shapes, path=None, view='iso', size=(800, 600), edges=True, background='white', tolerance=None)

Render shapes to a PNG image.

Args

• shapes: Parts, sketches, shells, faces, edges, wires, meshes, or lists of them.
• path: Also write the PNG to this file.
• view: "iso" (default), "front", "back", "left", "right", "top", "bottom", a direction from the model towards the camera, or "sheet" for a drawing sheet in ISO projection method E (first angle): front view, the view from the left to its right, the top view below it, and the iso view, all at one scale.
• size: Width and height in pixels.
• edges: Draw the edges of faces (hidden edges stay hidden).
• background: Background color.
• tolerance: Tessellation tolerance; default 0.1 % of each body's size.

Returns

The PNG file contents.

show

show(*shapes, title='smlibpy', path=None, open_browser=True, tolerance=None, angle=12.0, edges=True)

Show shapes (parts, sketches, faces, edges, wires, meshes, lists) in a 3D viewer.

In Jupyter the viewer is displayed inline; elsewhere an HTML file is written (to path or a temporary file) and opened in the default browser. Returns the path, or the IPython display object in a notebook.