warp.Volume

class warp.Volume(*args, **kwargs)

Sparse volumetric data structure based on NanoVDB for efficient 3D sampling.

Class representing a sparse grid.

Parameters:

• data – Array of bytes representing the volume in NanoVDB format.

• copy – Whether the incoming data will be copied or aliased.

Methods

allocate(min, max, voxel_size[, bg_value, ...])	Allocate a new Volume based on the bounding box defined by min and max.
allocate_by_tiles(tile_points[, voxel_size, ...])	Allocate a new Volume with active tiles for each point tile_points.
allocate_by_voxels(voxel_points[, ...])	Allocate a new Volume with an active voxel for each point in voxel_points.
array()	Return the raw memory buffer of the Volume as an array.
feature_array(feature_index[, dtype])	Return one the grid's feature data arrays as a Warp array.
get_active_stats()	Return actual topology statistics from the current grid metadata.
get_feature_array_count()	Return the number of supplemental data arrays stored alongside the grid
get_feature_array_info(feature_index)	Return the metadata associated to the feature array at feature_index.
get_grid_info()	Return the metadata associated with this Volume.
get_rebuild_info()	Return rebuild input kind and reserved capacity metadata.
get_tile_count()	Return the number of tiles (NanoVDB leaf nodes) of the volume.
get_tiles([out])	Return the integer coordinates of all allocated tiles for this volume.
get_voxel_count()	Return the total number of allocated voxels for this volume
get_voxel_size()	Return the voxel size, i.e, world coordinates of voxel's diagonal vector
get_voxels([out])	Return the integer coordinates of all allocated voxels for this volume.
load_from_address(grid_ptr[, buffer_size, ...])	Create a new Volume aliasing an in-memory grid buffer.
load_from_numpy(ndarray[, min_world, ...])	Create a Volume object from a dense 3D NumPy array.
load_from_nvdb(file_or_buffer[, device])	Create a Volume object from a serialized NanoVDB file or in-memory buffer.
load_next_grid()	Create a new Volume for the next grid that is linked to by this Volume.
rebuild(points[, status, point_mask])	Rebuild this volume's topology in place from points.
save_to_nvdb(path[, codec])	Serialize the Volume into a NanoVDB (.nvdb) file.

Attributes

CLOSEST	Enum value to specify nearest-neighbor interpolation during sampling
LINEAR	Enum value to specify trilinear interpolation during sampling
REBUILD_INVALID_INPUT	Rebuild was called with invalid arguments or on a non-rebuildable volume.
REBUILD_LEAF_CAPACITY_EXCEEDED	Rebuild produced more leaf nodes than the volume capacity.
REBUILD_LOWER_CAPACITY_EXCEEDED	Rebuild produced more lower internal nodes than the volume capacity.
REBUILD_SUCCESS	Rebuild completed without setting a status flag.
REBUILD_UPPER_CAPACITY_EXCEEDED	Rebuild produced more upper internal nodes than the volume capacity.
REBUILD_VOXEL_CAPACITY_EXCEEDED	Rebuild produced more active voxels than the volume capacity.
dtype	Type of the Volume's values as a Warp type.
is_index	Whether this Volume contains an index grid, that is, a type of grid that does not explicitly store values but associates each voxel to linearized index.
is_rebuildable	Whether this volume was allocated with persistent capacity for rebuild().

CLOSEST = 0

Enum value to specify nearest-neighbor interpolation during sampling

LINEAR = 1

Enum value to specify trilinear interpolation during sampling

class RebuildInfo(

kind,

max_voxel_count,

max_leaf_node_count,

max_lower_node_count,

max_upper_node_count,

)

Capacity metadata for a Volume allocated with rebuild support.

The counts describe reserved storage, not the currently active topology. Use Volume.get_active_stats() to query the current grid metadata.

Create new instance of RebuildInfo(kind, max_voxel_count, max_leaf_node_count, max_lower_node_count, max_upper_node_count)

Parameters:

• kind (str | None)

• max_voxel_count (int)

• max_leaf_node_count (int)

• max_lower_node_count (int)

• max_upper_node_count (int)

kind: str | None

Input kind used for rebuilds. One of "tiles", "voxels", or None when the volume is not rebuildable.

max_voxel_count: int

Maximum active voxel or index count reserved for rebuilds.

max_leaf_node_count: int

Maximum NanoVDB leaf node count reserved for rebuilds.

max_lower_node_count: int

Maximum NanoVDB lower internal node count reserved for rebuilds.

max_upper_node_count: int

