Tree — leaf nodes#

Leaves are terminal Node subclasses: they do not wrap other nodes as children. They are where concrete implicit geometry and sources live—analytic primitives, meshes, CAD imports, lattices, extruded profiles, and signed-distance fields.

The enums documented next to a node configure that node. Classes that are not nodes themselves, such as the beams and balls of a BeamLattice, the 3MF import helpers, and the component and provenance records of the mapped and stochastic lattices, are grouped at the end under Supporting types (not nodes).

Nodes that combine or transform subtrees are composition operators; see Tree — composition nodes.

class pyvcad.Function#

A function geometry primitive/leaf node. This is analogous to an F-rep. Functions can be defined in Cartesian, cylindrical, or spherical coordinates.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.Function, function: str, min: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1046ea2f0>, max: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1046ea5b0>) -> None

Constructor that takes a math expression string to evaluate and a bounding box.

Parameters:
  • function (str) – The function expression to evaluate. This can be any math expression, such as x^2 + y^2 + z^2 - 1.

  • min (Vec3) – The minimum bounding box coordinates. Defaults to (-10, -10, -10).

  • max (Vec3) – The maximum bounding box coordinates. Defaults to (10, 10, 10).

  1. __init__(self: pyvcad.pyvcad.Function, function: object, min: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x104733970>, max: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1047439b0>) -> None

Constructor that takes a callable to evaluate and a bounding box.

The callable must return the signed distance to the surface for a given point. Two kinds of callable are accepted:

  • A numba.cfunc with signature float64(float64, float64, float64) -> (x, y, z). This is dispatched through the native function pointer and is the fast path.

  • A plain Python callable taking eight floats (x, y, z, rho, phic, r, theta, phis). This is supported for convenience but is slow (a Python call per evaluation).

Parameters:
  • function (callable) – The signed-distance callable (numba.cfunc preferred).

  • min (Vec3) – The minimum bounding box coordinates. Defaults to (-10, -10, -10).

  • max (Vec3) – The maximum bounding box coordinates. Defaults to (10, 10, 10).

Example

>>> from numba import cfunc, types
>>> import math
>>> import pyvcad as pv
>>> @cfunc(types.float64(types.float64, types.float64, types.float64))
... def gyroid(x, y, z):
...     f = 2.0 * math.pi / 10.0
...     return (math.sin(f*x)*math.cos(f*y) + math.sin(f*y)*math.cos(f*z)
...             + math.sin(f*z)*math.cos(f*x))
>>> node = pv.Function(gyroid, pv.Vec3(-15, -15, -15), pv.Vec3(15, 15, 15))
expression(self: pyvcad.pyvcad.Function) → str#

Returns the math expression evaluated by this node, or an empty string when the node wraps a callable.

uses_expression(self: pyvcad.pyvcad.Function) → bool#

Returns True when the node evaluates a string expression rather than a callable.

class pyvcad.Mesh#

A mesh geometry primitive/leaf node. The mesh is loaded from a file and converted into a signed distance field using OpenVDB.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.Mesh, path: str, center: bool = False, disable_validation: bool = False, override_voxel_size: typing.SupportsFloat | typing.SupportsIndex | None = None, compensate_slicer_ras: bool = False) -> None

Creates a Mesh from a file path.

Parameters:
  • path (str) – The path to the mesh file to load.

  • center (bool) – If true, the mesh will be centered at the origin after loading.

  • disable_validation (bool) – If true, the mesh will not be validated for errors.

  • override_voxel_size (float, optional) – Explicit voxel size to use when voxelizing the mesh into an SDF.

  • compensate_slicer_ras (bool) – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.

Example

>>> import pyvcad as pv
>>> node = pv.Mesh('model.stl', center=True, override_voxel_size=0.1)
  1. __init__(self: pyvcad.pyvcad.Mesh, path: str, sample_size: pyvcad.pyvcad.Vec3, center: bool = False, disable_validation: bool = False, override_voxel_size: typing.SupportsFloat | typing.SupportsIndex | None = None, compensate_slicer_ras: bool = False) -> None

Creates a Mesh from a file path and sample size.

Parameters:
  • path (str) – The path to the mesh file to load.

  • sample_size (Vec3) – The voxel size to use when voxelizing the mesh into an SDF.

  • center (bool) – If true, the mesh will be centered at the origin after loading.

  • disable_validation (bool) – If true, the mesh will not be validated for errors.

  • override_voxel_size (float, optional) – Explicit voxel size to use when voxelizing the mesh into an SDF. If provided, this takes precedence over sample_size.

  • compensate_slicer_ras (bool) – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.

Example

>>> import pyvcad as pv
>>> node = pv.Mesh('model.stl', pv.Vec3(0.1, 0.1, 0.1), center=True)
  1. __init__(self: pyvcad.pyvcad.Mesh, mesh: pyvcad.pyvcad.SurfaceMesh, center: bool = False, override_voxel_size: typing.SupportsFloat | typing.SupportsIndex | None = None, compensate_slicer_ras: bool = False) -> None

Creates a Mesh from an existing SurfaceMesh.

Parameters:
  • mesh (SurfaceMesh) – The mesh to load.

  • center (bool) – If true, the mesh will be centered at the origin before voxelization.

  • override_voxel_size (float, optional) – Explicit voxel size to use when voxelizing the mesh into an SDF.

  • compensate_slicer_ras (bool) – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.

Example

>>> import pyvcad as pv
>>> surface = pv.SurfaceMesh('model.stl')
>>> node = pv.Mesh(surface, center=True, override_voxel_size=0.1)
center(self: pyvcad.pyvcad.Mesh) → bool#

Returns whether the mesh was centered at the origin after loading.

compensate_slicer_ras(self: pyvcad.pyvcad.Mesh) → bool#

Returns whether the mesh is mirrored across Y to compensate for 3D Slicer RAS exports.

disable_validation(self: pyvcad.pyvcad.Mesh) → bool#

Returns whether mesh validation was disabled when loading the file.

file_path(self: pyvcad.pyvcad.Mesh) → str#

Returns the path of the mesh file, or an empty string for a mesh built from a SurfaceMesh.

override_voxel_size(self: pyvcad.pyvcad.Mesh) → float | None#

Returns the explicit voxel size that bypasses the minimum bound heuristic, or None if it was not given.

sample_size(self: pyvcad.pyvcad.Mesh) → pyvcad.pyvcad.Vec3 | None#

Returns the requested voxel size for voxelizing the mesh, or None if it was not given.

sdf_shim(self: pyvcad.pyvcad.Mesh) → float#

Returns the amount subtracted from evaluated signed distance values.

class pyvcad.TexturedMesh#

A closed 3MF or OBJ textured solid with an intrinsic volumetric COLOR_RGBA field.

__init__(self: pyvcad.pyvcad.TexturedMesh, path: str, color_depth: SupportsFloat | SupportsIndex = 1.0, core_color: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1046fc470>, fallback_color: pyvcad.pyvcad.Vec3 | None = None, center: bool = False, obj_unit_scale: SupportsFloat | SupportsIndex = 1.0, override_voxel_size: SupportsFloat | SupportsIndex | None = None, disable_validation: bool = False) → None#

Loads a closed textured 3MF or OBJ solid. Surface color is extended inward from the closest surface point during prepare(). Source alpha is ignored and the intrinsic COLOR_RGBA field is opaque.

Parameters:
  • path (str) – Path to a .3mf or .obj file. OBJ dependencies resolve relative to this path.

  • color_depth (float) – Inward textured-shell depth in millimeters.

  • core_color (Vec3) – RGB color below the shell, with components in [0, 1].

  • fallback_color (Vec3, optional) – RGB color for triangles that have no imported appearance.

  • center (bool) – If true, center the resolved scene at the origin.

  • obj_unit_scale (float) – Millimeters per OBJ coordinate unit; 3MF units are automatic.

  • override_voxel_size (float, optional) – Explicit SDF and color-shell preparation voxel size.

  • disable_validation (bool) – Bypass closed-manifold validation for imperfect scans.

Example

>>> import pyvcad as pv
>>> node = pv.TexturedMesh('model.3mf', color_depth=1.0, center=True)
center(self: pyvcad.pyvcad.TexturedMesh) → bool#

Returns whether the resolved scene was centered at the origin.

color_depth(self: pyvcad.pyvcad.TexturedMesh) → float#

Returns the inward textured-shell depth.

Parameters:

arguments. (This method takes no)

Example

>>> depth = node.color_depth()
core_color(self: pyvcad.pyvcad.TexturedMesh) → pyvcad.pyvcad.Vec3#

Returns the opaque core RGB color.

Parameters:

arguments. (This method takes no)

Example

>>> color = node.core_color()
disable_validation(self: pyvcad.pyvcad.TexturedMesh) → bool#

Returns whether closed-manifold validation was bypassed.

fallback_color(self: pyvcad.pyvcad.TexturedMesh) → pyvcad.pyvcad.Vec3 | None#

Returns the RGB color used for triangles without appearance, or None if it was not given.

file_path(self: pyvcad.pyvcad.TexturedMesh) → str#

Returns the path of the .3mf or .obj file.

obj_unit_scale(self: pyvcad.pyvcad.TexturedMesh) → float#

Returns the OBJ millimeters-per-source-unit scale.

Parameters:

arguments. (This method takes no)

Example

>>> scale = node.obj_unit_scale()
override_voxel_size(self: pyvcad.pyvcad.TexturedMesh) → float | None#

Returns the explicit preparation voxel size in millimeters, or None if it was not given.

class pyvcad.RectPrism#

An axis-aligned rectangular prism leaf node/geometric primitive, defined by a center point and a size. Its value is the exact signed distance to the box.

static FromMinAndMax(min: pyvcad.pyvcad.Vec3, max: pyvcad.pyvcad.Vec3) → pyvcad.pyvcad.RectPrism#

Create a RectPrism from the given minimum and maximum points.

Parameters:
  • min (Vec3) – The minimum point of the RectPrism.

  • max (Vec3) – The maximum point of the RectPrism.

Returns:

The created RectPrism.

Return type:

RectPrism

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.RectPrism) -> None

Default constructor. Creates a RectPrism with a center of (0, 0, 0), size of (1, 1, 1).

  1. __init__(self: pyvcad.pyvcad.RectPrism, center: pyvcad.pyvcad.Vec3, size: pyvcad.pyvcad.Vec3) -> None

Constructor. Creates a RectPrism with a center and a size.

Parameters:
  • center (Vec3) – The center point of the RectPrism.

  • size (Vec3) – The full side lengths of the RectPrism in X, Y, and Z.

center(self: pyvcad.pyvcad.RectPrism) → pyvcad.pyvcad.Vec3#

Returns the center point of the RectPrism.

size(self: pyvcad.pyvcad.RectPrism) → pyvcad.pyvcad.Vec3#

Returns the side lengths of the RectPrism in X, Y, and Z.

class pyvcad.Sphere#

A sphere leaf node/geometric primitive. This node is a sphere with a center point and a radius. Its value is the exact signed distance.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.Sphere) -> None

Default constructor. Creates a Sphere with a center of (0, 0, 0) and a radius of 1.

Example

>>> import pyvcad as pv
>>> sphere = pv.Sphere()
  1. __init__(self: pyvcad.pyvcad.Sphere, center: pyvcad.pyvcad.Vec3, radius: typing.SupportsFloat | typing.SupportsIndex) -> None

Constructor. Creates a Sphere with a center and a radius.

Parameters:
  • center (Vec3) – The center point of the Sphere.

  • radius (float) – The radius of the Sphere.

