Python API

Main interface

class vortrace.ProjectionCloud(pos, fields, boundbox=None, vol=None, *, periodic=False, _skip_build_tree=False)

Main interface for projections through an unstructured Voronoi mesh.

Wraps the C++ Cvortrace backend to provide grid-based projections, arbitrary ray projections, and single-ray segment queries. Supports multiple fields and reduction modes (sum/integrate, max, min, volume).

grid_projection(extent, nres, bounds, center, *, proj=None, yaw=0.0, pitch=0.0, roll=0.0, reduction='integrate')

Make a grid projection through the point cloud.

Parameters:

• extent – Spatial extent [min, max] or [[xmin,xmax], [ymin,ymax]].

• nres – Number of pixels (int for square, or (nx, ny)).

• bounds – Integration bounds [z_start, z_end].

• center – Rotation center (x, y, z) or None.

• proj – Cartesian projection string (e.g. 'xy').

• yaw – Yaw angle in radians.

• pitch – Pitch angle in radians.

• roll – Roll angle in radians.

• reduction – 'integrate'/'sum', 'max', 'min', or 'volume'. Volume rendering requires exactly 4 fields (R, G, B, alpha) and returns 3 output channels (RGB).

Returns:

Shape (nres, nres) for single field,

(nres, nres, nfields) for multi-field, or (nres, nres, 3) for volume rendering.

Return type:

ndarray

projection(pos_start, pos_end, *, reduction='integrate')

Make a projection through the point cloud.

Parameters:

• pos_start (array of float) – Starting points of the projection.

• pos_end (array of float) – Ending points of the projection.

• reduction (str) – Reduction mode: ‘integrate’/’sum’, ‘max’, ‘min’, or ‘volume’. Volume rendering requires 4 fields (R, G, B, alpha) and returns 3 channels (RGB).

Returns:

The projection data. Shape (N,) when

a single field was loaded, (N, nfields) otherwise.

Return type:

dat (array of float)

traced_projection(pos_start, pos_end, return_midpoint=True, *, reduction='integrate', flatten=False)

Projection with per-segment detail for one or more rays.

Accepts a single ray (shape (3,) or (1, 3)) or a batch of rays (shape (N, 3)).

Parameters:

• pos_start – Ray start point(s). Shape (3,), (1, 3), or (N, 3).

• pos_end – Ray end point(s), same shape as pos_start.

• return_midpoint – If True, return the midpoint of each segment; otherwise return the entry distance.

• reduction – 'integrate'/'sum', 'max', 'min', or 'volume'.

• flatten – If True, return flat arrays with an offset index instead of per-ray lists. Only applies to batch (N > 1) inputs.

Returns:

(value, cell_ids, s_vals, ds_vals)

• value: scalar when nfields == 1, else 1-D array.

• cell_ids, s_vals, ds_vals: 1-D arrays.

For a batch with flatten=False (default):

(values, cell_ids_list, s_vals_list, ds_vals_list)

• values: shape (N,) or (N, nfields).

• cell_ids_list, s_vals_list, ds_vals_list: lists of N arrays, one per ray.

For a batch with flatten=True:

(values, cell_ids, s_vals, ds_vals, offsets)

• Flat concatenated arrays for all segments plus an offsets array of length N + 1. Ray i’s data is at offsets[i]:offsets[i+1].

Return type:

For a single ray (input shape (3,) or (1, 3))

single_projection(*args, **kwargs)

Removed. Use traced_projection() instead.

slice(extent, nres, depth)

Extract a 2D slice at constant depth through the point cloud.

Unlike a projection (which integrates along the line of sight), a slice returns the nearest-cell field value at each pixel position.

Parameters:

• extent – Spatial extent [xmin, xmax, ymin, ymax].

• nres – Number of pixels (int for square, or (nx, ny)).

• depth – The z-coordinate of the slicing plane.

Returns:

Shape (nx, ny) for single field,

(nx, ny, nfields) for multi-field.

Return type:

ndarray

save_tree_bytes()

Serialize the kD-tree to bytes, or None if not built.

load_tree_bytes(data)

Restore the kD-tree from a bytes object.

save(filename, *, fmt='npz', save_tree=True)

Save this cloud to disk.

See vortrace.io.save_cloud() for details.

classmethod load(filename)

Load a cloud from disk.

See vortrace.io.load_cloud() for details.

Verbose control

vortrace.set_verbose(verbose: bool) → None

Enable or disable verbose C++ status messages to stdout.

vortrace.get_verbose() → bool

Return the current verbose setting.

I/O

Save and load projection grids and point clouds.

Supports two formats: - npz (default) – zero extra dependencies, fast. - hdf5 – requires h5py; natural for astronomy workflows.

The format is chosen via the fmt parameter on save, and auto-detected from the file extension on load.

vortrace.io.save_grid(filename, data, *, extent=None, metadata=None, fmt='npz')

Save a 2-D projection array to disk.

Parameters:

• filename (str or path-like) – Destination path.

• data (array_like) – 2-D projection grid.

• extent (array_like, optional) – Spatial extent, e.g. [xmin, xmax, ymin, ymax].

• metadata (dict, optional) – Arbitrary metadata stored alongside the grid.

• fmt ({'npz', 'hdf5'}) – File format.

vortrace.io.load_grid(filename)

Load a projection grid saved by save_grid().

The format is auto-detected from the file extension.

Parameters:

filename (str or path-like) – Path to a .npz or .hdf5 / .h5 file.

Returns:

• data (np.ndarray) – The 2-D projection array.