Maximum NanoVDB upper internal node count reserved for rebuilds.

class ActiveStats(

voxel_count,

leaf_node_count,

lower_node_count,

upper_node_count,

)

Active topology statistics from the current Volume grid metadata.

Create new instance of ActiveStats(voxel_count, leaf_node_count, lower_node_count, upper_node_count)

Parameters:

• voxel_count (int)

• leaf_node_count (int)

• lower_node_count (int)

• upper_node_count (int)

voxel_count: int

Current active voxel or index count.

leaf_node_count: int

Current NanoVDB leaf node count.

lower_node_count: int

Current NanoVDB lower internal node count.

upper_node_count: int

Current NanoVDB upper internal node count.

array()

Return the raw memory buffer of the Volume as an array.

Return type:

array

get_tile_count()

Return the number of tiles (NanoVDB leaf nodes) of the volume.

Return type:

int

get_tiles(out=None)

Return the integer coordinates of all allocated tiles for this volume.

Parameters:

out (array | None) – If provided, use the out array to store the tile coordinates, otherwise a new array will be allocated. out must be a contiguous array of tile_count vec3i or tile_count x 3 int32 on the same device as this volume.

Return type:

array

get_voxel_count()

Return the total number of allocated voxels for this volume

Return type:

int

get_active_stats()

Return actual topology statistics from the current grid metadata.

For rebuildable volumes, this reports the current active topology rather than the reserved capacity returned by get_rebuild_info(). For non-rebuildable volumes, these counts match the allocated grid topology.

Returns:

A Volume.ActiveStats tuple containing the active voxel, leaf, lower, and upper node counts.

Return type:

ActiveStats

get_voxels(out=None)

Return the integer coordinates of all allocated voxels for this volume.

Parameters:

out (array | None) – If provided, use the out array to store the voxel coordinates, otherwise a new array will be allocated. out must be a contiguous array of voxel_count vec3i or voxel_count x 3 int32 on the same device as this volume.

Return type:

array

get_voxel_size()

Return the voxel size, i.e, world coordinates of voxel’s diagonal vector

Return type:

tuple[float, float, float]

class GridInfo(

name,

size_in_bytes,

grid_index,

grid_count,

type_str,

translation,

transform_matrix,

)

Grid metadata

Create new instance of GridInfo(name, size_in_bytes, grid_index, grid_count, type_str, translation, transform_matrix)

Parameters:

• name (str)

• size_in_bytes (int)

• grid_index (int)

• grid_count (int)

• type_str (str)

• translation (vec3f)

• transform_matrix (mat33f)

name: str

Grid name

size_in_bytes: int

Size of this grid’s data, in bytes

grid_index: int

Index of this grid in the data buffer

grid_count: int

Total number of grids in the data buffer

type_str: str

String describing the type of the grid values

translation: vec3f

Index-to-world translation

transform_matrix: mat33f

Linear part of the index-to-world transform

get_grid_info()

Return the metadata associated with this Volume.

Return type:

GridInfo

property dtype: type

Type of the Volume’s values as a Warp type.

If the grid does not contain values (e.g. index grids) or if the NanoVDB type is not representable as a Warp type, returns None.

property is_index: bool

Whether this Volume contains an index grid, that is, a type of grid that does not explicitly store values but associates each voxel to linearized index.

property is_rebuildable: bool

Whether this volume was allocated with persistent capacity for rebuild().

get_rebuild_info()

Return rebuild input kind and reserved capacity metadata.

Returns:

A Volume.RebuildInfo tuple. kind is "tiles" for volumes created by allocate_by_tiles(), "voxels" for volumes created by allocate_by_voxels(), and None for volumes that cannot be rebuilt. Capacity fields are zero when kind is None.

Return type:

RebuildInfo

get_feature_array_count()

Return the number of supplemental data arrays stored alongside the grid

Return type:

int

class FeatureArrayInfo(name, ptr, value_size, value_count, type_str)

Metadata for a supplemental data array

Create new instance of FeatureArrayInfo(name, ptr, value_size, value_count, type_str)

Parameters:

• name (str)

• ptr (int)

• value_size (int)

• value_count (int)

• type_str (str)

name: str

Name of the data array

ptr: int

Memory address of the start of the array

value_size: int

Size in bytes of the array values

value_count: int

Number of values in the array

type_str: str

String describing the type of the array values

get_feature_array_info(feature_index)

Return the metadata associated to the feature array at feature_index.

Parameters:

feature_index (int)

Return type:

FeatureArrayInfo

feature_array(feature_index, dtype=None)