Example

>>> import pyvcad as pv
>>> sphere = pv.Sphere(pv.Vec3(0, 0, 0), 5)
center(self: pyvcad.pyvcad.Sphere) → pyvcad.pyvcad.Vec3#

Returns the center point of the Sphere.

radius(self: pyvcad.pyvcad.Sphere) → float#

Returns the radius of the Sphere.

class pyvcad.Strut#

A leaf node that represents a strut. A strut is the conical frustum swept between two points, closed by a capping mode at each end.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.Strut, start: pyvcad.pyvcad.Vec3, end: pyvcad.pyvcad.Vec3, radius: typing.SupportsFloat | typing.SupportsIndex) -> None

Constructor. Creates a capsule shaped Strut with a start point, end point, and one radius.

Parameters:
  • start (Vec3) – The start point of the strut.

  • end (Vec3) – The end point of the strut.

  • radius (float) – The radius of the strut.

Example

>>> import pyvcad as pv
>>> strut = pv.Strut(pv.Vec3(0, 0, 0), pv.Vec3(10, 0, 0), 1.0)
  1. __init__(self: pyvcad.pyvcad.Strut, start: pyvcad.pyvcad.Vec3, end: pyvcad.pyvcad.Vec3, start_radius: typing.SupportsFloat | typing.SupportsIndex, end_radius: typing.SupportsFloat | typing.SupportsIndex, start_cap: pyvcad.pyvcad.CapMode = <CapMode.Sphere: 0>, end_cap: pyvcad.pyvcad.CapMode = <CapMode.Sphere: 0>) -> None

Constructor. Creates a Strut with an independent radius and cap mode at each end.

Parameters:
  • start (Vec3) – The start point of the strut.

  • end (Vec3) – The end point of the strut.

  • start_radius (float) – The radius at the start point.

  • end_radius (float) – The radius at the end point.

  • start_cap (CapMode) – The capping mode at the start point. Defaults to CapMode.Sphere.

  • end_cap (CapMode) – The capping mode at the end point. Defaults to CapMode.Sphere.

Example

>>> import pyvcad as pv
>>> beam = pv.Strut(pv.Vec3(0, 0, 0), pv.Vec3(10, 0, 0), 1.0, 3.0, pv.CapMode.Butt, pv.CapMode.Sphere)
property end#

The end point of the strut.

property end_cap#

The capping mode at the end point.

property end_radius#

The radius at the end point.

property start#

The start point of the strut.

property start_cap#

The capping mode at the start point.

property start_radius#

The radius at the start point.

class pyvcad.CapMode#

How the end of a strut or beam is closed off. Mirrors ST_CapMode from the 3MF Beam Lattice Extension.

Members:

Sphere : The end is closed with a full sphere of the end radius.

HemiSphere : The end is closed with the outward half of a sphere of the end radius.

Butt : The end is closed flat, leaving a cylindrical or conical shape.

Butt = <CapMode.Butt: 2>#
HemiSphere = <CapMode.HemiSphere: 1>#
Sphere = <CapMode.Sphere: 0>#
CapMode.name -> str
property value#
class pyvcad.CAD#

A CAD geometry primitive/leaf node. The CAD is loaded from a file into memory for sampling. The node supports STEP (.step, .stp) and IGES (.iges, .igs) files, matched case-insensitively. NOTE: using fast mode will convert the CAD model into a mesh for faster sampling. This hurts accuracy but dramatically speeds up performance. For the Inkjet compiler fast mode is recommended.

__init__(self: pyvcad.pyvcad.CAD, path: str, use_fast_mode: bool = True, fast_sdf_voxel_size: SupportsFloat | SupportsIndex | None = None) → None#

Constructor that takes a path to the CAD file to load.

Parameters:
  • path (str) – The path to the CAD file to load.

  • use_fast_mode (bool) – Whether to build an accelerated SDF cache during prepare.

  • fast_sdf_voxel_size (float | None) – Optional uniform SDF cache spacing in millimetres. None uses the smallest sampling voxel dimension.

property fast_sdf_voxel_size#

Requested uniform fast-SDF cache spacing in millimetres, or None for the sampler-derived default.

file_path(self: pyvcad.pyvcad.CAD) → str#

Returns the path of the CAD file, or an empty string for a node built from a CADPart.

property prepared_fast_sdf_voxel_size#

Uniform fast-SDF cache spacing used by the latest prepare call, or None before preparation.

use_fast_mode(self: pyvcad.pyvcad.CAD) → bool#

Returns whether preparation constructs an accelerated SDF grid.

class pyvcad.Cylinder#

A cylinder leaf node/geometric primitive. The cylinder’s axis is parallel to the Z-axis and passes through its center point. It extends height/2 above and below the center.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.Cylinder) -> None

Default constructor. Creates a Cylinder with a center of (0,0,0), radius of 1, height of 1.

  1. __init__(self: pyvcad.pyvcad.Cylinder, center: pyvcad.pyvcad.Vec3, radius: typing.SupportsFloat | typing.SupportsIndex, height: typing.SupportsFloat | typing.SupportsIndex) -> None

Constructor. Creates a Cylinder with a center, radius and height.

Parameters:
  • center (Vec3) – The center point of the Cylinder (the midpoint of its axis).

  • radius (float) – The radius of the Cylinder.

  • height (float) – The full height of the Cylinder along Z.

center(self: pyvcad.pyvcad.Cylinder) → pyvcad.pyvcad.Vec3#

Returns the center point of the Cylinder.

height(self: pyvcad.pyvcad.Cylinder) → float#

Returns the height of the Cylinder.

radius(self: pyvcad.pyvcad.Cylinder) → float#

Returns the radius of the Cylinder.

class pyvcad.Cone#

A cone leaf node/geometric primitive. The apex is at the origin and the axis points along +Y: the cone opens downward and its flat base lies in the plane y = -height, with radius height * tan(angle).

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.Cone) -> None

Default constructor. Creates a Cone with a half-angle of 0.5 radians and a height of 1.

  1. __init__(self: pyvcad.pyvcad.Cone, angle: typing.SupportsFloat | typing.SupportsIndex, height: typing.SupportsFloat | typing.SupportsIndex) -> None

Constructor. Creates a Cone defined by an angle and height.

Parameters:
  • angle (float) – The aperture half-angle in radians. The value is an exact distance for angles in (0, pi/2).

  • height (float) – The height of the cone, from the apex at the origin down to the base at y = -height.

angle(self: pyvcad.pyvcad.Cone) → float#

Returns the aperture half-angle of the cone in radians.

height(self: pyvcad.pyvcad.Cone) → float#

Returns the height of the cone.

class pyvcad.Torus#

A torus leaf node/geometric primitive with a major and a minor radius. The torus is centered at the origin and its ring lies in the XY plane, around the Z-axis.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.Torus) -> None

Default constructor. Creates a Torus with a center of (0, 0, 0), major radius of 2 and minor radius of 1.

  1. __init__(self: pyvcad.pyvcad.Torus, r1: typing.SupportsFloat | typing.SupportsIndex, r2: typing.SupportsFloat | typing.SupportsIndex) -> None

Constructor. Creates a Torus with a major and minor radii.

Parameters:
  • r1 (float) – Major radius (distance from the torus center to the tube center).

  • r2 (float) – Minor radius (radius of the tube).

r1(self: pyvcad.pyvcad.Torus) → float#

Returns the major radius (distance from the torus center to the tube center).

r2(self: pyvcad.pyvcad.Torus) → float#

Returns the minor radius (radius of the tube).

class pyvcad.GraphLattice#

A graph lattice leaf node. This class represents a lattice structure defined by a set of edges and a radius for the struts.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.GraphLattice, edges: collections.abc.Sequence[tuple[pyvcad.pyvcad.Vec3, pyvcad.pyvcad.Vec3]], radius: typing.SupportsFloat | typing.SupportsIndex) -> None

Constructor. Creates a GraphLattice from a list of edges and a strut radius.

Parameters:
  • edges (list[tuple[Vec3, Vec3]]) – The edges of the lattice.

  • radius (float) – The radius of the struts.

  1. __init__(self: pyvcad.pyvcad.GraphLattice, type: pyvcad.pyvcad.LatticeType, size: pyvcad.pyvcad.Vec3, radius: typing.SupportsFloat | typing.SupportsIndex) -> None

Constructor. Creates a GraphLattice with a lattice type, unit cell size and strut radius.

Parameters:
  • type (LatticeType) – The type of the lattice (BodyCenteredCubic, FaceCenteredCubic, Cubic, or KelvinCell).

  • size (Vec3) – The size of the lattice unit cell.

  • radius (float) – The radius of the struts.

cell_size(self: pyvcad.pyvcad.GraphLattice) → pyvcad.pyvcad.Vec3 | None#

Returns the unit cell size, or None if the lattice was built from an edge list.

edges(self: pyvcad.pyvcad.GraphLattice) → list[tuple[pyvcad.pyvcad.Vec3, pyvcad.pyvcad.Vec3]]#

Returns the strut edges, either as supplied or as generated for the unit cell.

lattice_type(self: pyvcad.pyvcad.GraphLattice) → pyvcad.pyvcad.LatticeType | None#

Returns the unit cell type, or None if the lattice was built from an edge list.

member_blend_radius(self: pyvcad.pyvcad.GraphLattice) → float#

Returns the smooth-blend radius between distinct struts.

radius(self: pyvcad.pyvcad.GraphLattice) → float#

Returns the strut radius.

set_member_blend_radius(self: pyvcad.pyvcad.GraphLattice, radius: SupportsFloat | SupportsIndex) → None#

Sets the smooth-blend radius between distinct struts; 0 (the default) is sharp.

Struts are joined with the shared quadratic blend, which fillets the nodes. Every edge is its own member, so give each edge once. Call before prepare(). Fillet material takes the nearest strut’s attributes. The quadratic blend keeps the distance a bound.

Parameters:

radius (float) – The non-negative blend radius in millimetres.

Example

>>> lattice = pv.GraphLattice(pv.LatticeType.BodyCenteredCubic, pv.Vec3(10, 10, 10), 1.0)
>>> lattice.set_member_blend_radius(0.5)
class pyvcad.LatticeType#

Enumeration of lattice types.

Members:

BodyCenteredCubic : Body Centered Cubic lattice type.

FaceCenteredCubic : Face Centered Cubic lattice type.

Cubic : Cubic lattice type.

KelvinCell : Kelvin Cell lattice type.

BodyCenteredCubic = <LatticeType.BodyCenteredCubic: 0>#
Cubic = <LatticeType.Cubic: 2>#
FaceCenteredCubic = <LatticeType.FaceCenteredCubic: 1>#
KelvinCell = <LatticeType.KelvinCell: 3>#
LatticeType.name -> str
property value#
class pyvcad.BeamLattice#

A beam and ball lattice defined over a shared vertex list, following the geometry model of the 3MF Beam Lattice Extension.

__init__(self: pyvcad.pyvcad.BeamLattice, vertices: collections.abc.Sequence[pyvcad.pyvcad.Vec3], beams: collections.abc.Sequence[pyvcad.pyvcad.Beam], radius: typing.SupportsFloat | typing.SupportsIndex, min_length: typing.SupportsFloat | typing.SupportsIndex = 0.0, cap: pyvcad.pyvcad.CapMode = <CapMode.Sphere: 0>, ball_mode: pyvcad.pyvcad.BallMode = <BallMode.None_: 0>, ball_radius: typing.SupportsFloat | typing.SupportsIndex = 0.0, balls: collections.abc.Sequence[pyvcad.pyvcad.Ball] = []) → None#