• metadata (dict) – Metadata dictionary (empty if none was stored).

vortrace.io.save_cloud(filename, cloud, *, fmt='npz', save_tree=True)

Save a ProjectionCloud to disk.

Positions, fields, bounding box, and (optionally) the kD-tree index are stored. When the tree is included, load_cloud() restores it without rebuilding.

Parameters:

• filename (str or path-like) – Destination path.

• cloud (ProjectionCloud) – The cloud to save.

• fmt ({'npz', 'hdf5'}) – File format.

• save_tree (bool, optional) – If True (default) and the kD-tree has been built, serialize the tree index into the file so it can be restored on load.

vortrace.io.load_cloud(filename)

Load a ProjectionCloud saved by save_cloud().

If a kD-tree index was saved, it is restored directly; otherwise the tree is rebuilt from scratch.

Parameters:

filename (str or path-like) – Path to a .npz or .hdf5 / .h5 file.

Returns:

A fully usable cloud with a ready kD-tree.

Return type:

ProjectionCloud

Grid utilities

Grid generation utilities for vortrace projections.

Provides routines for building start/end point grids used by grid_projection, including Tait-Bryan rotation support and numpy-vectorized grid construction.

vortrace.grid.generate_base_grid(extent, nres)

Generates a 2D primitive grid.

Generates a 2D primitive grid spanning a given extent with a certain number of resolution elements. The grid is 2D but the output is given as a 3D array with the z-values of all grid points set to zero.

Parameters:

• extent (array of float) – A (2,2) or (2,) array specifying the extent of the base grid. If a (2,) array is given, assumes the same extent in both directions.

• nres (int or array of int) – Number of resolution elements. Either an int or a (2,) array of ints, specifying in each direction.

Returns:

A (N,3) array of grid points, where N is the

total number of resolution elements in the grid.

Return type:

grid (array of float)

vortrace.grid.generate_projection_grid(extent, nres, bounds, center, *, proj=None, yaw=0.0, pitch=0.0, roll=0.0)

Generates a projection grid.

This generates a projection grid which can be arbitrarily rotated about a center. A grid_start and grid_end grids are returned, which give the starting and ending integration positions to be integrated.

The grid is constructed by first laying down a grid in the x-y plane spanning extent with nres elements. We then construct grid_start and grid_end by assigning the z-coordinates of the base grid either bounds[0] or bounds[1], respectively. Both grids are then optionally rotated about the point center.

You can use grid_start and grid_end as starting and ending positions for projection integrations.

The Euler angle convention used here is that given by the ‘x-z-x’ convention, described here: https://mathworld.wolfram.com/EulerAngles.html

Parameters:

• extent (array of float) – A (2,2) or (2,) array specifying the extent of the base grid. If a (2,) array is given, assumes the same extent in both directions.

• nres (int or array of int) – Number of resolution elements. Either an int or a (2,) array of ints, specifying in each direction.

• bounds (array of float) – A (2,) array indicating the start and end bounds for the integration. The integration will start at bounds[0] and end at bounds[1] along the z-axis before any rotation.

• center (array of float or None) – A (3,) array indicating the center about which the Euler rotations should be performed. If center is set to None, no rotation is done and the projection is by default ‘xy’.

• proj (string) – A two letter string indicating the desired Cartesian projection

• yaw (float, optional) – Yaw angle, describing the rotation about the original z-axis

• pitch (float, optional) – Pitch angle, describing the rotation about the new xprime-axis.

• roll (float, optional) – Roll angle, describing the rotation about the new zprime-axis.

Returns:

A (N0,N1,3) array of grid points, where N0

and N1 are nres[0] and nres[1], respectively (or nres if nres is an int). Starting points for integration specified by bounds.

grid_end (array of float): A (N0,N1,3) array of grid poitns, where N0

and N1 are nres[0] and nres[1], respectively (or nres if nres is an int). Ending points for integration specified by bounds.

Return type:

grid_start (array of float)

Plotting

Quick plotting helpers for vortrace projections.

matplotlib is imported lazily inside each function, so import vortrace.plot succeeds even without matplotlib installed.

vortrace.plot.plot_grid(data, *, extent=None, ax=None, log=True, cmap='inferno', colorbar=True, label=None, **imshow_kwargs)

Display a 2-D projection grid as an image.

Parameters:

• data (array_like) – 2-D projection array (will be transposed for display so that the first axis corresponds to x and the second to y).

• extent (array_like, optional) – [xmin, xmax, ymin, ymax] passed to imshow.

• ax (matplotlib Axes, optional) – Axes to plot into. A new figure is created if None.

• log (bool) – If True (default), use LogNorm.

• cmap (str) – Colormap name (default "inferno").

• colorbar (bool) – Whether to add a colorbar.

• label (str, optional) – Colorbar label.

• **imshow_kwargs – Extra keyword arguments forwarded to ax.imshow.

Returns:

• fig (matplotlib Figure)

• ax (matplotlib Axes)

• im (matplotlib AxesImage)

vortrace.plot.plot_ray(s_vals, dens, *, ax=None, log=True, **plot_kwargs)

Plot a 1-D ray density profile.

Parameters:

• s_vals (array_like) – Position along the ray.

• dens (array_like) – Density values at each position.

• ax (matplotlib Axes, optional) – Axes to plot into. A new figure is created if None.

• log (bool) – If True (default), use a log scale for the y-axis.

• **plot_kwargs – Extra keyword arguments forwarded to ax.plot.

Returns:

• fig (matplotlib Figure)

• ax (matplotlib Axes)