Return one the grid’s feature data arrays as a Warp array.

Parameters:

• feature_index (int) – Index of the supplemental data array in the grid

• dtype – Data type for the returned Warp array. If not provided, will be deduced from the array metadata.

Return type:

array

classmethod load_from_nvdb(file_or_buffer, device=None)

Create a Volume object from a serialized NanoVDB file or in-memory buffer.

Returns:

A Volume object.

Return type:

Volume

save_to_nvdb(path, codec='none')

Serialize the Volume into a NanoVDB (.nvdb) file.

Parameters:

• path – File path where the .nvdb file will be saved.

• codec (Literal['none', 'zip', 'blosc']) –

  Compression codec to use. Defaults to "none". Available options:

  • "none" - No compression

  • "zip" - ZIP compression

  • "blosc" - BLOSC compression (requires blosc package)

classmethod load_from_address(grid_ptr, buffer_size=0, device=None)

Create a new Volume aliasing an in-memory grid buffer.

In contrast to load_from_nvdb() which should be used to load serialized NanoVDB grids, here the buffer must be uncompressed and must not contain file header information. If the passed address does not contain a NanoVDB grid, the behavior of this function is undefined.

Parameters:

• grid_ptr (int) – Integer address of the start of the grid buffer.

• buffer_size (int) – Size of the buffer, in bytes. If not provided, the size will be assumed to be that of the single grid starting at grid_ptr.

• device – Device of the buffer and of the returned Volume. If not provided, the current Warp device is assumed.

Returns:

The newly created Volume.

Raises:

• RuntimeError – If grid_ptr is invalid (null pointer).

• RuntimeError – If a Warp Volume has already been created for this grid address.

Return type:

Volume

load_next_grid()

Create a new Volume for the next grid that is linked to by this Volume.

The existence of a next grid is determined by checking if there are more grids in the sequence (based on grid_index and grid_count metadata) and if there is sufficient buffer space remaining in this Volume’s in-memory buffer.

Returns:

The newly created Volume, or None if there is no next grid.

Return type:

Volume | None

classmethod load_from_numpy(

ndarray,

min_world=(0.0, 0.0, 0.0),

voxel_size=1.0,

bg_value=0.0,

device=None,

)

Create a Volume object from a dense 3D NumPy array.

This function is only supported for CUDA devices.

Parameters:

• min_world – The 3D coordinate of the lower corner of the volume.

• voxel_size (int | float | list[float] | tuple[float, float, float]) – The size of each voxel in spatial coordinates. Can be a scalar for isotropic voxels or a 3-element sequence (sx, sy, sz) for anisotropic voxels.

• bg_value – Background value

• device (Device | str | None) – The CUDA device to create the volume on, e.g.: "cuda" or "cuda:0".

• ndarray (ndarray)

Returns:

A warp.Volume object.

Return type:

Volume

classmethod allocate(

min,

max,

voxel_size,

bg_value=0.0,

translation=(0.0, 0.0, 0.0),

points_in_world_space=False,

device=None,

)

Allocate a new Volume based on the bounding box defined by min and max.

This function is only supported for CUDA devices.

Allocate a volume that is large enough to contain voxels [min[0], min[1], min[2]] - [max[0], max[1], max[2]], inclusive. If points_in_world_space is true, then min and max are first converted to index space using the given voxel size (per-axis for anisotropic volumes) and translation, and the volume is allocated with those.

The smallest unit of allocation is a dense tile of 8x8x8 voxels, the requested bounding box is rounded up to tiles, and the resulting tiles will be available in the new volume.

Parameters:

• min (list[int]) – Lower 3D coordinates of the bounding box in index space or world space, inclusive.

• max (list[int]) – Upper 3D coordinates of the bounding box in index space or world space, inclusive.

• voxel_size (int | float | list[float] | tuple[float, float, float]) – Voxel size(s) of the new volume. Can be a scalar for isotropic voxels or a 3-element sequence (sx, sy, sz) for anisotropic voxels.

• bg_value – Value of unallocated voxels of the volume, also defines the volume’s type, a warp.vec3 volume is created if this is array-like, otherwise a float volume is created

• translation – Translation between the index and world spaces.

• device (Device | str | None) – The CUDA device to create the volume on, e.g.: "cuda" or "cuda:0".

Return type:

Volume

REBUILD_SUCCESS: ClassVar[int] = 0

Rebuild completed without setting a status flag.

REBUILD_LEAF_CAPACITY_EXCEEDED: ClassVar[int] = 1