Constructor. Creates a BeamLattice from a vertex list and a list of beams.

Parameters:
  • vertices (list[Vec3]) – The shared vertex list that beams and balls index into.

  • beams (list[Beam]) – The beams of the lattice.

  • radius (float) – The default beam radius, used when a beam does not specify one.

  • min_length (float) – Beams shorter than this length are discarded. Defaults to 0.

  • cap (CapMode) – The default cap mode. Defaults to CapMode.Sphere.

  • ball_mode (BallMode) – Whether balls are generated. Defaults to no balls.

  • ball_radius (float) – The default ball radius. Required when balls are enabled.

  • balls (list[Ball]) – Explicit per-vertex ball entries. Defaults to an empty list.

Example

>>> import pyvcad as pv
>>> vertices = [pv.Vec3(0, 0, 0), pv.Vec3(10, 0, 0)]
>>> lattice = pv.BeamLattice(vertices, [pv.Beam(0, 1)], 1.0)
>>> lattice.prepare(pv.Vec3(0.25, 0.25, 0.25), 1.0)
property active_ball_count#

The number of balls that were generated.

property active_beam_count#

The number of beams that survived the min_length filter.

property ball_mode#

The ball mode.

property ball_radius#

The default ball radius.

property balls#

The explicit ball entries as supplied.

property beams#

The beams as supplied, including any dropped by min_length.

property cap#

The default cap mode.

property min_length#

The minimum beam length.

property radius#

The default beam radius.

property vertices#

The shared vertex list.

class pyvcad.BallMode#

Whether balls are generated at beam vertices. Mirrors ST_BallMode from the 3MF Beam Lattice Extension.

Members:

None_ : No balls are created.

Mixed : Balls are created only at vertices with an explicit ball entry.

All : Balls are created at every vertex that terminates a beam.

All = <BallMode.All: 2>#
Mixed = <BallMode.Mixed: 1>#
None_ = <BallMode.None_: 0>#
BallMode.name -> str
property value#
class pyvcad.ThreeMFBeamLattice#

Imports a 3MF Beam Lattice Extension file as an implicit tree. Covers geometry only; per-beam property references are not read.

__init__(self: pyvcad.pyvcad.ThreeMFBeamLattice, path: str, object_id: SupportsInt | SupportsIndex | None = None, include_triangle_mesh: bool = True, apply_clipping: bool = True, use_representation_mesh: bool = False, mesh_voxel_size: SupportsFloat | SupportsIndex | None = None) → None#

Constructor. Imports the beam lattice geometry of a 3MF file.

Parameters:
  • path (str) – The path to the .3mf file.

  • object_id (int, optional) – Imports only this object resource id. Defaults to None, the whole build.

  • include_triangle_mesh (bool) – Unions each object’s triangle shell with its lattice. Defaults to True.

  • apply_clipping (bool) – Applies the lattice clipping mode against its clipping mesh. Defaults to True.

  • use_representation_mesh (bool) – Substitutes the representation mesh for the lattice.

  • preview (The specification restricts representation meshes to display and)

  • part (so a)

  • False. (must not be manufactured from that result. Defaults to)

  • mesh_voxel_size (float, optional) – Explicit voxel size for triangle and clipping meshes. Defaults to None.

Example

>>> import pyvcad as pv
>>> lattice = pv.ThreeMFBeamLattice('pyramid.3mf')
>>> lattice.prepare(pv.Vec3(0.5, 0.5, 0.5), 1.0)
property apply_clipping#

True if lattice clipping modes are applied against their clipping meshes.

property ball_count#

The total number of explicit balls across the imported objects.

property beam_count#

The total number of beams across the imported objects.

property file_path#

The source file path.

property imported_objects#

The objects that were imported into the tree.

property include_triangle_mesh#

True if each object’s triangle shell is unioned with its lattice.

property mesh_voxel_size#

The explicit voxel size for triangle and clipping meshes, or None.

property object_id#

The selected object resource id, or None when the whole build is imported.

property scene#

The scene that was read from the file.

property use_representation_mesh#

True if representation meshes replace the lattice geometry.

class pyvcad.ClipMode#

How a beam lattice is clipped against its clipping mesh. Mirrors ST_ClippingMode from the 3MF Beam Lattice Extension.

Members:

None_ : The lattice is not clipped.

Inside : Only lattice geometry inside the clipping mesh is retained.

Outside : Only lattice geometry outside the clipping mesh is retained.

Inside = <ClipMode.Inside: 1>#
None_ = <ClipMode.None_: 0>#
Outside = <ClipMode.Outside: 2>#
ClipMode.name -> str
property value#
class pyvcad.MappedImplicitLattice#

A metric-corrected periodic implicit lattice evaluated through a CellMap.

__init__(self: pyvcad.pyvcad.MappedImplicitLattice, cell_map: pyvcad.pyvcad.CellMap, unit_cell: pyvcad.pyvcad.ImplicitUnitCell, mode: str = 'sheet', wall_thickness: object = None, level: object = None) → None#

Construct a mapped implicit lattice node.

Parameters:
  • cell_map (CellMap) – Immutable coordinate map.

  • unit_cell (ImplicitUnitCell) – Periodic scalar unit cell.

  • mode (str) – ‘sheet’ or ‘solid’.

  • wall_thickness (FloatAttribute | float | None) – Consumer-relative sheet thickness.

  • level (FloatAttribute | float | None) – Consumer-relative solid level offset.

Example

>>> node = pv.MappedImplicitLattice(cell_map, cell, 'sheet', thickness, level)
property cell_map#

Immutable coordinate map.

property component_side#

Negative or positive side of the underlying TPMS mid-surface.

property component_surface_distance#

Signed distance to the underlying TPMS mid-surface.

property level#

Solid level-offset field.

property mode#

Evaluation mode, ‘sheet’ or ‘solid’.

property shell#

Repeated implicit shell component.

property unit_cell#

Periodic implicit unit cell.

property wall_thickness#

Sheet wall-thickness field.

class pyvcad.MappedGraphLattice#

A compact graph unit cell tiled and curved through a CellMap.

Struts and joints are combined sharply unless member_blend_radius is given; then distinct struts and joints are joined with the shared smooth blend, which fillets the nodes. Copies of a strut or joint shared by neighbouring cells count as one member and never bulge. Fillet material takes the nearest member’s attributes.

Distance accuracy: always approximate. Where no map cell is found the value is the distance to the map domain rather than to the struts, and tapered pieces use a bounded nearest-point search.

__init__(self: pyvcad.pyvcad.MappedGraphLattice, cell_map: pyvcad.pyvcad.CellMap, unit_cell: pyvcad.pyvcad.GraphUnitCell, beam_radius: object, node_radius: object = None, curve_tolerance: SupportsFloat | SupportsIndex = 0.05, member_blend_radius: object = 0.0) → None#

Construct a mapped graph lattice node.

Parameters:
  • cell_map (CellMap) – Immutable coordinate map.

  • unit_cell (GraphUnitCell) – Normalized graph unit cell.

  • beam_radius (FloatAttribute | float) – Consumer-relative beam radius.

  • node_radius (FloatAttribute | float | None) – Optional node radius.

  • curve_tolerance (float) – Maximum mapped chord error in millimetres.

  • member_blend_radius (float | FloatAttribute | ScalarParameter | callable) – Smooth-blend radius between distinct struts and joints in millimetres; 0 (default) is sharp. A field needs ScalarParameter bounds.

Example

>>> node = pv.MappedGraphLattice(cell_map, cell, radius)
>>> filleted = pv.MappedGraphLattice(cell_map, cell, radius, member_blend_radius=0.3)
property beam_radius#

Beam-radius field.

property cell_map#

Immutable coordinate map.

property component_direction#

Selected strut tangent as a Vec3Attribute.

property component_id#

Selected component ID as a float attribute.

property component_material_tag#

Selected component legacy material tag as a float attribute.

property component_orientation_tag#

Selected component orientation tag as a float attribute.

property component_parameter#

Axial fraction along the selected strut.

property component_surface_distance#

Signed distance to the selected graph component.

property component_tag#

Selected component topology tag as a float attribute.

property curve_tolerance#

Maximum mapped chord error in millimetres.

property joints#

Reusable unit-cell joint components.

property member_blend_radius#

Smooth-blend radius between distinct struts and joints, as a ScalarParameter.

property node_radius#

Optional node-radius field, or None.

segment_info(self: pyvcad.pyvcad.MappedGraphLattice, world: pyvcad.pyvcad.Vec3) → object#

Return provenance for the nearest prepared beam segment inside the mapped domain.

Parameters:

world (Vec3) – World coordinate to inspect.

Returns:

The segment’s provenance, or None before prepare() or outside the map domain.

Return type:

MappedGraphSegmentInfo | None

property struts#

Reusable unit-cell strut components.

property unit_cell#

Graph unit cell used for tiling.

class pyvcad.MappedFaceLattice#

A native face unit cell tiled, adaptively curved, and thickened through a CellMap.

__init__(self: pyvcad.pyvcad.MappedFaceLattice, cell_map: pyvcad.pyvcad.CellMap, unit_cell: pyvcad.pyvcad.FaceUnitCell, wall_thickness: object, surface_mode: str = 'bilinear', surface_tolerance: SupportsFloat | SupportsIndex = 0.05) → None#

Construct a mapped face lattice node.

Parameters:
  • cell_map (CellMap) – Immutable structured coordinate map.

  • unit_cell (FaceUnitCell) – Static or native parametric face cell.

  • wall_thickness (FloatAttribute | float) – Positive consumer-relative full thickness.

  • surface_mode (str) – ‘bilinear’ or legacy-seamed ‘triangulated’.

  • surface_tolerance (float) – Maximum mapping and thickness interpolation error.

Example

>>> node = pv.MappedFaceLattice(cell_map, cell, thickness)
property cell_map#

Immutable coordinate map.

property component_direction#

Selected face normal as a Vec3Attribute.

property component_id#

Selected source face ID as a float attribute.

property component_material_tag#

Selected source face legacy material tag as a float attribute.

property component_orientation_tag#

Selected source face orientation tag as a float attribute.

property component_surface_distance#

Signed distance to the selected face component.

property component_tag#

Selected source face tag as a float attribute.

face_info(self: pyvcad.pyvcad.MappedFaceLattice, world: pyvcad.pyvcad.Vec3) → object#

Return provenance for the nearest prepared face inside the mapped domain.

Parameters:

world (Vec3) – World coordinate to inspect.

Returns:

The face’s provenance, or None before prepare() or outside the domain.

Return type:

MappedFaceInfo | None

midsurface_patches(self: pyvcad.pyvcad.MappedFaceLattice) → list[pyvcad.pyvcad.MappedFacePatch]#

Return authored world-space midsurface patches and sampled thicknesses.

The deterministic triangle or quadrilateral patches precede the node’s adaptive rendering triangulation. Folded plates retain their legacy boundary overhang.

Returns:

The patches.

Return type:

list[MappedFacePatch]

midsurface_vertex(self: pyvcad.pyvcad.MappedFaceLattice, logical: pyvcad.pyvcad.Vec3) → pyvcad.pyvcad.MappedFaceVertex#

Map one authored logical patch point through OpenVCAD and sample its full thickness.

Parameters:

logical (Vec3) – Logical CellMap coordinate on a midsurface patch.

Returns:

The logical point, its world position and the full thickness there.

Return type:

