Analysis#

Tools that measure a design: inkjet support volume (pyvcad.SupportAnalyzer, see the Inkjet support volumes guide), mass properties (pyvcad.mass_properties()), and wall thickness and pore size (pyvcad.local_thickness(), pyvcad.pore_size()), and connected pieces of material (pyvcad.analyze_connected_components()).

Support volume#

class pyvcad.SupportAnalyzer#

Compute the inkjet support volume beneath a model.

Inkjet printers require material in the column below every printed voxel. SupportAnalyzer samples the input model on a uniform grid, processing XY columns concurrently, and returns the unsupported downward-facing volume as an ordinary OpenVCAD implicit solid. Fill that solid with support material, a lattice, or any other node.

__init__(self: pyvcad.pyvcad.SupportAnalyzer, input_model: pyvcad.pyvcad.Node, voxel_size: pyvcad.pyvcad.Vec3) → None#

Create a SupportAnalyzer.

Parameters:
  • input_model (Node) – The design to analyze.

  • voxel_size (Vec3) – Sampling pitch in millimetres. Every component must be positive. The smallest component is used as a uniform voxel size.

analyze(self: pyvcad.pyvcad.SupportAnalyzer) → pyvcad.pyvcad.Node#

Sample the model and return the support volume as a Node.

The returned solid occupies empty space that has model or support material above it, filling downward to the bottom of the model’s bounding box. The input model is not modified.

Mass properties#

mass_properties() integrates a design over a voxel grid with partial-volume weighting at the surface. It returns volume, surface area, centroid, mass, centre of mass, the inertia tensor and principal axes, per-material volumes, volume integrals of any scalar attribute, and an estimate of the sampling error. Units are mm, g/cm^3, g and g mm^2.

Mass needs a density. It comes from a modelled density attribute, from volume fractions times each material’s density (the optional "density" key of a material configuration, MaterialDefs.density() and MaterialDefs.set_density()), or from one uniform density for a design that is only geometry. MassSource picks one when a design offers several.

pyvcad.mass_properties(root: pyvcad.pyvcad.Node, voxel_size: SupportsFloat | SupportsIndex, density: SupportsFloat | SupportsIndex | None = None, mass_source: object = 'automatic', materials: pyvcad.pyvcad.MaterialDefs = None, density_attribute: str = 'density', attributes: collections.abc.Sequence[str] = [], bounds: object = None, estimate_error: bool = True, root_already_prepared: bool = False) → pyvcad.pyvcad.MassProperties#

Compute volume, surface area, mass, centre of mass and inertia of a design.

The design is sampled on a voxel grid. Voxels cut by the surface are weighted by the exact fraction on the inside of the local surface plane (from the signed distance and its gradient), so the result is far more accurate than counting inside voxels. Units: mm, g/cm^3, g and g mm^2.

Accuracy. On smooth surfaces the error falls with the square of the voxel size h (a sphere of radius R reads about (h/R)^2 / 4 high in volume). Sharp edges are rounded off by about a voxel, so a sharp-edged part reads slightly high in volume and low in area, by amounts that fall linearly with h (a box 16 voxels thick: about 0.2% and 3%). With estimate_error the integration is repeated at 2h and volume_error, surface_area_error and mass_error are the difference between the passes, a conservative estimate once every feature spans several voxels. Features thinner than about two voxels are not resolved. Attributes are sampled once per voxel, so a boundary between materials inside the part is placed to within half a voxel.

Density. Mass needs a density, which comes from one of three sources:

  1. a density attribute modelled on the design (density_attribute, default “density”);

  2. volume fractions times each material’s density from materials (a MaterialDefs; densities come from the optional “density” key of the material configuration or MaterialDefs.set_density()). Fractions are normalised; void has density 0;

  3. one uniform density, for a design that is only geometry.

With mass_source=”automatic” (the default) the first source the design offers is used, point by point in that order. A design that offers several can name one with mass_source; density then fills in where that source is absent. When the design offers no source, mass, center_of_mass and the inertia values are None. The call never guesses: it raises if the chosen source is missing, if a material in the volume fractions has no density, or if part of the volume has no density from any available source.

