Analysis#
-
class SupportAnalyzer#
- #include <support_analyzer.h>
Computes the inkjet support volume beneath an OpenVCAD design.
Inkjet printers cannot print a voxel unless there is already material in the column directly below it. This analyzer samples the input model on a uniform voxel grid and marks every empty voxel that has occupied model or support material above it, filling downward to the bottom of the model’s bounding box. XY columns are processed concurrently.
analyze()returns that occupancy as an implicit OpenVCAD solid (a signed-distance field). Downstream code can fill the solid with support material, a lattice, or any other OpenVCAD geometry. The input model is not modified.Public Functions
-
std::shared_ptr<Node> analyze()#
Sample the model and return the inkjet support volume as an implicit solid.
- Returns:
A node representing the support occupancy. The original input model is unchanged.
Construct an analyzer for a model.
- Parameters:
input_model – The design to analyze. Must be non-null.
voxel_size – Sampling pitch in millimetres. Every component must be positive and finite. The analyzer uses the smallest component as a uniform voxel size.
-
std::shared_ptr<Node> analyze()#
Enums
-
enum class MassSource#
Where mass_properties() takes the density from.
Values:
-
enumerator automatic#
Use the first source the design offers, point by point: the density attribute, then volume fractions with material densities, then the uniform density.
-
enumerator density_attribute#
The design’s own density attribute (DefaultAttributes::DENSITY unless renamed), in g/cm^3.
-
enumerator volume_fractions#
Volume fractions times each material’s density from MaterialDefs.
-
enumerator uniform#
One uniform density for the whole design.
-
enumerator none#
No density: mass, centre of mass and inertia are not computed.
As input it skips every density source (volume, area and centroid only); a report also gives it when no source was available.
-
enumerator automatic#
Functions
Computes volume, surface area, mass, centre of mass and inertia of a node.
The node is sampled at voxel centres on a uniform grid over its bounding box, one voxel wider on every side and shifted by a fixed fraction of a voxel so that flat faces bounding the box do not fall on voxel boundaries. Away from the surface a voxel is wholly inside or outside. Near the surface the signed distance d and its central-difference gradient g on the grid give a local plane; the voxel is weighted by the exact fraction of the cube on its inside, with the exact first and second moments of that part along the normal, and the plane’s area inside the voxel adds to the surface area. Dividing by |g| makes this hold for fields that are not true distances (TPMS, scaled bodies).
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 and corners are rounded off by about a voxel, so on a sharp-edged part volume reads slightly high and surface area slightly low, by amounts that fall linearly with h (a box 16 voxels thick: about 0.2% and 3%). With estimate_error on, the integration is repeated at 2h and each error is estimated as |Q_h - Q_2h|: the error itself where it falls linearly, three times it where it falls with the square, so the estimate is conservative once every feature spans several voxels. Features thinner than about two voxels are not resolved.
Density. Mass, centre of mass and inertia need a density in g/cm^3. It comes from one of three sources:
a density attribute modelled on the design (options.density_attribute, default “density”);
volume fractions times each material’s density from options.materials (MaterialDefs::density(), the optional “density” key of a material configuration). Fractions are normalised to sum to one, and the void material has density 0;
a uniform density (options.density), for a design that is only geometry.
With MassSource::automatic (the default) the first source the design offers is used, point by point in that order: a point without the density attribute uses its volume fractions, then the uniform density. A design that offers several sources can name one with options.mass_source; options.density then fills in wherever that source is absent. When the design offers no source at all, mass, centre of mass and inertia are left empty and the report still gives volume, area and centroid.
The call never guesses a density. It throws when the chosen source is missing from the design, when a material present in the volume fractions has no density, or when part of the volume has no density from any available source.
Attributes are sampled once per voxel: at its centre, or just inside the surface along the grid normal for a cut voxel whose centre is outside. A boundary between materials or attribute values inside the part is therefore placed to within half a voxel. Voxels where the field kinks (sharp edges, creases between bodies, curvature radius under about seven voxels) are split into eight half-size pieces for the geometry. Z-slabs are sampled in parallel with thread-local clones; sums are taken per row and added in order, so results do not depend on threading.
- Parameters:
root – Node to analyse. It is prepared with the voxel size unless options say it already is.
voxel_size – Positive sampling pitch in mm.
options – Density source, attributes to integrate, bounds and error estimate.
- Throws:
std::runtime_error – for invalid input or missing densities, as described above.
- Returns:
The report.
-
std::string mass_source_name(MassSource source)#
Returns the lower-case name of a mass source, e.g.
“volume_fractions”.
- Parameters:
source – The mass source.
- Returns:
Its name, which mass_properties() in Python also accepts as a string.
-
struct AttributeIntegral#
- #include <mass_properties.h>
Volume integral of one scalar attribute.
Public Members
-
double integral = 0.0#
Integral of the attribute over the volume where it is defined, in (attribute units) mm^3.
-
double maximum = 0.0#
Largest sampled value.
-
double mean = 0.0#
Volume-weighted mean, integral / volume.
-
double minimum = 0.0#
Smallest sampled value.
-
double volume = 0.0#
Volume in mm^3 where the attribute is defined.
-
double integral = 0.0#
-
struct MassPropertiesOptions#
- #include <mass_properties.h>
Inputs of mass_properties() beyond the node and voxel size.
Public Members
-
std::vector<std::string> attributes#
Scalar attributes to integrate over the volume (see AttributeIntegral).
-
std::optional<std::pair<glm::vec3, glm::vec3>> bounds#
Optional analysis box; it is intersected with the node’s bounding box.
-
std::optional<double> density#
Uniform density in g/cm^3.
It is the whole density for a design that is only geometry, and it fills in wherever the chosen source is absent.
-
std::string density_attribute = DefaultAttributes::DENSITY#
Name of the scalar density attribute (g/cm^3).
-
bool estimate_error = true#
Repeat the integration at twice the voxel size to estimate the sampling error.
-
MassSource mass_source = MassSource::automatic#
Density source; see mass_properties() for the rules.
-
std::shared_ptr<MaterialDefs> materials#
Material definitions whose densities (MaterialDefs::density()) weight the volume fractions.
-
bool root_already_prepared = false#
Skip prepare() when the caller already prepared the node.
-
std::string volume_fractions_attribute = DefaultAttributes::VOLUME_FRACTIONS#
Name of the volume-fraction attribute.
-
std::vector<std::string> attributes#
-
struct MassPropertiesReport#
- #include <mass_properties.h>
Volume, area, mass, centre of mass and inertia of a design, from mass_properties().
Lengths are in mm, densities in g/cm^3, mass in g and inertia in g mm^2.
Public Functions
-
glm::dmat3 inertia_about(const glm::dvec3 &point) const#
Inertia tensor about another point, by the parallel axis theorem.
- Parameters:
point – Reference point in mm.
- Throws:
std::runtime_error – when the report has no mass.
- Returns:
The tensor in g mm^2.
Public Members
-
std::vector<AttributeIntegral> attribute_integrals#
Integrals of the requested scalar attributes, in request order.
-
std::optional<glm::dvec3> center_of_mass#
Centre of mass, when a density source was available.
-
glm::dvec3 centroid = {0.0}#
Centroid of the volume (uniform density).
-
glm::ivec3 dimensions = {0}#
Number of voxels along X, Y and Z.
-
std::optional<glm::dmat3> inertia_tensor#
Inertia tensor about the centre of mass in g mm^2 (symmetric; column-major like glm).
-
std::optional<double> mass#
Mass in g, when a density source was available.
-
std::optional<double> mass_error#
Estimated absolute error of mass.
-
MassSource mass_source = MassSource::none#
Density source that was used.
With MassSource::automatic this is the first source in the precedence order that applied anywhere; mass_source_volumes says where each one applied.
-
std::map<MassSource, double> mass_source_volumes#
Volume in mm^3 where each source supplied the density, by source.
-
std::map<uint8_t, double> material_volumes#
Volume in mm^3 of each material, from the volume fractions (normalised to sum to one).
-
glm::dvec3 origin = {0.0}#
Centre of the first voxel.
-
std::optional<glm::dmat3> principal_axes#
Principal axes as unit columns matching principal_moments, forming a right-handed frame.
-
std::optional<glm::dvec3> principal_moments#
Principal moments of inertia in ascending order, in g mm^2.
-
double surface_area = 0.0#
Surface area in mm^2 (the part of the surface inside the analysis box).
-
std::optional<double> surface_area_error#
Estimated absolute error of surface_area.
-
double volume = 0.0#
Volume in mm^3.
-
std::optional<double> volume_error#
Estimated absolute error of volume, |V_h - V_2h| from the 2h pass (when estimate_error is on).
-
double voxel_size = 0.0#
Sampling pitch in mm.
-
glm::dmat3 inertia_about(const glm::dvec3 &point) const#
-
namespace PartialVolume#
Exact volume, area and moments of a unit cube cut by a plane, for partial-voxel weighting.
Analyses that integrate over a voxel grid (mass_properties()) treat the surface inside a voxel as the plane given by the signed distance and its gradient at the voxel centre. These helpers return the exact fraction of the voxel on the inside of that plane, the area of the plane inside the voxel and the first two moments of the inside part along the normal, so a planar surface is integrated exactly at any orientation.
Functions
-
inline CubeCut cut_unit_cube(const glm::dvec3 &normal, double offset)#
Cuts the unit cube [-1/2, 1/2]^3 with the half-space { x : normal .
x <= offset }.
Reflecting the axes makes the coefficients a, b, c non-negative; with s = a.y on the cube [0, 1]^3 and t = offset + (a + b + c) / 2, the inside part is s <= t. Its volume is the inclusion-exclusion sum G_3(t), where G_j(t) = sum over the corners e of (-1)^|e| max(0, t - a.e)^j / (j! abc). The area is G_2(t) (dV/dt for a unit normal), and the moments of s are t G_3 - G_4 and t^2 G_3 - 2 t G_4 + 2 G_5. Coefficients below 1e-6 are treated as zero and the 2D or 1D form is used, which avoids the cancellation of the 3D form.
An axis-aligned plane that lies on a cube face belongs to both neighbouring voxels. Its area is given to the cube below it (plane within 1e-5 of the top face, inclusive) and not to the cube above, so a face that falls on the voxel grid is counted exactly once.
- Parameters:
normal – Unit normal of the plane, pointing out of the half-space.
offset – Signed offset of the plane from the cube centre along the normal, in side lengths.
- Returns:
The inside fraction, the plane area inside the cube and the moments along the normal.
-
struct CubeCut#
- #include <partial_volume.h>
Result of cutting the unit cube [-1/2, 1/2]^3 with a half-space.
With u = normal . x the coordinate along the normal (x measured from the cube centre), normal_moment is the integral of u and normal_second_moment the integral of u^2 over the inside part. A whole cube has 0 and 1/12.
Public Members
-
double area = 0.0#
Area of the cutting plane inside the cube, in units of the side length squared.
-
double normal_moment = 0.0#
Integral of u over the inside part, in side lengths to the fourth.
-
double normal_second_moment = 0.0#
Integral of u^2 over the inside part, in side lengths to the fifth.
-
double volume_fraction = 0.0#
Fraction of the cube inside the half-space, in [0, 1].
-
double area = 0.0#
-
inline CubeCut cut_unit_cube(const glm::dvec3 &normal, double offset)#
Enums
-
enum class ThicknessPhase#
Which space local_thickness() measures.
Values:
-
enumerator solid#
The material: wall and strut thickness.
-
enumerator empty#
The empty space inside the analysis box: pore and channel size.
-
enumerator solid#
Functions
Measures wall thickness (or pore size) at every point of a design, on a voxel grid.
The local thickness at a point is the diameter of the largest ball that fits inside the measured space and contains the point (the Hildebrand-Rueegsegger definition). In a plate it is the plate’s thickness, in a strut its diameter, and at a thin neck the neck’s width. Measuring the empty space instead gives pore size: the largest ball of empty space through each point, so channels too narrow to clear powder or resin read small.
Steps: the signed distance is sampled on a dense grid (bounds plus one voxel for the solid). The surface is sampled once per voxel of the other space that touches the measured space: the voxel centre moved along the grid normal by d / |g|. An exact separable Euclidean feature transform gives every voxel its nearest such sample, which answers “nearest surface point to here” in constant time. From each surface sample p a shrinking ball finds the largest ball tangent at p with no surface point inside: it starts large and shrinks to the ball through p and the intruding point until nothing intrudes, in a few steps. Every measured point lies in the ball of its nearest surface point, so the thickness at x is 2 max r over the balls that contain x; they are painted plane by plane in parallel in decreasing r so that each voxel is written once. Because distances are rebuilt from the sampled surface, the result does not depend on the field being a true distance inside: unions, lattices and TPMS fields (whose inside values are only bounds, or not distances at all) measure correctly.
Edges and walls. By definition no large ball reaches into a sharp convex edge or corner, so the field reads small in a band along them (about a fifth of the wall thickness wide at a 90-degree edge). That is not a thin wall. A ball whose shrinking stopped at a surface point with an opposing normal (more than 120 degrees apart) spans a wall, strut, neck or gap; the report’s minimum and regions count only places painted by such balls, which includes knife edges sharper than about 60 degrees, since those are thin.
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; use a voxel of at most a quarter of the smallest thickness that matters. Values at the cap mean “at least the cap”. For the empty space, pores within about one pore of the analysis box edge read as lower bounds, because balls are not searched outside the box. With bounds on the solid, walls cut by the box are measured only inside it.
The dense working arrays need about 17 bytes per voxel; the call throws before allocating more than max_memory_mb. The result is a sparse FloatVDBVolume holding values only in and next to the measured space.
- Parameters:
root – Node to analyse. It is prepared with the voxel size unless options say it already is.
voxel_size – Positive sampling pitch in mm.
options – Phase, cap, threshold, histogram, bounds and memory limit.
- Throws:
std::runtime_error – for invalid input or when the grid would exceed the memory limit.
- Returns:
The report, whose attribute can be set on the analysed node to colour or grade by thickness.
-
struct LocalThicknessOptions#
- #include <local_thickness.h>
Inputs of local_thickness() beyond the node and voxel size.
Public Members
-
std::optional<std::pair<glm::vec3, glm::vec3>> bounds#
Optional analysis box, intersected with the node’s bounding box for the solid phase.
For the empty phase it sets the space searched for pores (default: the node’s bounding box).
-
int histogram_bins = 32#
Number of histogram bins between the smallest and largest thickness.
-
double max_memory_mb = 4096.0#
Limit on the dense working arrays (about 17 bytes per voxel), in megabytes.
-
std::optional<double> max_thickness#
Optional cap in mm.
Thicker places read as the cap (“at least this”), which bounds the work to a shell of half the cap near the surface. Leave empty to measure every thickness exactly.
-
ThicknessPhase phase = ThicknessPhase::solid#
Space to measure.
-
bool root_already_prepared = false#
Skip prepare() when the caller already prepared the node.
-
std::optional<double> threshold#
Optional limit in mm: places thinner than this are reported as regions.
-
std::optional<std::pair<glm::vec3, glm::vec3>> bounds#
-
struct LocalThicknessReport#
- #include <local_thickness.h>
Thickness field and summary from local_thickness().
Public Members
-
std::shared_ptr<FloatAttribute> attribute#
The same field as an attribute, ready to set on the analysed node.
-
double capped_volume = 0.0#
Volume in mm^3 that reached the cap.
-
glm::ivec3 dimensions = {0}#
Number of voxels along X, Y and Z.
-
std::vector<double> histogram_edges#
Histogram bin edges in mm (histogram_bins + 1 values).
-
std::vector<double> histogram_volumes#
Volume in mm^3 in each bin.
-
std::optional<double> max_thickness#
Cap that was applied, if any.
-
double maximum = 0.0#
Largest thickness in mm (at most max_thickness when that is set).
-
double mean = 0.0#
Volume-weighted mean thickness in mm.
-
double measured_volume = 0.0#
Volume of the measured space in mm^3 (voxel count times the voxel volume).
-
double minimum = 0.0#
Thinnest wall, strut or gap in mm: the smallest ball that touches opposite sides of the space (the smallest field value when there is none).
Sharp convex edges are not walls; see local_thickness().
-
glm::dvec3 minimum_location = {0.0}#
Centre of that thinnest ball.
-
glm::dvec3 origin = {0.0}#
Centre of the first voxel.
-
ThicknessPhase phase = ThicknessPhase::solid#
Space that was measured.
-
std::vector<ThinRegion> regions#
Connected walls, struts and gaps thinner than the threshold, thinnest first.
-
std::optional<double> threshold#
Threshold that was applied, if any.
-
std::shared_ptr<FloatVDBVolume> volume#
Thickness (diameter of the largest ball that fits and contains the point) in mm, as a volume.
Values continue two voxels past the measured space so sampling at the surface never blends with empty voxels; elsewhere the volume is zero.
-
double volume_below_threshold = 0.0#
Volume in mm^3 of walls, struts and gaps thinner than the threshold.
-
double voxel_size = 0.0#
Sampling pitch in mm.
-
std::shared_ptr<FloatAttribute> attribute#
-
struct ThinRegion#
- #include <local_thickness.h>
A connected piece of the measured space thinner than the threshold.
Public Members
-
glm::dvec3 location = {0.0}#
Voxel centre where the smallest thickness was found.
-
glm::dvec3 maximum_corner = {0.0}#
Maximum corner of the region’s voxel centres.
-
double minimum = 0.0#
Smallest thickness in the region, in mm.
-
glm::dvec3 minimum_corner = {0.0}#
Minimum corner of the region’s voxel centres.
-
double volume = 0.0#
Volume in mm^3.
-
size_t voxel_count = 0#
Number of voxels in the region.
-
glm::dvec3 location = {0.0}#
-
namespace DistanceTransform#
Exact Euclidean feature transform on a dense voxel grid.
Used by local_thickness() to find, for every voxel, the nearest voxel of the other space, from which the inscribed radius is measured to a sub-voxel surface point.
Functions
-
void feature_transform(std::vector<uint32_t> &features, const glm::ivec3 &dimensions)#
Replaces every entry with the linear index of its nearest seed voxel (exact Euclidean).
Before the call, a seed voxel holds its own linear index and every other voxel holds no_feature. Indices are x-fastest: index = x + nx * (y + ny * z). After the call each voxel holds the index of a seed at the smallest Euclidean distance between voxel centres (ties go to the lower coordinate along the last axis processed). The transform is separable: a scan along X, then the lower envelope of parabolas along Y and along Z (Felzenszwalb and Huttenlocher), each pass parallel over lines. Time is linear in the number of voxels.
- Parameters:
features – The seed marks, replaced by nearest-seed indices; size nx * ny * nz.
dimensions – Grid size (nx, ny, nz), all positive, with nx * ny * nz below no_feature.
- Throws:
std::runtime_error – when the size does not match the dimensions.
Variables
-
constexpr uint32_t no_feature = std::numeric_limits<uint32_t>::max()#
Marks a voxel with no seed found (only when the grid has no seeds at all).
-
void feature_transform(std::vector<uint32_t> &features, const glm::ivec3 &dimensions)#
Functions
Count the connected pieces of solid material in a node.
The node is sampled at voxel centres on a uniform grid covering its bounding box (or the supplied bounds). A sample is solid when the signed distance is <= 0. Solid samples are joined through 6- or 26-neighbourhoods with a streaming run-length union-find, so memory grows with the number of solid runs rather than the grid size. Z-slabs are sampled in parallel with thread-local clones of the node.
The result depends on resolution: necks thinner than about one voxel can be reported as separate components and gaps narrower than one voxel can be bridged. Use a voxel size of at most about half of the thinnest strut radius or wall thickness.
- Parameters:
root – Node to analyze. It is prepared with the voxel size unless already prepared.
voxel_size – Positive sampling pitch in millimetres; the smallest component is used.
connectivity – 6 or 26.
bounds – Optional analysis box; it is intersected with the node’s bounding box.
root_already_prepared – Skip prepare() when the caller already prepared the node.
cull_far_cells – Decide whole 8^3 voxel blocks from one centre probe when the field there is farther from zero than 1.5 times the block’s half diagonal. Exact for true signed distances such as primitives, booleans and stochastic strut lattices (and any field with slope up to 1.5). TPMS fields can change faster than distance, so leave it off for designs that contain them.
- Returns:
Component report.
-
ConnectedComponentReport label_connected_components(const std::vector<unsigned char> &occupancy, const glm::ivec3 &dimensions, int connectivity = 26, const std::array<bool, 3> &periodic = {{false, false, false}}, std::vector<int> *cell_labels = nullptr)#
Label connected solid cells in a dense occupancy grid.
Cells are indexed x-fastest: index = x + nx * (y + ny * z). This shares the run-length union-find used by analyze_connected_components(). Periodic axes join the first and last layers along that axis.
- Parameters:
occupancy – Non-zero entries are solid; size must equal nx * ny * nz.
dimensions – Grid size (nx, ny, nz), all positive.
connectivity – 6 or 26.
periodic – Periodic flags for X, Y and Z.
cell_labels – Optional output: for each cell, the index of its component in the report’s (sorted) components list, or -1 for an empty cell. Resized to the occupancy size.
- Returns:
Report in index units (origin 0, voxel size 1).
-
struct ConnectedComponentReport#
- #include <connected_components.h>
Voxel connectivity summary of an implicit solid.
Public Functions
-
inline size_t component_count() const#
Return the number of connected components.
- Returns:
components.size().
Public Members
-
std::vector<SolidComponent> components#
Components sorted by decreasing voxel count (ties by sample position).
-
int connectivity = 26#
Neighbourhood used to join voxels: 6 (faces) or 26 (faces, edges and corners).
-
glm::ivec3 dimensions = {0}#
Number of samples along X, Y and Z.
-
glm::vec3 origin = {0.0f}#
Center of the first voxel sample.
-
size_t solid_voxel_count = 0#
Total number of solid samples.
-
glm::vec3 voxel_size = {0.0f}#
Uniform sampling pitch used on every axis.
-
inline size_t component_count() const#
-
struct SolidComponent#
- #include <connected_components.h>
One connected piece of solid material found by analyze_connected_components().
Public Members
-
glm::vec3 maximum = {0.0f}#
Maximum corner of the component’s sample bounding box.
-
glm::vec3 minimum = {0.0f}#
Minimum corner of the component’s sample bounding box.
-
glm::vec3 sample_point = {0.0f}#
One solid sample location inside the component, useful for locating islands.
-
double volume = 0.0#
Approximate volume in cubic millimetres (voxel_count times the voxel volume).
-
size_t voxel_count = 0#
Number of solid voxel samples in the component.
-
glm::vec3 maximum = {0.0f}#