MappedFaceVertex

property plates#

Reusable source face or plate components.

property prepared_triangle_count#

Number of compact world-space triangles after preparation.

property surface_mode#

Prepared warped-quad interpretation.

property surface_tolerance#

Adaptive mapping tolerance in world units.

property unit_cell#

Face unit cell used for tiling.

property wall_thickness#

Full wall-thickness field.

class pyvcad.MappedRim#

A solid band along the cropped edges of a CellMap, built as a signed distance field from the map’s edge wall. The band spans the full map height, follows the cropped edge exactly, and extends the sampled width inward, so unioning it with a lattice mapped through the same CellMap seals the lattice’s open edge cells.

__init__(self: pyvcad.pyvcad.MappedRim, cell_map: pyvcad.pyvcad.CellMap, width: object = None) → None#

Construct a rim over a cell map’s cropped edge wall.

Parameters:
  • cell_map (CellMap) – Immutable coordinate map whose edges the rim follows.

  • width (FloatAttribute | float | None) – Inward rim width in world units. None (the default) means 1.0.

Raises:

RuntimeError – If cell_map is None, folded or invalid, or has no finite edge wall (every lateral direction is periodic and untrimmed).

Example

>>> rim = pv.MappedRim(cell_map, 2.0)
property cell_map#

Immutable coordinate map.

property width#

Inward rim width attribute.

class pyvcad.CellMapDomain#

The active volume of a CellMap as a solid node. Its field is the map’s signed domain distance in millimetres: negative inside the active, trimmed map volume and positive outside, including trimmed margins and holes. Use it to clip other nodes to a liner volume, as a keep-out, or as the host of a stochastic lattice.

__init__(self: pyvcad.pyvcad.CellMapDomain, cell_map: pyvcad.pyvcad.CellMap) → None#

Construct the solid domain of a cell map.

Parameters:

cell_map (CellMap) – Map whose active domain becomes the solid.

Example

>>> domain = pv.CellMapDomain(cell_map)
property cell_map#

Immutable coordinate map.

class pyvcad.Text#

A text leaf node which generates a 3D text object by extruding the text along the Z-axis. The node takes a string, height, depth, font aspect, font name, and alignment options. The anchor point is the origin, and the extrusion is centered on z = 0 (from -depth/2 to depth/2). The CAD part is created from the provided text.

__init__(self: pyvcad.pyvcad.Text, text: str, height: SupportsFloat | SupportsIndex, depth: SupportsFloat | SupportsIndex, aspect: pyvcad.pyvcad.FontAspect = <FontAspect.Regular: 0>, font: str = 'Consolas', h_align: pyvcad.pyvcad.HorizontalAlignment = <HorizontalAlignment.Center: 1>, v_align: pyvcad.pyvcad.VerticalAlignment = <VerticalAlignment.Center: 1>) → None#

Constructor. Creates a Text node with the provided text content, height, depth, font aspect, font name and alignment options.

Parameters:
  • text (str) – The text content for the 3D text.

  • height (float) – The height of the text.

  • depth (float) – The extrusion depth of the text.

  • aspect (FontAspect, optional) – The font aspect. Defaults to FontAspect.Regular.

  • font (str, optional) – The name of the font to use. Defaults to Consolas.

  • h_align (HorizontalAlignment, optional) – Horizontal alignment of the text. Defaults to HorizontalAlignment.Center.

  • v_align (VerticalAlignment, optional) – Vertical alignment of the text. Defaults to VerticalAlignment.Center.

aspect(self: pyvcad.pyvcad.Text) → pyvcad.pyvcad.FontAspect#

Returns the font aspect of the text.

depth(self: pyvcad.pyvcad.Text) → float#

Returns the extrusion depth of the text.

font(self: pyvcad.pyvcad.Text) → str#

Returns the name of the font used for the text.

h_align(self: pyvcad.pyvcad.Text) → pyvcad.pyvcad.HorizontalAlignment#

Returns the horizontal alignment of the text.

height(self: pyvcad.pyvcad.Text) → float#

Returns the height of the text.

text(self: pyvcad.pyvcad.Text) → str#

Returns the text content used for generating the 3D object.

v_align(self: pyvcad.pyvcad.Text) → pyvcad.pyvcad.VerticalAlignment#

Returns the vertical alignment of the text.

class pyvcad.FontAspect#

Specifies the font aspect for the text node

Members:

Regular : Regular font

Bold : Bold font

Italic : Italic font

BoldItalic : Bold and italic font

Bold = <FontAspect.Bold: 1>#
BoldItalic = <FontAspect.BoldItalic: 3>#
Italic = <FontAspect.Italic: 2>#
Regular = <FontAspect.Regular: 0>#
FontAspect.name -> str
property value#
class pyvcad.HorizontalAlignment#

Defines the horizontal position of text relative to its anchor point

Members:

Left : Text is aligned to the left of the anchor point

Center : Text is centered horizontally at the anchor point

Right : Text is aligned to the right of the anchor point

Center = <HorizontalAlignment.Center: 1>#
Left = <HorizontalAlignment.Left: 0>#
Right = <HorizontalAlignment.Right: 2>#
HorizontalAlignment.name -> str
property value#
class pyvcad.VerticalAlignment#

Defines the vertical position of text relative to its anchor point

Members:

Bottom : The anchor lies on the last line of the text

Center : The anchor lies on the center of the text

Top : The anchor lies on the line preceding the first line of the text

Top_First_Line : The anchor lies on the first line of the text

Bottom = <VerticalAlignment.Bottom: 0>#
Center = <VerticalAlignment.Center: 1>#
Top = <VerticalAlignment.Top: 2>#
Top_First_Line = <VerticalAlignment.Top_First_Line: 3>#
VerticalAlignment.name -> str
property value#
class pyvcad.SignedDistanceField#

A leaf node that samples a signed distance field stored in an OpenVDB FloatGrid. Negative values are inside.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.SignedDistanceField) -> None

Default constructor. Creates an empty SignedDistanceField.

  1. __init__(self: pyvcad.pyvcad.SignedDistanceField, grid: openvdb::v13_2::Grid<openvdb::v13_2::tree::Tree<openvdb::v13_2::tree::RootNode<openvdb::v13_2::tree::InternalNode<openvdb::v13_2::tree::InternalNode<openvdb::v13_2::tree::LeafNode<float, 3u>, 4u>, 5u>>>>) -> None

Constructor. Creates a SignedDistanceField from an OpenVDB FloatGrid level set.

pyvcad does not bind OpenVDB grid types, so this overload is only reachable with a grid object from a C++ extension. From Python, load a VDB file or wrap a FloatVolume instead.

Parameters:

grid (FloatGrid) – The OpenVDB level set. Negative values are inside.

  1. __init__(self: pyvcad.pyvcad.SignedDistanceField, occupancy_grid: openvdb::v13_2::Grid<openvdb::v13_2::tree::Tree<openvdb::v13_2::tree::RootNode<openvdb::v13_2::tree::InternalNode<openvdb::v13_2::tree::InternalNode<openvdb::v13_2::tree::LeafNode<bool, 3u>, 4u>, 5u>>>>, half_width_voxels: typing.SupportsInt | typing.SupportsIndex = 3, closing_steps: typing.SupportsInt | typing.SupportsIndex = 0, dilation_voxels: typing.SupportsInt | typing.SupportsIndex = 0, smoothing_steps: typing.SupportsInt | typing.SupportsIndex = 3) -> None

Create a SignedDistanceField from an OpenVDB BoolGrid occupancy grid.

The topology options are passed to OpenVDB topologyToLevelSet(). They only apply when converting boolean occupancy grids. The defaults preserve OpenVCAD’s existing conversion behavior. pyvcad does not bind OpenVDB grid types, so this overload is only reachable with a grid object from a C++ extension.

Parameters:
  • occupancy_grid (BoolGrid) – Grid whose active voxels represent occupied space.

  • half_width_voxels (int) – Half the width of the generated narrow-band level set, in voxel units.

  • closing_steps (int) – Number of morphological closing steps used to fill gaps in the active voxel region.

  • dilation_voxels (int) – Number of voxels to expand the active voxel region before conversion.

  • smoothing_steps (int) – Number of smoothing iterations applied after level-set generation.

  1. __init__(self: pyvcad.pyvcad.SignedDistanceField, vdb_volume: VDBVolume<openvdb::v13_2::Grid<openvdb::v13_2::tree::Tree<openvdb::v13_2::tree::RootNode<openvdb::v13_2::tree::InternalNode<openvdb::v13_2::tree::InternalNode<openvdb::v13_2::tree::LeafNode<float, 3u>, 4u>, 5u>>>>>) -> None

Constructor. Creates a SignedDistanceField that uses the grid of a FloatVolume as its level set.

The volume’s grid is copied, so the caller’s volume is not changed.

Parameters:

vdb_volume (FloatVolume) – A volume holding signed distances. Negative values are inside.

Raises:

RuntimeError – If vdb_volume is None.

  1. __init__(self: pyvcad.pyvcad.SignedDistanceField, vdb_file_path: str, grid_name: str = ‘occupancy’, half_width_voxels: typing.SupportsInt | typing.SupportsIndex = 3, closing_steps: typing.SupportsInt | typing.SupportsIndex = 0, dilation_voxels: typing.SupportsInt | typing.SupportsIndex = 0, smoothing_steps: typing.SupportsInt | typing.SupportsIndex = 3) -> None

Create a SignedDistanceField from a VDB file.

The named grid may be either a FloatGrid signed distance field or a BoolGrid occupancy grid. FloatGrid inputs are used directly, and the topology options are ignored. BoolGrid inputs are converted with OpenVDB topologyToLevelSet() using the supplied topology options. The defaults preserve OpenVCAD’s existing conversion behavior.

Parameters:
  • vdb_file_path (str) – Path to the VDB file.

  • grid_name (str) – Name of the grid to load from the file. Defaults to ‘occupancy’.

  • half_width_voxels (int) – Half the width of the generated narrow-band level set, in voxel units.

  • closing_steps (int) – Number of morphological closing steps used to fill gaps in the active voxel region.

  • dilation_voxels (int) – Number of voxels to expand the active voxel region before conversion.

  • smoothing_steps (int) – Number of smoothing iterations applied after level-set generation.

Example

>>> import pyvcad as pv
>>> node = pv.SignedDistanceField('part.vdb', 'occupancy')
closing_steps(self: pyvcad.pyvcad.SignedDistanceField) → int#

Returns the number of morphological closing steps used to convert an occupancy grid.

dilation_voxels(self: pyvcad.pyvcad.SignedDistanceField) → int#

Returns the number of dilation voxels used to convert an occupancy grid.

file_path(self: pyvcad.pyvcad.SignedDistanceField) → str#

Returns the path of the VDB file the field was loaded from, or an empty string for an in-memory grid.

from_occupancy_grid(self: pyvcad.pyvcad.SignedDistanceField) → bool#

Returns whether the field was converted from a BoolGrid occupancy grid.

grid_name(self: pyvcad.pyvcad.SignedDistanceField) → str#

Returns the name of the grid loaded from the VDB file, or an empty string for an in-memory grid.

half_width_voxels(self: pyvcad.pyvcad.SignedDistanceField) → int#

Returns the narrow-band half width, in voxels, used to convert an occupancy grid.

save_openvdb_occupancy_grid(self: pyvcad.pyvcad.SignedDistanceField, file_path: str) → None#

Save this node as a single OpenVDB BoolGrid named ‘occupancy’. Active SDF voxels with values <= 0 are occupied.

