C++ API¶

All public headers live in include/. Include <vortrace/vortrace.hpp> for the full API, or include individual headers as needed.

CMake target: vortrace::vortrace_core

Types¶

Defined in mytypes.hpp.

using Float = double¶: Floating-point type used throughout the library.

using Point = std::array<Float, 3>¶: A 3D point.

enum class ReductionMode¶

enumerator Sum = 0¶: Weighted integral: accumulate field * ds over segments.

enumerator Max = 1¶: Maximum field value along the ray.

enumerator Min = 2¶: Minimum field value along the ray.

enumerator VolumeRender = 3¶: Front-to-back emission-absorption compositing. Requires 4 input fields (R, G, B, alpha). Returns 3 output values (RGB).

Verbose and warnings¶

std::atomic<bool> vortrace::verbose¶: Runtime flag to enable verbose output. Default: false.

using vortrace::WarningCallback = std::function<void(const std::string&)>¶: Callback type for warnings.

vortrace::WarningCallback vortrace::warning_handler¶: The active warning callback. Default: prints to stderr.

void vortrace::warn(const std::string &msg)¶: Emit a warning through the current handler.

PointCloud¶

Defined in pointcloud.hpp. Manages particle data and a nanoflann kD-tree for nearest-neighbor queries.

class PointCloud¶

void loadPoints(const double *pos, size_t npart, const double *fields, size_t npart_fields, size_t nfields_in, const std::array<Float, 6> &subbox, const double *vol = nullptr, size_t nvol = 0, bool periodic = false)¶

Load particle positions and field data.

Parameters:

pos – Flat array of positions [x0,y0,z0, x1,y1,z1, ...].
npart – Number of particles.
fields – Flat row-major field array [f0_0, f0_1, ..., f1_0, ...].
npart_fields – Number of particles in the fields array (must equal npart).
nfields_in – Number of scalar fields per particle.
subbox – Bounding box {xmin, xmax, ymin, ymax, zmin, zmax}.
vol – Optional per-cell volumes for adaptive padding.
nvol – Length of vol array.
periodic – Enable periodic boundary conditions.

void buildTree()¶: Build the kD-tree. Must be called after loadPoints.

size_t queryTree(const Point &query_pt) const¶: Find the nearest particle to query_pt.

void queryTreeK(const Point &query_pt, size_t k, size_t *results, Float *r2) const¶: Find the k nearest particles.

size_t get_npart() const¶: Number of particles after filtering.

size_t get_nfields() const¶: Number of fields per particle.

Point get_pt(size_t idx) const¶: Position of particle idx.

Float get_field(size_t idx, size_t f) const¶: Field f of particle idx.

bool get_tree_built() const¶: Whether the kD-tree has been built.

bool get_periodic() const¶: Whether periodic mode is enabled.

const std::vector<size_t> &get_orig_ids() const¶: Mapping from filtered particle indices to original indices.

std::array<Float, 6> get_subbox() const¶: The active bounding box.

double get_pad() const¶: The padding added to the subbox.

Ray¶

Defined in ray.hpp. Traces a single ray through the Voronoi mesh.

class Ray¶

struct Segment¶

A single cell crossing along the ray.

size_t cell_id¶: Particle index of the Voronoi cell.

Float s_enter¶: Distance along the ray where the cell begins.

Float s_exit¶: Distance along the ray where the cell ends.

Float ds() const¶: Path length through the cell (s_exit - s_enter).

Ray(const Point &start, const Point &end)¶: Construct a ray from start to end.

const std::vector<Segment> &walk(const PointCloud &cloud)¶: Trace the ray through cloud and return the ordered list of segments.

void integrate(const PointCloud &cloud, ReductionMode mode = ReductionMode::Sum)¶: Walk the ray and apply a reduction. Results are stored internally and accessed via the getter methods below.

Float findSplitPointDistance(const Point &pos1, const Point &pos2)¶: Analytic bisector-ray intersection distance.

const std::vector<Float> &get_col() const¶: Column values after Sum reduction.

const std::vector<Float> &get_max_val() const¶: Maximum values after Max reduction.

const std::vector<Float> &get_min_val() const¶: Minimum values after Min reduction.

const std::vector<Float> &get_vol_render_val() const¶: RGB values (length 3) after VolumeRender reduction.

const std::vector<Segment> &get_segments() const¶: The segments from the last walk call.

Projection¶

Defined in projection.hpp. Integrates fields along a batch of rays.

class Projection¶

Projection(const Float *pos_start, const Float *pos_end, size_t ngrid)¶

Construct from flat arrays of ray start/end points.

Parameters:

pos_start – [x0,y0,z0, x1,y1,z1, ...] (length 3 * ngrid).
pos_end – Same layout as pos_start.
ngrid – Number of rays.

void makeProjection(const PointCloud &cloud, ReductionMode reduction = ReductionMode::Sum)¶: Trace all rays and reduce.

const std::vector<Float> &getProjectionData() const¶: Flat result array of size ngrid * nfields (or ngrid * 3 for VolumeRender).

size_t getNgrid() const¶: Number of rays.

size_t getNfields() const¶: Number of output values per ray.

BruteProjection¶

Defined in brute_projection.hpp. Grid-based projection over a regular 3D extent.

class BruteProjection¶

BruteProjection(std::array<size_t, 3> npix, std::array<Float, 6> extent)¶

Parameters:

npix – {nx, ny, nz} – grid resolution. Rays are cast along the z-axis; the output has nx * ny pixels.
extent – {xmin, xmax, ymin, ymax, zmin, zmax}.

void makeProjection(const PointCloud &cloud, ReductionMode reduction = ReductionMode::Sum)¶: Trace rays and reduce.

void saveProjection(const std::string savename) const¶: Write the projection to a binary file.

const std::vector<Float> &getProjectionData() const¶: Flat result array of size nx * ny * nfields.

size_t getNfields() const¶

std::array<size_t, 3> getNpix() const¶

Slice¶

Defined in slice.hpp. Extracts a 2D slice at a constant depth.

class Slice¶

Slice(std::array<size_t, 2> npix, std::array<Float, 4> extent, Float depth)¶

Parameters:

npix – {nx, ny} – output resolution.
extent – {xmin, xmax, ymin, ymax}.
depth – z-coordinate of the slice plane.

void makeSlice(const PointCloud &cloud)¶: Compute the slice.

void saveSlice(const std::string savename) const¶: Write the slice to a binary file.

const std::vector<Float> &getSliceData() const¶: Flat result array of size nx * ny * nfields.

size_t getNfields() const¶

std::array<size_t, 2> getNpix() const¶

Reduction functions¶

Defined in reduction.hpp. Standalone functions that operate on walked ray segments. These are used internally by Ray::integrate and Projection::makeProjection.

std::vector<Float> reduce_sum(const std::vector<Ray::Segment> &segments, const PointCloud &cloud)¶

std::vector<Float> reduce_max(const std::vector<Ray::Segment> &segments, const PointCloud &cloud)¶

std::vector<Float> reduce_min(const std::vector<Ray::Segment> &segments, const PointCloud &cloud)¶

std::vector<Float> reduce_volume_render(const std::vector<Ray::Segment> &segments, const PointCloud &cloud)¶: Requires 4 fields (R, G, B, alpha). Returns a vector of length 3 (RGB).

std::vector<Float> reduce(const std::vector<Ray::Segment> &segments, const PointCloud &cloud, ReductionMode mode)¶: Dispatch to the appropriate reduction function.

size_t reduce_output_size(ReductionMode mode, size_t cloud_nfields)¶: Number of output values for a given mode and field count.