Tree — composition nodes#
Composition nodes are non-Leaf nodes that each own one or more child subtrees. They describe how pieces are placed and combined in space: rigid transforms, mirrors, warps and tilings, sums and mixes of fields, constructive solid geometry (union, intersection, difference and bbox variants), offsets and shells.
Use them to assemble and modify designs built from Tree — leaf nodes without duplicating underlying primitives.
- class pyvcad.Identity#
A pass-through identity node that implements no transformations or operations of its own.
This node operates identically to the base Unary node. Its primary use case is to act as an attachment point for AttributeModifiers without affecting the global coordinate space of the attributes, which is useful when its child node contains an arbitrary transformation.
- Parameters:
child (Node) – The child node
Example
>>> import pyvcad as pv >>> child = pv.Sphere(pv.Vec3(0, 0, 0), 10) >>> node = pv.Identity(child)
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Identity) -> None
Default constructor.
Example
>>> import pyvcad as pv >>> node = pv.Identity()
__init__(self: pyvcad.pyvcad.Identity, child: pyvcad.pyvcad.Node) -> None
Constructor with child.
- Parameters:
child (Node) – The child node to attach to the tree
Example
>>> import pyvcad as pv >>> child = pv.Sphere(pv.Vec3(0, 0, 0), 10) >>> node = pv.Identity(child)
- class pyvcad.Rotate#
Rotates a child node about the centre of the child’s bounding box by three Euler angles in degrees.
Parameters, always in this order: pitch (about the X axis), yaw (about the Y axis), roll (about the Z axis). The Vec3 constructors pack the same angles as (x, y, z) = (pitch, yaw, roll).
Order: the child is turned by roll about Z first, then by yaw about Y, then by pitch about X, all about the fixed world axes through the pivot. The applied matrix is R = Rx(-pitch) * Ry(-yaw) * Rz(-roll), and a child point c lands at R * (c - pivot) + pivot.
Sign: each angle is negated before it is applied, so a positive angle turns the child clockwise when looking from the positive end of its axis toward the origin (the opposite of the right-hand rule). Rotate(90, 0, 0) sends +Y to -Z; Rotate(0, 90, 0) sends +Z to -X; Rotate(0, 0, 90) sends +X to -Y.
Pivot: the rotation turns about the child’s bounding-box centre (see pivot()), not about the origin. Use Transform to rotate about the origin.
Helpers: Rotate.from_axis_angle(axis, degrees, child) builds a right-hand-rule rotation about any axis, matrix() returns the exact 4x4 that is applied, and pyvcad.alignment_angles(forward, up) computes angles that aim a child’s local axes.
Rotation keeps the child’s signed distance exact.
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Rotate) -> None
Default constructor. Defaults to no rotation.
__init__(self: pyvcad.pyvcad.Rotate, pitch: typing.SupportsFloat | typing.SupportsIndex, yaw: typing.SupportsFloat | typing.SupportsIndex, roll: typing.SupportsFloat | typing.SupportsIndex) -> None
Constructor. Creates a Rotate from pitch, yaw, and roll angles in degrees (applied roll first, then yaw, then pitch).
- Parameters:
pitch (float) – Angle in degrees about the X axis, applied last.
yaw (float) – Angle in degrees about the Y axis, applied second.
roll (float) – Angle in degrees about the Z axis, applied first.
Example
>>> import pyvcad as pv >>> node = pv.Rotate(90, 0, 0) # +Y of the child points to -Z
__init__(self: pyvcad.pyvcad.Rotate, pitch: typing.SupportsFloat | typing.SupportsIndex, yaw: typing.SupportsFloat | typing.SupportsIndex, roll: typing.SupportsFloat | typing.SupportsIndex, child: pyvcad.pyvcad.Node) -> None
Constructor. Creates a Rotate from pitch, yaw, and roll angles in degrees and a child node.
- Parameters:
pitch (float) – Angle in degrees about the X axis, applied last.
yaw (float) – Angle in degrees about the Y axis, applied second.
roll (float) – Angle in degrees about the Z axis, applied first.
child (Node) – The child node.
__init__(self: pyvcad.pyvcad.Rotate, rotation_angles: pyvcad.pyvcad.Vec3) -> None
Constructor. Creates a Rotate from Euler angles packed in a Vec3 as (pitch, yaw, roll) in degrees, i.e. about (X, Y, Z).
- Parameters:
rotation_angles (Vec3) – Euler angles in degrees (pitch, yaw, roll).
__init__(self: pyvcad.pyvcad.Rotate, rotation_angles: pyvcad.pyvcad.Vec3, child: pyvcad.pyvcad.Node) -> None
Constructor. Creates a Rotate from Euler angles packed in a Vec3 as (pitch, yaw, roll) in degrees and a child node.
- angles(self: pyvcad.pyvcad.Rotate) pyvcad.pyvcad.Vec3#
Returns the authored Euler angles in degrees as a Vec3 (pitch, yaw, roll).
- static from_axis_angle(axis: pyvcad.pyvcad.Vec3, degrees: SupportsFloat | SupportsIndex, child: pyvcad.pyvcad.Node = None) pyvcad.pyvcad.Rotate#
Builds a rotation by an angle about any axis through the pivot, using the right-hand rule: a positive angle turns counter-clockwise when looking from the tip of the axis toward the origin. The equivalent (pitch, yaw, roll) are stored, so angles() reports them.
- Parameters:
Example
>>> import pyvcad as pv >>> node = pv.Rotate.from_axis_angle(pv.Vec3(0, 0, 1), 90, child) # +X of the child points to +Y
- matrix(self: pyvcad.pyvcad.Rotate) numpy.typing.NDArray[numpy.float64]#
Returns the 4x4 child-to-world matrix this node applies as a NumPy array, pivot included: T(pivot) @ R @ T(-pivot). Points are column vectors, so world = matrix @ [x, y, z, 1]. Transform(rotate.matrix(), child) reproduces this node.
- pivot(self: pyvcad.pyvcad.Rotate) pyvcad.pyvcad.Vec3#
Returns the point the rotation turns around: the child’s bounding-box centre.
- class pyvcad.Scale#
Scales a child about the origin by positive factors, uniformly or per axis. This node is unary, therefore can only have one child.
Uniform scaling (one factor, or three equal factors) is exact: the child’s signed distance is multiplied by the factor, so a true signed distance field stays a true signed distance field.
Non-uniform scaling (different factors per axis) is allowed but warps the signed distance field, so use it with caution. The node returns a first-order estimate
d / |S^-1 n|(d the child’s value, n its unit gradient direction, S = diag(sx, sy, sz)). It is exact on planar faces and accurate near the surface, and always lies between d * min(s) and d * max(s), but it drifts from the true distance far from curved surfaces. Offset, Shell, distance-driven attributes and smooth blends above a non-uniform Scale are therefore approximate. The sign, and so the surface itself, is always exact. A non-uniform scale costs about seven child evaluations per evaluation.- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Scale) -> None
Default constructor. Sets the scale to 1.0.
__init__(self: pyvcad.pyvcad.Scale, scale: typing.SupportsFloat | typing.SupportsIndex) -> None
Constructor. Sets the uniform scale.
- Parameters:
scale (float) – The positive uniform scale factor.
__init__(self: pyvcad.pyvcad.Scale, scale: typing.SupportsFloat | typing.SupportsIndex, child: pyvcad.pyvcad.Node) -> None
Constructor. Sets the uniform scale and child.
- Parameters:
scale (float) – The positive uniform scale factor.
child (Node) – The child node.
__init__(self: pyvcad.pyvcad.Scale, x: typing.SupportsFloat | typing.SupportsIndex, y: typing.SupportsFloat | typing.SupportsIndex, z: typing.SupportsFloat | typing.SupportsIndex) -> None
Constructor. Sets a per-axis scale. Unequal factors warp the signed distance field (see the class docs).
- Parameters:
x (float) – The positive scale factor along X.
y (float) – The positive scale factor along Y.
z (float) – The positive scale factor along Z.
Example
>>> import pyvcad as pv >>> node = pv.Scale(2.0, 1.0, 1.0)
__init__(self: pyvcad.pyvcad.Scale, x: typing.SupportsFloat | typing.SupportsIndex, y: typing.SupportsFloat | typing.SupportsIndex, z: typing.SupportsFloat | typing.SupportsIndex, child: pyvcad.pyvcad.Node) -> None
Constructor. Sets a per-axis scale and child. Unequal factors warp the signed distance field (see the class docs).
- Parameters:
x (float) – The positive scale factor along X.
y (float) – The positive scale factor along Y.
z (float) – The positive scale factor along Z.
child (Node) – The child node.
Example
>>> import pyvcad as pv >>> ellipsoid = pv.Scale(2.0, 1.0, 1.0, pv.Sphere(pv.Vec3(0, 0, 0), 5.0))
- factor(self: pyvcad.pyvcad.Scale) float#
Returns the authored uniform scale factor. Raises RuntimeError if the scale is non-uniform; use factors() instead.
- factors(self: pyvcad.pyvcad.Scale) pyvcad.pyvcad.Vec3#
Returns the per-axis scale factors as a Vec3 (sx, sy, sz).
- is_uniform(self: pyvcad.pyvcad.Scale) bool#
Returns True if all three factors are equal, so the signed distance is exact.
- class pyvcad.Translate#
Translates a child in Cartesian space by a given amount. This node is unary, with only one child, and evaluates and samples its child at the inversely translated point.
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Translate) -> None
Default constructor. Sets the translation to 0, 0, 0.
__init__(self: pyvcad.pyvcad.Translate, x: typing.SupportsFloat | typing.SupportsIndex, y: typing.SupportsFloat | typing.SupportsIndex, z: typing.SupportsFloat | typing.SupportsIndex) -> None
Constructor. Sets the translation to given values in Cartesian space.
- Parameters:
x (float) – Translation in the x direction.
y (float) – Translation in the y direction.
z (float) – Translation in the z direction.
__init__(self: pyvcad.pyvcad.Translate, x: typing.SupportsFloat | typing.SupportsIndex, y: typing.SupportsFloat | typing.SupportsIndex, z: typing.SupportsFloat | typing.SupportsIndex, child: pyvcad.pyvcad.Node) -> None
Constructor. Sets the translation to given values and sets the child.
- Parameters:
x (float) – Translation in the x direction.
y (float) – Translation in the y direction.
z (float) – Translation in the z direction.
child (Node) – The child to set.
- offset(self: pyvcad.pyvcad.Translate) pyvcad.pyvcad.Vec3#
Returns the authored translation offset as a Vec3.
- class pyvcad.Transform#
Places a child with a full 4x4 affine matrix in one step. This node is unary, so it may only have one child.
Convention: the matrix is written row by row, as on paper and as NumPy prints it. Points are column vectors and the matrix maps child coordinates to world coordinates, world = M @ [x, y, z, 1], so the translation is the last column. The matrix acts about the origin (unlike Rotate, which turns about the child’s bounding-box centre). Compose the usual way, M = T @ R @ S, to scale first, then rotate, then translate. The bottom row must be [0, 0, 0, 1] and the upper-left 3x3 block must be invertible; reflections are allowed.
Distance: if the 3x3 block is a rotation or reflection times a uniform scale, the signed distance stays exact. Otherwise it stretches space unevenly and warps the signed distance field, so use it with caution: the node returns the first-order estimate
d / |A^-T n|, like a non-uniform Scale. It is exact on planar faces and accurate near the surface, but it drifts from the true distance far from curved surfaces, so Offset, Shell, distance-driven attributes and smooth blends above it are approximate. The sign, and so the surface itself, is always exact. preserves_distance() tells which case applies.Transform.shear() and Transform.shear_matrix() build a shear.
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Transform) -> None
Default constructor. Sets the identity matrix.
__init__(self: pyvcad.pyvcad.Transform, matrix: typing.Annotated[numpy.typing.ArrayLike, numpy.float64]) -> None
Constructor. Sets the child-to-world matrix.
- Parameters:
matrix (array-like) – A (4, 4) affine matrix written row by row, world = matrix @ [x, y, z, 1].
Example
>>> import numpy as np >>> import pyvcad as pv >>> node = pv.Transform(np.array([[1, 0, 0, 10], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]]))
__init__(self: pyvcad.pyvcad.Transform, matrix: typing.Annotated[numpy.typing.ArrayLike, numpy.float64], child: pyvcad.pyvcad.Node) -> None
Constructor. Sets the child-to-world matrix and child.
- Parameters:
matrix (array-like) – A (4, 4) affine matrix written row by row, world = matrix @ [x, y, z, 1].
child (Node) – The child node.
Example
>>> import numpy as np >>> import pyvcad as pv >>> T = np.eye(4); T[:3, 3] = [10, 0, 0] >>> S = np.diag([2.0, 2.0, 2.0, 1.0]) >>> node = pv.Transform(T @ S, pv.Sphere(pv.Vec3(0, 0, 0), 5.0)) # scale, then translate
- inverse_matrix(self: pyvcad.pyvcad.Transform) numpy.typing.NDArray[numpy.float64]#
Returns the world-to-child matrix as a (4, 4) NumPy array written row by row.
- matrix(self: pyvcad.pyvcad.Transform) numpy.typing.NDArray[numpy.float64]#
Returns the child-to-world matrix as a (4, 4) NumPy array written row by row.
- preserves_distance(self: pyvcad.pyvcad.Transform) bool#
Returns True if the 3x3 block is a rotation or reflection times a uniform scale, so the signed distance is exact.
- static shear(direction: pyvcad.pyvcad.Vec3, normal: pyvcad.pyvcad.Vec3, factor: SupportsFloat | SupportsIndex, child: pyvcad.pyvcad.Node, origin: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x10477bd70>) pyvcad.pyvcad.Transform#
Shears a child: points slide along direction in proportion to their height above a fixed plane.
Returns a Transform built from shear_matrix(). Attributes follow the material. The surface is exact; distances away from it are the first-order estimate (exact above faces parallel to the fixed plane).
- Parameters:
direction (Vec3) – The direction points slide in.
normal (Vec3) – The normal of the fixed plane; must be perpendicular to direction.
factor (float) – How far a point slides per unit of height above the plane (tan of the shear angle).
child (Node) – The child node.
origin (Vec3) – A point on the fixed plane (default the origin).
Example
>>> import pyvcad as pv >>> block = pv.RectPrism(pv.Vec3(0, 0, 10), pv.Vec3(10, 10, 20)) >>> leaning = pv.Transform.shear(pv.Vec3(1, 0, 0), pv.Vec3(0, 0, 1), 0.5, block) # x += 0.5 * z
- static shear_matrix(direction: pyvcad.pyvcad.Vec3, normal: pyvcad.pyvcad.Vec3, factor: SupportsFloat | SupportsIndex, origin: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1046fe770>) numpy.typing.NDArray[numpy.float64]#
Returns the (4, 4) matrix of a shear, written row by row, ready to compose with other matrices.
Points slide along direction in proportion to their height above a fixed plane: p’ = p + factor * ((p - origin) . n) * d, with d and n the unit direction and normal. Points on the plane through origin with normal n stay put. factor is the tangent of the shear angle. A shear keeps volume; it is not a rotation or uniform scale, so a Transform built from it returns the first-order distance estimate (exact surface, approximate distances away from it).
- Parameters:
Example
>>> import numpy as np >>> import pyvcad as pv >>> S = pv.Transform.shear_matrix(pv.Vec3(1, 0, 0), pv.Vec3(0, 0, 1), np.tan(np.radians(20))) >>> T = np.eye(4); T[:3, 3] = [0, 0, 5] >>> node = pv.Transform(T @ S, pv.RectPrism(pv.Vec3(0, 0, 0), pv.Vec3(10, 10, 10)))
- class pyvcad.Mirror#
Reflects child geometry across a plane. The original child geometry is not retained; use Union(source, Mirror(…, source)) when both the source and reflected copy are desired.
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Mirror) -> None
Default constructor. Reflects across the x=0 plane.
__init__(self: pyvcad.pyvcad.Mirror, axis: str) -> None
Constructor. Reflects across a coordinate plane through the origin.
- Parameters:
axis (str) – One of ‘x’, ‘y’, or ‘z’ (case-insensitive).
Example
>>> import pyvcad as pv >>> m = pv.Mirror("x")
__init__(self: pyvcad.pyvcad.Mirror, axis: str, child: pyvcad.pyvcad.Node) -> None
Constructor. Reflects a child across a coordinate plane through the origin.
- Parameters:
axis (str) – One of ‘x’, ‘y’, or ‘z’ (case-insensitive).
child (Node) – The child node.
Example
>>> import pyvcad as pv >>> m = pv.Mirror("y", pv.Sphere(pv.Vec3(0, 5, 0), 2.0))
__init__(self: pyvcad.pyvcad.Mirror, axis: str, offset: typing.SupportsFloat | typing.SupportsIndex) -> None
Constructor. Reflects across an offset coordinate plane.
- Parameters:
axis (str) – One of ‘x’, ‘y’, or ‘z’ (case-insensitive).
offset (float) – Coordinate value of the mirror plane on the selected axis.
Example
>>> import pyvcad as pv >>> m = pv.Mirror("z", 10.0)
__init__(self: pyvcad.pyvcad.Mirror, axis: str, offset: typing.SupportsFloat | typing.SupportsIndex, child: pyvcad.pyvcad.Node) -> None
Constructor. Reflects a child across an offset coordinate plane.
- Parameters:
axis (str) – One of ‘x’, ‘y’, or ‘z’ (case-insensitive).
offset (float) – Coordinate value of the mirror plane on the selected axis.
child (Node) – The child node.
__init__(self: pyvcad.pyvcad.Mirror, point: pyvcad.pyvcad.Vec3, normal: pyvcad.pyvcad.Vec3) -> None
Constructor. Reflects across a plane defined by a point and normal.
- Parameters:
__init__(self: pyvcad.pyvcad.Mirror, point: pyvcad.pyvcad.Vec3, normal: pyvcad.pyvcad.Vec3, child: pyvcad.pyvcad.Node) -> None
Constructor. Reflects a child across a plane defined by a point and normal.
- Parameters:
__init__(self: pyvcad.pyvcad.Mirror, p0: pyvcad.pyvcad.Vec3, p1: pyvcad.pyvcad.Vec3, p2: pyvcad.pyvcad.Vec3) -> None
Constructor. Reflects across a plane defined by three non-collinear points.
- Parameters:
__init__(self: pyvcad.pyvcad.Mirror, p0: pyvcad.pyvcad.Vec3, p1: pyvcad.pyvcad.Vec3, p2: pyvcad.pyvcad.Vec3, child: pyvcad.pyvcad.Node) -> None
Constructor. Reflects a child across a plane defined by three non-collinear points.
- plane_normal(self: pyvcad.pyvcad.Mirror) pyvcad.pyvcad.Vec3#
Returns the unit normal of the mirror plane.
- plane_point(self: pyvcad.pyvcad.Mirror) pyvcad.pyvcad.Vec3#
Returns a point on the mirror plane.
- class pyvcad.MappedNode#
Wraps any child node through a CellMap so geometry designed in a flat box follows the curved map. A world point is inverted to logical map coordinates (u, v, w) and the child is evaluated at (u * s_u, v * s_v, w * s_w). With space=’physical’ the scale s is the map’s average millimetres per logical unit, so the child is authored in approximate millimetres inside child_bounds; with space=’logical’ the child is authored in cell units. The returned distance is a first-order Jacobian estimate (child value over the world gradient length): accurate near the surface and safe for meshing within a narrow band, but approximate far from it. The mapped child exists only inside the active map domain.
- __init__(self: pyvcad.pyvcad.MappedNode, cell_map: pyvcad.pyvcad.CellMap, child: pyvcad.pyvcad.Node, space: str = 'physical', scale: pyvcad.pyvcad.Vec3 | None = None, clip_to_domain: bool = True) None#
Wrap a child node through a cell map.
- Parameters:
cell_map (CellMap) – Map the child follows.
child (Node) – Node authored in child coordinates.
space (str) – ‘physical’ (default, approximate millimetres) or ‘logical’ (cell units).
scale (Vec3 | None) – Explicit child units per logical unit along U, V, W; overrides space.
clip_to_domain (bool) – True (default) clips the field with the domain distance inside the domain, so the wrapped solid ends where the map ends. False keeps the child’s own depth there, for a node that marks a zone of the map (zones, overlap bands).
Example
>>> pad = pv.MappedNode(cell_map, pv.RectPrism(pv.Vec3(20, 10, 2), pv.Vec3(8, 8, 4)))
- property cell_map#
Immutable coordinate map.
- property child_bounds#
Child-space box (minimum, maximum) that covers the whole logical map domain.
- property clip_to_domain#
Whether the field is clipped with the domain distance inside the domain.
- static physical_scale(cell_map: pyvcad.pyvcad.CellMap) pyvcad.pyvcad.Vec3#
Return a map’s average millimetres per logical unit along U, V, and W.
- Parameters:
cell_map (CellMap) – The map to measure.
Example
>>> scale = pv.MappedNode.physical_scale(cell_map)
- property scale#
Child units per logical unit along U, V, and W.
- property space#
Child coordinate convention.
- to_child(self: pyvcad.pyvcad.MappedNode, world: pyvcad.pyvcad.Vec3) object#
Map a world point into child coordinates, or None outside the active map domain.
- Parameters:
world (Vec3) – World-space point.
Example
>>> local = node.to_child(pv.Vec3(0, 0, 18))
- class pyvcad.Warp#
Deforms space: the child is sampled at g(p), where a map g pulls each world point p back to the child point it came from.
Attributes (pull-back): the child’s attributes are sampled at g(p), so material follows the deformation. coordinate_field() turns the map’s coordinates into fields: ‘child_x’, ‘child_y’ and ‘child_z’ (where a point pulls back to) for every map, plus the map’s own.
Distance accuracy: the surface is exact. The value is the first-order estimate
f / |J^T n|(f the child’s value at g(p), J the map’s Jacobian, n the child’s gradient direction): accurate near the surface, approximate far from it, like a MappedNode or a non-uniform Scale. With lipschitz=L, an upper bound on how much g stretches lengths, the value is f / L instead, never larger than the true distance inside the box for an exact child. distance_accuracy() is approximate either way: just outside the box f / L can fall below the distance to the box, so the value jumps where the box ends.Bounding box: a warp moves material, so a field map needs explicit bounds (the world box that holds the warped child). Built-in deformations work out their own box.
Built-in deformations: Warp.twist(), Warp.taper(), Warp.bend(), Warp.wrap_cylinder() and Warp.wrap_sphere(), whose maps are analytic, so their Jacobians are exact and cheap; and Warp.displace(), which moves material by a displacement field such as a simulation result.
- __init__(self: pyvcad.pyvcad.Warp, map: object, child: pyvcad.pyvcad.Node, bounds: object, lipschitz: SupportsFloat | SupportsIndex | None = None) None#
Constructor from a vector field: g(p) is the field’s value at p.
The map is sampled with d = 0. Its Jacobian is estimated by central differences (six more map evaluations per point), so keep the map smooth.
- Parameters:
map (Vec3Attribute | tuple | numba.cfunc | callable) – The map from world to child points. Any vector input: three expression strings such as (‘x’, ‘y - 2 * sin(x / 5)’, ‘z’), three component numba.cfuncs or callables, one numba.cfunc with signature void(float64, float64, float64, float64, CPointer(float64)) that writes x’, y’, z’ into its last argument, a callable f(x, y, z, d) returning three numbers (compiled with numba), a vector volume, or any Vec3Attribute. Callbacks run natively, in parallel, without the GIL.
child (Node) – The child node.
bounds (tuple[Vec3, Vec3]) – The (minimum, maximum) world box that holds the warped child.
lipschitz (float | None) – Optional upper bound L on how much g stretches lengths (
|g(p) - g(q)| <= L |p - q|). When given the value is f / L, never larger than the true distance inside the box for an exact child. distance_accuracy() is still approximate.
Example
>>> import math >>> import pyvcad as pv >>> plate = pv.RectPrism(pv.Vec3(0, 0, 0), pv.Vec3(40, 40, 4)) >>> wavy = pv.Warp(lambda x, y, z, d: (x, y, z - 2.0 * math.sin(x / 5.0)), plate, ... bounds=(pv.Vec3(-20, -20, -4), pv.Vec3(20, 20, 4)))
- static bend(radius: SupportsFloat | SupportsIndex, child: pyvcad.pyvcad.Node, origin: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1047a28b0>, direction: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1047c4930>, axis: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1047c4970>) pyvcad.pyvcad.Warp#
Bends a child around an axis.
The line through origin along direction is bent into a circle of radius
abs(radius)about an axis parallel to axis: toward direction x axis for a positive radius, away for a negative one. Lengths along that line are kept, and the child stays put at the origin. On the side it curls toward, keep the child closer to the line thanabs(radius)(farther would pass the bend centre and fold), and within half a turn each way (length along direction belowpi * abs(radius)). Coordinates: ‘angle’ (degrees, zero at the origin) and ‘radius’ (distance from the bend’s centre line).- Parameters:
radius (float) – The bend radius; non-zero, its sign picks the side.
child (Node) – The child node.
origin (Vec3) – A point on the line that is bent; it stays put (default the origin).
direction (Vec3) – The direction of the line that is bent (default +x).
axis (Vec3) – The bend axis direction (default +y).
Example
>>> import pyvcad as pv >>> strip = pv.RectPrism(pv.Vec3(0, 0, -1), pv.Vec3(60, 10, 2)) >>> arch = pv.Warp.bend(-20.0, strip) # curls down, away from +z
- bounds(self: pyvcad.pyvcad.Warp) object#
Returns the explicit (minimum, maximum) bounds, or None when the box comes from the map.
- coordinate_field(self: pyvcad.pyvcad.Warp, name: str) pyvcad.pyvcad.FloatAttribute#
A field for one of the map’s coordinates, defined everywhere in space.
Every map has ‘child_x’, ‘child_y’ and ‘child_z’: the child point a world point pulls back to. Built-in deformations add their own (see coordinate_names()).
- Parameters:
name (str) – The coordinate name.
Example
>>> wavy.set_attribute(pv.DefaultAttributes.TEMPERATURE, wavy.coordinate_field('child_x'))
- coordinate_names(self: pyvcad.pyvcad.Warp) list[str]#
Returns the names coordinate_field() accepts.
- static displace(displacement: object, child: pyvcad.pyvcad.Node, bounds: object = None) pyvcad.pyvcad.Warp#
Moves a child’s material by a displacement field: material at X moves to X + u(X).
Frame: u is sampled at the undeformed point X, in the child’s coordinates, and is a vector in those same coordinates (world coordinates when the Warp is the root). This is how simulation results store displacements: on the undeformed part. Attributes ride along with the material.
The pull-back solves X + u(X) = p by fixed-point iteration, with Newton steps when that stalls. A displacement that folds material onto itself (det(I + grad u) <= 0) has no pull-back: prepare() raises an error that names the place. failed_inversions() counts points that did not converge. Coordinate: ‘displacement’, how far the material at a point moved.
- Parameters:
displacement (str | Vec3Attribute | tuple | numba.cfunc | callable) – The field u. Any vector input (a constant, expressions, numba, a vector volume, or a simulation result from UnstructuredFieldDataset.vec3_attribute()), or the name of a Vec3Attribute set on the child node itself, which is then sampled directly at X (also outside the material).
child (Node) – The child node.
bounds (tuple[Vec3, Vec3] | None) – The world box of the moved child. None (default) estimates it by sampling u over the child’s box.
Example
>>> import pyvcad as pv >>> beam = pv.RectPrism(pv.Vec3(50, 0, 0), pv.Vec3(100, 10, 10)) >>> sag = pv.Warp.displace(('0', '0', '-0.0004 * x * x'), beam) # the free end drops 4 mm
- failed_inversions(self: pyvcad.pyvcad.Warp) int#
Returns how many points failed to pull back (displacements only; 0 for closed-form maps).
- lipschitz(self: pyvcad.pyvcad.Warp) float | None#
Returns the Lipschitz bound on the map, or None.
- static taper(rate: object, child: pyvcad.pyvcad.Node, axis: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1047787f0>, origin: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x10477b9f0>) pyvcad.pyvcad.Warp#
Tapers a child along an axis.
The section perpendicular to the axis at height h (measured from origin) is scaled about the axis by s(h) = 1 + the integral of the rate from 0 to h: a constant rate is a linear taper, and s = 1 at the origin. Heights are unchanged. The rate may be a field, read along the axis and integrated. s must stay positive over the child. Coordinates: ‘scale’ and ‘height’.
- Parameters:
rate (float | FloatAttribute | ScalarParameter | numba.cfunc | callable) – Scale change per unit length.
child (Node) – The child node.
axis (Vec3) – The taper axis direction (default +z).
origin (Vec3) – A point on the axis where the scale is 1 (default the origin).
Example
>>> import pyvcad as pv >>> column = pv.RectPrism(pv.Vec3(0, 0, 30), pv.Vec3(20, 20, 60)) >>> tapered = pv.Warp.taper(-0.01, column) # 40% of full size at the top
- static twist(rate: object, child: pyvcad.pyvcad.Node, axis: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x10471c930>, origin: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x10475b330>) pyvcad.pyvcad.Warp#
Twists a child about an axis.
The section at height h along the axis (measured from origin) turns counter-clockwise about the axis by the integral of the rate from 0 to h: a constant rate is a uniform twist, zero at the origin. The rate may be a field: it is read along the axis (at origin + h * axis) and integrated, so the angle keeps its meaning as the rate varies. Coordinates: ‘angle’ (degrees) and ‘height’. The box is the cylinder about the axis that holds the child. Distances use the analytic Jacobian (approximate away from the surface, like any warp).
- Parameters:
rate (float | FloatAttribute | ScalarParameter | numba.cfunc | callable) – Degrees per unit length.
child (Node) – The child node.
axis (Vec3) – The twist axis direction (default +z).
origin (Vec3) – A point on the axis where the angle is zero (default the origin).
Example
>>> import pyvcad as pv >>> bar = pv.RectPrism(pv.Vec3(0, 0, 30), pv.Vec3(10, 10, 60)) >>> uniform = pv.Warp.twist(3.0, bar) # 180 degrees over 60 mm >>> winding = pv.Warp.twist(pv.FloatAttribute('0.1 * z'), bar) # tighter toward the top
- static wrap_cylinder(radius: SupportsFloat | SupportsIndex, child: pyvcad.pyvcad.Node, center: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x10474ceb0>, axis: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1047c49f0>, reference_direction: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1047c4a30>) pyvcad.pyvcad.Warp#
Wraps a flat design around a cylinder.
Author the child flat: x is arc length around the cylinder, from 0 at the seam (reference_direction) counter-clockwise about axis up to 2 * pi * radius; y is height along the axis, from center; z is height above the cylinder surface, so z = 0 lies on the surface and z > 0 stands proud of it. Lengths on the surface are kept. The cylinder is exact and the inverse is closed form. Coordinates: ‘angle’ (degrees from the seam) and ‘radius’ (distance from the axis). For arbitrary curved surfaces, map the design with a MappedNode and a cell map instead.
- Parameters:
Example
>>> import math >>> import pyvcad as pv >>> band = pv.RectPrism(pv.Vec3(math.pi * 20, 0, 1), pv.Vec3(2 * math.pi * 20, 10, 2)) >>> ring = pv.Warp.wrap_cylinder(20.0, band) # a 2 mm wall from radius 20 to 22
- static wrap_sphere(radius: SupportsFloat | SupportsIndex, child: pyvcad.pyvcad.Node, center: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x10472a1b0>, north_axis: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1047c4ab0>, reference_direction: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1047c4af0>) pyvcad.pyvcad.Warp#
Wraps a flat design onto a sphere.
Author the child flat: x is arc length along the equator (longitude times radius, from 0 at reference_direction, counter-clockwise about north_axis), y is arc length along a meridian (latitude times radius, from the equator), and z is height above the sphere surface. Lengths along the equator and the meridians are kept; parallels shrink toward the poles, so a design gets narrower there. Keep it away from the poles (
abs(y) < pi * radius / 2). Coordinates: ‘longitude’, ‘latitude’ (degrees) and ‘radius’.- Parameters:
Example
>>> import pyvcad as pv >>> badge = pv.RectPrism(pv.Vec3(0, 0, 0.5), pv.Vec3(12, 12, 1)) >>> on_globe = pv.Warp.wrap_sphere(25.0, pv.Translate(30, 0, 0, badge))
- class pyvcad.Sum#
A node that sums all child Signed Distance Fields (SDFs). This node is N-ary, meaning it can have multiple children. The sum is calculated during evaluate() and results in the combined sum of all child SDFs.
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Sum) -> None
Default constructor.
__init__(self: pyvcad.pyvcad.Sum, iso_value: typing.SupportsFloat | typing.SupportsIndex) -> None
Constructor. Sets the iso value for the sum node.
- Parameters:
iso_value (float) – The iso value for the sum node.
__init__(self: pyvcad.pyvcad.Sum, iso_value: typing.SupportsFloat | typing.SupportsIndex, children: collections.abc.Sequence[pyvcad.pyvcad.Node]) -> None
Constructor. Sets the iso value and the children for the sum node.
- Parameters:
iso_value (float) – The iso value for the sum node.
children (list[Node]) – The children of the sum node.
- iso_value(self: pyvcad.pyvcad.Sum) float#
Returns the iso value added to the summed child distances.
- class pyvcad.Mix#
Interpolate two geometry and attribute fields with a spatial weight.
- class AttributePolicy#
Policy used when the same attribute is present on both children.
Members:
weighted : Linearly interpolate continuous values and material fractions.
dominant : Select the left value below 0.5 and the right value at or above 0.5.
- __init__(self: pyvcad.pyvcad.Mix.AttributePolicy, value: SupportsInt | SupportsIndex) None#
- dominant = <AttributePolicy.dominant: 1>#
- Mix.AttributePolicy.name -> str
- property value#
- weighted = <AttributePolicy.weighted: 0>#
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Mix, left: pyvcad.pyvcad.Node, right: pyvcad.pyvcad.Node, weight: FloatAttribute) -> None
Construct a field-driven geometry mix.
- Parameters:
left (Node) – Child selected by a zero weight.
right (Node) – Child selected by a one weight.
weight (FloatAttribute | float) – Clamped consumer-relative weight.
Example
>>> mixed = pv.Mix(left, right, pv.FloatAttribute(0.5))
__init__(self: pyvcad.pyvcad.Mix, left: pyvcad.pyvcad.Node, right: pyvcad.pyvcad.Node, weight: typing.SupportsFloat | typing.SupportsIndex) -> None
Construct a constant-weight geometry mix.
- Parameters:
Example
>>> mixed = pv.Mix(left, right, 0.5)
__init__(self: pyvcad.pyvcad.Mix, left: pyvcad.pyvcad.Node, right: pyvcad.pyvcad.Node, region: pyvcad.pyvcad.Node, half_width: typing.SupportsFloat | typing.SupportsIndex) -> None
Construct a smooth region-driven geometry mix.
- Parameters:
Example
>>> mixed = pv.Mix(left, right, region, 8.0)
- attribute_policies(self: pyvcad.pyvcad.Mix) dict[str, pyvcad.pyvcad.Mix.AttributePolicy]#
Return the per-attribute mix policies.
Example
>>> policies = mixed.attribute_policies()
- half_width(self: pyvcad.pyvcad.Mix) float#
Return the half-width of the region transition band (0 for a field-driven mix).
- region(self: pyvcad.pyvcad.Mix) pyvcad.pyvcad.Node#
Return the region node, or None for a field-driven mix.
- set_attribute_policy(self: pyvcad.pyvcad.Mix, name: str, policy: pyvcad.pyvcad.Mix.AttributePolicy) None#
Set the combination policy for one conflicting attribute.
- Parameters:
name (str) – Attribute name.
policy (Mix.AttributePolicy) – Weighted or dominant policy.
Example
>>> mixed.set_attribute_policy('segment_id', pv.Mix.AttributePolicy.dominant)
- weight(self: pyvcad.pyvcad.Mix) FloatAttribute#
Return the weight field, or None for a region-driven mix.
- class pyvcad.Tile#
A node that tiles a child geometry in a grid pattern.
Cell k along an axis spans [k c, (k + 1) c) with the child’s origin at the cell centre. The grid is infinite unless a count is given, which makes a finite array of copies 0 … n - 1 per axis (a count of 0 keeps that axis infinite). Copies that overhang their cell are measured against their neighbours too, so touching or overlapping copies union correctly.
Attributes follow the material (pull-back). instance_index_field() gives the copy index as a field to vary material per copy. Distance accuracy (distance_accuracy()): the child’s (a bound if copies touch or overlap) when the neighbouring copies checked cover the child’s overhang plus the bandwidth; an approximation otherwise, for example when the child fills its cell.
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Tile) -> None
Default constructor. The cell dimensions will be calculated from the child node when prepare is called.
__init__(self: pyvcad.pyvcad.Tile, child: pyvcad.pyvcad.Node) -> None
Constructor. Sets the child node. The cell dimensions will be calculated from the child node.
- Parameters:
child (Node) – The child node.
__init__(self: pyvcad.pyvcad.Tile, cell_x: typing.SupportsFloat | typing.SupportsIndex, cell_y: typing.SupportsFloat | typing.SupportsIndex, cell_z: typing.SupportsFloat | typing.SupportsIndex) -> None
Constructor. Sets the dimensions of a cell in the grid.
- Parameters:
cell_x (float) – The x dimension of a cell.
cell_y (float) – The y dimension of a cell.
cell_z (float) – The z dimension of a cell.
__init__(self: pyvcad.pyvcad.Tile, cell_x: typing.SupportsFloat | typing.SupportsIndex, cell_y: typing.SupportsFloat | typing.SupportsIndex, cell_z: typing.SupportsFloat | typing.SupportsIndex, child: pyvcad.pyvcad.Node, count: typing.Annotated[collections.abc.Sequence[typing.SupportsInt | typing.SupportsIndex], “FixedSize(3)”] | None = None) -> None
Constructor. Sets the dimensions of a cell in the grid, the child, and optionally a finite count.
- Parameters:
cell_x (float) – The x dimension of a cell.
cell_y (float) – The y dimension of a cell.
cell_z (float) – The z dimension of a cell.
child (Node) – The child node.
count (tuple[int, int, int] | None) – Copies along x, y and z; 0 keeps an axis infinite. None (default) tiles infinitely.
Example
>>> import pyvcad as pv >>> row = pv.Tile(12, 12, 12, pv.Sphere(pv.Vec3(0, 0, 0), 5.0), count=(5, 1, 1))
- cell_size(self: pyvcad.pyvcad.Tile) pyvcad.pyvcad.Vec3#
Returns the cell dimensions as a Vec3. Components are negative while the size is unset; prepare() then derives it from the child.
- count(self: pyvcad.pyvcad.Tile) Annotated[list[int], 'FixedSize(3)']#
Returns the number of copies along x, y and z (0 means infinite).
- has_cell_size(self: pyvcad.pyvcad.Tile) bool#
Returns True if the cell dimensions are set (authored, or derived from the child by prepare()).
- instance_index_field(self: pyvcad.pyvcad.Tile, axis: SupportsInt | SupportsIndex = -1) FloatAttribute#
The copy index of the cell containing a point, as a FloatAttribute.
Attach it (or a field derived from it) to this Tile to vary material per copy.
- Parameters:
axis (int) – 0, 1 or 2 for that axis’ cell index; -1 (default) for the linear index i + nx * (j + ny * k) of a finite array.
Example
>>> weight = row.instance_index_field(0).normalize(0.0, 4.0)
- class pyvcad.PolarArray#
Repeats a child N times around an axis.
Copy 0 is the child as authored. Without an angle range the copies are spaced 360 / N degrees apart; with angle_range=(start, end) in degrees they are spaced evenly from start to end inclusive (copy 0 rotated to start).
Attributes follow the material (pull-back). instance_index_field() gives the copy index as a field to vary material per copy. Distance accuracy (distance_accuracy()): the child’s when the copies checked around each point include every copy that could be nearest (a bound if copies overlap, or for a bound child turned off the coordinate axes); an approximation otherwise.
- __init__(self: pyvcad.pyvcad.PolarArray, count: SupportsInt | SupportsIndex, child: pyvcad.pyvcad.Node, axis: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x1046fc9f0>, center: pyvcad.pyvcad.Vec3 = <pyvcad.pyvcad.Vec3 object at 0x10472a7f0>, angle_range: tuple[typing.SupportsFloat | typing.SupportsIndex, typing.SupportsFloat | typing.SupportsIndex] | None=None) None#
Constructor.
- Parameters:
count (int) – The number of copies, at least 1.
child (Node) – The child node; copy 0.
axis (Vec3) – The rotation axis direction (default +z).
center (Vec3) – A point on the axis (default the origin).
angle_range (tuple[float, float] | None) – (start, end) in degrees to spread the copies over; None (default) fills the full circle.
Example
>>> import pyvcad as pv >>> blade = pv.RectPrism(pv.Vec3(12, 0, 0), pv.Vec3(14, 2, 4)) >>> fan = pv.PolarArray(8, blade) >>> arc = pv.PolarArray(5, blade, angle_range=(0.0, 90.0))
- angle_range(self: pyvcad.pyvcad.PolarArray) tuple[float, float] | None#
Returns the (start, end) angle range in degrees, or None for the full circle.
- axis(self: pyvcad.pyvcad.PolarArray) pyvcad.pyvcad.Vec3#
Returns the unit axis direction.
- center(self: pyvcad.pyvcad.PolarArray) pyvcad.pyvcad.Vec3#
Returns the point the axis passes through.
- count(self: pyvcad.pyvcad.PolarArray) int#
Returns the number of copies.
- instance_index_field(self: pyvcad.pyvcad.PolarArray) FloatAttribute#
The index of the copy nearest a point, as a FloatAttribute.
Attach it (or a field derived from it) to this PolarArray to vary material per copy.
Example
>>> weight = fan.instance_index_field().normalize(0.0, 7.0)
Booleans can be blended where their children meet. Union, Intersection and
Difference take a blend_radius (a number, or a field with bounds, where 0 means a sharp
edge) and a profile:
import pyvcad as pv
plate = pv.RectPrism(pv.Vec3(0, 0, 0), pv.Vec3(14, 14, 3))
post = pv.Cylinder(pv.Vec3(0, 0, 6.5), 3.0, 10.0)
joint = pv.Union([plate, post], blend_radius=2.0, profile=pv.BlendProfile.circular)
- class pyvcad.BlendProfile#
The cross-section of the fillet a blended Union, Intersection or Difference puts where surfaces meet. With r the blend radius:
quadratic: the original smooth blend (the default). Deepest at r, reaches 4r.
circular: a circular arc of radius r where surfaces meet at right angles.
chamfer: a flat 45-degree bevel of width about r.
cubic: a curvature-continuous fillet. Deepest at r, reaches 6r.
Members:
quadratic : The original smooth blend: a polynomial fillet, dip r, support 4r.
circular : A circular-arc fillet of radius r between perpendicular surfaces.
chamfer : A flat 45-degree bevel.
cubic : A curvature-continuous (C2) polynomial fillet, dip r, support 6r.
- chamfer = <BlendProfile.chamfer: 2>#
- circular = <BlendProfile.circular: 1>#
- cubic = <BlendProfile.cubic: 3>#
- BlendProfile.name -> str
- quadratic = <BlendProfile.quadratic: 0>#
- property value#
- class pyvcad.Difference#
A difference binary node. The difference is taken as the left child minus the right child.
An optional blend rounds the edge the cut leaves on the left child. The blend radius may be a number or a field (a FloatAttribute, callable or ScalarParameter with bounds); where it is 0 the edge stays sharp. The profile is a BlendProfile: quadratic (the default, and the original k blend), circular, chamfer or cubic. Attributes come from the left child.
Distance accuracy (distance_accuracy()): a bound for sharp differences and for a constant quadratic or cubic blend radius; an approximation for circular and chamfer blends and for any field radius. Never better than the less accurate child.
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Difference) -> None
Default constructor. Creates a Difference node.
__init__(self: pyvcad.pyvcad.Difference, left: pyvcad.pyvcad.Node, right: pyvcad.pyvcad.Node, blend_radius: object = 0.0, profile: pyvcad.pyvcad.BlendProfile = <BlendProfile.quadratic: 0>) -> None
Constructor. Creates a Difference node with the given left and right children and an optional blend.
- Parameters:
left (Node) – The left child node.
right (Node) – The right child node, subtracted from the left.
blend_radius (float | FloatAttribute | ScalarParameter | numba.cfunc | callable) – The blend radius; 0 is sharp. A field needs ScalarParameter bounds.
profile (BlendProfile) – The fillet profile.
Example
>>> import pyvcad as pv >>> radius = 5 >>> left_sphere = pv.Sphere(pv.Vec3(-radius/2, 0, 0), radius) >>> right_sphere = pv.Sphere(pv.Vec3(radius/2, 0, 0), radius) >>> difference = pv.Difference(left_sphere, right_sphere) >>> chamfered = pv.Difference(left_sphere, right_sphere, blend_radius=0.5, ... profile=pv.BlendProfile.chamfer)
__init__(self: pyvcad.pyvcad.Difference, k: typing.SupportsFloat | typing.SupportsIndex) -> None
Constructor for smooth difference.
- Parameters:
k (float) – The smoothing radius. When k > 0, produces a smooth subtraction.
Example
>>> import pyvcad as pv >>> left_sphere = pv.Sphere(pv.Vec3(-2, 0, 0), 3) >>> right_sphere = pv.Sphere(pv.Vec3(2, 0, 0), 3) >>> smooth_diff = pv.Difference(1.0) >>> smooth_diff.set_left(left_sphere) >>> smooth_diff.set_right(right_sphere)
__init__(self: pyvcad.pyvcad.Difference, k: typing.SupportsFloat | typing.SupportsIndex, left: pyvcad.pyvcad.Node, right: pyvcad.pyvcad.Node) -> None
Constructor for smooth difference with children.
- Parameters:
Example
>>> import pyvcad as pv >>> left_sphere = pv.Sphere(pv.Vec3(-2, 0, 0), 3) >>> right_sphere = pv.Sphere(pv.Vec3(2, 0, 0), 3) >>> smooth_diff = pv.Difference(1.0, left_sphere, right_sphere)
- blend_profile(self: pyvcad.pyvcad.Difference) pyvcad.pyvcad.BlendProfile#
Returns the blend profile.
- blend_radius(self: pyvcad.pyvcad.Difference) pyvcad.pyvcad.ScalarParameter#
Returns the blend radius as a ScalarParameter (a constant or a field).
- static clearance(left: pyvcad.pyvcad.Node, right: pyvcad.pyvcad.Node, gap: object, blend_radius: object = 0.0, profile: pyvcad.pyvcad.BlendProfile = <BlendProfile.quadratic: 0>) pyvcad.pyvcad.Difference#
Subtract right from left, leaving a gap around right.
Builds Difference(left, Offset(gap, right)): use it to cut a hole or slot that a part fits into with a clearance. The gap may be a field (with ScalarParameter bounds), so the clearance can vary around the part. Attributes come from left.
- Parameters:
left (Node) – The body to cut.
right (Node) – The part the cut must clear.
gap (float | FloatAttribute | ScalarParameter | numba.cfunc | callable) – The clearance; never negative.
blend_radius (float | FloatAttribute | ScalarParameter | callable) – Blend radius of the cut’s edges; 0 (default) is sharp.
profile (BlendProfile) – The fillet profile.
Example
>>> import pyvcad as pv >>> plate = pv.RectPrism(pv.Vec3(0, 0, 0), pv.Vec3(30, 30, 6)) >>> peg = pv.Cylinder(pv.Vec3(0, 0, 0), 4.0, 10.0) >>> socket = pv.Difference.clearance(plate, peg, 0.3)
- smooth_k(self: pyvcad.pyvcad.Difference) float#
Returns the constant smoothing radius (0 for a sharp difference). Raises for a field radius.
- class pyvcad.Intersection#
Intersection of two or more nodes. This node is N-ary, so it can have multiple children.
An optional blend rounds the inside corners where children meet. The blend radius may be a number or a field (a FloatAttribute, callable or ScalarParameter with bounds); where it is 0 the corner stays sharp. The profile is a BlendProfile: quadratic (the default, and the original k blend), circular, chamfer or cubic. The result does not depend on the order of the children. Blending only removes material, so attributes are combined as before.
Distance accuracy (distance_accuracy()): a bound for sharp intersections and for a constant quadratic or cubic blend radius; an approximation for circular and chamfer blends, for any field radius, and for children whose boxes do not overlap. Never better than the least accurate child.
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Intersection) -> None
Default constructor. Creates an Intersection node.
__init__(self: pyvcad.pyvcad.Intersection, lhs: pyvcad.pyvcad.Node, rhs: pyvcad.pyvcad.Node) -> None
Constructor with two children.
__init__(self: pyvcad.pyvcad.Intersection, k: typing.SupportsFloat | typing.SupportsIndex) -> None
Constructor for smooth intersection.
- Parameters:
k (float) – The smoothing radius. When k > 0, produces a smooth blend.
__init__(self: pyvcad.pyvcad.Intersection, k: typing.SupportsFloat | typing.SupportsIndex, children: collections.abc.Sequence[pyvcad.pyvcad.Node]) -> None
Constructor for smooth intersection with children.
- Parameters:
k (float) – The smoothing radius. When k > 0, produces a smooth blend.
children (list[Node]) – The children nodes.
__init__(self: pyvcad.pyvcad.Intersection, children: collections.abc.Sequence[pyvcad.pyvcad.Node], blend_radius: object = 0.0, profile: pyvcad.pyvcad.BlendProfile = <BlendProfile.quadratic: 0>) -> None
Constructor with children and an optional blend.
- Parameters:
children (list[Node]) – The children nodes.
blend_radius (float | FloatAttribute | ScalarParameter | numba.cfunc | callable) – The blend radius; 0 is sharp. A field needs ScalarParameter bounds.
profile (BlendProfile) – The fillet profile.
Example
>>> import pyvcad as pv >>> box = pv.RectPrism(pv.Vec3(0, 0, 0), pv.Vec3(10, 10, 10)) >>> ball = pv.Sphere(pv.Vec3(0, 0, 0), 6.5) >>> rounded = pv.Intersection([box, ball], blend_radius=1.0, profile=pv.BlendProfile.chamfer)
- blend_profile(self: pyvcad.pyvcad.Intersection) pyvcad.pyvcad.BlendProfile#
Returns the blend profile.
- blend_radius(self: pyvcad.pyvcad.Intersection) pyvcad.pyvcad.ScalarParameter#
Returns the blend radius as a ScalarParameter (a constant or a field).
- smooth_k(self: pyvcad.pyvcad.Intersection) float#
Returns the constant smoothing radius (0 for a sharp intersection). Raises for a field radius.
- class pyvcad.BBoxIntersection#
Intersection of multiple nodes using an AABB tree to speed things up. This node is N-ary, so it can have any number of children.
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.BBoxIntersection) -> None
Default constructor for BBoxIntersection.
__init__(self: pyvcad.pyvcad.BBoxIntersection, children: collections.abc.Sequence[pyvcad.pyvcad.Node]) -> None
Constructor that creates a BBoxIntersection node with the given list of child nodes.
- Parameters:
children (list of Node) – The list of child nodes.
- class pyvcad.Union#
A union of two or more nodes. This node is N-ary, so it can have multiple children.
An optional blend rounds the seams between children. The blend radius may be a number or a field (a FloatAttribute, callable or ScalarParameter with bounds); where it is 0 the seam stays sharp, so a field can blend only chosen regions. The profile is a BlendProfile: quadratic (the default, and the original k blend), circular, chamfer or cubic. The result does not depend on the order of the children.
Attributes: inside a child its attributes apply as before. A blend also adds fillet material outside every child; there the two nearest children’s surface attributes are mixed by the blend weight, so a fillet between two materials grades from one to the other.
Distance accuracy (distance_accuracy()): a bound for sharp unions and for a constant quadratic or cubic blend radius, with any number of children; an approximation for circular and chamfer blends and for any field radius. Never better than the least accurate child.
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Union) -> None
Default constructor. Creates a Union node with no children.
__init__(self: pyvcad.pyvcad.Union, left_child: pyvcad.pyvcad.Node, right_child: pyvcad.pyvcad.Node) -> None
Constructor. Creates a Union node with two children.
__init__(self: pyvcad.pyvcad.Union, k: typing.SupportsFloat | typing.SupportsIndex) -> None
Constructor for smooth union.
- Parameters:
k (float) – The smoothing radius. When k > 0, produces a smooth blend between children.
__init__(self: pyvcad.pyvcad.Union, k: typing.SupportsFloat | typing.SupportsIndex, children: collections.abc.Sequence[pyvcad.pyvcad.Node]) -> None
Constructor for smooth union with children.
- Parameters:
k (float) – The smoothing radius. When k > 0, produces a smooth blend between children.
children (list[Node]) – The children nodes.
__init__(self: pyvcad.pyvcad.Union, children: collections.abc.Sequence[pyvcad.pyvcad.Node], blend_radius: object = 0.0, profile: pyvcad.pyvcad.BlendProfile = <BlendProfile.quadratic: 0>) -> None
Constructor with children and an optional blend.
- Parameters:
children (list[Node]) – The children nodes.
blend_radius (float | FloatAttribute | ScalarParameter | numba.cfunc | callable) – The blend radius; 0 is sharp. A field needs ScalarParameter bounds.
profile (BlendProfile) – The fillet profile.
Example
>>> import pyvcad as pv >>> a = pv.Sphere(pv.Vec3(-4, 0, 0), 5.0) >>> b = pv.Sphere(pv.Vec3(4, 0, 0), 5.0) >>> rounded = pv.Union([a, b], blend_radius=1.5, profile=pv.BlendProfile.circular)
- blend_profile(self: pyvcad.pyvcad.Union) pyvcad.pyvcad.BlendProfile#
Returns the blend profile.
- blend_radius(self: pyvcad.pyvcad.Union) pyvcad.pyvcad.ScalarParameter#
Returns the blend radius as a ScalarParameter (a constant or a field).
- smooth_k(self: pyvcad.pyvcad.Union) float#
Returns the constant smoothing radius (0 for a sharp union). Raises for a field radius.
- class pyvcad.BBoxUnion#
An accelerated n-ary union that limits child queries using bounding boxes. An optional positive k produces smooth blends.
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.BBoxUnion) -> None
Default constructor for BBoxUnion.
__init__(self: pyvcad.pyvcad.BBoxUnion, children: collections.abc.Sequence[pyvcad.pyvcad.Node]) -> None
Constructor that creates a BBoxUnion node with the given list of child nodes.
- Parameters:
children (list of Node) – The list of child nodes.
__init__(self: pyvcad.pyvcad.BBoxUnion, k: typing.SupportsFloat | typing.SupportsIndex) -> None
Construct a smooth BBoxUnion.
- Parameters:
k (float) – Smoothing radius. Values at or below zero make a sharp union.
__init__(self: pyvcad.pyvcad.BBoxUnion, k: typing.SupportsFloat | typing.SupportsIndex, children: collections.abc.Sequence[pyvcad.pyvcad.Node]) -> None
Construct a smooth BBoxUnion with child nodes.
- Parameters:
k (float) – Smoothing radius.
children (list of Node) – The child nodes.
- smooth_k(self: pyvcad.pyvcad.BBoxUnion) float#
Returns the smoothing radius (0 for a sharp union).
A MappedStructureCollection is a Union of mapped lattices that keeps each
member’s attachment scopes, so one call can set an attribute on the same component of every map.
The scope objects below are returned by its struts, joints, plates and shell properties.
- class pyvcad.MappedStructureCollection#
A sharp union of mapped structures, each paired with its own CellMap. It keeps the mapped and component attachment scopes, so one set_attribute() call reaches every child in that child’s own map coordinates.
- __init__(self: pyvcad.pyvcad.MappedStructureCollection, cell_maps: collections.abc.Sequence[pyvcad.pyvcad.CellMap], children: collections.abc.Sequence[pyvcad.pyvcad.Node]) None#
Constructor. Creates a collection from aligned maps and children.
- Parameters:
- Raises:
RuntimeError – If children is empty, the two lists differ in length, or either holds None.
Example
>>> collection = pv.MappedStructureCollection([map_a, map_b], [lattice_a, lattice_b])
- property joints#
All unit-cell joints, forwarded to every child. Every child must be a MappedGraphLattice, or reading this raises RuntimeError.
- property mapped_children#
Mapped child nodes in map order.
- property maps#
CellMaps in child order.
- property plates#
All source faces or plates, forwarded to every child. Every child must be a MappedFaceLattice, or reading this raises RuntimeError.
- set_attribute(self: pyvcad.pyvcad.MappedStructureCollection, name: str, attribute: Attribute, coordinates: str = 'node') None#
Attach an attribute to every child in that child’s own map coordinates.
Unlike Node.set_attribute(), nothing is set on the collection itself: each child gets its own clone of the attribute, bound to the child’s CellMap, through the child’s set_attribute().
- Parameters:
name (str) – Attribute name.
attribute (Attribute) – Attribute definition, cloned for each child.
coordinates (str) – ‘node’, ‘map’, ‘logical’, ‘cell_index’, or ‘cell’. Defaults to ‘node’.
- Raises:
RuntimeError – If attribute is None, coordinates is not one of the values above, or a child already has an attribute of this name.
Example
>>> collection.set_attribute('modulus', pv.FloatAttribute('1000 + 100*x'), 'logical')
- property shell#
The repeated implicit shell, forwarded to every child. Every child must be a MappedImplicitLattice, or reading this raises RuntimeError.
- property struts#
All unit-cell struts, forwarded to every child. Every child must be a MappedGraphLattice, or reading this raises RuntimeError.
- class pyvcad.MappedCollectionGraphComponents#
A graph-component selection forwarded to every map in a collection.
- set_attribute(self: pyvcad.pyvcad.MappedCollectionGraphComponents, name: str, attribute: Attribute, coordinates: str = 'node') None#
Attach one named attribute to the selected struts or joints of every child.
Each component in every child gets its own clone of the attribute, bound to that child’s map, 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 a child lattice has its own attribute of this name with a different return type.
Example
>>> collection.struts.set_attribute('modulus', pv.FloatAttribute(2400))
- where(self: pyvcad.pyvcad.MappedCollectionGraphComponents, selector: collections.abc.Callable) pyvcad.pyvcad.MappedCollectionGraphComponents#
Select components with an authoring-time Python predicate.
- Parameters:
selector (callable) – Receives the MappedGraphComponent metadata of the first child’s unit cell and returns True to keep the component.
Example
>>> vertical = collection.struts.where(lambda item: abs(item.direction.z) > 0.9)
- with_orientation(self: pyvcad.pyvcad.MappedCollectionGraphComponents, tag: SupportsInt | SupportsIndex) pyvcad.pyvcad.MappedCollectionGraphComponents#
Select components carrying an integer orientation tag.
- Parameters:
tag (int) – Orientation tag to match.
Example
>>> selected = collection.struts.with_orientation(1)
- with_tag(self: pyvcad.pyvcad.MappedCollectionGraphComponents, tag: SupportsInt | SupportsIndex) pyvcad.pyvcad.MappedCollectionGraphComponents#
Select components carrying an integer topology tag.
Tags are read from the first child’s unit cell, so every child should share one cell layout.
- Parameters:
tag (int) – Tag to match.
Example
>>> selected = collection.struts.with_tag(2)
- class pyvcad.MappedCollectionFaceComponents#
A face-component selection forwarded to every map in a collection.
- set_attribute(self: pyvcad.pyvcad.MappedCollectionFaceComponents, name: str, attribute: Attribute, coordinates: str = 'node') None#
Attach one named attribute to the selected plates of every child.
Each component in every child gets its own clone of the attribute, bound to that child’s map, 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 a child lattice has its own attribute of this name with a different return type.
Example
>>> collection.plates.set_attribute('modulus', pv.FloatAttribute(2400))
- with_orientation(self: pyvcad.pyvcad.MappedCollectionFaceComponents, tag: SupportsInt | SupportsIndex) pyvcad.pyvcad.MappedCollectionFaceComponents#
Select source faces carrying an integer orientation tag.
- Parameters:
tag (int) – Orientation tag to match.
Example
>>> selected = collection.plates.with_orientation(1)
- with_tag(self: pyvcad.pyvcad.MappedCollectionFaceComponents, tag: SupportsInt | SupportsIndex) pyvcad.pyvcad.MappedCollectionFaceComponents#
Select source faces carrying an integer topology tag.
Tags are read from the first child’s unit cell, so every child should share one cell layout.
- Parameters:
tag (int) – Tag to match.
Example
>>> selected = collection.plates.with_tag(2)
- class pyvcad.MappedCollectionShell#
The implicit shell scope forwarded to every map in a collection.
- set_attribute(self: pyvcad.pyvcad.MappedCollectionShell, name: str, attribute: Attribute, coordinates: str = 'node') None#
Attach one named attribute to the repeated shell of every child.
Each child gets its own clone of the attribute, and 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 a child lattice has its own attribute of this name with a different return type.
Example
>>> collection.shell.set_attribute('temperature', pv.FloatAttribute('20 + 5*x'), 'cell')
- class pyvcad.Offset#
Moves a child’s surface outward (positive offset) or inward (negative offset).
The offset may be a constant or a field: a FloatAttribute, a numba.cfunc, a plain callable f(x, y, z, d) or a ScalarParameter. A field is sampled with the child’s signed distance as d.
Attributes: inside the child the child’s attributes apply. Material grown outside the child follows the growth policy: GrowthPolicy.undefined (the default, no attributes), GrowthPolicy.extend (the child’s attributes at its closest surface point) or GrowthPolicy.own (only this node’s attributes).
Distance accuracy (distance_accuracy()): the child’s for a zero offset, a bound with the child’s lipschitz_bound() for any other constant offset, an approximation for a field offset (with or without a lipschitz hint). A field offset needs known bounds (ScalarParameter minimum and maximum) to size its bounding box.
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Offset) -> None
Default constructor with zero offset.
__init__(self: pyvcad.pyvcad.Offset, offset: typing.SupportsFloat | typing.SupportsIndex) -> None
Constructor with a constant offset. Set the child with set_child().
- Parameters:
offset (float) – The offset; positive grows the child.
__init__(self: pyvcad.pyvcad.Offset, offset: object, child: pyvcad.pyvcad.Node, growth: pyvcad.pyvcad.GrowthPolicy = <GrowthPolicy.undefined: 0>) -> None
Constructor with a constant or field offset, a child and a growth policy.
- Parameters:
offset (float | FloatAttribute | ScalarParameter | numba.cfunc | callable) – The offset; positive grows the child. A field needs ScalarParameter bounds.
child (Node) – The child node.
growth (GrowthPolicy) – Attributes of material grown outside the child.
Example
>>> import pyvcad as pv >>> sphere = pv.Sphere(pv.Vec3(0, 0, 0), 10.0) >>> grown = pv.Offset(2.0, sphere, growth=pv.GrowthPolicy.extend) >>> wavy = pv.Offset(pv.ScalarParameter(pv.FloatAttribute('1 + 0.1 * x'), minimum=0.0, maximum=2.0), sphere)
- distance(self: pyvcad.pyvcad.Offset) pyvcad.pyvcad.ScalarParameter#
Returns the offset as a ScalarParameter (a constant or a field).
- growth(self: pyvcad.pyvcad.Offset) pyvcad.pyvcad.GrowthPolicy#
Returns the growth policy for material grown outside the child.
- offset(self: pyvcad.pyvcad.Offset) float#
Returns the constant offset. Positive values grow the child and negative values shrink it. Raises for a field offset; use distance() instead.
- class pyvcad.Shell#
A wall of a given thickness that follows a child’s surface.
With f the child’s signed distance and t the thickness, the wall lies inward (the default, -t <= f <= 0), outward (0 <= f <= t) or centered (abs(f) <= t / 2). The thickness may be a constant or a field: a FloatAttribute, a numba.cfunc, a plain callable f(x, y, z, d) or a ScalarParameter, sampled with the child’s signed distance as d.
Attributes: wall inside the child keeps the child’s attributes. Wall outside the child (outward and centered shells) is grown material and follows the growth policy.
Distance accuracy (distance_accuracy()): a bound, with the child’s lipschitz_bound(), for a constant thickness in any direction; an approximation for a field thickness. Outward and centered shells with a field thickness need ScalarParameter bounds to size their bounding box.
The legacy form Shell(-1.0, child) (a negative thickness) is still accepted.
- class Direction#
Which side of the child’s surface the wall lies on.
Members:
inward : Inside the child.
outward : Outside the child.
centered : Half inside and half outside the child.
- __init__(self: pyvcad.pyvcad.Shell.Direction, value: SupportsInt | SupportsIndex) None#
- centered = <Direction.centered: 2>#
- inward = <Direction.inward: 0>#
- Shell.Direction.name -> str
- outward = <Direction.outward: 1>#
- property value#
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: pyvcad.pyvcad.Shell, thickness: typing.SupportsFloat | typing.SupportsIndex) -> None
Constructor with an inward shell thickness. Set the child with set_child().
- Parameters:
thickness (float) – The wall thickness (negative in the legacy form). Zero raises ValueError.
__init__(self: pyvcad.pyvcad.Shell, thickness: object, child: pyvcad.pyvcad.Node, direction: pyvcad.pyvcad.Shell.Direction = <Direction.inward: 0>, growth: pyvcad.pyvcad.GrowthPolicy = <GrowthPolicy.undefined: 0>) -> None
Constructor with a constant or field thickness, a child, a direction and a growth policy.
- Parameters:
thickness (float | FloatAttribute | ScalarParameter | numba.cfunc | callable) – The positive wall thickness. A field for an outward or centered shell needs ScalarParameter bounds.
child (Node) – The child node.
direction (Shell.Direction) – Which side of the surface the wall lies on.
growth (GrowthPolicy) – Attributes of wall grown outside the child.
Example
>>> import pyvcad as pv >>> sphere = pv.Sphere(pv.Vec3(0, 0, 0), 10.0) >>> hollow = pv.Shell(1.0, sphere) >>> skin = pv.Shell(1.0, sphere, direction=pv.Shell.Direction.outward, ... growth=pv.GrowthPolicy.extend)
- direction(self: pyvcad.pyvcad.Shell) pyvcad.pyvcad.Shell.Direction#
Returns which side of the surface the wall lies on.
- growth(self: pyvcad.pyvcad.Shell) pyvcad.pyvcad.GrowthPolicy#
Returns the growth policy for wall outside the child.
- thickness(self: pyvcad.pyvcad.Shell) float#
Returns the constant thickness as authored (negative in the legacy form). Raises for a field thickness; use thickness_parameter() instead.
- thickness_parameter(self: pyvcad.pyvcad.Shell) pyvcad.pyvcad.ScalarParameter#
Returns the positive thickness as a ScalarParameter (a constant or a field).
- class pyvcad.Thicken#
Turns a surface or thin body into a solid of thickness t: the value is abs(f) - t / 2.
Use it on a child whose value is an unsigned distance to a sheet, or on a thin body to make it thicker. It is a centered Shell: the part inside the child keeps the child’s attributes, the rest is grown material and follows the growth policy. A field thickness needs ScalarParameter bounds.
- __init__(self: pyvcad.pyvcad.Thicken, thickness: object, child: pyvcad.pyvcad.Node, growth: pyvcad.pyvcad.GrowthPolicy = <GrowthPolicy.undefined: 0>) None#
Constructor with a constant or field thickness, a child and a growth policy.
- Parameters:
thickness (float | FloatAttribute | ScalarParameter | numba.cfunc | callable) – The positive total thickness.
child (Node) – The surface or thin body.
growth (GrowthPolicy) – Attributes of material outside the child.
Example
>>> import pyvcad as pv >>> sheet = pv.Function('abs(z)') >>> plate = pv.Thicken(2.0, sheet)