Parameters:

file_path (str) – The path of the .vdb file to write.

save_openvdb_sdf_grid(self: pyvcad.pyvcad.SignedDistanceField, file_path: str) → None#

Save this node as a single OpenVDB FloatGrid named ‘surface’.

Parameters:

file_path (str) – The path of the .vdb file to write.

smoothing_steps(self: pyvcad.pyvcad.SignedDistanceField) → int#

Returns the number of smoothing steps used to convert an occupancy grid.

class pyvcad.SurfaceReliefVolume#

A compact live implicit relief operand over an explicitly selected parametric surface. The operand extends inward by embed_mm and outward by the sampled height. Its zero surface is correct, but the varying-height field is not necessarily an exact Euclidean signed-distance field.

__init__(self: pyvcad.pyvcad.SurfaceReliefVolume, surface: pyvcad.pyvcad.ParametricSurface, height_field: pyvcad.pyvcad.HeightField, embed_mm: SupportsFloat | SupportsIndex, edge_falloff_mm: SupportsFloat | SupportsIndex = 0.0) → None#

Constructor. Creates a relief volume over a selected surface.

The volume is every point q + t * n(q) with -embed_mm <= t <= h(u, v) above the selected patch, where h is the height field sampled at the closest surface point. distance_accuracy() is always approximate.

Parameters:
  • surface (ParametricSurface) – The selected surface patch the relief stands on.

  • height_field (HeightField) – The outward height in millimeters, sampled in the surface’s normalized (u, v). Values are clamped to [0, maximum_height].

  • embed_mm (float) – How far the volume extends inward below the surface, in millimeters. Must be positive.

  • edge_falloff_mm (float) – Width of a smoothstep ramp that brings the height to zero at the patch boundary, in millimeters. 0 (the default) disables it.

Raises:

RuntimeError – If surface or height_field is None, embed_mm is not finite and positive, or edge_falloff_mm is negative or not finite.

property edge_falloff_mm#

The width of the boundary falloff ramp in millimeters (0 when disabled).

property embed_mm#

The inward embed depth in millimeters.

property height_field#

The height field sampled over the surface.

property surface#

The selected surface patch.

class pyvcad.PolygonExtrude#

An extruded polygon leaf node/geometric primitive. Takes a planar polygon defined by 3D vertices and extrudes it along its computed normal (right-hand rule) by a given height.

This is the polygon case of Extrude, placed in the polygon’s own plane: the distance is exact and Extrude’s coordinate fields are available.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.PolygonExtrude) -> None

Default constructor. Creates a unit square in the XY plane extruded 1 unit in +Z.

Example

>>> import pyvcad as pv
>>> poly = pv.PolygonExtrude()
  1. __init__(self: pyvcad.pyvcad.PolygonExtrude, vertices: collections.abc.Sequence[pyvcad.pyvcad.Vec3], height: typing.SupportsFloat | typing.SupportsIndex, symmetric: bool = False) -> None

Constructor. Creates an extruded polygon from coplanar 3D vertices.

Parameters:
  • vertices (list[Vec3]) – The vertices of the planar polygon (minimum 3, must be coplanar).

  • height (float) – The extrusion distance along the polygon normal.

  • symmetric (bool) – If True, extrudes height/2 on each side of the polygon plane.

Example

>>> import pyvcad as pv
>>> verts = [pv.Vec3(0,0,0), pv.Vec3(10,0,0), pv.Vec3(10,10,0), pv.Vec3(0,10,0)]
>>> poly = pv.PolygonExtrude(verts, 5.0, False)
vertices(self: pyvcad.pyvcad.PolygonExtrude) → list[pyvcad.pyvcad.Vec3]#

Returns the vertices of the planar polygon.

class pyvcad.PolygonRevolve#

A revolved polygon leaf node/geometric primitive. Takes a planar half-profile polygon and revolves it around an arbitrary axis line.

This is the polygon case of Revolve, placed on the given axis: the distance is exact for full and partial sweeps and Revolve’s coordinate fields are available.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.PolygonRevolve) -> None

Default constructor. Creates a unit-radius cylinder centered on the origin.

Example

>>> import pyvcad as pv
>>> node = pv.PolygonRevolve()
  1. __init__(self: pyvcad.pyvcad.PolygonRevolve, vertices: collections.abc.Sequence[pyvcad.pyvcad.Vec3], axis_start: pyvcad.pyvcad.Vec3, axis_end: pyvcad.pyvcad.Vec3, sweep_degrees: typing.SupportsFloat | typing.SupportsIndex = 360.0) -> None

Constructor. Creates a revolved polygon from a planar half-profile.

Parameters:
  • vertices (list[Vec3]) – The vertices of the planar half-profile polygon.

  • axis_start (Vec3) – A point on the revolve axis.

  • axis_end (Vec3) – A second point on the revolve axis defining positive direction.

  • sweep_degrees (float) – Positive sweep angle in degrees, in the range (0, 360].

Example

>>> import pyvcad as pv
>>> verts = [pv.Vec3(0,0,-5), pv.Vec3(10,0,-5), pv.Vec3(10,0,5), pv.Vec3(0,0,5)]
>>> node = pv.PolygonRevolve(verts, pv.Vec3(0,0,-5), pv.Vec3(0,0,5), 270.0)
axis_end(self: pyvcad.pyvcad.PolygonRevolve) → pyvcad.pyvcad.Vec3#

Returns the second point on the revolve axis, which defines the positive direction.

axis_start(self: pyvcad.pyvcad.PolygonRevolve) → pyvcad.pyvcad.Vec3#

Returns the first point on the revolve axis.

sweep_degrees(self: pyvcad.pyvcad.PolygonRevolve) → float#

Returns the sweep angle in degrees.

vertices(self: pyvcad.pyvcad.PolygonRevolve) → list[pyvcad.pyvcad.Vec3]#

Returns the vertices of the planar half-profile polygon.

Stochastic lattices#

Non-periodic Delaunay or Voronoi lattices built from world-space seed points and confined to a host Node. They take the host as an input but, like the other lattices, are terminal geometry. See sample_poisson_seeds(), blend_seed_sets() and jitter_seed_sites() on the Geometry page for making seed sets.

class pyvcad.StochasticGraphLattice#

A host-confined Delaunay or Voronoi beam lattice prepared from world-space seeds.

__init__(self: pyvcad.pyvcad.StochasticGraphLattice, host: pyvcad.pyvcad.Node, seed_points: collections.abc.Sequence[pyvcad.pyvcad.Vec3], extraction: pyvcad.pyvcad.StochasticGraphExtraction, beam_radius: object, node_radius: object = None, boundary_mode: pyvcad.pyvcad.StochasticBoundaryMode = <StochasticBoundaryMode.OPEN_CLIP: 0>, field_tolerance: typing.SupportsFloat | typing.SupportsIndex = 0.05, boundary_tolerance: typing.SupportsFloat | typing.SupportsIndex = 0.1, member_blend_radius: typing.SupportsFloat | typing.SupportsIndex = 0.0, prune_loose_fragments: bool = False, allow_outside_seeds: bool = False) → None#

Construct a non-periodic beam lattice. The host and attribute fields are prepared recursively when this node is prepared.

Parameters:
  • host (Node) – Implicit host that confines the lattice.

  • seed_points (list[Vec3]) – Unique world-space points, inside the host unless allow_outside_seeds is True.

  • extraction (StochasticGraphExtraction) – Graph extraction mode.

  • beam_radius (FloatAttribute | float) – Positive beam radius.

  • node_radius (FloatAttribute | float | None) – Optional joint-sphere radius.

  • boundary_mode (StochasticBoundaryMode) – Open or closed inspection topology.

  • field_tolerance (float) – Maximum radius interpolation error.

  • boundary_tolerance (float) – Host-boundary root tolerance.

  • member_blend_radius (float) – Smooth-union radius between distinct struts and joints.

  • prune_loose_fragments (bool) – Drop strut pieces the host cuts off at both ends, edges that never enter the host, and joints centred outside it, so clipping leaves no loose pieces.

  • allow_outside_seeds (bool) – Accept seeds outside the host, for example a layer that bounds the Voronoi cells at the host surface.

Example

>>> lattice = pv.StochasticGraphLattice(host, points, pv.StochasticGraphExtraction.VORONOI_EDGES, 0.5)
property allow_outside_seeds#

Whether seeds outside the host are accepted.

property beam_radius#

Beam-radius field.

boundary_caps(self: pyvcad.pyvcad.StochasticGraphLattice) → list[pyvcad.pyvcad.StochasticBoundaryCapProduct]#

Return explicit cap records for closed confinement after prepare().

property boundary_mode#

Configured boundary topology mode.

property boundary_tolerance#

Host-boundary inspection tolerance.

confined_edges(self: pyvcad.pyvcad.StochasticGraphLattice) → list[pyvcad.pyvcad.StochasticEdgeProduct]#

Return centerline fragments confined to the host after prepare().

delaunay_cells(self: pyvcad.pyvcad.StochasticGraphLattice) → list[pyvcad.pyvcad.DelaunayCellProduct]#

Return inspectable Delaunay tetrahedra after prepare().

property extraction#

Configured graph extraction mode.

property field_tolerance#

Maximum radius interpolation error.

property host#

Implicit host that confines the lattice.

property member_blend_radius#

Smooth-union radius between distinct struts and joints.

property node_radius#

Optional graph-node radius field, or None.

property prune_loose_fragments#

Whether loose host-clipped strut pieces are dropped.

property seed_points#

World-space seed points.

tessellation_edges(self: pyvcad.pyvcad.StochasticGraphLattice) → list[pyvcad.pyvcad.StochasticEdgeProduct]#

Return raw pre-host-intersection edges after prepare().

voronoi_cells(self: pyvcad.pyvcad.StochasticGraphLattice) → list[pyvcad.pyvcad.VoronoiCellProduct]#

Return working-domain Voronoi cells after prepare().

class pyvcad.StochasticFaceLattice#

A host-confined Delaunay or Voronoi plate lattice prepared from world-space seeds.

__init__(self: pyvcad.pyvcad.StochasticFaceLattice, host: pyvcad.pyvcad.Node, seed_points: collections.abc.Sequence[pyvcad.pyvcad.Vec3], extraction: pyvcad.pyvcad.StochasticFaceExtraction, wall_thickness: object, boundary_mode: pyvcad.pyvcad.StochasticBoundaryMode = <StochasticBoundaryMode.OPEN_CLIP: 0>, surface_tolerance: typing.SupportsFloat | typing.SupportsIndex = 0.05, boundary_tolerance: typing.SupportsFloat | typing.SupportsIndex = 0.1, member_blend_radius: typing.SupportsFloat | typing.SupportsIndex = 0.0) → None#

Construct a non-periodic plate lattice. The host and thickness field are prepared recursively when this node is prepared.

Parameters:
  • host (Node) – Implicit host that confines the lattice.

  • seed_points (list[Vec3]) – Unique world-space points inside the host.

  • extraction (StochasticFaceExtraction) – Face extraction mode.

  • wall_thickness (FloatAttribute | float) – Positive full plate thickness.

  • boundary_mode (StochasticBoundaryMode) – Open or closed inspection topology.

  • surface_tolerance (float) – Maximum thickness interpolation error.

  • boundary_tolerance (float) – Host-boundary inspection tolerance.

  • member_blend_radius (float) – Smooth-union radius between distinct plates.

Example