Parameters:
  • root (Node) – Design to analyse; prepared with voxel_size unless already prepared.

  • voxel_size (float) – Sampling pitch in mm.

  • density (float | None) – Uniform density in g/cm^3 (for example 1.18 for a rigid photopolymer), used for plain geometry and to fill in where the chosen source is absent.

  • mass_source (str | MassSource) – “automatic”, “density_attribute”, “volume_fractions”, “uniform” or “none”. “none” skips density, giving only volume, area and centroid.

  • materials (MaterialDefs | None) – Material definitions with densities for volume fractions.

  • density_attribute (str) – Name of the scalar density attribute.

  • attributes (list[str]) – Scalar attributes to integrate (see report.attribute_integrals).

  • bounds (tuple | None) – Optional (minimum, maximum) analysis box.

  • estimate_error (bool) – Repeat at twice the voxel size to estimate the error.

  • root_already_prepared (bool) – Skip prepare() when the node is already prepared.

Example

>>> report = pv.mass_properties(part, 0.25, density=1.18)
>>> report.mass, report.center_of_mass
>>> materials = pv.MaterialDefs(pv.j750_materials_path)
>>> report = pv.mass_properties(graded_part, 0.25, materials=materials)
class pyvcad.MassProperties#

Volume, surface area, mass, centre of mass and inertia of a design, from pv.mass_properties(). Lengths are in mm, densities in g/cm^3, mass in g and inertia in g mm^2. Vectors and tensors are NumPy arrays. Mass, centre of mass and inertia are None when the design offered no density source.

attribute_integral(self: pyvcad.pyvcad.MassProperties, name: str) → pyvcad.pyvcad.AttributeIntegral#

Returns the integral of one requested attribute.

Parameters:

name (str) – Attribute name given in attributes=.

Example

>>> report.attribute_integral("modulus").mean
property attribute_integrals#

Integrals of the requested attributes (list of pv.AttributeIntegral).

property center_of_mass#

Centre of mass in mm, or None.

property centroid#

Centroid of the volume (uniform density).

property dimensions#

Number of voxels along X, Y and Z.

inertia_about(self: pyvcad.pyvcad.MassProperties, point: object) → numpy.typing.NDArray[numpy.float64]#

Inertia tensor about another point, by the parallel axis theorem.

Parameters:

point (Vec3 | sequence) – Reference point in mm.

Example

>>> report.inertia_about((0, 0, 0))
property inertia_tensor#

3x3 inertia tensor about the centre of mass in g mm^2, or None.

property mass#

Mass in g, or None without a density source.

property mass_error#

Estimated absolute error of mass (g), or None.

property mass_source#

Density source used (pv.MassSource). With automatic, the first source in the precedence order that applied anywhere; mass_source_volumes says where each applied.

property mass_source_volumes#

Volume in mm^3 where each source supplied the density, keyed by source name.

property material_volumes#

Volume in mm^3 of each material id, from the volume fractions.

property origin#

Centre of the first voxel.

property principal_axes#

3x3 array whose columns are the unit principal axes (right-handed), or None.

property principal_moments#

Principal moments of inertia in ascending order (g mm^2), or None.

property surface_area#

Surface area in mm^2 (the part inside the analysis box).

property surface_area_error#

Estimated absolute error of surface_area (mm^2), or None.

property volume#

Volume in mm^3.

property volume_error#

Estimated absolute error of volume (mm^3), or None without estimate_error.

property voxel_size#

Sampling pitch in mm.

class pyvcad.MassSource#

Where pv.mass_properties() takes the density from.

  • automatic: the first source the design offers, point by point: the density attribute, then volume fractions with material densities, then the uniform density.

  • density_attribute: the design’s own density attribute (g/cm^3).

  • volume_fractions: volume fractions times each material’s MaterialDefs density.

  • uniform: one density for the whole design.

  • none: no mass; only volume, area and centroid are computed.

Members:

automatic