Rebuild produced more leaf nodes than the volume capacity.

REBUILD_LOWER_CAPACITY_EXCEEDED: ClassVar[int] = 2

Rebuild produced more lower internal nodes than the volume capacity.

REBUILD_UPPER_CAPACITY_EXCEEDED: ClassVar[int] = 4

Rebuild produced more upper internal nodes than the volume capacity.

REBUILD_VOXEL_CAPACITY_EXCEEDED: ClassVar[int] = 8

Rebuild produced more active voxels than the volume capacity.

REBUILD_INVALID_INPUT: ClassVar[int] = 16

Rebuild was called with invalid arguments or on a non-rebuildable volume.

classmethod allocate_by_tiles(

tile_points,

voxel_size=None,

bg_value=0.0,

translation=(0.0, 0.0, 0.0),

device=None,

transform=None,

rebuildable=False,

max_tiles=None,

max_lower_nodes=None,

max_upper_nodes=None,

status=None,

point_mask=None,

)

Allocate a new Volume with active tiles for each point tile_points.

This function is supported on CPU and CUDA devices.

The smallest unit of allocation is a dense tile of 8x8x8 voxels. This is the primary method for allocating sparse volumes. It uses an array of points indicating the tiles that must be allocated.

Example use cases:

• tile_points can mark tiles directly in index space as in the case this method is called by allocate().

• tile_points can be a list of points used in a simulation that needs to transfer data to a volume.

If rebuildable is True or any rebuild capacity argument is supplied, the returned volume reserves persistent storage and can be updated in place with rebuild(). The rebuild input kind is "tiles", so later rebuilds must provide tile points rather than voxel points. Use get_rebuild_info() to inspect reserved capacities and get_active_stats() to inspect the current active topology.

Rebuildable CUDA volumes can be allocated during CUDA graph capture when CUDA memory-pool allocation is supported and enabled. Exact, non-rebuildable volume allocation is not graph-capture safe because determining the exact topology size requires device synchronization. Active-topology queries such as get_active_stats() must also be performed outside graph capture.

Parameters:

• tile_points (warp.array) – Array of positions that define the tiles to be allocated. The array may use an integer scalar type (2D N-by-3 array of warp.int32 or 1D array of warp.vec3i values), indicating index space positions, or a floating point scalar type (2D N-by-3 array of warp.float32 or 1D array of warp.vec3f values), indicating world space positions. Repeated points per tile are allowed and will be efficiently deduplicated.

• voxel_size (int | float | list[float] | tuple[float, float, float] | None) – Voxel size(s) of the new volume. Ignored if transform is given.

• bg_value – Value of unallocated voxels of the volume, also defines the volume’s type. An index volume will be created if bg_value is None. Other supported grid types are int, float, vec3f, and vec4f.

• translation – Translation between the index and world spaces.

• transform – Linear transform between the index and world spaces. If None, deduced from voxel_size.

• rebuildable (bool) – Whether to allocate persistent capacity for rebuilds.

• max_tiles (int | None) – Maximum number of NanoVDB leaf nodes reserved for rebuilds. Supplying this makes the volume rebuildable. Each tile can contain up to 512 voxels.

• max_lower_nodes (int | None) – Maximum number of lower internal nodes reserved for rebuilds. Supplying this makes the volume rebuildable.

• max_upper_nodes (int | None) – Maximum number of upper internal nodes reserved for rebuilds. Supplying this makes the volume rebuildable.

• status (array | None) – Optional one-element uint32 array receiving Volume.REBUILD_* status flags from the initial build. Volume.REBUILD_SUCCESS means the requested topology fit in the reserved capacity.

• point_mask (array | None) – Optional int32 array with one entry per point. Points with a zero mask value are ignored.

• device (Device | str | None) – The device to create the volume on, e.g. "cpu", "cuda", or "cuda:0".

Raises:

• RuntimeError – If tile_points, point_mask, or status is not a contiguous array of the required type and shape.

• RuntimeError – If Volume creation fails.

• ValueError – If neither voxel_size nor transform is provided.

• ValueError – If both voxel_size and transform are provided.

• ValueError – If a rebuild capacity is not positive or does not fit in uint32.

Return type:

Volume

classmethod allocate_by_voxels(

voxel_points,

voxel_size=None,

translation=(0.0, 0.0, 0.0),

device=None,

transform=None,

rebuildable=False,

max_active_voxels=None,

max_leaf_nodes=None,

max_lower_nodes=None,

max_upper_nodes=None,

status=None,

point_mask=None,

)