>>> lattice = pv.StochasticFaceLattice(host, points, pv.StochasticFaceExtraction.VORONOI_FACES, 0.5)
boundary_contact_patches(self: pyvcad.pyvcad.StochasticFaceLattice) → list[pyvcad.pyvcad.StochasticBoundaryContactProduct]#

Return approximate host-surface closure patches after prepare().

property boundary_mode#

Configured boundary topology mode.

boundary_seams(self: pyvcad.pyvcad.StochasticFaceLattice) → list[pyvcad.pyvcad.StochasticBoundarySeamProduct]#

Return approximate closure-patch seam segments after prepare().

property boundary_tolerance#

Host-boundary inspection tolerance.

delaunay_cells(self: pyvcad.pyvcad.StochasticFaceLattice) → list[pyvcad.pyvcad.DelaunayCellProduct]#

Return inspectable Delaunay tetrahedra after prepare().

property extraction#

Configured face extraction mode.

property host#

Implicit host that confines the lattice.

property member_blend_radius#

Smooth-union radius between distinct plates.

prepared_triangle_count(self: pyvcad.pyvcad.StochasticFaceLattice) → int#

Return the number of compact SDF triangles after prepare().

property seed_points#

World-space seed points.

property surface_tolerance#

Maximum thickness interpolation error.

tessellation_faces(self: pyvcad.pyvcad.StochasticFaceLattice) → list[pyvcad.pyvcad.StochasticFaceProduct]#

Return raw pre-host-intersection faces after prepare().

voronoi_cells(self: pyvcad.pyvcad.StochasticFaceLattice) → list[pyvcad.pyvcad.VoronoiCellProduct]#

Return working-domain Voronoi cells after prepare().

property wall_thickness#

Full plate-thickness field.

class pyvcad.StochasticGraphExtraction#

Graph geometry extracted from the shared three-dimensional tessellation.

Members:

DELAUNAY_EDGES : Unique edges of the Delaunay tetrahedralization.

DELAUNAY_FACET_VERTEX_CENTROID : Spokes from every Delaunay facet centroid to its vertices.

DELAUNAY_BARYCENTRIC_DUAL : Connections between neighboring tetrahedron centroids.

VORONOI_EDGES : Edges of bounded three-dimensional Voronoi cells.

DELAUNAY_BARYCENTRIC_DUAL = <StochasticGraphExtraction.DELAUNAY_BARYCENTRIC_DUAL: 2>#
DELAUNAY_EDGES = <StochasticGraphExtraction.DELAUNAY_EDGES: 0>#
DELAUNAY_FACET_VERTEX_CENTROID = <StochasticGraphExtraction.DELAUNAY_FACET_VERTEX_CENTROID: 1>#
VORONOI_EDGES = <StochasticGraphExtraction.VORONOI_EDGES: 3>#
StochasticGraphExtraction.name -> str
property value#
class pyvcad.StochasticFaceExtraction#

Plate geometry extracted from the shared three-dimensional tessellation.

Members:

DELAUNAY_FACETS : Unique triangular facets of the Delaunay tetrahedralization.

VORONOI_FACES : Polygonal faces separating bounded Voronoi cells.

DELAUNAY_FACETS = <StochasticFaceExtraction.DELAUNAY_FACETS: 0>#
VORONOI_FACES = <StochasticFaceExtraction.VORONOI_FACES: 1>#
StochasticFaceExtraction.name -> str
property value#
class pyvcad.StochasticBoundaryMode#

Boundary topology reported by a host-confined stochastic lattice.

Members:

OPEN_CLIP : Intersect geometry with the host and leave cut members open.

CLOSED_CONFINE : Confine geometry and mark host-boundary closures explicitly.

CLOSED_CONFINE = <StochasticBoundaryMode.CLOSED_CONFINE: 1>#
OPEN_CLIP = <StochasticBoundaryMode.OPEN_CLIP: 0>#
StochasticBoundaryMode.name -> str
property value#

Curves and profiles#

Solids built from curves and profiles.

class pyvcad.Tube#

A tube (pipe) of constant or varying radius along any curve.

The tube is every point within r of the curve, with r measured at the curve point closest to the query: the value is |p - c(t*)| - r(c(t*)). The radius may be a number or a field (FloatAttribute, callable, numba cfunc or ScalarParameter), sampled on the curve. A law along the curve is a field built from the curve’s own fields, for example curve.length_field(normalized=True).map_range(0, 1, 2.0, 0.5) for a radius tapering from 2 to 0.5. A field radius needs ScalarParameter bounds to size the bounding box.

Ends of open curves: CapMode.Sphere and CapMode.HemiSphere give a rounded end; CapMode.Butt cuts it flat. Closed curves have no ends.

Attributes: the node’s own, plus coordinate fields from coordinate_field(): ‘parameter’, ‘length’, ‘normalized_length’, ‘angle’ (degrees around the curve) and ‘distance’ (from the curve).

Distance accuracy (distance_accuracy()): exact for a straight tube with a constant radius, a bound for a curved one, approximate for a field radius or for butt caps on a curved open curve. Keep the radius below the curve’s radius of curvature, or the surface folds over itself.

__init__(self: pyvcad.pyvcad.Tube, curve: pyvcad.pyvcad.Curve, radius: object, start_cap: pyvcad.pyvcad.CapMode = <CapMode.Sphere: 0>, end_cap: pyvcad.pyvcad.CapMode = <CapMode.Sphere: 0>) → None#

Create a tube along a curve.

Parameters:
  • curve (Curve) – The centre curve.

  • radius (float | FloatAttribute | ScalarParameter | numba.cfunc | callable) – The radius, sampled on the curve. A field needs ScalarParameter bounds.

  • start_cap (CapMode) – How the start of an open curve is closed. Defaults to CapMode.Sphere.

  • end_cap (CapMode) – How the end of an open curve is closed. Defaults to CapMode.Sphere.

Example

>>> import pyvcad as pv
>>> path = pv.BSplineCurve.interpolate([(0, 0, 0), (20, 10, 5), (40, 0, 10)])
>>> pipe = pv.Tube(path, 2.0)
>>> taper = path.length_field(normalized=True).map_range(0.0, 1.0, 3.0, 1.0)
>>> horn = pv.Tube(path, pv.ScalarParameter(taper, minimum=1.0, maximum=3.0))
coordinate_field(self: pyvcad.pyvcad.Tube, name: str) → FloatAttribute#

A field for one of the tube’s coordinates, defined everywhere in space.

Parameters:

name (str) – ‘parameter’, ‘length’, ‘normalized_length’ (0 to 1 along the curve), ‘angle’ (degrees around the curve, from the rotation-minimizing frame) or ‘distance’ (from the curve).

Example

>>> pipe.set_attribute(pv.DefaultAttributes.MODULUS, pipe.coordinate_field('normalized_length').map_range(0, 1, 100, 1000))
curve(self: pyvcad.pyvcad.Tube) → pyvcad.pyvcad.Curve#

Returns the centre curve.

end_cap(self: pyvcad.pyvcad.Tube) → pyvcad.pyvcad.CapMode#

Returns how the end is closed.

radius(self: pyvcad.pyvcad.Tube) → pyvcad.pyvcad.ScalarParameter#

Returns the radius as a ScalarParameter.

start_cap(self: pyvcad.pyvcad.Tube) → pyvcad.pyvcad.CapMode#

Returns how the start is closed.

class pyvcad.Extrude#

A profile extruded from a sketch plane along its normal, with optional draft (taper), twist and a wall offset law.

The profile lies in plane (the XY plane by default) and is extruded along the plane’s normal from 0 to height (the other way for a negative height), or symmetrically about the plane. Draft tapers the walls: the section at distance s from the profile plane is the profile shrunk by s * tan(draft) (a negative draft widens it). Twist turns the section counter-clockwise about the normal, from 0 at the profile plane to twist degrees at the far end. The offset law shapes the walls along the height: points (f, w) grow the section by w (shrink it for negative w) at fraction f of the way from the profile plane to the far end (from bottom to top when symmetric), joined smoothly between the points.

Attributes: the node’s own, plus coordinate fields from coordinate_field(): ‘u’ and ‘v’ (section coordinates with the twist undone), ‘height’ (above the bottom face), ‘normalized_height’ (0 to 1) and ‘profile_distance’ (signed distance to the section outline).

Distance accuracy (distance_accuracy()): exact without draft, twist or offset law; an approximation with any of them (just outside the part the value drops below the distance to its bounding box).

__init__(self: pyvcad.pyvcad.Extrude, profile: object, height: SupportsFloat | SupportsIndex, symmetric: bool = False, draft: SupportsFloat | SupportsIndex = 0.0, twist: SupportsFloat | SupportsIndex = 0.0, plane: object = None, offset_law: object = None) → None#

Extrude a profile.

Parameters:
  • profile (Profile | Polygon2) – The profile, in the plane’s coordinates.

  • height (float) – Extrusion height; non-zero, negative extrudes against the normal.

  • symmetric (bool) – Extrude abs(height) / 2 to each side of the profile plane.

  • draft (float) – Wall taper in degrees, in (-90, 90); positive narrows away from the profile plane. Raises RuntimeError if the draft shrinks the section to nothing before the far end.

  • twist (float) – Total twist in degrees, counter-clockwise about the normal.

  • plane (Plane | None) – The sketch plane; None is the XY plane.

  • offset_law (list[tuple[float, float]] | None) – Points (fraction of the height, outward wall offset), at least two; None for straight walls. Raises RuntimeError if the walls meet.

Example

>>> import pyvcad as pv
>>> plate = pv.Profile.rounded_rectangle(40, 20, 3) - pv.Profile.circle(4)
>>> part = pv.Extrude(plate, 5.0)
>>> vase = pv.Extrude(pv.Profile.circle(10), 40.0, offset_law=[(0, 0), (0.4, 6), (1, -3)])
>>> column = pv.Extrude(pv.Profile.regular_polygon(6, 8.0), 40.0, twist=120.0, draft=3.0)
coordinate_field(self: pyvcad.pyvcad.Extrude, name: str) → FloatAttribute#

A field for one of the extrusion’s coordinates, defined everywhere in space.

Parameters:

name (str) – ‘u’, ‘v’, ‘height’, ‘normalized_height’ or ‘profile_distance’.

Example

>>> part.set_attribute(pv.DefaultAttributes.MODULUS, part.coordinate_field('normalized_height').map_range(0, 1, 100, 1000))
draft(self: pyvcad.pyvcad.Extrude) → float#

Returns the draft angle in degrees.

height(self: pyvcad.pyvcad.Extrude) → float#

Returns the extrusion height.

profile(self: pyvcad.pyvcad.Extrude) → pyvcad.pyvcad.Profile#

Returns the profile.

symmetric(self: pyvcad.pyvcad.Extrude) → bool#

Returns whether the extrusion is symmetric about the profile plane.

twist(self: pyvcad.pyvcad.Extrude) → float#

Returns the total twist in degrees.

class pyvcad.Revolve#

A profile revolved about an axis in its sketch plane, fully or through a partial angle.

The profile lies in plane and turns about the plane’s y axis through its origin. Its x is the distance from the axis (it must not be negative) and its y the position along the axis. The default plane is Plane.xz(): the axis is +Z, x is the radius and y becomes z. The sweep starts in the sketch plane and turns counter-clockwise about the axis. Profile edges on the axis are interior to the solid. A partial sweep is closed by flat caps.

Attributes: the node’s own, plus coordinate fields from coordinate_field(): ‘u’ (distance from the axis), ‘v’ (height along it), ‘angle’ (degrees from the start), ‘normalized_angle’ (0 to 1) and ‘profile_distance’ (signed distance in the meridian plane).