density_attribute

volume_fractions

uniform

none

automatic = <MassSource.automatic: 0>#
density_attribute = <MassSource.density_attribute: 1>#
MassSource.name -> str
none = <MassSource.none: 4>#
uniform = <MassSource.uniform: 3>#
property value#
volume_fractions = <MassSource.volume_fractions: 2>#
class pyvcad.AttributeIntegral#

Volume integral of one scalar attribute, reported by pv.mass_properties().

property integral#

Integral over the volume where the attribute is defined, in (attribute units) mm^3.

property maximum#

Largest sampled value.

property mean#

Volume-weighted mean.

property minimum#

Smallest sampled value.

property name#

Attribute name.

property volume#

Volume in mm^3 where the attribute is defined.

Wall thickness and pore size#

local_thickness() gives, at every point of the material, the diameter of the largest ball that fits there and contains the point; pore_size() does the same in the empty space. The result is a volume-backed FloatAttribute (set it on the analysed node to colour, grade or drive geometry by thickness) plus a summary: the thinnest wall, a volume histogram and the connected regions thinner than a threshold. Sharp convex edges read small in the field, as every ball misses them, but only walls, struts, necks and gaps count as thin in the summary.

pyvcad.local_thickness(root: pyvcad.pyvcad.Node, voxel_size: SupportsFloat | SupportsIndex, threshold: SupportsFloat | SupportsIndex | None = None, max_thickness: SupportsFloat | SupportsIndex | None = None, bounds: object = None, bins: SupportsInt | SupportsIndex = 32, max_memory_mb: SupportsFloat | SupportsIndex = 4096.0, root_already_prepared: bool = False) → pyvcad.pyvcad.LocalThickness#

Measure wall thickness at every point of a design.

The local thickness at a point is the diameter of the largest ball that fits inside the material and contains the point: a plate reads its thickness, a strut its diameter and a neck its width. Use it to find walls too thin to print. The result is a volume-backed FloatAttribute plus a summary: minimum and where it is, mean, a volume histogram and, with threshold, the connected regions thinner than the threshold.

How it works: the surface is sampled at sub-voxel points (voxel centres next to the surface, moved onto it along the field’s gradient), and from each one the largest ball tangent there with no surface point inside is found. Because distances are rebuilt from these surface points, unions, lattices and TPMS fields measure correctly even though their inside values are not true distances.

Edges: no large ball reaches into a sharp convex edge or corner, so the field reads small in a band along them. minimum and regions count only balls that touch opposite sides (normals more than 120 degrees apart), which excludes those bands but keeps knife edges sharper than about 60 degrees.

Resolution limits: thicknesses are accurate to about a tenth of a voxel for walls, struts and gaps two or more voxels thick. Thinner ones are unreliable and may vanish.

Parameters:
  • root (Node) – Design to analyse; prepared with voxel_size unless already prepared.

  • voxel_size (float) – Sampling pitch in mm. Use at most a quarter of the smallest thickness that matters; values are accurate to about a tenth of a voxel for features two or more voxels thick.

  • threshold (float | None) – Report the connected regions thinner than this (mm).

  • max_thickness (float | None) – Cap in mm; thicker places read as the cap (“at least this”), which keeps the work near the surface. None measures every thickness.

  • bounds (tuple | None) – Optional (minimum, maximum) analysis box.

  • bins (int) – Number of histogram bins.

  • max_memory_mb (float) – Limit on the working arrays (about 17 bytes per voxel).

  • root_already_prepared (bool) – Skip prepare() when the node is already prepared.

Example

>>> report = pv.local_thickness(part, 0.1, threshold=0.8)
>>> report.minimum, report.regions[0].location
>>> part.set_attribute("thickness", report.attribute)
pyvcad.pore_size(root: pyvcad.pyvcad.Node, voxel_size: SupportsFloat | SupportsIndex, threshold: SupportsFloat | SupportsIndex | None = None, max_thickness: SupportsFloat | SupportsIndex | None = None, bounds: object = None, bins: SupportsInt | SupportsIndex = 32, max_memory_mb: SupportsFloat | SupportsIndex = 4096.0, root_already_prepared: bool = False) → pyvcad.pyvcad.LocalThickness#

