warp.Volume

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

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

__init__(data, copy=True)

Class representing a sparse grid.

Parameters:

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

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

Methods

__init__(data[, copy])	Class representing a sparse grid.
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 active voxel for each point 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_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_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.
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
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.

CLOSEST = 0

Enum value to specify nearest-neighbor interpolation during sampling

LINEAR = 1

Enum value to specify trilinear interpolation during sampling

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_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

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.

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

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

classmethod allocate_by_tiles(

tile_points,

voxel_size=None,

bg_value=0.0,

translation=(0.0, 0.0, 0.0),

device=None,

transform=None,

)

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

This function is only supported for 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.

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.

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

Return type:

Volume

classmethod allocate_by_voxels(

voxel_points,

voxel_size=None,

translation=(0.0, 0.0, 0.0),

device=None,

transform=None,

)

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

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

This function is only supported for CUDA devices.

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 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.

• translation – Translation between the index and world spaces.

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

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

Raises:

• RuntimeError – If the device is not a CUDA device.

• RuntimeError – If voxel_points is not a contiguous array of the correct 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.

Return type:

Volume