Distance accuracy: exact, for full and partial sweeps.

__init__(self: pyvcad.pyvcad.Revolve, profile: object, angle: SupportsFloat | SupportsIndex = 360.0, plane: object = None) → None#

Revolve a profile.

Parameters:
  • profile (Profile | Polygon2) – The profile, in x >= 0 of the plane’s coordinates.

  • angle (float) – Sweep angle in degrees, in (0, 360].

  • plane (Plane | None) – The sketch plane; the axis is its y axis. None is Plane.xz() (axis +Z).

Example

>>> import pyvcad as pv
>>> ring = pv.Revolve(pv.Profile.circle(2.0, center=(10, 0)))  # a torus
>>> cup = pv.Revolve(pv.Profile.polygon([(0, 0), (8, 0), (10, 12), (9, 12), (7, 1), (0, 1)]), 270.0)
angle(self: pyvcad.pyvcad.Revolve) → float#

Returns the sweep angle in degrees.

coordinate_field(self: pyvcad.pyvcad.Revolve, name: str) → FloatAttribute#

A field for one of the revolve’s coordinates, defined everywhere in space.

Parameters:

name (str) – ‘u’, ‘v’, ‘angle’, ‘normalized_angle’ or ‘profile_distance’.

Example

>>> cup.set_attribute(pv.DefaultAttributes.MODULUS, cup.coordinate_field('normalized_angle').map_range(0, 1, 100, 1000))
profile(self: pyvcad.pyvcad.Revolve) → pyvcad.pyvcad.Profile#

Returns the profile.

class pyvcad.Sweep#

A profile swept along a path curve.

The profile’s (u, v) plane is carried along the path in its rotation-minimizing frames (u along the frame normal, v along the binormal), so it does not twist on its own. For a planar path v follows the plane normal unless up says otherwise. scale and twist (degrees, counter-clockwise about the path tangent) may be numbers or fields sampled at the closest path point, so a law along the path is a field built from the path’s own fields, e.g. path.length_field(normalized=True). twist is the section’s angle at each point, not a total as in Extrude: a constant turns the whole section by that angle, and path.length_field(normalized=True) * 180 twists it half a turn from end to end. A field scale needs ScalarParameter bounds with a positive minimum. Open paths end in flat caps; closed paths close up.

Attributes: the node’s own, plus coordinate fields from coordinate_field(): ‘parameter’, ‘length’, ‘normalized_length’, ‘u’, ‘v’ (profile coordinates) and ‘profile_distance’.

Distance accuracy (distance_accuracy()): exact for a straight path with constant scale and a constant twist; otherwise approximate. Keep the profile inside the path’s radius of curvature; the constructor raises RuntimeError where the section certainly reaches past the centre of a bend.

__init__(self: pyvcad.pyvcad.Sweep, profile: object, path: pyvcad.pyvcad.Curve, scale: object = 1.0, twist: object = 0.0, up: object = None) → None#

Sweep a profile along a path.

Parameters:
  • profile (Profile | Polygon2) – The cross-section in its own (u, v) plane.

  • path (Curve) – The path.

  • scale (float | FloatAttribute | ScalarParameter | numba.cfunc | callable) – Section scale.

  • twist (float | FloatAttribute | ScalarParameter | numba.cfunc | callable) – Section angle in degrees at each point along the path (a constant rotates the whole section).

  • up (tuple | Vec3 | None) – Initial direction of the profile’s v axis.

Example

>>> import pyvcad as pv
>>> path = pv.BSplineCurve.interpolate([(0, 0, 0), (30, 10, 10), (60, 0, 20)])
>>> grow = path.length_field(normalized=True).map_range(0, 1, 1.0, 2.0)
>>> horn = pv.Sweep(pv.Profile.rounded_rectangle(8, 4, 1), path,
...                 scale=pv.ScalarParameter(grow, minimum=1.0, maximum=2.0),
...                 twist=path.length_field(normalized=True) * 180.0)
coordinate_field(self: pyvcad.pyvcad.Sweep, name: str) → FloatAttribute#

A field for one of the sweep’s coordinates, defined everywhere in space.

Parameters:

name (str) – ‘parameter’, ‘length’, ‘normalized_length’, ‘u’, ‘v’ or ‘profile_distance’.

Example

>>> horn.set_attribute(pv.DefaultAttributes.MODULUS, horn.coordinate_field('normalized_length').map_range(0, 1, 100, 1000))
path(self: pyvcad.pyvcad.Sweep) → pyvcad.pyvcad.Curve#

Returns the path.

profile(self: pyvcad.pyvcad.Sweep) → pyvcad.pyvcad.Profile#

Returns the profile.

scale(self: pyvcad.pyvcad.Sweep) → pyvcad.pyvcad.ScalarParameter#

Returns the scale as a ScalarParameter.

twist(self: pyvcad.pyvcad.Sweep) → pyvcad.pyvcad.ScalarParameter#

Returns the twist (degrees) as a ScalarParameter.

class pyvcad.Loft#

A solid that blends between profiles placed at heights along a sketch plane’s normal.

Each section is a profile drawn in plane (the XY plane by default) and lifted to its height. Between sections the cross-section is the zero level of a blend of the sections’ signed distances: smooth through every section (a monotone cubic, so no section is overshot) or linear between neighbours. Because it blends distances instead of matching boundary points, sections may differ in shape and in topology: a circle can become a square, and one hole can split into two. Flat caps close the first and last sections.

Attributes: the node’s own, plus coordinate fields from coordinate_field(): ‘u’ and ‘v’ (position in the sketch plane), ‘height’ (above the first section), ‘normalized_height’ (0 to 1) and ‘profile_distance’ (the blended section distance).

Distance accuracy (distance_accuracy()): approximate; the surface is exact to the blend, the value away from it is not a true distance.

__init__(self: pyvcad.pyvcad.Loft, sections: list, heights: collections.abc.Sequence[SupportsFloat | SupportsIndex], smooth: bool = True, plane: object = None) → None#

Loft through section profiles.

Parameters:
  • sections (list[Profile | Polygon2]) – The sections from bottom to top; at least two.

  • heights (list[float]) – The height of each section along the plane normal; strictly increasing.

  • smooth (bool) – True (the default) for a smooth blend through all sections, False for a linear blend between neighbours.

  • plane (Plane | None) – The sketch plane the sections are drawn in; None is the XY plane.

Example

>>> import pyvcad as pv
>>> transition = pv.Loft([pv.Profile.circle(10), pv.Profile.rectangle(16, 16)], [0.0, 30.0])
coordinate_field(self: pyvcad.pyvcad.Loft, name: str) → FloatAttribute#

A field for one of the loft’s coordinates, defined everywhere in space.

Parameters:

name (str) – ‘u’, ‘v’, ‘height’, ‘normalized_height’ or ‘profile_distance’.

Example

>>> transition.set_attribute(pv.DefaultAttributes.MODULUS,
...     transition.coordinate_field('normalized_height').map_range(0, 1, 100, 1000))
heights(self: pyvcad.pyvcad.Loft) → list[float]#

Returns the section heights.

sections(self: pyvcad.pyvcad.Loft) → list[pyvcad.pyvcad.Profile]#

Returns the section profiles, from bottom to top.

smooth(self: pyvcad.pyvcad.Loft) → bool#

Returns True for the smooth blend.

Supporting types (not nodes)#

These classes describe the parts of a lattice or its provenance. They are not Node subclasses: they are passed to, or returned by, the leaf nodes above.

3MF beam lattices

class pyvcad.Beam#

One beam of a BeamLattice. Unset radii and cap modes fall back to the lattice defaults.

__init__(self: pyvcad.pyvcad.Beam, v1: SupportsInt | SupportsIndex, v2: SupportsInt | SupportsIndex, r1: SupportsFloat | SupportsIndex | None = None, r2: SupportsFloat | SupportsIndex | None = None, cap1: pyvcad.pyvcad.CapMode | None = None, cap2: pyvcad.pyvcad.CapMode | None = None) → None#

Constructor. Creates a Beam between two vertex indices.

Parameters:
  • v1 (int) – Index of the first vertex.

  • v2 (int) – Index of the second vertex.

  • r1 (float, optional) – Radius at v1. Defaults to None, meaning the lattice radius.

  • r2 (float, optional) – Radius at v2. Defaults to None, meaning r1.

  • cap1 (CapMode, optional) – Cap at v1. Defaults to None, meaning the lattice cap mode.

  • cap2 (CapMode, optional) – Cap at v2. Defaults to None, meaning the lattice cap mode.

Example

>>> import pyvcad as pv
>>> beam = pv.Beam(0, 1, r1=1.0, r2=2.0, cap2=pv.CapMode.Butt)
property cap1#

Cap mode at v1, or None to use the lattice cap mode.

property cap2#

Cap mode at v2, or None to use the lattice cap mode.

property r1#

Radius at v1, or None to use the lattice radius.

property r2#

Radius at v2, or None to use r1.

property v1#

Index of the first vertex.

property v2#

Index of the second vertex.

class pyvcad.Ball#

One ball of a BeamLattice, centred on a vertex.

__init__(self: pyvcad.pyvcad.Ball, vertex: SupportsInt | SupportsIndex, radius: SupportsFloat | SupportsIndex | None = None) → None#

Constructor. Creates a Ball centred on a vertex index.

Parameters:
  • vertex (int) – Index of the vertex the ball is centred on.

  • radius (float, optional) – Ball radius. Defaults to None, meaning the lattice ball radius.

Example

>>> import pyvcad as pv
>>> ball = pv.Ball(3, radius=2.0)
property radius#

Ball radius, or None to use the lattice ball radius.

property vertex#

Index of the vertex the ball is centred on.

class pyvcad.ThreeMFBeamLatticeObject#

One mesh object resolved from a 3MF build, with its beam lattice if it carries one. Coordinates are in millimeters and already carry the build transforms.

property ball_mode#

The ball mode.

property ball_radius#

The default ball radius.

property balls#

The explicit ball entries of the lattice.

property beams#

The beams of the lattice.

property cap#

The most common resolved beam cap mode (CapMode.Sphere when there are no beams).

property clip_mode#

The clipping mode of the lattice.

property clip_triangles#

Clipping mesh triangles, as (i, j, k) vertex index tuples.

property clip_vertices#

Clipping mesh vertices, under the same transform.

property clipping_mesh_id#

The resource id of the clipping mesh, or None.

property has_lattice#

True when the object carries a beam lattice.

property min_length#

The minimum beam length.

property name#

The object name, when the file supplies one.

property object_id#

The 3MF resource id of the object.

property radius#

The most common resolved beam radius (1.0 when there are no beams). Every imported beam carries its own end radii, so this is informational.

property representation_mesh_id#

The resource id of the representation mesh, or None.

property representation_triangles#

Representation mesh triangles, as (i, j, k) vertex index tuples.

property representation_vertices#

Representation mesh vertices, under the same transform.

property triangles#

The triangle shell of the same object, as (i, j, k) vertex index tuples.

property vertices#

The mesh vertex list beams index into.

class pyvcad.ThreeMFBeamLatticeScene#

The resolved contents of a 3MF file read through the Beam Lattice Extension.

property objects#

Objects in build order.

property unit_scale_mm#

Millimeters per source model unit.

pyvcad.read_3mf_beam_lattice(path: str) → pyvcad.pyvcad.ThreeMFBeamLatticeScene#

Reads the geometry of a 3MF file, including any beam lattices, without building a tree.

