warp.Volume

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

__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()	Returns 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()

Returns 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 – The size of each voxel in spatial coordinates.

• bg_value – Background value

• device – 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 with the given voxel size 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 (array-like) – Lower 3D coordinates of the bounding box in index space or world space, inclusive.

• max (array-like) – Upper 3D coordinates of the bounding box in index space or world space, inclusive.

• voxel_size (float) – Voxel size of the new volume.

• bg_value (float or array-like) – 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 (array-like) – 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 (float or array-like) – Voxel size(s) of the new volume. Ignored if transform is given.

• bg_value (array-like, scalar or None) – 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 (array-like) – Translation between the index and world spaces.

• transform (array-like) – 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 (float or array-like) – Voxel size(s) of the new volume. Ignored if transform is given.

• translation (array-like) – Translation between the index and world spaces.

• transform (array-like) – 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