Volumes#
VDB-backed volumes and the VDB, DICOM, PNG, unstructured-field and scattered-point loaders used with attribute / grid workflows.
Typedefs
-
typedef openvdb::Grid<openvdb::tree::Tree4<openvdb::Vec2s, 5, 4, 3>::Type> Vec2sGrid#
-
typedef openvdb::Grid<openvdb::tree::Tree4<openvdb::Vec4s, 5, 4, 3>::Type> Vec4sGrid#
-
template<typename GridType>
class VDBVolume# - #include <vdb_volume.h>
A sampled OpenVDB grid in world space.
Wraps a grid of one value type and samples it with trilinear interpolation (openvdb::tools::BoxSampler) at world-space points. Points away from active voxels read the grid’s background value. Use the aliases FloatVDBVolume, Vec2sVDBVolume, Vec3sVDBVolume and Vec4sVDBVolume.
- Template Parameters:
GridType – The OpenVDB grid type.
Public Types
Public Functions
-
inline std::pair<glm::vec3, glm::vec3> bounding_box() const#
The world-space bounding box of the active voxels.
Spans the centres of the outermost active voxels.
- Returns:
(min, max) corners.
-
inline std::shared_ptr<VDBVolume<GridType>> clone() const#
A copy for use on another thread.
The copy shares the grid but has its own accessor and sampler.
- Returns:
The copy.
-
inline std::string grid_type() const#
The OpenVDB type name of the grid, such as “float” or “vec3s”.
- Returns:
The type name, or “None” when there is no grid.
-
inline ValueType sample(const double x, const double y, const double z) const#
Sample the grid at a world-space point with trilinear interpolation.
- Parameters:
x – World x coordinate.
y – World y coordinate.
z – World z coordinate.
- Returns:
The interpolated value.
-
inline void set_transform(const openvdb::math::Transform &transform)#
Replace the grid’s index-to-world transform.
The grid is shared with clones and with the code that created it, so they all move.
- Parameters:
transform – The new transform.
-
inline VDBVolume()#
Create a volume around a new, empty grid.
-
inline explicit VDBVolume(GridPtr grid, bool center = false)#
Wrap an existing grid.
The grid is shared, not copied.
- Parameters:
grid – The grid to wrap.
center – If true, post-translate the grid’s transform so the world bounding box of its active voxels is centred at the origin. This changes the shared grid. An empty grid is left in place.
- Throws:
std::invalid_argument – if
gridis null.
Public Static Functions
-
static inline std::shared_ptr<VDBVolume<GridType>> from_dense(const ValueType *data, size_t nx, size_t ny, size_t nz, const glm::vec3 &voxel_size, const glm::vec3 &origin = glm::vec3(0.0f), float tolerance = 0.0f, bool center = false)#
Build a sparse volume from a dense, row-major block of voxel values.
The block is indexed like a C-ordered numpy array
arr[i, j, k]whereiruns along world X,jalong Y andkalong Z, sokis the fastest-varying index in memory. Voxel(i, j, k)is centred atorigin + (i * voxel_size.x, j * voxel_size.y, k * voxel_size.z), and sampling at a voxel centre returns that voxel’s value exactly.Voxels whose value lies within
toleranceof zero (every component, for vector grids) are left inactive at the background value of zero, which keeps mostly-empty data sparse in memory. A tolerance of zero drops only exact zeros. With a positive tolerance, an 8x8x8 block whose values all lie withintoleranceof each other may be collapsed into a single tile.The conversion uses
openvdb::tools::copyFromDenseand runs in parallel; the input is only read.- Parameters:
data – Pointer to
nx * ny * nzvalues,kfastest. For vector grids each value is the grid’s packed vector type (e.g. three floats forVec3sVDBVolume).nx – Number of voxels along X.
ny – Number of voxels along Y.
nz – Number of voxels along Z.
voxel_size – Spacing between voxel centres along X, Y and Z in mm. Each component must be positive.
origin – World position of the centre of voxel
(0, 0, 0)in mm.tolerance – Values within this distance of zero stay inactive. Must be non-negative.
center – If true, place the volume so the full
nx * ny * nzblock is centred at the origin (originis then ignored). Unlike the loaders’centerflag this uses the array extent rather than the active voxels, so several fields cut from the same array stay aligned however sparse each one is.
- Returns:
A new volume that owns its own sparse copy of the data.
-
namespace VDB_Loader#
Reading and writing VDBVolume grids as .vdb files.
Functions
-
std::shared_ptr<Vec3sVDBVolume> load_vdb_vec3s_volume_from_grid(const std::string &file_path, const std::string &grid_name, bool center = false)#
Load one Vec3s grid from a .vdb file.
See load_vdb_volume_from_grid().
- Parameters:
file_path – Path to the .vdb file.
grid_name – Name of the grid to load.
center – If true, centre the bounding box of the grid’s active voxels at the origin.
- Returns:
The loaded volume.
-
std::shared_ptr<Vec4sVDBVolume> load_vdb_vec4s_volume_from_grid(const std::string &file_path, const std::string &grid_name, bool center = false)#
Load one Vec4s grid from a .vdb file.
See load_vdb_volume_from_grid().
- Parameters:
file_path – Path to the .vdb file.
grid_name – Name of the grid to load.
center – If true, centre the bounding box of the grid’s active voxels at the origin.
- Returns:
The loaded volume.
-
std::shared_ptr<FloatVDBVolume> load_vdb_volume_from_grid(const std::string &file_path, const std::string &grid_name, bool center = false)#
Load one float grid from a .vdb file.
- Parameters:
file_path – Path to the .vdb file.
grid_name – Name of the grid to load.
center – If true, centre the bounding box of the grid’s active voxels at the origin.
- Throws:
std::runtime_error – if the file cannot be opened or the grid is not a FloatGrid. A missing grid raises openvdb::KeyError.
- Returns:
The loaded volume.
Write a Vec3s volume to a .vdb file as a single named grid.
See
save_vdb_volume.- Parameters:
volume – The volume to write.
file_path – Destination .vdb path.
grid_name – Name stored for the grid, used to load it again.
Write a float volume to a .vdb file as a single named grid.
The grid is written with its current transform, so a volume built with
FloatVDBVolume::from_densereloads at the same world position. Any existing file is overwritten.- Parameters:
volume – The volume to write.
file_path – Destination .vdb path.
grid_name – Name stored for the grid, used to load it again.
-
std::shared_ptr<Vec3sVDBVolume> load_vdb_vec3s_volume_from_grid(const std::string &file_path, const std::string &grid_name, bool center = false)#
-
class DICOMLoader#
- #include <dicom_loader.h>
Loads a DICOM slice stack into a float volume of Hounsfield Units.
Each stored pixel becomes HU = value * rescale_slope + rescale_intercept. Pixel (column c, row r) of slice i becomes voxel (c, r, i). The volume is placed in world space by the pixel spacing and slice thickness, then by the rigid patient transform read from the first slice, and optionally centred. Only uncompressed pixel data is supported.
Public Functions
-
std::shared_ptr<FloatVDBVolume> as_volume()#
The loaded volume of Hounsfield Units.
Each call returns a new FloatVDBVolume that shares the loader’s grid.
- Returns:
The volume, placed in world space.
-
DICOMLoader(const std::string &directory, bool center = false, double rescale_slope = -std::numeric_limits<double>::infinity(), double rescale_intercept = -std::numeric_limits<double>::infinity(), double slice_thickness = -std::numeric_limits<double>::infinity(), double x_pixel_spacing = -std::numeric_limits<double>::infinity(), double y_pixel_spacing = -std::numeric_limits<double>::infinity(), DICOMSliceOrder slice_order = DICOMSliceOrder::AUTO, const std::string &filename_prefix = "")#
Construct a DICOM volume from the given directory.
Values left at -infinity are read from the first slice’s metadata.
- Parameters:
directory – The directory containing the DICOM stack.
center – Whether to center the volume at the origin. Default is false.
rescale_slope – The rescale slope to apply to the pixel values. If not provided, it will be read from the DICOM metadata.
rescale_intercept – The rescale intercept to apply to the pixel values. If not provided, it will be read from the DICOM metadata.
slice_thickness – The slice thickness in mm. If not provided, it will be read from the DICOM metadata.
x_pixel_spacing – The pixel spacing in the x direction in mm. If not provided, it will be read from the DICOM metadata.
y_pixel_spacing – The pixel spacing in the y direction in mm. If not provided, it will be read from the DICOM metadata.
slice_order – How the slice files are ordered into a stack. See DICOMSliceOrder.
filename_prefix – A literal filename prefix ignored when the order falls back to filenames. Use it when the fixed part of a filename contains digits that must not take part in the ordering (for example “scan2024_” in “scan2024_001.dcm”).
- Throws:
std::runtime_error – if a value is neither given nor found in the metadata, or a slice cannot be read.
-
std::pair<glm::vec3, glm::vec3> get_bounding_box() const#
The world-space bounding box of the placed volume.
Equals as_volume()->bounding_box(), so it includes the patient transform and centering.
- Returns:
(min, max) corners in mm.
-
inline glm::vec3 get_dimensions() const#
The physical size of the stack in mm, before placement.
- Returns:
(columns * x spacing, rows * y spacing, (slices - 1) * slice thickness).
-
inline std::pair<double, double> get_min_max_hu() const#
The smallest and largest Hounsfield Unit in the stack.
- Returns:
(min, max).
-
inline double get_rescale_intercept() const#
The rescale intercept used, given or read from the metadata.
- Returns:
The intercept.
-
inline double get_rescale_slope() const#
The rescale slope used, given or read from the metadata.
- Returns:
The slope.
-
inline glm::vec3 get_voxel_size() const#
The voxel size in mm.
- Returns:
(x pixel spacing, y pixel spacing, slice thickness).
Private Types
-
using GridType = openvdb::FloatGrid#
Private Functions
-
std::vector<std::vector<double>> load_dicom_image(const std::string &file_path)#
Load a single DICOM image from the given file path and return the pixel data as a 2D vector.
-
void load_dicom_stack(const std::string &directory)#
Load a DICOM stack from the given directory into an OpenVDB volume.
- Parameters:
directory – The directory containing the DICOM stack.
Private Members
-
bool m_center = false#
-
std::string m_filename_prefix#
-
double m_hu_max = std::numeric_limits<double>::lowest()#
-
double m_hu_min = std::numeric_limits<double>::max()#
-
double m_rescale_intercept = -std::numeric_limits<double>::infinity()#
-
double m_rescale_slope = -std::numeric_limits<double>::infinity()#
-
DICOMSliceOrder m_slice_order = DICOMSliceOrder::AUTO#
-
double m_x_size = 0#
-
double m_x_spacing = -std::numeric_limits<double>::infinity()#
-
double m_y_size = 0#
-
double m_y_spacing = -std::numeric_limits<double>::infinity()#
-
double m_z_size = 0#
-
double m_z_spacing = -std::numeric_limits<double>::infinity()#
Private Static Functions
-
static DICOM_Meta_Data GetDICOMMetaData(const std::string &file_path)#
Get the metadata for a DICOM image from the given file path.
-
static glm::mat4 GetDICOMRigidTransform(DcmDataset *dataset)#
-
static double GetRescaledValue(Uint16 pixel_value, double rescale_slope, double rescale_intercept)#
-
struct DICOM_Meta_Data#
Public Members
-
bool found_rescale_intercept = false#
-
bool found_rescale_slope = false#
-
bool found_thickness = false#
-
bool found_width_and_height = false#
-
bool found_xy_spacing = false#
-
size_t height = 0#
-
double rescale_intercept = 0.0#
-
double rescale_slope = 1.0#
-
glm::mat4 rigid_transform = glm::mat4(1.0f)#
-
double slice_thickness = 1#
-
size_t width = 0#
-
double x_pixel_spacing = -1#
-
double y_pixel_spacing = -1#
-
bool found_rescale_intercept = false#
-
std::shared_ptr<FloatVDBVolume> as_volume()#
Enums
-
enum class PNGColorMode#
Which channels a PNGLoader keeps.
Values:
-
enumerator COLOR_RGB#
Keep red, green and blue; build a Vec3sVDBVolume.
-
enumerator COLOR_RGBA#
Keep all four channels; build a Vec4sVDBVolume.
-
enumerator COLOR_RGB#
-
class PNGLoader#
- #include <png_loader.h>
Loads PNG images into a color volume.
Either extrudes a single image through a depth, or stacks a directory of images along z. Channels are scaled from 0-255 to [0, 1]. Pixel (column c, row r) of slice z becomes voxel (width - 1 - c, r, z), and voxel (i, j, k) is centred at (i, j, k) * voxel_size unless the volume is centred. Every pixel is stored, transparent or black ones included.
Public Functions
-
std::shared_ptr<Vec3sVDBVolume> as_rgb_volume() const#
The RGB volume, with channels in [0, 1].
- Throws:
std::runtime_error – if the loader was not created in COLOR_RGB mode.
- Returns:
The volume.
-
std::shared_ptr<Vec4sVDBVolume> as_rgba_volume() const#
The RGBA volume, with channels in [0, 1].
- Throws:
std::runtime_error – if the loader was not created in COLOR_RGBA mode.
- Returns:
The volume.
-
inline PNGColorMode color_mode() const#
The color mode the loader was created with.
- Returns:
The mode.
-
std::pair<glm::vec3, glm::vec3> get_bounding_box() const#
The world-space bounding box of the volume.
Equals the loaded volume’s bounding_box(): it spans the first to the last voxel centre, and is centred at the origin when the loader was created with center = true.
- Returns:
(min, max) corners in mm.
-
inline glm::vec3 get_dimensions() const#
The physical size of the volume in mm.
- Returns:
(width, height, slices) multiplied by the voxel size.
-
inline size_t get_slice_count() const#
The number of slices along z.
- Returns:
The slice count.
-
inline glm::vec3 get_voxel_size() const#
The voxel size in mm.
- Returns:
The voxel size along x, y and z.
Public Static Functions
-
static std::shared_ptr<PNGLoader> FromImage(const std::string &file_path, const glm::vec3 &voxel_size, double depth_mm, PNGColorMode color_mode, bool center = false)#
Extrude one PNG image into a volume.
- Parameters:
file_path – Path to the PNG image.
voxel_size – Voxel size in mm along x, y and z. Every component must be positive.
depth_mm – Extrusion depth in mm; the image is repeated ceil(depth_mm / voxel_size.z) times, at least once. Must be positive.
color_mode – Which channels to keep.
center – If true, translate the volume so its bounding box is centred at the origin.
- Throws:
std::runtime_error – if the file is missing or cannot be decoded, or a size is invalid.
- Returns:
The loader holding the volume.
-
static std::shared_ptr<PNGLoader> FromStack(const std::string &directory, const glm::vec3 &voxel_size, PNGColorMode color_mode, bool center = false)#
Stack a directory of PNG images along z.
Files with a .png extension (any case) are ordered by the number at the end of their name, then by name; files without a trailing number come last. All images must have the same size.
- Parameters:
directory – Directory holding the slices.
voxel_size – Voxel size in mm along x, y and z. Every component must be positive.
color_mode – Which channels to keep.
center – If true, translate the volume so its bounding box is centred at the origin.
- Throws:
std::runtime_error – if the directory is missing or has no PNGs, an image cannot be decoded, or the slice sizes differ.
- Returns:
The loader holding the volume.
Private Functions
-
void finalize_volumes()#
-
void initialize_grids(size_t width, size_t height, size_t slices)#
-
void load_from_single_image(const std::string &file_path, double depth_mm)#
-
void load_from_stack(const std::string &directory)#
-
PNGLoader() = default#
-
void set_voxel(size_t x, size_t y, size_t z, unsigned char r, unsigned char g, unsigned char b, unsigned char a)#
-
void validate_voxel_size() const#
Private Members
-
bool m_center = false#
-
PNGColorMode m_color_mode = PNGColorMode::COLOR_RGBA#
-
glm::vec3 m_dimensions = glm::vec3(0.0f, 0.0f, 0.0f)#
-
openvdb::Vec3SGrid::Ptr m_rgb_grid#
-
std::shared_ptr<Vec3sVDBVolume> m_rgb_volume#
-
std::shared_ptr<Vec4sVDBVolume> m_rgba_volume#
-
size_t m_slice_count = 0#
-
glm::vec3 m_voxel_size = glm::vec3(1.0f, 1.0f, 1.0f)#
-
std::shared_ptr<Vec3sVDBVolume> as_rgb_volume() const#
Enums
-
enum class FieldAssociation#
Location of result values on an unstructured finite-element domain.
Values:
-
enumerator point#
One value per point, interpolated with barycentric weights inside a cell.
-
enumerator cell#
One value per cell, constant over the cell.
-
enumerator point#
-
enum class OutsidePolicy#
Explicit behavior when a query is outside an unstructured field domain.
Values:
-
enumerator error#
Outside queries have no value; attributes raise an error.
-
enumerator constant#
Outside queries return the supplied constant.
-
enumerator boundary_clamp#
Queries within max_distance of the boundary use the nearest boundary point.
-
enumerator error#
-
enum class SampleStatus#
Geometric classification assigned to one unstructured-field query.
Values:
-
enumerator inside#
Inside a cell; all barycentric weights are non-negative.
-
enumerator tolerance_adjusted#
Within round-off of a cell; its weights were clamped and renormalized.
-
enumerator boundary_clamped#
Outside, but within max_distance; projected to the nearest boundary face.
-
enumerator outside#
Outside the domain and any clamp band.
-
enumerator inside#
-
struct CoverageFailure#
- #include <unstructured_field.h>
One representative query that remained outside a field domain.
-
struct CoverageReport#
- #include <unstructured_field.h>
Opt-in batch classification report for expensive downstream sampling.
Public Functions
-
double fraction(SampleStatus status) const#
Return the fraction of queries in one classification.
- Parameters:
status – Classification to inspect.
- Returns:
Count divided by total_queries, or zero for an empty report.
Public Members
-
size_t boundary_clamped_count = 0#
Queries classified boundary_clamped.
-
size_t inside_count = 0#
Queries classified inside.
-
double maximum_clamp_distance = 0.0#
Largest clamp distance among clamped queries.
-
size_t outside_count = 0#
Queries classified outside.
-
std::vector<CoverageFailure> representative_failures#
The first outside queries, up to the maximum_failures passed to coverage().
-
size_t tolerance_adjusted_count = 0#
Queries classified tolerance_adjusted.
-
size_t total_queries = 0#
Number of positions classified.
-
double fraction(SampleStatus status) const#
-
struct FieldMetadata#
- #include <unstructured_field.h>
Discoverable description and numeric range for one named result field.
Public Members
-
FieldAssociation association = FieldAssociation::point#
Whether values sit on points or cells.
-
std::string cell_type = "TET4"#
Cell type of the domain; always “TET4”.
-
size_t component_count = 0#
1 for scalars, 3 for vectors.
-
std::string description#
Free-form description.
-
std::vector<double> maximum#
Per-component maximum of the stored values.
-
std::vector<double> minimum#
Per-component minimum of the stored values.
-
std::string name#
Field name.
-
std::string step_identifier#
Free-form solver step or time label.
-
std::string units#
Free-form units label; never used for conversion.
-
size_t value_count = 0#
Number of stored values.
-
FieldAssociation association = FieldAssociation::point#
-
struct FieldSamplingOptions#
- #include <unstructured_field.h>
Outside-domain settings used when creating or diagnostically sampling a field.
boundary_clamp requires a finite non-negative max_distance in dataset-coordinate units. If a constant is also supplied, it is used only beyond the clamp band. Constant values are expressed in stored field coordinates; vector_transform is applied before a vector is returned.
Public Members
-
std::optional<double> constant_scalar#
Value outside the domain for scalar fields. Required by constant; not allowed with error.
-
std::optional<glm::dvec3> constant_vector#
Value outside the domain for vector fields. Required by constant; not allowed with error.
-
double max_distance = std::numeric_limits<double>::quiet_NaN()#
Clamp band for boundary_clamp, in dataset units. Must stay NaN for the other policies.
-
OutsidePolicy outside_policy = OutsidePolicy::error#
Behavior outside the domain.
-
std::optional<double> constant_scalar#
-
struct ScalarFieldSample#
- #include <unstructured_field.h>
Diagnostic scalar sample including geometric classification.
Public Members
-
size_t cell_index = std::numeric_limits<size_t>::max()#
Cell used, or SIZE_MAX when outside.
-
double clamp_distance = 0.0#
Distance to the boundary when clamped, else 0.
-
SampleStatus status = SampleStatus::outside#
How the query was classified.
-
std::optional<double> value#
The sampled value, or empty when outside with no constant.
-
size_t cell_index = std::numeric_limits<size_t>::max()#
-
class TetrahedralDomain#
- #include <unstructured_field.h>
Immutable validated TET4 domain with shared point-location and boundary queries.
Input containers are copied. Cell winding is normalized, all barycentric work is performed in double precision, and prepared CGAL query structures are read-only and safe to share among independently cloned attributes.
Public Functions
-
size_t boundary_face_count() const#
Number of outer boundary triangles.
- Returns:
The boundary face count.
-
std::pair<glm::dvec3, glm::dvec3> bounding_box() const#
Axis-aligned bounds of the points, in dataset coordinates.
- Returns:
(min, max) corners.
-
size_t cell_count() const#
Number of cells.
- Returns:
The cell count.
-
const std::vector<std::array<size_t, 4>> &cells() const#
The stored connectivity, after any reorientation.
- Returns:
The cells.
-
Location locate(const glm::dvec3 &position, OutsidePolicy outside_policy = OutsidePolicy::error, double max_distance = std::numeric_limits<double>::quiet_NaN()) const#
Classify and locate one dataset-space position.
When several cells contain the point, the lowest cell index wins.
- Parameters:
position – Position in dataset coordinates.
outside_policy – Whether bounded boundary projection should be attempted.
max_distance – Finite clamp band in dataset-coordinate units for boundary_clamp.
- Returns:
Deterministic cell, barycentric weights, status, and boundary distance.
-
size_t point_count() const#
Number of points.
- Returns:
The point count.
-
const std::vector<glm::dvec3> &points() const#
The stored point coordinates.
- Returns:
The points.
-
size_t reoriented_cell_count() const#
Number of cells whose winding was flipped during construction.
- Returns:
The reoriented cell count.
-
TetrahedralDomain(const std::vector<glm::dvec3> &points, const std::vector<std::array<size_t, 4>> &cells)#
Construct and prepare an immutable tetrahedral domain.
Inverted cells are reoriented. The domain needs at least one cell, a finite 3D extent, no degenerate or duplicate cells, and at least one boundary face.
- Parameters:
points – Finite dataset-space point coordinates.
cells – Four-node connectivity. Indices must be valid and distinct per cell.
- Throws:
std::runtime_error – if the mesh fails validation.
Private Members
-
std::shared_ptr<const Impl> m_impl#
-
struct Location#
- #include <unstructured_field.h>
Internal/public geometric result used by diagnostic field sampling.
Public Members
-
std::array<double, 4> barycentric = {0.0, 0.0, 0.0, 0.0}#
Weights of the cell’s four nodes.
-
double boundary_distance = std::numeric_limits<double>::quiet_NaN()#
0 inside, the boundary distance when boundary_clamp was attempted, NaN otherwise.
-
size_t cell_index = std::numeric_limits<size_t>::max()#
Cell found, or SIZE_MAX when outside.
-
glm::dvec3 sample_position = {0.0}#
The query, or its boundary projection when clamped.
-
SampleStatus status = SampleStatus::outside#
How the position was classified.
-
std::array<double, 4> barycentric = {0.0, 0.0, 0.0, 0.0}#
-
size_t boundary_face_count() const#
-
class UnstructuredFieldDataset#
- #include <unstructured_field.h>
Solver-neutral named scalar/vector results sharing one immutable TET4 domain.
The default position and vector transforms are identity. position_transform maps consuming-node coordinates into dataset coordinates. vector_transform maps stored vector components into the consuming-node coordinate basis; it never deforms the domain. Unit conversion is therefore explicit rather than inferred from metadata.
Public Functions
-
void add_cell_scalar(const std::string &name, const std::vector<double> &values, const std::string &units = "", const std::string &step_identifier = "", const std::string &description = "")#
Add a scalar field with one value per cell.
Same rules as add_point_scalar(), with one value per cell.
- Parameters:
name – Unique, non-empty field name.
values – One finite value per cell.
units – Free-form units label.
step_identifier – Free-form solver step label.
description – Free-form description.
-
void add_cell_vector(const std::string &name, const std::vector<glm::dvec3> &values, const std::string &units = "", const std::string &step_identifier = "", const std::string &description = "")#
Add a three-component field with one vector per cell.
Same rules as add_point_scalar(), with one vector per cell.
- Parameters:
name – Unique, non-empty field name.
values – One finite vector per cell.
units – Free-form units label.
step_identifier – Free-form solver step label.
description – Free-form description.
-
void add_point_scalar(const std::string &name, const std::vector<double> &values, const std::string &units = "", const std::string &step_identifier = "", const std::string &description = "")#
Add a scalar field with one value per point.
- Parameters:
name – Unique, non-empty field name.
values – One finite value per point.
units – Free-form units label.
step_identifier – Free-form solver step label.
description – Free-form description.
- Throws:
std::runtime_error – if the name is empty or taken, the count is wrong, or a value is not finite.
-
void add_point_vector(const std::string &name, const std::vector<glm::dvec3> &values, const std::string &units = "", const std::string &step_identifier = "", const std::string &description = "")#
Add a three-component field with one vector per point.
Same rules as add_point_scalar().
- Parameters:
name – Unique, non-empty field name.
values – One finite vector per point.
units – Free-form units label.
step_identifier – Free-form solver step label.
description – Free-form description.
-
CoverageReport coverage(const std::vector<glm::dvec3> &positions, OutsidePolicy outside_policy = OutsidePolicy::error, double max_distance = std::numeric_limits<double>::quiet_NaN(), size_t maximum_failures = 8) const#
Preflight many consuming-coordinate positions without persistent counters.
- Parameters:
positions – Positions to classify.
outside_policy – Outside behavior to model during classification.
max_distance – Finite clamp band in dataset-coordinate units for boundary_clamp.
maximum_failures – Maximum number of representative outside points to retain.
- Returns:
Counts per classification and the first outside points.
-
std::shared_ptr<const TetrahedralDomain> domain() const#
The shared domain.
- Returns:
The domain.
-
FieldMetadata field_metadata(const std::string &name) const#
The metadata of one field.
- Parameters:
name – Field name.
- Throws:
std::runtime_error – if there is no such field.
- Returns:
A copy of the metadata.
-
std::vector<std::string> field_names() const#
The names of all fields, sorted.
- Returns:
The field names.
-
std::shared_ptr<FloatAttribute> float_attribute(const std::string &name, const FieldSamplingOptions &options = {}) const#
Create an ordinary scalar attribute backed by a named result field.
- Parameters:
name – Scalar field name.
options – Explicit outside-domain behavior.
- Throws:
std::runtime_error – if the field is missing, is not scalar, or the options are invalid.
- Returns:
Cloneable FloatAttribute sharing this domain and immutable field values. It reads a snapshot of this dataset, and throws std::runtime_error for a query with no value.
-
bool has_field(const std::string &name) const#
Whether a field with this name exists.
- Parameters:
name – Field name.
- Returns:
True if the field exists.
-
const glm::dmat4 &position_transform() const#
The affine map from consuming coordinates to dataset coordinates.
- Returns:
The transform; identity by default.
-
ScalarFieldSample sample_scalar(const std::string &name, const glm::dvec3 &position, const FieldSamplingOptions &options = {}) const#
Sample a scalar field at one position, with its classification.
The position is mapped through position_transform(). Point fields are interpolated with barycentric weights; cell fields return the cell’s value. Outside the domain and any clamp band, the value is the constant or empty.
- Parameters:
name – Scalar field name.
position – Position in consuming coordinates.
options – Outside-domain behavior.
- Throws:
std::runtime_error – if the field is missing or not scalar, or the options are invalid.
- Returns:
The value and how the position was classified.
-
Vec3FieldSample sample_vector(const std::string &name, const glm::dvec3 &position, const FieldSamplingOptions &options = {}) const#
Sample a vector field at one position, with its classification.
Same rules as sample_scalar(). The value, including the outside constant, is multiplied by vector_transform().
- Parameters:
name – Three-component field name.
position – Position in consuming coordinates.
options – Outside-domain behavior.
- Throws:
std::runtime_error – if the field is missing or not a vector, or the options are invalid.
- Returns:
The value and how the position was classified.
-
std::shared_ptr<UnstructuredFieldDataset> transformed(const glm::dmat4 &position_transform, const glm::dmat3 &vector_transform = glm::dmat3(1.0)) const#
Return a transformed dataset view sharing the immutable domain and field arrays.
The transforms replace this dataset’s transforms; they are not composed with them.
- Parameters:
position_transform – Affine consumer-position to dataset-position transform.
vector_transform – Stored-vector to consumer-vector component transform.
- Throws:
std::runtime_error – if a transform is not finite, the position transform is not affine, or either linear part is singular.
- Returns:
Independent dataset view with the same named fields.
Construct a dataset that shares an immutable domain.
- Parameters:
domain – The domain. Must not be null.
- Throws:
std::runtime_error – if
domainis null.
-
std::shared_ptr<Vec3Attribute> vec3_attribute(const std::string &name, const FieldSamplingOptions &options = {}) const#
Create an ordinary Vec3 attribute backed by a named result field.
- Parameters:
name – Three-component field name.
options – Explicit outside-domain behavior.
- Throws:
std::runtime_error – if the field is missing, is not a vector, or the options are invalid.
- Returns:
Cloneable Vec3Attribute sharing this domain and immutable field values. It reads a snapshot of this dataset, and throws std::runtime_error for a query with no value.
-
const glm::dmat3 &vector_transform() const#
The map from stored vector components to the consuming basis.
- Returns:
The transform; identity by default.
Public Static Functions
-
static std::shared_ptr<UnstructuredFieldDataset> from_tetrahedra(const std::vector<glm::dvec3> &points, const std::vector<std::array<size_t, 4>> &cells)#
Construct a dataset from copied point and TET4 connectivity containers.
- Parameters:
points – Finite dataset-space point coordinates.
cells – Four-node connectivity.
- Returns:
A dataset with no fields.
Private Functions
-
void add_scalar(const std::string &name, FieldAssociation association, const std::vector<double> &values, const std::string &units, const std::string &step_identifier, const std::string &description)#
-
void add_vector(const std::string &name, FieldAssociation association, const std::vector<glm::dvec3> &values, const std::string &units, const std::string &step_identifier, const std::string &description)#
-
glm::dvec3 dataset_position(const glm::dvec3 &position) const#
Private Members
-
std::shared_ptr<const TetrahedralDomain> m_domain#
-
glm::dmat4 m_position_transform = {1.0}#
-
glm::dmat3 m_vector_transform = {1.0}#
Private Static Functions
-
static void validate_sampling_options(const FieldSamplingOptions &options, size_t component_count)#
-
static void validate_transform(const glm::dmat3 &transform)#
-
static void validate_transform(const glm::dmat4 &transform)#
-
struct FieldData#
Public Members
-
FieldMetadata metadata#
-
std::shared_ptr<const std::vector<double>> scalar_values#
-
std::shared_ptr<const std::vector<glm::dvec3>> vector_values#
-
FieldMetadata metadata#
-
void add_cell_scalar(const std::string &name, const std::vector<double> &values, const std::string &units = "", const std::string &step_identifier = "", const std::string &description = "")#
-
struct Vec3FieldSample#
- #include <unstructured_field.h>
Diagnostic vector sample including geometric classification.
Public Members
-
size_t cell_index = std::numeric_limits<size_t>::max()#
Cell used, or SIZE_MAX when outside.
-
double clamp_distance = 0.0#
Distance to the boundary when clamped, else 0.
-
SampleStatus status = SampleStatus::outside#
How the query was classified.
-
std::optional<glm::dvec3> value#
The sampled value, or empty when outside with no constant.
-
size_t cell_index = std::numeric_limits<size_t>::max()#
-
class XDMFFieldLoader#
- #include <xdmf_field_loader.h>
Loader for OpenVCAD’s documented XDMF 3/HDF5 TET4 result-field subset.
Supports direct HDF-backed Tetrahedron topology, XYZ geometry, and Node/Cell scalar or three-component vector attributes on a Uniform grid. Collections, temporal grids, mixed/HEX topology, inline XML, functions, hyperslabs, tensors, and other general XDMF features are rejected explicitly.
Public Static Functions
-
static std::shared_ptr<UnstructuredFieldDataset> load(const std::string &xdmf_path, const std::string &grid_name = "", const std::vector<std::string> &field_names = {})#
Load one supported uniform grid and selected fields.
- Parameters:
xdmf_path – Path to an XDMF 3 document.
grid_name – Grid name. Required when the document has multiple uniform grids.
field_names – Field names to load, or an empty list to load all supported fields.
- Returns:
A solver-neutral dataset independent of compilers and solver libraries.
-
static std::shared_ptr<UnstructuredFieldDataset> load(const std::string &xdmf_path, const std::string &grid_name = "", const std::vector<std::string> &field_names = {})#
-
class PointSet#
- #include <point_set.h>
An immutable set of 3D points with a k-d tree for nearest-neighbour and radius queries.
The storage behind fields built from scattered points (ScatteredInterpolator): data and evaluation stay separate, the way a VDB volume sits behind a FloatAttribute. The tree is an implicit, balanced k-d tree over an index array (median split on the widest axis, small leaves scanned directly), built once in the constructor.
Queries are const and write into caller-supplied buffers, so one PointSet is shared by every clone of the fields built on it and queried from many threads at once.
Public Functions
-
inline std::pair<glm::dvec3, glm::dvec3> bounds() const#
Returns the smallest and largest corner of the points’ bounding box.
- Returns:
(min, max) corners.
-
double median_spacing() const#
Returns the median distance from a point to its nearest other point (0 for a single point).
Computed on demand, in O(N log N); used to choose default interpolation radii.
- Returns:
The median nearest-neighbour distance.
-
void nearest(const glm::dvec3 &point, size_t k, std::vector<size_t> &indices, std::vector<double> &squared_distances) const#
Finds the k points nearest to a point, closest first.
- Parameters:
point – The query point.
k – How many to find; fewer are returned when the set is smaller.
indices – Receives the indices of the points found.
squared_distances – Receives their squared distances, ascending.
-
inline const std::vector<glm::dvec3> &points() const#
Returns the points, in the order given.
- Returns:
The points.
-
explicit PointSet(std::vector<glm::dvec3> points)#
Builds the set and its tree.
- Parameters:
points – The points; at least one, all finite.
- Throws:
std::runtime_error – for an empty set or a non-finite coordinate.
-
inline size_t size() const#
Returns the number of points.
- Returns:
The point count.
-
void within(const glm::dvec3 &point, double radius, std::vector<size_t> &indices, std::vector<double> &squared_distances) const#
Finds every point within a radius of a point, in no particular order.
- Parameters:
point – The query point.
radius – The radius (inclusive).
indices – Receives the indices of the points found.
squared_distances – Receives their squared distances.
Private Functions
-
void build(size_t begin, size_t end)#
-
void search_nearest(size_t begin, size_t end, const glm::dvec3 &point, size_t k, std::vector<size_t> &indices, std::vector<double> &squared_distances) const#
-
void search_within(size_t begin, size_t end, const glm::dvec3 &point, double squared_radius, std::vector<size_t> &indices, std::vector<double> &squared_distances) const#
-
inline std::pair<glm::dvec3, glm::dvec3> bounds() const#
Enums
-
enum class RadialKernel#
The kernel of radial-basis-function interpolation.
Values:
-
enumerator thin_plate_spline#
r^2 log r with a linear trend: smooth, global, no shape parameter.
-
enumerator wendland#
(1 - r/R)^4 (4 r/R + 1): smooth, compactly supported within the radius R.
-
enumerator thin_plate_spline#
-
enum class ScatteredMethod#
How values known at scattered points fill the space between them.
Values:
-
enumerator nearest#
The value of the nearest point: piecewise constant cells around the points.
-
enumerator inverse_distance#
A weighted average of the nearest points, closer points weighing more.
-
enumerator radial_basis#
A smooth radial-basis-function interpolant through every point.
-
enumerator nearest#
Functions
-
RadialKernel radial_kernel_from_name(const std::string &name)#
Returns a kernel by name (“thin_plate_spline”, “wendland”).
-
ScatteredMethod scattered_method_from_name(const std::string &name)#
Returns a method by name (“nearest”, “idw”, “rbf”).
-
std::string scattered_method_name(ScatteredMethod method)#
Returns the name of a method (“nearest”, “idw”, “rbf”).
-
class ScatteredInterpolator#
- #include <scattered_interpolator.h>
Values known at scattered points (one or three components each), interpolated through space.
The evaluation half of a scattered field; the points and their k-d tree live in a shared PointSet. Everything is computed in the constructor and the object is immutable afterwards, so the attributes built on it (ScatteredFloatAttribute, ScatteredVec3Attribute) share one copy across clones and threads.
Methods, with their cost and behaviour away from the data:
nearest: each sample finds one neighbour (O(log N)). Far away: the nearest point’s value.
inverse_distance: modified Shepard weighting of the k nearest points, w = ((R - d) / (R d))^p, with R the distance to the (k + 1)-th point, so the field stays continuous as the neighbour set changes; with N <= k points, plain 1 / d^p over all of them. Exact at the points, and always between the smallest and largest value. O(log N + k) per sample. Far away: the average of the nearest points.
radial_basis with thin_plate_spline: solves a dense (N + 4)^2 system once (O(N^3); about a second for 2,000 points), capped at max_thin_plate_points; each sample sums over every point (O(N)). Smooth, exact at the points (unless smoothing > 0), may overshoot the data range. Far away it follows the fitted linear trend. Coplanar or collinear points fit a lower trend.
radial_basis with wendland: a sparse system solved by conjugate gradients, with nonzeros only between points closer than the radius; each sample visits the points within the radius. Scales to large N while the radius holds tens of points. Away from the data it returns to the mean of the values.
Public Functions
-
inline size_t components() const#
Returns the number of components per value.
- Returns:
1 for scalars, 3 for vectors.
-
void evaluate(const glm::dvec3 &point, double *result, Scratch &scratch) const#
Evaluates every component at a point.
- Parameters:
point – The point.
result – Receives components() values.
scratch – Query buffers owned by the calling thread.
-
inline const ScatteredOptions &options() const#
Returns the options, with the Wendland radius resolved.
- Returns:
The options.
Fits the interpolator.
- Parameters:
points – The points.
values – components values per point, point after point.
components – 1 for scalar values, 3 for vectors.
options – The method and its settings.
- Throws:
std::runtime_error – for mismatched sizes, non-finite values, invalid options, a thin-plate fit with too many points, repeated points in an exact radial-basis fit, or a solve that fails.
-
inline bool stays_in_range() const#
Returns whether every sample stays within the data range (nearest and inverse_distance).
- Returns:
True unless the method is radial_basis.
-
std::pair<double, double> value_range(size_t component) const#
Returns the smallest and largest data value of one component.
- Parameters:
component – The component index, below components().
- Returns:
(min, max) of that component over the data.
Public Static Attributes
-
static constexpr size_t max_thin_plate_points = 2500#
The most points a thin-plate-spline fit accepts (its dense system grows as N^2 in memory).
Private Functions
-
void check_distinct_points() const#
-
void fit_thin_plate_spline()#
-
void fit_wendland()#
-
double polynomial(const glm::dvec3 &point, size_t component) const#
Private Members
-
glm::dvec3 m_center = {0.0}#
-
size_t m_components#
-
std::vector<double> m_mean#
-
ScatteredOptions m_options#
-
std::vector<double> m_trend#
-
std::vector<glm::dvec3> m_trend_directions#
-
std::vector<double> m_values#
-
std::vector<double> m_weights#
-
struct Scratch#
- #include <scattered_interpolator.h>
Per-thread query buffers.
-
struct ScatteredOptions#
- #include <scattered_interpolator.h>
Settings of a ScatteredInterpolator.
Public Members
-
RadialKernel kernel = RadialKernel::thin_plate_spline#
radial_basis: the kernel.
-
ScatteredMethod method = ScatteredMethod::inverse_distance#
The interpolation method.
-
size_t neighbors = 8#
inverse_distance: points averaged.
-
double power = 2.0#
inverse_distance: weight exponent, positive.
-
double radius = 0.0#
radial_basis with wendland: support radius in mm; 0 picks 3x the median spacing.
-
double smoothing = 0.0#
radial_basis: added to the kernel matrix diagonal; > 0 fits noisy data loosely.
-
RadialKernel kernel = RadialKernel::thin_plate_spline#