Measure pore and channel size in the empty space of a design.

The same measure as pv.local_thickness() applied to the empty space inside the analysis box (bounds, or the design’s bounding box): the diameter of the largest empty ball through each point. Openings too narrow to clear powder or resin read small. The field lives in the empty space, so to view it set it on a node that fills that space, for example pv.Difference(pv.RectPrism(…), part). Pores within about one pore of the box edge read as lower bounds, because balls are not searched outside the box.

How it works: the surface is sampled at sub-voxel points (voxel centres next to the surface, moved onto it along the field’s gradient), and from each one the largest ball tangent there with no surface point inside is found. Because distances are rebuilt from these surface points, unions, lattices and TPMS fields measure correctly even though their inside values are not true distances.

Edges: no large ball reaches into a sharp convex edge or corner, so the field reads small in a band along them. minimum and regions count only balls that touch opposite sides (normals more than 120 degrees apart), which excludes those bands but keeps knife edges sharper than about 60 degrees.

Resolution limits: thicknesses are accurate to about a tenth of a voxel for walls, struts and gaps two or more voxels thick. Thinner ones are unreliable and may vanish.

Parameters:
  • root (Node) – Design to analyse; prepared with voxel_size unless already prepared.

  • voxel_size (float) – Sampling pitch in mm. Use at most a quarter of the smallest thickness that matters; values are accurate to about a tenth of a voxel for features two or more voxels thick.

  • threshold (float | None) – Report the connected regions thinner than this (mm).

  • max_thickness (float | None) – Cap in mm; thicker places read as the cap (“at least this”), which keeps the work near the surface. None measures every thickness.

  • bounds (tuple | None) – Optional (minimum, maximum) analysis box.

  • bins (int) – Number of histogram bins.

  • max_memory_mb (float) – Limit on the working arrays (about 17 bytes per voxel).

  • root_already_prepared (bool) – Skip prepare() when the node is already prepared.

Example

>>> report = pv.pore_size(lattice, 0.1, threshold=0.5)
>>> report.minimum, report.volume_below_threshold
class pyvcad.LocalThickness#

Thickness field and summary from pv.local_thickness() or pv.pore_size(). Values are diameters in mm. Set attribute on the analysed node to colour, grade or drive geometry by thickness.

property attribute#

The thickness as a pv.FloatAttribute, ready to set on the analysed node.

property capped_volume#

Volume in mm^3 that reached the cap.

property dimensions#

Number of voxels along X, Y and Z.

property histogram#

the bin edges in mm and the volume in mm^3 in each bin.

Type:

Tuple of two arrays

property max_thickness#

Cap that was applied, or None.

property maximum#

Largest thickness in mm.

property mean#

Volume-weighted mean thickness in mm.

property measured_volume#

Volume of the measured space in mm^3.

property minimum#

the smallest ball that touches opposite sides of the space, or the smallest field value when there is none. The thin band along sharp convex edges is not counted as a wall.

Type:

Thinnest wall, strut or gap in mm

property minimum_location#

Centre of that thinnest ball (the voxel centre of the smallest field value when there is no such ball).

property origin#

Centre of the first voxel.

property phase#

Space that was measured (pv.ThicknessPhase).

property regions#

Connected walls, struts and gaps thinner than the threshold, thinnest first (list of pv.ThinRegion). Edge bands are not counted.

property threshold#

Threshold that was applied, or None.

property volume#

The thickness as a pv.FloatVolume (zero away from the measured space).

property volume_below_threshold#

Volume in mm^3 of walls, struts and gaps thinner than the threshold.

property voxel_size#

Sampling pitch in mm.

class pyvcad.ThinRegion#

A connected region thinner than the threshold, reported by pv.local_thickness() and pv.pore_size().

property location#

Voxel centre of the smallest thickness.

property maximum_corner#

Maximum corner of the region’s voxel centres.