Every build item is resolved through its component graph, transforms are baked into the returned coordinates, and coordinates are converted to millimeters. Beam and ball property references are not read; this importer covers geometry only.

Parameters:

path (str) – The path to the .3mf file.

Example

>>> import pyvcad as pv
>>> scene = pv.read_3mf_beam_lattice('pyramid.3mf')
>>> len(scene.objects[0].beams)

Mapped lattice components and provenance

class pyvcad.MappedGraphSegmentInfo#

Unit-cell provenance for the nearest prepared mapped graph segment.

property cell_index#

Integer (i, j, k) index of the map cell holding the segment.

property edge_tag#

Topology tag of the unit-cell edge, or -1.

property first_vertex_tag#

Tag of the edge’s first unit-cell vertex, or -1.

property material_tag#

Legacy material tag of the unit-cell edge, or -1.

property orientation_tag#

Orientation tag of the unit-cell edge, or -1.

property second_vertex_tag#

Tag of the edge’s second unit-cell vertex, or -1.

property unit_cell_edge_id#

Index of the unit-cell edge the segment came from, or -1.

class pyvcad.MappedGraphComponent#

Authoring metadata for one reusable graph-unit-cell component.

property direction#

Unit strut direction in unit-cell coordinates, from its first to its second vertex. (0, 0, 0) for joints.

property id#

Unit-cell edge index for a strut, or vertex index for a joint.

property material_tag#

Legacy strut material tag from the unit cell, or -1. Always -1 for joints.

property orientation_tag#

Strut orientation tag from the unit cell, or -1. Always -1 for joints.

property tag#

Edge tag (strut) or vertex tag (joint) from the unit cell, or -1 when the cell has none.

class pyvcad.MappedGraphComponents#

A reusable selection of struts or joints in one mapped graph unit cell.

set_attribute(self: pyvcad.pyvcad.MappedGraphComponents, name: str, attribute: Attribute, coordinates: str = 'node') → None#

Attach one named attribute to every selected repeated component.

Each component gets its own clone of the attribute, and an earlier attribute of the same name on that component is replaced.

Parameters:
  • name (str) – Attribute name.

  • attribute (Attribute) – Attribute definition.

  • coordinates (str) – ‘node’, ‘map’, ‘logical’, ‘cell_index’, or ‘cell’. Defaults to ‘node’.

Raises:

RuntimeError – If the lattice itself has an attribute of this name with a different return type.

Example

>>> lattice.struts[0].set_attribute('modulus', pv.FloatAttribute(2400))
where(self: pyvcad.pyvcad.MappedGraphComponents, selector: collections.abc.Callable) → pyvcad.pyvcad.MappedGraphComponents#

Select components with an authoring-time Python predicate.

Parameters:

selector (callable) – Receives MappedGraphComponent metadata.

Example

>>> vertical = lattice.struts.where(lambda item: abs(item.direction.z) > 0.9)
with_orientation(self: pyvcad.pyvcad.MappedGraphComponents, tag: SupportsInt | SupportsIndex) → pyvcad.pyvcad.MappedGraphComponents#

Select components carrying an integer orientation tag.

Parameters:

tag (int) – Orientation tag to match.

Example

>>> selected = lattice.struts.with_orientation(1)
with_tag(self: pyvcad.pyvcad.MappedGraphComponents, tag: SupportsInt | SupportsIndex) → pyvcad.pyvcad.MappedGraphComponents#

Select components carrying an integer topology tag.

Parameters:

tag (int) – Tag to match.

Example

>>> selected = lattice.struts.with_tag(2)
class pyvcad.MappedImplicitShell#

The repeated shell component of a mapped implicit lattice.

set_attribute(self: pyvcad.pyvcad.MappedImplicitShell, name: str, attribute: Attribute, coordinates: str = 'node') → None#

Attach one named attribute to the repeated implicit shell.

An earlier shell attribute of the same name is replaced.

Parameters:
  • name (str) – Attribute name.

  • attribute (Attribute) – Attribute definition.

  • coordinates (str) – ‘node’, ‘map’, ‘logical’, ‘cell_index’, or ‘cell’. Defaults to ‘node’.

Raises:

RuntimeError – If the lattice itself has an attribute of this name with a different return type.

Example

>>> gyroid.shell.set_attribute('temperature', pv.FloatAttribute('20 + 5*x'), 'cell')
class pyvcad.MappedFaceComponent#

Authoring metadata for one reusable face or plate component.

property id#

Index of the source face in the unit cell.

property material_tag#

Legacy material tag of the source face, or -1.

property orientation_tag#

Orientation tag of the source face, or -1.

property tag#

Topology tag of the source face, or -1 when the unit cell has none.

class pyvcad.MappedFaceComponents#

A reusable selection of source faces or plates.

set_attribute(self: pyvcad.pyvcad.MappedFaceComponents, name: str, attribute: Attribute, coordinates: str = 'node') → None#

Attach one named attribute to every selected repeated plate.

Each plate gets its own clone of the attribute, and an earlier attribute of the same name on that plate is replaced.

Parameters:
  • name (str) – Attribute name.

  • attribute (Attribute) – Attribute definition.

  • coordinates (str) – ‘node’, ‘map’, ‘logical’, ‘cell_index’, or ‘cell’. Defaults to ‘node’.

Raises:

RuntimeError – If the lattice itself has an attribute of this name with a different return type.

Example

>>> lattice.plates[0].set_attribute('modulus', pv.FloatAttribute(2400))
with_orientation(self: pyvcad.pyvcad.MappedFaceComponents, tag: SupportsInt | SupportsIndex) → pyvcad.pyvcad.MappedFaceComponents#

Select source faces carrying an integer orientation tag.

Parameters:

tag (int) – Orientation tag to match.

Example

>>> selected = lattice.plates.with_orientation(1)
with_tag(self: pyvcad.pyvcad.MappedFaceComponents, tag: SupportsInt | SupportsIndex) → pyvcad.pyvcad.MappedFaceComponents#

Select source faces carrying an integer topology tag.

Parameters:

tag (int) – Tag to match.

Example

>>> selected = lattice.plates.with_tag(2)
class pyvcad.MappedFaceInfo#

Unit-cell provenance for the nearest prepared mapped face triangle.

property cell_index#

Integer (i, j, k) index of the map cell holding the face.

property face_tag#

Topology tag of the source face, or -1.

property material_tag#

Legacy material tag of the source face, or -1.

property orientation_tag#

Orientation tag of the source face, or -1.

property unit_cell_face_id#

Index of the source face in the unit cell, or -1.

property vertex_tags#

Tags of the source face’s unit-cell vertices.

class pyvcad.MappedFacePatch#

One authored mapped midsurface triangle or quadrilateral before adaptive triangulation.

property cell_index#

Integer (i, j, k) index of the map cell holding the patch.

property face_tag#

Topology tag of the source face, or -1.

property logical_vertices#

Patch vertices in logical CellMap coordinates.

property material_tag#

Legacy material tag of the source face, or -1.

property orientation_tag#

Orientation tag of the source face, or -1.

property thicknesses#

Full wall thickness sampled at each patch vertex.

property unit_cell_face_id#

Index of the source face in the unit cell, or -1.

property vertex_tags#

Tags of the source face’s unit-cell vertices.

property world_vertices#

Patch vertices in world coordinates.

class pyvcad.MappedFaceVertex#

One exact OpenVCAD midsurface and thickness-field sample.

property logical#

The point in logical CellMap coordinates.

property thickness#

The full wall thickness sampled at the point.

property world#

The mapped point in world coordinates.

Stochastic lattice products

Inspection records returned by StochasticGraphLattice and StochasticFaceLattice.

class pyvcad.StochasticEdgeProduct#

One inspectable tessellation edge or host-confined edge fragment.

property cell_ids#

Adjacent Delaunay cell identifiers, padded with -1.

property extraction#

Graph extraction that produced this edge.

property first#

First world-space endpoint.

property first_is_boundary#

Whether the first endpoint lies on the host boundary.

property first_radius#

Prepared beam radius at the first endpoint.

property fragment_id#

Zero-based fragment identifier after host confinement.

property id#

Stable source edge identifier.

property is_boundary#

Whether a confined endpoint lies on the host boundary.

property is_hull#

Whether the source touches the convex hull.

property second#

Second world-space endpoint.

property second_is_boundary#

Whether the second endpoint lies on the host boundary.

property second_radius#

Prepared beam radius at the second endpoint.

property seed_ids#

Contributing input seed identifiers, padded with -1.

property working_domain_truncated#

Whether the finite working box truncated an unbounded dual.

class pyvcad.StochasticBoundaryCapProduct#

One explicit host-boundary cap record for a closed graph lattice.

property cell_ids#

Adjacent Delaunay cell identifiers, padded with -1.

property center#

World-space cap center on the host boundary.

property edge_id#

Source tessellation edge identifier.

property fragment_id#

Source confined-fragment identifier.

property id#

Stable cap identifier.

property radius#

Prepared beam radius at the cap.

property seed_ids#

Contributing seed identifiers, padded with -1.

property tangent#

Inward fragment tangent at the cap.

class pyvcad.StochasticFaceProduct#

One inspectable polygonal Delaunay or Voronoi face.

property cell_ids#

Adjacent Delaunay cell identifiers, padded with -1.

property extraction#

Face extraction that produced this polygon.

property id#

Stable face identifier.

property is_boundary_contact#

Whether the face contacts the implicit host boundary.

property is_hull#

Whether the face touches the convex hull.

property neighboring_seed_ids#

Seeds separated by a Voronoi face, padded with -1.

property seed_ids#

Contributing input seed identifiers, padded with -1.

property vertex_thicknesses#

Prepared full-thickness samples at polygon vertices.

property vertices#

World-space polygon vertices in winding order.

property working_domain_truncated#

Whether the finite working box truncated the face.

class pyvcad.StochasticBoundaryContactProduct#

One approximate host-surface patch closing a plate lattice.

property id#

Stable boundary-patch identifier.

property source_face_id#

Nearest source tessellation-face identifier.

property vertices#

Ordered polygon vertices on the temporary host mesh.

class pyvcad.StochasticBoundarySeamProduct#

One approximate seam segment around plate contact patches.

property first#

First world-space seam endpoint.

property id#

Stable seam-segment identifier.

property second#

Second world-space seam endpoint.

class pyvcad.DelaunayCellProduct#

One inspectable Delaunay tetrahedron with geometric quality metadata.

property centroid#

World-space tetrahedron centroid.

property circumcenter#

World-space Delaunay circumcenter.

property edge_ratio_quality#

Shortest-to-longest edge ratio in [0, 1].

property id#

Stable finite-cell identifier.

property seed_ids#

Four contributing input seed identifiers.

property vertices#

Four world-space tetrahedron vertices.

property volume#

Tetrahedron volume in cubic world units.

class pyvcad.VoronoiCellProduct#

One working-domain-bounded Voronoi cell and its size metrics.

property equivalent_diameter#

Diameter of a sphere with the same cell volume.

property face_ids#

Separating Voronoi face identifiers.

property id#

Stable cell identifier.

property maximum_diameter#

Maximum pairwise cell-vertex distance.

property neighboring_seed_ids#

Input seed identifiers sharing a Voronoi face.

property seed#

Owning world-space seed point.

property seed_id#

Input seed identifier owning this cell.

property vertices#

Unique world-space cell vertices.

property volume#

Working-domain cell volume in cubic world units.

property working_domain_truncated#

Whether this originally unbounded cell touches the working box.