Allocate a new Volume with an active voxel for each point in voxel_points.

This function creates an index volume, a special kind of volume that does not store any explicit payload but encodes a linearized index for each active voxel, allowing to lookup and sample data from arbitrary external arrays.

If rebuildable is True or any rebuild capacity argument is supplied, the returned volume reserves persistent storage and can be updated in place with rebuild(). The rebuild input kind is "voxels", so later rebuilds must provide voxel points rather than tile points. Use get_rebuild_info() to inspect reserved capacities and get_active_stats() to inspect the current active topology.

Rebuildable CUDA volumes can be allocated during CUDA graph capture when CUDA memory-pool allocation is supported and enabled. Exact, non-rebuildable volume allocation is not graph-capture safe because determining the exact topology size requires device synchronization. Active-topology queries such as get_active_stats() must also be performed outside graph capture.

Unspecified node capacities use conservative sparse-grid defaults. In particular, max_leaf_nodes defaults to max_active_voxels because arbitrary voxel points can place one active voxel in each leaf node. For dense voxel sets, pass tighter node capacities explicitly to reduce memory use. Non-index volumes are allocated and rebuilt by tiles with allocate_by_tiles(), where max_tiles directly controls leaf capacity.

Parameters:

• voxel_points (warp.array) – Array of positions that define the voxels to be allocated. The array may use an integer scalar type (2D N-by-3 array of warp.int32 or 1D array of warp.vec3i values), indicating index space positions, or a floating point scalar type (2D N-by-3 array of warp.float32 or 1D array of warp.vec3f values), indicating world space positions. Repeated points per voxel are allowed and will be efficiently deduplicated.

• voxel_size (int | float | list[float] | tuple[float, float, float] | None) – Voxel size(s) of the new volume. Ignored if transform is given.

• translation – Translation between the index and world spaces.

• transform – Linear transform between the index and world spaces. If None, deduced from voxel_size.

• rebuildable (bool) – Whether to allocate persistent capacity for rebuilds.

• max_active_voxels (int | None) – Maximum number of active voxels reserved for rebuilds. Supplying this makes the volume rebuildable.

• max_leaf_nodes (int | None) – Maximum number of NanoVDB leaf nodes reserved for rebuilds. Supplying this makes the volume rebuildable.

• max_lower_nodes (int | None) – Maximum number of lower internal nodes reserved for rebuilds. Supplying this makes the volume rebuildable.

• max_upper_nodes (int | None) – Maximum number of upper internal nodes reserved for rebuilds. Supplying this makes the volume rebuildable.

• status (array | None) – Optional one-element uint32 array receiving Volume.REBUILD_* status flags from the initial build. Volume.REBUILD_SUCCESS means the requested topology fit in the reserved capacity.

• point_mask (array | None) – Optional int32 array with one entry per point. Points with a zero mask value are ignored.

• device (Device | str | None) – The device to create the volume on, e.g. "cpu", "cuda", or "cuda:0".

Raises:

• RuntimeError – If voxel_points, point_mask, or status is not a contiguous array of the required type and shape.

• RuntimeError – If Volume creation fails.

• ValueError – If neither voxel_size nor transform is provided.

• ValueError – If both voxel_size and transform are provided.

• ValueError – If a rebuild capacity is not positive or does not fit in uint32.

Return type:

Volume

rebuild(points, status=None, point_mask=None)

Rebuild this volume’s topology in place from points.

The volume must have been created with rebuildable=True or explicit capacity arguments. The input kind must match the allocation method: volumes created by allocate_by_tiles() rebuild from tile points, and volumes created by allocate_by_voxels() rebuild from voxel points.

Rebuilds preserve the volume’s transform, background value, grid type, and reserved capacity. Capacity does not grow automatically; pass status to detect whether the requested topology fit in the reserved storage.

Parameters:

• points (array) – Contiguous array of tile or voxel positions. The array may be a 1D array of vec3i or vec3f values, or a 2D N x 3 array of int32 or float32 values. Integer points are interpreted in index space, and floating-point points are interpreted in world space.

• status (array | None) – Optional one-element uint32 array receiving Volume.REBUILD_* status flags. Volume.REBUILD_SUCCESS means the requested topology fit in the reserved capacity.

• point_mask (array | None) – Optional int32 array with one entry per point. Points with a zero mask value are ignored.

Returns:

The status array if one was provided, otherwise None.

Raises:

• RuntimeError – If the volume is not rebuildable.

• RuntimeError – If points, point_mask, or status is not a contiguous array of the required type and shape.

Return type:

array | None