property minimum#

Smallest thickness in the region, in mm.

property minimum_corner#

Minimum corner of the region’s voxel centres.

property volume#

Volume in mm^3.

property voxel_count#

Number of voxels in the region.

class pyvcad.ThicknessPhase#

Space measured by a thickness analysis: solid (wall thickness) or empty (pore size).

Members:

solid

empty

empty = <ThicknessPhase.empty: 1>#
ThicknessPhase.name -> str
solid = <ThicknessPhase.solid: 0>#
property value#

Connected components#

analyze_connected_components() samples a node on a voxel grid and counts the separate pieces of solid material, for example to find floating islands in a lattice before printing. label_connected_components() does the same for an occupancy array you already have.

pyvcad.analyze_connected_components(root: pyvcad.pyvcad.Node, voxel_size: SupportsFloat | SupportsIndex, connectivity: SupportsInt | SupportsIndex = 26, bounds: tuple[pyvcad.pyvcad.Vec3, pyvcad.pyvcad.Vec3] | None = None, root_already_prepared: bool = False, cull_far_cells: bool = False) → pyvcad.pyvcad.ConnectedComponentReport#

Count the connected pieces of solid material in a node.

The node is sampled at voxel centres on a uniform grid over its bounding box (or bounds) and solid samples (signed distance <= 0) are joined through face (6) or face, edge and corner (26) neighbours. Memory grows with the number of solid runs, not the grid size. Necks thinner than about one voxel may be reported as separate pieces, so use a voxel size of at most about half the thinnest strut radius or wall thickness.

Parameters:
  • root (Node) – Node to analyze; prepared with voxel_size unless already prepared.

  • voxel_size (float) – Sampling pitch in millimetres.

  • connectivity (int) – 6 or 26.

  • bounds (tuple[Vec3, Vec3] | None) – Optional analysis box.

  • root_already_prepared (bool) – Skip prepare() when the node is already prepared.

  • cull_far_cells (bool) – Decide whole 8x8x8 voxel blocks from one probe when the field there is far from zero. Exact for true distances (stochastic strut lattices, primitives, booleans); leave it off for TPMS designs, whose fields can change faster than distance.

Example

>>> report = pv.analyze_connected_components(lattice, 0.25)
>>> report.component_count
pyvcad.label_connected_components(occupancy: Annotated[numpy.typing.ArrayLike, numpy.uint8], connectivity: SupportsInt | SupportsIndex = 26, periodic: Annotated[collections.abc.Sequence[bool], 'FixedSize(3)'] = [False, False, False]) → pyvcad.pyvcad.ConnectedComponentReport#

Label connected solid cells in a dense occupancy array.

The array is indexed [z, y, x]; non-zero entries are solid. Periodic flags join the first and last layers along X, Y and Z. Component boxes and sample points are reported in (x, y, z) index units.

Parameters:
  • occupancy (numpy.ndarray) – 3D boolean or integer array.

  • connectivity (int) – 6 or 26.

  • periodic (tuple[bool, bool, bool]) – Periodic X, Y and Z flags.

Example

>>> report = pv.label_connected_components(mask, 26, (False, False, False))
class pyvcad.ConnectedComponentReport#

Voxel connectivity summary of an implicit solid.

property component_count#

Number of connected components.

property components#

Components sorted by decreasing voxel count.

property connectivity#

6 or 26.

Type:

Neighbourhood used to join voxels

property dimensions#

Number of samples along X, Y and Z.

property origin#

Centre of the first voxel sample.

property solid_voxel_count#

Total number of solid samples.

property voxel_size#

Uniform sampling pitch on every axis.

class pyvcad.SolidComponent#

One connected piece of solid material reported by analyze_connected_components().

property maximum#

Maximum corner of the component’s sample bounding box.

property minimum#

Minimum corner of the component’s sample bounding box.

property sample_point#

One solid sample inside the component, useful for locating islands.

property volume#

Approximate volume in cubic millimetres.

property voxel_count#

Number of solid voxel samples in the component.