Sparse Grids

class fvdb.Grid(*, data: fvdb._fvdb_cpp.GridBatchData)[source]

A single sparse voxel grid backed by a C++ GridBatchData with grid_count == 1.

Grid represents a single sparse 3D voxel grid that can be processed efficiently on GPU. The class provides methods for common operations like sampling, convolution, pooling, dilation, union, etc. It also provides more advanced features such as marching cubes, TSDF fusion, and fast ray marching.

A Grid does not store voxel data itself, but rather the structure (or topology) of the sparse voxel grid. Voxel data (e.g., features, colors, densities) are stored separately as torch.Tensor associated with the grid. This separation allows for flexibility in the type and number of channels of data with which a grid can be used to index into.

When using a Grid, there are three important coordinate systems:

World Space: The continuous 3D coordinate system in which the grid exists.
Voxel Space: The discrete voxel index system, where each voxel is identified by its integer indices (i, j, k).
Index Space: The linear indexing of active voxels in the grid’s internal storage.

Note

The grid is stored in a sparse format using NanoVDB where only active (non-empty) voxels are allocated, making it extremely memory efficient for representing large volumes with sparse occupancy.

Note

The Grid constructor is for internal use only. To create a Grid with actual content, use the classmethods:

from_ijk(): from explicit voxel coordinates
from_points(): from point clouds
from_mesh(): from triangle meshes
from_dense(): from dense data
from_dense_axis_aligned_bounds(): from dense data defined by axis-aligned bounds
from_nearest_voxels_to_points(): from nearest voxels to points
from_zero_voxels(): for a grid with zero voxels

Apply average pooling to voxel data.

Note

Supports backpropagation.

Parameters:

pool_factor (NumericMaxRank1) – Downsample factor, broadcastable to shape (3,), integer dtype.
data (torch.Tensor) – Voxel data of shape (num_voxels, channels).
stride (NumericMaxRank1) – Pooling stride. If 0, equals pool_factor.
coarse_grid (Grid | None) – Pre-allocated coarse Grid. If None, a new one is created.

Returns:

pooled_data (torch.Tensor) – Pooled data of shape (coarse_num_voxels, channels).
coarse_grid (Grid) – Coarse Grid after pooling.

property bbox: Tensor

The voxel-space bounding box of this Grid.

Returns:: bbox (torch.Tensor) – Shape (2, 3) with [[min_i, min_j, min_k], [max_i, max_j, max_k]]. Returns a zero tensor if the grid has zero voxels.

Clip this Grid and its features to the region [ijk_min, ijk_max].

Parameters:

features (torch.Tensor) – Voxel features of shape (num_voxels, channels*).
ijk_min (NumericMaxRank1) – Minimum voxel bounds.
ijk_max (NumericMaxRank1) – Maximum voxel bounds.

Returns:

clipped_features (torch.Tensor) – Clipped features.
clipped_grid (Grid) – A new Grid with only voxels in bounds.

Return a Grid clipped to the region [ijk_min, ijk_max].

Parameters:

ijk_min (NumericMaxRank1) – Minimum voxel bounds, broadcastable to shape (3,), integer dtype.
ijk_max (NumericMaxRank1) – Maximum voxel bounds, broadcastable to shape (3,), integer dtype.

Returns:

clipped_grid (Grid) – A new Grid containing only voxels within the specified bounds.

Return a coarsened version of this Grid.

Parameters:: coarsening_factor (NumericMaxRank1) – Factor by which to coarsen, broadcastable to shape (3,), integer dtype.
Returns:: coarsened_grid (Grid) – A new coarsened Grid.

contiguous() → Grid[source]

Return a contiguous copy of this Grid.

Returns:: grid (Grid) – A contiguous copy of this Grid.

Return the output Grid for a convolution with the given kernel.

Parameters:

kernel_size (NumericMaxRank1) – Size of the convolution kernel, broadcastable to shape (3,), integer dtype.
stride (NumericMaxRank1) – Convolution stride, broadcastable to shape (3,), integer dtype.

Returns:

conv_grid (Grid) – A new Grid representing the convolution output topology.

Return the output Grid for a transposed convolution.

Parameters:

kernel_size (NumericMaxRank1) – Size of the convolution kernel, broadcastable to shape (3,), integer dtype.
stride (NumericMaxRank1) – Convolution stride, broadcastable to shape (3,), integer dtype.

Returns:

conv_transpose_grid (Grid) – A new Grid representing the transposed convolution output topology.

coords_in_grid(ijk: Tensor) → Tensor[source]

Check which voxel-space coordinates correspond to active voxels.

Parameters:: ijk (torch.Tensor) – Voxel coordinates of shape (N, 3) with integer dtype.
Returns:: mask (torch.Tensor) – Boolean mask of shape (N,).

cpu() → Grid[source]

Return a copy of this Grid on the CPU.

Returns:: grid (Grid) – A Grid on CPU, or self if already on CPU.

Test whether cubes are fully contained within active voxels.

Parameters:

cube_centers (torch.Tensor) – World-space centers of shape (N, 3).
cube_min (NumericMaxRank1) – Minimum offsets from center defining cube bounds, broadcastable to shape (3,).
cube_max (NumericMaxRank1) – Maximum offsets from center defining cube bounds, broadcastable to shape (3,).

Returns:

mask (torch.Tensor) – Boolean mask of shape (N,).

Test whether cubes intersect any active voxels.

Parameters:

cube_centers (torch.Tensor) – World-space centers of shape (N, 3).
cube_min (NumericMaxRank1) – Minimum offsets from center.
cube_max (NumericMaxRank1) – Maximum offsets from center.

Returns:

mask (torch.Tensor) – Boolean mask of shape (N,).

cuda() → Grid[source]

Return a copy of this Grid on CUDA.

Returns:: grid (Grid) – A Grid on CUDA, or self if already on CUDA.

data

property device: device

The torch.device where this Grid is stored.

Returns:: device (torch.device) – The device of the grid.

dilated_grid(dilation: int) → Grid[source]

Return a dilated version of this Grid.

Parameters:: dilation (int) – Dilation radius in voxels.
Returns:: dilated_grid (Grid) – A new Grid with dilated active regions.

property dual_bbox: Tensor

The voxel-space bounding box of the dual of this Grid.

The dual grid has voxel centers at the corners of this grid’s voxels.

See also

bbox, dual_grid()

Returns:: dual_bbox (torch.Tensor) – Shape (2, 3). Returns a zero tensor if the grid has zero voxels.

dual_grid(exclude_border: bool = False) → Grid[source]

Return the dual grid whose voxel centers correspond to corners of this Grid.

Parameters:: exclude_border (bool) – If True, exclude border voxels that extend beyond the primal grid bounds.
Returns:: dual_grid (Grid) – A new Grid representing the dual grid.

edge_network(return_voxel_coordinates: bool = False) → tuple[Tensor, Tensor][source]

Return the edge network of this Grid.

Parameters:

return_voxel_coordinates (bool) – If True, return voxel coordinates instead of linear indices.

Returns:

edge_a (torch.Tensor) – One endpoint of each edge.
edge_b (torch.Tensor) – Other endpoint of each edge.

Create a dense Grid with a voxel for every coordinate in an axis-aligned box.

Parameters:

dense_dims (NumericMaxRank1) – Dimensions of the dense grid, broadcastable to shape (3,), integer dtype.
ijk_min (NumericMaxRank1) – Minimum voxel index for the grid, broadcastable to shape (3,), integer dtype.
voxel_size (NumericMaxRank1) – World-space size of each voxel, broadcastable to shape (3,), floating dtype.
origin (NumericMaxRank1) – World-space coordinate of the center of the [0,0,0] voxel, broadcastable to shape (3,), floating dtype.
mask (torch.Tensor | None) – Boolean mask with shape (W, H, D) selecting active voxels.
device (DeviceIdentifier | None) – Device to create the grid on.

Returns:

grid (Grid) – A new Grid object.

Create a dense Grid defined by axis-aligned bounds in world space.

Parameters:

dense_dims (NumericMaxRank1) – Dimensions of the dense grid, broadcastable to shape (3,), integer dtype.
bounds_min (NumericMaxRank1) – Minimum world-space bounds, broadcastable to shape (3,), floating dtype.
bounds_max (NumericMaxRank1) – Maximum world-space bounds, broadcastable to shape (3,), floating dtype.
voxel_center (bool) – Whether the bounds correspond to voxel centers (True) or edges (False). Defaults to False.
device (DeviceIdentifier) – Device to create the grid on.

Returns:

grid (Grid) – A new Grid object.

Create a Grid from voxel coordinates.

If multiple voxels map to the same coordinate, only one voxel will be created at that coordinate.

Parameters:

ijk (torch.Tensor) – Voxel coordinates of shape (num_voxels, 3) with integer dtype.
voxel_size (NumericMaxRank1) – Size of each voxel, broadcastable to shape (3,), floating dtype.
origin (NumericMaxRank1) – World-space position of the center of the [0,0,0] voxel, broadcastable to shape (3,), floating dtype.

Returns:

grid (Grid) – A new Grid object.

Create a Grid by voxelizing the surface of a triangle mesh.

Parameters:

mesh_vertices (torch.Tensor) – Vertices of shape (num_vertices, 3).
mesh_faces (torch.Tensor) – Faces of shape (num_faces, 3).
voxel_size (NumericMaxRank1) – Size of each voxel, broadcastable to shape (3,), floating dtype.
origin (NumericMaxRank1) – World-space position of the center of the [0,0,0] voxel, broadcastable to shape (3,), floating dtype.

Returns:

grid (Grid) – A new Grid with voxels covering the mesh surface.

classmethod from_nanovdb(path: str | Path, *, device: str | device = 'cpu', verbose: bool = False) → tuple[Grid, Tensor, str][source]

classmethod from_nanovdb(path: str | Path, *, index: int, device: str | device = 'cpu', verbose: bool = False) → tuple[Grid, Tensor, str]

classmethod from_nanovdb(path: str | Path, *, name: str, device: str | device = 'cpu', verbose: bool = False) → tuple[Grid, Tensor, str]

Load a single Grid from a .nvdb file.

Parameters:

path (str | pathlib.Path) – Path to the .nvdb file.
index (int) – Index of the grid to load from the file.
name (str | None) – Name of the grid to load (mutually exclusive with index).
device (DeviceIdentifier) – Device to load the grid onto.
verbose (bool) – If True, print information about the loaded grid.

Returns:

grid (Grid) – The loaded Grid.
data (torch.Tensor) – Voxel data with shape (num_voxels, channels*).
name (str) – Name of the loaded grid.

Create a Grid by adding the eight nearest voxels to every point.

Parameters:

points (torch.Tensor) – Points of shape (num_points, 3).
voxel_size (NumericMaxRank1) – Size of each voxel, broadcastable to shape (3,), floating dtype.
origin (NumericMaxRank1) – World-space position of the center of the [0,0,0] voxel, broadcastable to shape (3,), floating dtype.

Returns:

grid (Grid) – A new Grid object.

Create a Grid from a point cloud.

Parameters:

points (torch.Tensor) – Points of shape (num_points, 3).
voxel_size (NumericMaxRank1) – Size of each voxel, broadcastable to shape (3,), floating dtype.
origin (NumericMaxRank1) – World-space position of the center of the [0,0,0] voxel, broadcastable to shape (3,), floating dtype.

Returns:

grid (Grid) – A new Grid object.

Create a Grid with zero voxels on a specific device.

Parameters:

device (DeviceIdentifier) – Device to create the grid on.
voxel_size (NumericMaxRank1) – Size of each voxel, broadcastable to shape (3,), floating dtype.
origin (NumericMaxRank1) – Origin of the grid, broadcastable to shape (3,), floating dtype.

Returns:

grid (Grid) – A new Grid object with zero voxels.

has_same_address_and_grid_count(other: Any) → bool[source]

Check if this Grid has the same underlying data identity as another object.

Parameters:: other – Object to compare with.
Returns:: result (bool) – True if same address and grid count.

property has_zero_voxels: bool

True if this Grid has zero active voxels.

Returns:: has_zero_voxels (bool) – Whether the grid is empty.

property hilbert: Tensor

Hilbert curve codes for active voxels.

Returns:: hilbert (torch.Tensor) – Shape (num_voxels,).

property hilbert_zyx: Tensor

Transposed Hilbert curve codes (zyx) for active voxels.

Returns:: hilbert_zyx (torch.Tensor) – Shape (num_voxels,).

property ijk: Tensor

The voxel coordinates of every active voxel, in index order.

Returns:: ijk (torch.Tensor) – Shape (num_voxels, 3).

ijk_to_index(ijk: Tensor, cumulative: bool = False) → Tensor[source]

Convert voxel-space coordinates to linear index-space.

Returns -1 for coordinates that do not correspond to active voxels.

Parameters:

ijk (torch.Tensor) – Voxel coordinates of shape (N, 3) with integer dtype.
cumulative (bool) – If True, return cumulative indices. For a single grid this is equivalent to the default.

Returns:

indices (torch.Tensor) – Linear indices of shape (N,).

ijk_to_inv_index(ijk: Tensor, cumulative: bool = False) → Tensor[source]

Get inverse permutation of ijk_to_index().

For each voxel in the grid, return the index in the input ijk tensor that maps to it, or -1 if no such coordinate exists.

Parameters:

ijk (torch.Tensor) – Voxel coordinates of shape (N, 3) with integer dtype.
cumulative (bool) – If True, return cumulative indices.

Returns:

inv_map (torch.Tensor) – Inverse permutation of shape (N,).

inject_from(src_grid: Grid, src: Tensor, dst: Tensor | None = None, default_value: float | int | bool = 0) → Tensor[source]

Inject data from src_grid into this Grid.

Copies sidecar data for voxels shared between the two grids. The copy occurs in voxel space; the voxel-to-world transform is not applied.

Note

Supports backpropagation.

Parameters:

src_grid (Grid) – Source Grid to inject data from.
src (torch.Tensor) – Source data of shape (src_grid.num_voxels, *).
dst (torch.Tensor | None) – Optional destination data modified in-place. Shape (self.num_voxels, *) or None.
default_value (float | int | bool) – Fill value for voxels without source data. Used only if dst is None.

Returns:

dst (torch.Tensor) – The destination data after injection.

Inject values from a dense tensor (CXYZ order) into sparse voxel data.

dense_data has shape (1, C*, X, Y, Z).

Note

Supports backpropagation.

Parameters:

dense_data (torch.Tensor) – Dense tensor to read from, shape (1, C*, X, Y, Z).
dense_origin (NumericMaxRank1) – Origin of the dense tensor in voxel space, broadcastable to shape (3,), integer dtype.

Returns:

sparse_data (torch.Tensor) – Shape (num_voxels, channels*).

Inject values from a dense tensor (XYZC order) into sparse voxel data.

dense_data has shape (1, X, Y, Z, C*).

Note

Supports backpropagation.

Parameters:

dense_data (torch.Tensor) – Dense tensor to read from, shape (1, X, Y, Z, C*).
dense_origin (NumericMaxRank1) – Origin of the dense tensor in voxel space, broadcastable to shape (3,), integer dtype.

Returns:

sparse_data (torch.Tensor) – Shape (num_voxels, channels*).

inject_from_ijk(src_ijk: Tensor, src: Tensor, dst: Tensor | None = None, default_value: float | int | bool = 0) → Tensor[source]

Inject data from source voxel coordinates into this Grid.

Note

Supports backpropagation.

Parameters:

src_ijk (torch.Tensor) – Source voxel coordinates of shape (num_src_voxels, 3) with integer dtype.
src (torch.Tensor) – Source data of shape (num_src_voxels, *).
dst (torch.Tensor | None) – Optional destination data modified in-place. Shape (self.num_voxels, *) or None.
default_value (float | int | bool) – Fill value for voxels without source data. Used only if dst is None.

Returns:

dst (torch.Tensor) – The destination data after injection.

inject_to(dst_grid: Grid, src: Tensor, dst: Tensor | None = None, default_value: float | int | bool = 0) → Tensor[source]

Inject data from this Grid into dst_grid.

Copies sidecar data for voxels shared between the two grids. The copy occurs in voxel space; the voxel-to-world transform is not applied.

Note

Supports backpropagation.

Parameters:

dst_grid (Grid) – Destination Grid to inject data into.
src (torch.Tensor) – Source data of shape (self.num_voxels, *).
dst (torch.Tensor | None) – Optional destination data modified in-place. Shape (dst_grid.num_voxels, *) or None.
default_value (float | int | bool) – Fill value for voxels without source data. Used only if dst is None.

Returns:

dst (torch.Tensor) – The destination data after injection.

Write sparse voxel data into a dense tensor in CXYZ order.

Note

Supports backpropagation.

Parameters:

sparse_data (torch.Tensor) – Voxel data of shape (num_voxels, channels*).
min_coord (NumericMaxRank1 | None) – Minimum voxel coordinate for the output dense tensor. If None, uses the grid’s bounding box minimum.
grid_size (NumericMaxRank1 | None) – Size of the output dense tensor. If None, computed to fit all active voxels.

Returns:

dense_data (torch.Tensor) – Dense tensor of shape (channels*, X, Y, Z).

Write sparse voxel data into a dense tensor in XYZC order.

Note

Supports backpropagation.

Parameters:

sparse_data (torch.Tensor) – Voxel data of shape (num_voxels, channels*).
min_coord (NumericMaxRank1 | None) – Minimum voxel coordinate for the output dense tensor. If None, uses the grid’s bounding box minimum.
grid_size (NumericMaxRank1 | None) – Size of the output dense tensor. If None, computed to fit all active voxels.

Returns:

dense_data (torch.Tensor) – Dense tensor of shape (X, Y, Z, channels*).

integrate_tsdf(truncation_distance: float, projection_matrices: Tensor, cam_to_world_matrices: Tensor, tsdf: Tensor, weights: Tensor, depth_images: Tensor, weight_images: Tensor | None = None) → tuple[Grid, Tensor, Tensor][source]

Integrate depth images into a TSDF volume.

Updates TSDF values and weights by integrating new depth observations from camera viewpoints.

Parameters:

truncation_distance (float) – Maximum TSDF truncation distance.
projection_matrices (torch.Tensor) – Camera projection matrices.
cam_to_world_matrices (torch.Tensor) – Camera-to-world transforms.
tsdf (torch.Tensor) – Current TSDF values of shape (num_voxels, 1).
weights (torch.Tensor) – Current integration weights of shape (num_voxels, 1).
depth_images (torch.Tensor) – Depth images.
weight_images (torch.Tensor | None) – Optional weight images.

Returns:

updated_grid (Grid) – Updated Grid.
updated_tsdf (torch.Tensor) – Updated TSDF values.
updated_weights (torch.Tensor) – Updated weights.

integrate_tsdf_with_features(truncation_distance: float, projection_matrices: Tensor, cam_to_world_matrices: Tensor, tsdf: Tensor, features: Tensor, weights: Tensor, depth_images: Tensor, feature_images: Tensor, weight_images: Tensor | None = None) → tuple[Grid, Tensor, Tensor, Tensor][source]

Integrate depth and feature images into a TSDF volume.

Similar to integrate_tsdf() but also integrates feature observations (e.g., color).

Parameters:

truncation_distance (float) – Maximum TSDF truncation distance.
projection_matrices (torch.Tensor) – Camera projection matrices.
cam_to_world_matrices (torch.Tensor) – Camera-to-world transforms.
tsdf (torch.Tensor) – Current TSDF values of shape (num_voxels, 1).
features (torch.Tensor) – Current features of shape (num_voxels, feature_dim).
weights (torch.Tensor) – Current integration weights of shape (num_voxels, 1).
depth_images (torch.Tensor) – Depth images.
feature_images (torch.Tensor) – Feature images.
weight_images (torch.Tensor | None) – Optional weight images.

Returns:

updated_grid (Grid) – Updated Grid.
updated_tsdf (torch.Tensor) – Updated TSDF values.
updated_features (torch.Tensor) – Updated features.
updated_weights (torch.Tensor) – Updated weights.

property is_contiguous: bool

Whether the grid data is stored contiguously in memory.

Returns:: is_contiguous (bool) – True if contiguous.

is_same(other: Grid) → bool[source]

Check if two Grid objects share the same underlying data.

Parameters:: other (Grid) – The other Grid to compare with.
Returns:: is_same (bool) – True if the grids share underlying data.

marching_cubes(field: Tensor, level: float = 0.0) → tuple[Tensor, Tensor, Tensor][source]

Extract isosurface mesh using marching cubes.

Parameters:

field (torch.Tensor) – Scalar field of shape (num_voxels, 1).
level (float) – Isovalue at which to extract the surface.

Returns:

vertices (torch.Tensor) – Vertex positions of shape (num_vertices, 3).
faces (torch.Tensor) – Triangle face indices of shape (num_faces, 3).
normals (torch.Tensor) – Vertex normals of shape (num_vertices, 3).

Apply max pooling to voxel data.

Note

Supports backpropagation.

Parameters:

pool_factor (NumericMaxRank1) – Downsample factor, broadcastable to shape (3,), integer dtype.
data (torch.Tensor) – Voxel data of shape (num_voxels, channels).
stride (NumericMaxRank1) – Pooling stride. If 0, equals pool_factor.
coarse_grid (Grid | None) – Pre-allocated coarse Grid. If None, a new one is created.

Returns:

pooled_data (torch.Tensor) – Pooled data of shape (coarse_num_voxels, channels).
coarse_grid (Grid) – Coarse Grid after pooling.

merged_grid(other: Grid) → Grid[source]

Return the union of this Grid with another.

Parameters:: other (Grid) – The other Grid to merge with.
Returns:: merged_grid (Grid) – A new Grid containing the union of active voxels from both grids.

property morton: Tensor

Morton codes (Z-order curve, xyz interleaving) for active voxels.

Returns:: morton (torch.Tensor) – Shape (num_voxels,).

property morton_zyx: Tensor

Transposed Morton codes (zyx interleaving) for active voxels.

Returns:: morton_zyx (torch.Tensor) – Shape (num_voxels,).

neighbor_indexes(ijk: Tensor, extent: int, bitshift: int = 0) → Tensor[source]

Get linear indices of neighboring voxels in an N-ring neighborhood.

Parameters:

ijk (torch.Tensor) – Voxel coordinates of shape (N, 3) with integer dtype.
extent (int) – Size of the neighborhood ring (N-ring).
bitshift (int) – Bit shift applied to input coordinates before querying. Default is 0.

Returns:

neighbor_indexes (torch.Tensor) – Shape (N, K) where K is the number of neighbors per voxel. -1 for inactive neighbors.

property num_bytes: int

The size in bytes this Grid occupies in memory.

Returns:: num_bytes (int) – Size in bytes.

property num_leaf_nodes: int

The number of leaf nodes in the NanoVDB tree for this Grid.

Returns:: num_leaf_nodes (int) – Number of leaf nodes.

property num_voxels: int

The number of active voxels in this Grid.

Returns:: num_voxels (int) – Number of active voxels.

property origin: Tensor

The world-space origin of this Grid, i.e. the center of voxel (0,0,0).

Returns:: origin (torch.Tensor) – Shape (3,).

points_in_grid(points: Tensor) → Tensor[source]

Check if world-space points are located within active voxels.

Parameters:: points (torch.Tensor) – World-space points of shape (N, 3).
Returns:: mask (torch.Tensor) – Boolean mask of shape (N,).

pruned_grid(mask: Tensor) → Grid[source]

Return a pruned Grid keeping only voxels where mask is True.

Parameters:: mask (torch.Tensor) – Boolean mask of shape (num_voxels,).
Returns:: pruned_grid (Grid) – A new Grid with pruned voxels.

ray_implicit_intersection(ray_origins: Tensor, ray_directions: Tensor, grid_scalars: Tensor, eps: float = 0.0) → Tensor[source]

Find ray intersections with an implicit surface defined by voxel scalars.

The implicit surface is defined by the zero level-set of grid_scalars.

Parameters:

ray_origins (torch.Tensor) – Ray origins of shape (N, 3).
ray_directions (torch.Tensor) – Ray directions of shape (N, 3).
grid_scalars (torch.Tensor) – Scalar field of shape (num_voxels, 1).
eps (float) – Epsilon for numerical stability.

Returns:

intersection_distances (torch.Tensor) – Distance along each ray, or -1 if no intersection. Shape (N,).

rays_intersect_voxels(ray_origins: Tensor, ray_directions: Tensor, eps: float = 0.0) → Tensor[source]

Check whether rays hit any voxels in this Grid.

Parameters:

ray_origins (torch.Tensor) – Ray origins of shape (N, 3).
ray_directions (torch.Tensor) – Ray directions of shape (N, 3).
eps (float) – Epsilon for numerical stability.

Returns:

hit_mask (torch.Tensor) – Boolean tensor of shape (N,).

Refine (upsample) voxel data into a higher-resolution Grid.

For each voxel (i, j, k) in this grid, copies its data to the subdivided voxels in the fine grid.

Note

Supports backpropagation.

Parameters:

subdiv_factor (NumericMaxRank1) – Refinement factor, broadcastable to shape (3,), integer dtype.
data (torch.Tensor) – Voxel data of shape (num_voxels, channels).
mask (torch.Tensor | None) – Boolean mask of shape (num_voxels,) indicating which voxels to refine.
refined (Grid | None) – Pre-allocated fine Grid. If None, a new one is created.

Returns:

refined_data (torch.Tensor) – Refined data for the fine grid.
fine_grid (Grid) – The fine Grid.

Return a refined (subdivided) version of this Grid.

Parameters:

subdiv_factor (NumericMaxRank1) – Factor by which to refine, broadcastable to shape (3,), integer dtype.
mask (torch.Tensor | None) – Boolean mask of shape (num_voxels,) indicating which voxels to refine. If None, all voxels are refined.

Returns:

refined_grid (Grid) – A new refined Grid.

sample_bezier(points: Tensor, voxel_data: Tensor) → Tensor[source]

Sample voxel data at world-space points using Bezier interpolation.

Note

Supports backpropagation. Samples outside the grid return zero.

Parameters:

points (torch.Tensor) – World-space points of shape (N, 3).
voxel_data (torch.Tensor) – Voxel data of shape (num_voxels, channels*).

Returns:

interpolated_data (torch.Tensor) – Shape (N, channels*).

sample_bezier_with_grad(points: Tensor, voxel_data: Tensor) → tuple[Tensor, Tensor][source]

Sample voxel data using Bezier interpolation and return spatial gradients.

Note

Supports backpropagation. Samples outside the grid return zero.

Parameters:

points (torch.Tensor) – World-space points of shape (N, 3).
voxel_data (torch.Tensor) – Voxel data of shape (num_voxels, channels*).

Returns:

interpolated_data (torch.Tensor) – Shape (N, channels*).
gradients (torch.Tensor) – Spatial gradients of shape (N, 3, channels*).

sample_nearest(points: Tensor, voxel_data: Tensor) → Tensor[source]

Sample voxel data at world-space points using nearest-neighbor lookup.

For each query point the 8 nearest voxel centers are checked and the value of the closest active one is returned. Points where none of the 8 surrounding voxel centers are active return zero.

Note

Supports backpropagation w.r.t. voxel_data.

Parameters:

points (torch.Tensor) – World-space points of shape (N, 3).
voxel_data (torch.Tensor) – Voxel data of shape (num_voxels, channels*).

Returns:

sampled_data (torch.Tensor) – Shape (N, channels*).

sample_trilinear(points: Tensor, voxel_data: Tensor) → Tensor[source]

Sample voxel data at world-space points using trilinear interpolation.

Note

Supports backpropagation. Samples outside the grid return zero.

Parameters:

points (torch.Tensor) – World-space points of shape (N, 3).
voxel_data (torch.Tensor) – Voxel data of shape (num_voxels, channels*).

Returns:

interpolated_data (torch.Tensor) – Shape (N, channels*).

sample_trilinear_with_grad(points: Tensor, voxel_data: Tensor) → tuple[Tensor, Tensor][source]

Sample voxel data using trilinear interpolation and return spatial gradients.

Note

Supports backpropagation. Samples outside the grid return zero.

Parameters:

points (torch.Tensor) – World-space points of shape (N, 3).
voxel_data (torch.Tensor) – Voxel data of shape (num_voxels, channels*).

Returns:

interpolated_data (torch.Tensor) – Shape (N, channels*).
gradients (torch.Tensor) – Spatial gradients of shape (N, 3, channels*).

save_nanovdb(path: str | Path, data: Tensor | None = None, name: str | None = None, compressed: bool = False, verbose: bool = False) → None[source]

Save this Grid and optional voxel data to a .nvdb file.

Parameters:

path (str | pathlib.Path) – File path (should have .nvdb extension).
data (torch.Tensor | None) – Voxel data of shape (num_voxels, channels). If None, only the grid structure is saved.
name (str | None) – Optional name for the grid.
compressed (bool) – Whether to use Blosc compression.
verbose (bool) – Whether to print save information.

segments_along_rays(ray_origins: Tensor, ray_directions: Tensor, max_segments: int, eps: float = 0.0) → JaggedTensor[source]

Return continuous segments of ray traversal through this Grid.

Each segment is a (t_start, t_end) pair of distances along the ray.

Parameters:

ray_origins (torch.Tensor) – Ray origins of shape (N, 3).
ray_directions (torch.Tensor) – Ray directions of shape (N, 3).
max_segments (int) – Maximum segments to return per ray.
eps (float) – Epsilon for numerical stability.

Returns:

segments (JaggedTensor) – Per-ray segments with element shape (2,).

splat_bezier(points: Tensor, points_data: Tensor) → Tensor[source]

Splat point data into voxels using Bezier interpolation.

Each point distributes its data to surrounding voxels using cubic Bezier interpolation weights.

Note

Supports backpropagation.

Parameters:

points (torch.Tensor) – World-space point positions of shape (N, 3).
points_data (torch.Tensor) – Data to splat of shape (N, channels*).

Returns:

splatted_features (torch.Tensor) – Accumulated features of shape (num_voxels, channels*).

splat_trilinear(points: Tensor, points_data: Tensor) → Tensor[source]

Splat point data into voxels using trilinear interpolation.

Each point distributes its data to surrounding voxels using trilinear interpolation weights.

Note

Supports backpropagation.

Parameters:

points (torch.Tensor) – World-space point positions of shape (N, 3).
points_data (torch.Tensor) – Data to splat of shape (N, channels*).

Returns:

splatted_features (torch.Tensor) – Accumulated features of shape (num_voxels, channels*).

Move this Grid to the target device.

Parameters:: target – Target device specification. Can be a string, a torch.device, a torch.Tensor, a JaggedTensor, a Grid, or a GridBatch.
Returns:: grid (Grid) – A Grid on the target device.

to_gridbatch() → GridBatch[source]

Convert this Grid to a GridBatch with grid_count == 1.

Returns:: grid_batch (GridBatch) – A GridBatch wrapping the same underlying data.

uniform_ray_samples(ray_origins: Tensor, ray_directions: Tensor, t_min: Tensor, t_max: Tensor, step_size: float, cone_angle: float = 0.0, include_end_segments: bool = True, return_midpoints: bool = False, eps: float = 0.0) → JaggedTensor[source]

Generate uniformly spaced samples along rays intersecting this Grid.

Parameters:

ray_origins (torch.Tensor) – Ray origins of shape (N, 3).
ray_directions (torch.Tensor) – Ray directions of shape (N, 3).
t_min (torch.Tensor) – Minimum distances of shape (N,).
t_max (torch.Tensor) – Maximum distances of shape (N,).
step_size (float) – Distance between samples.
cone_angle (float) – Cone angle for adaptive sampling (radians).
include_end_segments (bool) – Include partial segments at ray ends.
return_midpoints (bool) – Return midpoints instead of start points.
eps (float) – Epsilon for numerical stability.

Returns:

samples (JaggedTensor) – Per-ray sample distances.

property voxel_size: Tensor

The world-space size of each voxel in this Grid.

Returns:: voxel_size (torch.Tensor) – Shape (3,).

voxel_to_world(ijk: Tensor) → Tensor[source]

Transform voxel-space coordinates to world-space positions.

Parameters:: ijk (torch.Tensor) – Voxel-space coordinates of shape (N, 3). Can be fractional for interpolation.
Returns:: world_coords (torch.Tensor) – World-space coordinates of shape (N, 3).

property voxel_to_world_matrix: Tensor

The voxel-to-world transformation matrix.

Returns:: voxel_to_world_matrix (torch.Tensor) – Shape (4, 4).

voxels_along_rays(ray_origins: Tensor, ray_directions: Tensor, max_voxels: int, eps: float = 0.0, return_ijk: bool = False) → tuple[JaggedTensor, JaggedTensor][source]

Enumerate voxels intersected by rays using DDA traversal.

Parameters:

ray_origins (torch.Tensor) – Ray origins of shape (N, 3).
ray_directions (torch.Tensor) – Ray directions of shape (N, 3).
max_voxels (int) – Maximum voxels to return per ray.
eps (float) – Epsilon for numerical stability.
return_ijk (bool) – If True, return voxel (i,j,k) coordinates instead of linear indices.

Returns:

voxels (JaggedTensor) – Per-ray voxel indices (or coordinates if return_ijk).
distances (JaggedTensor) – Per-ray entry/exit distances of shape (num_rays, num_voxels_per_ray, 2).

world_to_voxel(points: Tensor) → Tensor[source]

Convert world-space coordinates to voxel-space coordinates.

Parameters:: points (torch.Tensor) – World-space positions of shape (N, 3).
Returns:: voxel_coords (torch.Tensor) – Voxel-space coordinates of shape (N, 3). Can contain fractional values.

property world_to_voxel_matrix: Tensor

The world-to-voxel transformation matrix.

Returns:: world_to_voxel_matrix (torch.Tensor) – Shape (4, 4).

class fvdb.GridBatch(*, data: fvdb._fvdb_cpp.GridBatchData)[source]

A batch of sparse voxel grids with support for efficient operations.

GridBatch represents a collection of sparse 3D voxel grids that can be processed together efficiently on GPU. Each grid in the batch can have different resolutions, origins, and voxel sizes. The class provides methods for common operations like sampling, convolution, pooling, dilation, union, etc. It also provides more advanced features such as marching cubes, TSDF fusion, and fast ray marching.

A GridBatch can be thought of as a mini-batch of sparse grids and does not collect the sparse voxel grids’ data but only collects their structure (or topology). Voxel data (e.g., features, colors, densities) for the collection of grids is stored separately as an JaggedTensor associated with the GridBatch. This separation allows for flexibility in the type and number of channels of data with which a grid can be used to index into. This also allows multiple grids to share the same data storage if desired.

When using a GridBatch, there are three important coordinate systems to be aware of:

World Space: The continuous 3D coordinate system in which each grid in the batch exists.
Voxel Space: The discrete voxel index system of each grid in the batch, where each voxel is identified by its integer indices (i, j, k).
Index Space: The linear indexing of active voxels in each grid’s internal storage.

At its core, a GridBatch uses a very fast mapping from each grid’s voxel space into index space to perform operations on a fvdb.JaggedTensor of data associated with the grids in the batch. This mapping allows for efficient access and manipulation of voxel data. For example:

voxel_coords = torch.tensor([[8, 7, 6], [1, 2, 3], [4, 5, 6]], device="cuda")  # Voxel space coordinates
batch_voxel_coords = fvdb.JaggedTensor(
    [voxel_coords, voxel_coords + 44, voxel_coords - 44]
)  # Voxel space coordinates for 3 grids in the batch

# Create a GridBatch containing 3 grids with the 3 sets of voxel coordinates such that the voxels
# have a world space size of 1x1x1, and where the [0, 0, 0] voxel in voxel space of each grid is at world space origin (0, 0, 0).
grid_batch = fvdb.GridBatch.from_ijk(batch_voxel_coords, voxel_sizes=1.0, origins=0.0)

# Create some data associated with the grids - here we have 9 voxels and 2 channels per voxel
voxel_data = torch.randn(grid_batch.total_voxels, 2, device="cuda")  # Index space data

# Map voxel space coordinates to index space
indices = grid_batch.ijk_to_index(batch_voxel_coords, cumulative=True).jdata  # Shape: (9,)

# Access the data for the specified voxel coordinates
selected_data = voxel_data[indices]  # Shape: (9, 2)

Note

A GridBatch may contain zero grids, in which case it has no voxel sizes nor origins that can be queried. It may also contain one or more empty grids, which means grids that have zero voxels. An empty grid still has a voxel size and origin, which can be queried.

Note

The grids are stored in a sparse format using NanoVDB where only active (non-empty) voxels are allocated, making it extremely memory efficient for representing large volumes with sparse occupancy.

Note

The GridBatch constructor is for internal use only. To create a GridBatch with actual content, use the classmethods:

from_zero_grids(): for an empty grid batch where grid-count = 0.

from_zero_voxels(): for a grid batch where each grid has zero voxels.

from_dense(): for a grid batch where each grid is dense data

from_dense_axis_aligned_bounds(): for a grid batch where each grid is dense data defined by axis-aligned bounds

from_ijk(): for a grid batch from explicit voxel coordinates

from_mesh(): for a grid batch from triangle meshes

from_points(): for a grid batch from point clouds

from_nearest_voxels_to_points(): for a grid batch from nearest voxels to points

from_cat(): for a grid batch from concatenating other grids and grid batches

max_grids_per_batch

Maximum number of grids that can be stored in a single fvdb.GridBatch.

Type:: int

property address: int: Unique identifier (int) of the underlying C++ GridBatchData object.

property all_have_zero_voxels: bool: True (bool) if all grids in this grid batch have zero active voxels.

property any_have_zero_voxels: bool: True (bool) if any grid in this grid batch has zero active voxels.

Apply average pooling to voxel data associated with this grid batch.

Supports backpropagation.

Parameters:

pool_factor (NumericMaxRank1) – Downsample factor, broadcastable to shape (3,), integer dtype.
data (JaggedTensor) – Voxel data to pool. Shape: (batch_size, total_voxels, channels).
stride (NumericMaxRank1) – Pooling stride; if 0, equals pool_factor. Broadcastable to shape (3,), integer dtype.
coarse_grid (GridBatch | None) – Optional pre-allocated coarse grid batch for output.

Returns:

pooled_data (JaggedTensor) – Pooled voxel data. Shape: (batch_size, coarse_total_voxels, channels).
coarse_grid (GridBatch) – The coarse grid batch topology after pooling.

See also

Grid.avg_pool()

bbox_at(bi: int) → Tensor[source]

Get the voxel-space bounding box of a specific grid in this grid batch.

Parameters:: bi (int) – Batch index of the grid.
Returns:: bbox (torch.Tensor) – Bounding box of shape (2, 3) as [[bmin_i, bmin_j, bmin_k], [bmax_i, bmax_j, bmax_k]].

property bboxes: Tensor: Voxel-space bounding boxes (torch.Tensor) of shape (grid_count, 2, 3) for each grid in this grid batch.

Clip voxels and their features to a bounding box range for this grid batch.

Supports backpropagation.

Parameters:

features (JaggedTensor) – Voxel features to clip. Shape: (batch_size, total_voxels, channels).
ijk_min (NumericMaxRank2) – Minimum voxel-space bounds, broadcastable to shape (batch_size, 3), integer dtype.
ijk_max (NumericMaxRank2) – Maximum voxel-space bounds, broadcastable to shape (batch_size, 3), integer dtype.

Returns:

clipped_features (JaggedTensor) – Clipped voxel features. Shape: (batch_size, clipped_total_voxels, channels).
clipped_grid (GridBatch) – A new GridBatch containing only voxels within bounds.

See also

Grid.clip()

Return a new grid batch clipped to a voxel-space bounding box for this grid batch.

Parameters:

ijk_min (NumericMaxRank2) – Minimum voxel-space bounds, broadcastable to shape (batch_size, 3), integer dtype.
ijk_max (NumericMaxRank2) – Maximum voxel-space bounds, broadcastable to shape (batch_size, 3), integer dtype.

Returns:

clipped_grid (GridBatch) – A new GridBatch containing only voxels within bounds.

See also

Grid.clipped_grid()

Return a coarsened version of this grid batch by keeping every N-th voxel.

Parameters:: coarsening_factor (NumericMaxRank1) – Coarsening factor, broadcastable to shape (3,), integer dtype.
Returns:: coarsened_grid (GridBatch) – A new coarsened GridBatch.

See also

Grid.coarsened_grid()

contiguous() → GridBatch[source]

Return a contiguous copy of this grid batch in memory.

Returns:: grid_batch (GridBatch) – A new GridBatch with contiguous memory layout.

See also

Grid.contiguous()

Return the output grid topology for a convolution applied to this grid batch.

Parameters:

kernel_size (NumericMaxRank1) – Convolution kernel size, broadcastable to shape (3,), integer dtype.
stride (NumericMaxRank1) – Convolution stride, broadcastable to shape (3,), integer dtype.

Returns:

conv_grid (GridBatch) – A GridBatch representing the convolution output topology.

See also

Grid.conv_grid()

Return the output grid topology for a transposed convolution applied to this grid batch.

Parameters:

kernel_size (NumericMaxRank1) – Convolution kernel size, broadcastable to shape (3,), integer dtype.
stride (NumericMaxRank1) – Convolution stride, broadcastable to shape (3,), integer dtype.

Returns:

conv_transpose_grid (GridBatch) – A GridBatch representing the transposed convolution output topology.

See also

Grid.conv_transpose_grid()

coords_in_grid(ijk: JaggedTensor) → JaggedTensor[source]

Check which voxel-space coordinates lie on active voxels in this grid batch.

Parameters:: ijk (JaggedTensor) – Voxel coordinates to test. Shape: (batch_size, num_queries_for_grid_b, 3), integer dtype.
Returns:: mask (JaggedTensor) – Boolean mask indicating active voxel hits. Shape: (batch_size, num_queries_for_grid_b).

See also

Grid.coords_in_grid()

cpu() → GridBatch[source]

Move this grid batch to CPU.

Returns:: grid_batch (GridBatch) – A new GridBatch on CPU device.

See also

Grid.cpu()

Check if axis-aligned cubes are fully contained within active voxels of this grid batch.

Parameters:

cube_centers (JaggedTensor) – Cube centers in world coordinates. Shape: (batch_size, num_cubes_for_grid_b, 3).
cube_min (NumericMaxRank1) – Minimum offsets from center, broadcastable to shape (3,), floating dtype.
cube_max (NumericMaxRank1) – Maximum offsets from center, broadcastable to shape (3,), floating dtype.

Returns:

mask (JaggedTensor) – Boolean mask of fully contained cubes. Shape: (batch_size, num_cubes_for_grid_b).

See also

Grid.cubes_in_grid()

Check if axis-aligned cubes intersect any active voxels in this grid batch.

Parameters:

cube_centers (JaggedTensor) – Cube centers in world coordinates. Shape: (batch_size, num_cubes_for_grid_b, 3).
cube_min (NumericMaxRank1) – Minimum offsets from center, broadcastable to shape (3,), floating dtype.
cube_max (NumericMaxRank1) – Maximum offsets from center, broadcastable to shape (3,), floating dtype.

Returns:

mask (JaggedTensor) – Boolean mask of intersecting cubes. Shape: (batch_size, num_cubes_for_grid_b).

See also

Grid.cubes_intersect_grid()

cuda() → GridBatch[source]

Move this grid batch to CUDA device.

Returns:: grid_batch (GridBatch) – A new GridBatch on CUDA device.

See also

Grid.cuda()

property cum_voxels: Tensor: Cumulative voxel counts (torch.Tensor) of shape (grid_count,) for this grid batch.

cum_voxels_at(bi: int) → int[source]

Get the cumulative voxel count up to and including a specific grid in this grid batch.

Parameters:: bi (int) – Batch index of the grid.
Returns:: cum_voxels (int) – Cumulative number of voxels up to and including grid bi.

data

property device: device: The torch.device where this grid batch is stored.

dilated_grid(dilation: int) → GridBatch[source]

Return a dilated version of this grid batch by expanding active regions.

Parameters:: dilation (int) – Dilation radius in voxels.
Returns:: dilated_grid (GridBatch) – A new GridBatch with dilated active regions.

See also

Grid.dilated_grid()

dual_bbox_at(bi: int) → Tensor[source]

Get the dual voxel-space bounding box of a specific grid in this grid batch.

Parameters:: bi (int) – Batch index of the grid.
Returns:: dual_bbox (torch.Tensor) – Dual bounding box of shape (2, 3).

property dual_bboxes: Tensor: Dual voxel-space bounding boxes (torch.Tensor) of shape (grid_count, 2, 3) for this grid batch.

dual_grid(exclude_border: bool = False) → GridBatch[source]

Return the dual grid of this grid batch where voxel centers correspond to primal voxel corners.

Parameters:: exclude_border (bool) – If True, excludes border voxels beyond primal grid bounds.
Returns:: dual_grid (GridBatch) – A new GridBatch representing the dual grid.

See also

Grid.dual_grid()

classmethod from_cat(grids: Sequence[GridBatch | Grid]) → GridBatch[source]

Create a grid batch by concatenating a sequence of grids or grid batches along the batch dimension.

Parameters:: grids (Sequence[GridBatch | Grid]) – Grids or grid batches to concatenate.
Returns:: grid_batch (GridBatch) – A new GridBatch containing all grids from the inputs.

Create a grid batch of dense grids from dimensions and an optional mask.

Parameters:

num_grids (int) – Number of grids to create.
dense_dims (NumericMaxRank1) – Dimensions of the dense grid, broadcastable to shape (3,), integer dtype.
ijk_min (NumericMaxRank1) – Minimum voxel index for all grids, broadcastable to shape (3,), integer dtype.
voxel_sizes (NumericMaxRank2) – World-space size of each voxel, per-grid; broadcastable to shape (num_grids, 3), floating dtype.
origins (NumericMaxRank2) – World-space origin of each grid, per-grid; broadcastable to shape (num_grids, 3), floating dtype.
mask (torch.Tensor | None) – Optional boolean mask with shape (W, H, D) selecting active voxels.
device (DeviceIdentifier | None) – Device to create the grid batch on. Defaults to None.

Returns:

grid_batch (GridBatch) – A new GridBatch of dense grids.

See also

Grid.from_dense()

Create a grid batch of dense grids defined by axis-aligned world-space bounds.

Parameters:

num_grids (int) – Number of grids to create.
dense_dims (NumericMaxRank1) – Dimensions of the dense grids, broadcastable to shape (3,), integer dtype.
bounds_min (NumericMaxRank1) – Minimum world-space coordinate, broadcastable to shape (3,), floating dtype.
bounds_max (NumericMaxRank1) – Maximum world-space coordinate, broadcastable to shape (3,), floating dtype.
voxel_center (bool) – Whether bounds correspond to voxel centers (True) or edges (False).
device (DeviceIdentifier) – Device to create the grids on. Defaults to "cpu".

Returns:

grid_batch (GridBatch) – A new GridBatch of dense grids.

See also

Grid.from_dense_axis_aligned_bounds()

Create a grid batch from explicit voxel-space coordinates.

Parameters:

ijk (JaggedTensor) – Per-grid voxel coordinates. Shape: (batch_size, num_voxels_for_grid_b, 3), integer dtype.
voxel_sizes (NumericMaxRank2) – Size of each voxel, per-grid; broadcastable to shape (batch_size, 3), floating dtype.
origins (NumericMaxRank2) – World-space origin of each grid, per-grid; broadcastable to shape (batch_size, 3), floating dtype.

Returns:

grid_batch (GridBatch) – A new GridBatch with the specified voxel coordinates.

See also

Grid.from_ijk()

Create a grid batch by voxelizing the surface of triangle meshes.

Parameters:

mesh_vertices (JaggedTensor) – Per-grid mesh vertex positions. Shape: (batch_size, num_vertices_for_grid_b, 3).
mesh_faces (JaggedTensor) – Per-grid mesh face indices. Shape: (batch_size, num_faces_for_grid_b, 3).
voxel_sizes (NumericMaxRank2) – Size of each voxel, per-grid; broadcastable to shape (batch_size, 3), floating dtype.
origins (NumericMaxRank2) – World-space origin of each grid, per-grid; broadcastable to shape (batch_size, 3), floating dtype.

Returns:

grid_batch (GridBatch) – A new GridBatch with voxels covering mesh surfaces.

See also

Grid.from_mesh()

classmethod from_nanovdb(path: str, *, device: str | device = 'cpu', verbose: bool = False) → tuple[GridBatch, JaggedTensor, list[str]][source]

classmethod from_nanovdb(path: str, *, indices: list[int], device: str | device = 'cpu', verbose: bool = False) → tuple[GridBatch, JaggedTensor, list[str]]

classmethod from_nanovdb(path: str, *, index: int, device: str | device = 'cpu', verbose: bool = False) → tuple[GridBatch, JaggedTensor, list[str]]

classmethod from_nanovdb(path: str, *, names: list[str], device: str | device = 'cpu', verbose: bool = False) → tuple[GridBatch, JaggedTensor, list[str]]

classmethod from_nanovdb(path: str, *, name: str, device: str | device = 'cpu', verbose: bool = False) → tuple[GridBatch, JaggedTensor, list[str]]

Load a grid batch from a .nvdb file.

Parameters:

path (str) – Path to the .nvdb file to load.
indices (list[int] | None) – Optional list of grid indices to load.
index (int | None) – Optional single grid index to load.
names (list[str] | None) – Optional list of grid names to load.
name (str | None) – Optional single grid name to load.
device (DeviceIdentifier) – Device to load the grid batch on. Defaults to "cpu".
verbose (bool) – If True, print information about the loaded grids.

Returns:

grid_batch (GridBatch) – A GridBatch containing the loaded grids.
data (JaggedTensor) – A JaggedTensor containing voxel data.
names (list[str]) – Names of each loaded grid.

See also

Grid.from_nanovdb()

Create a grid batch by adding the eight nearest voxels to every input point.

Parameters:

points (JaggedTensor) – Per-grid world-space point positions. Shape: (batch_size, num_points_for_grid_b, 3).
voxel_sizes (NumericMaxRank2) – Size of each voxel, per-grid; broadcastable to shape (batch_size, 3), floating dtype.
origins (NumericMaxRank2) – World-space origin of each grid, per-grid; broadcastable to shape (batch_size, 3), floating dtype.

Returns:

grid_batch (GridBatch) – A new GridBatch with voxels surrounding each point.

See also

Grid.from_nearest_voxels_to_points()

Create a grid batch from point clouds by voxelizing each point’s location.

Parameters:

points (JaggedTensor) – Per-grid world-space point positions. Shape: (batch_size, num_points_for_grid_b, 3).
voxel_sizes (NumericMaxRank2) – Size of each voxel, per-grid; broadcastable to shape (batch_size, 3), floating dtype.
origins (NumericMaxRank2) – World-space origin of each grid, per-grid; broadcastable to shape (batch_size, 3), floating dtype.

Returns:

grid_batch (GridBatch) – A new GridBatch with one voxel per occupied point location.

See also

Grid.from_points()

classmethod from_zero_grids(device: str | device = 'cpu') → GridBatch[source]

Create an empty grid batch containing zero grids.

Parameters:: device (DeviceIdentifier) – Device to create the grid batch on. Defaults to "cpu".
Returns:: grid_batch (GridBatch) – A new empty GridBatch with grid_count == 0.

Create a grid batch with one or more grids that each have zero active voxels.

Parameters:

device (DeviceIdentifier) – Device to create the grid batch on. Defaults to "cpu".
voxel_sizes (NumericMaxRank2) – Voxel size per grid, broadcastable to shape (num_grids, 3), floating dtype.
origins (NumericMaxRank2) – World-space origin per grid, broadcastable to shape (num_grids, 3), floating dtype.

Returns:

grid_batch (GridBatch) – A new GridBatch with zero-voxel grids.

See also

Grid.from_zero_voxels()

property grid_count: int: Number of grids (int) in this grid batch.

has_same_address_and_grid_count(other: Any) → bool[source]

Check if another object shares the same underlying data address and grid count as this grid batch.

Parameters:: other (Any) – Object to compare with.
Returns:: result (bool) – True if both address and grid count match, False otherwise.

property has_zero_grids: bool: True (bool) if this grid batch contains zero grids.

has_zero_voxels_at(bi: int) → bool[source]

Check if a specific grid in this grid batch has zero active voxels.

Parameters:: bi (int) – Batch index of the grid.
Returns:: is_empty (bool) – True if the grid has zero voxels, False otherwise.

Return Hilbert curve codes for active voxels in this grid batch.

Parameters:: offset (NumericMaxRank1 | None) – Optional coordinate offset before encoding.
Returns:: codes (JaggedTensor) – Hilbert codes. Shape: (batch_size, num_voxels_for_grid_b, 1).

See also

Grid.hilbert()

Return zyx Hilbert curve codes (transposed) for active voxels in this grid batch.

Parameters:: offset (NumericMaxRank1 | None) – Optional coordinate offset before encoding.
Returns:: codes (JaggedTensor) – Transposed Hilbert codes. Shape: (batch_size, num_voxels_for_grid_b, 1).

See also

Grid.hilbert_zyx()

property ijk: JaggedTensor: Active voxel coordinates (JaggedTensor) of shape (batch_size, total_voxels, 3) in index order.

ijk_to_index(ijk: JaggedTensor, cumulative: bool = False) → JaggedTensor[source]

Convert voxel-space coordinates to linear indices for this grid batch.

Parameters:

ijk (JaggedTensor) – Voxel coordinates to convert. Shape: (batch_size, num_queries_for_grid_b, 3), integer dtype.
cumulative (bool) – If True, return batch-cumulative indices; otherwise per-grid.

Returns:

indices (JaggedTensor) – Linear indices, or -1 for inactive voxels. Shape: (batch_size, num_queries_for_grid_b).

See also

Grid.ijk_to_index()

ijk_to_inv_index(ijk: JaggedTensor, cumulative: bool = False) → JaggedTensor[source]

Get the inverse permutation of ijk_to_index() for this grid batch.

Parameters:

ijk (JaggedTensor) – Voxel coordinates to convert. Shape: (batch_size, num_queries_for_grid_b, 3), integer dtype.
cumulative (bool) – If True, return batch-cumulative indices; otherwise per-grid.

Returns:

inv_map (JaggedTensor) – Inverse permutation indices. Shape: (batch_size, num_queries_for_grid_b).

See also

Grid.ijk_to_inv_index()

index_int(bi: int | integer) → GridBatch[source]

Select a single grid from this grid batch by integer index.

Parameters:: bi (int | np.integer) – Grid index.
Returns:: grid_batch (GridBatch) – A new GridBatch containing the selected grid.

index_list(indices: list[bool] | list[int]) → GridBatch[source]

Select grids from this grid batch using a list of indices or booleans.

Parameters:: indices (list[bool] | list[int]) – List of grid indices or boolean mask.
Returns:: grid_batch (GridBatch) – A new GridBatch containing the selected grids.

index_slice(s: slice) → GridBatch[source]

Select grids from this grid batch using a slice.

Parameters:: s (slice) – Slice object specifying the range.
Returns:: grid_batch (GridBatch) – A new GridBatch containing the selected grids.

index_tensor(indices: Tensor) → GridBatch[source]

Select grids from this grid batch using a tensor of indices.

Parameters:: indices (torch.Tensor) – Integer or boolean tensor of grid indices.
Returns:: grid_batch (GridBatch) – A new GridBatch containing the selected grids.

inject_from(src_grid: GridBatch, src: JaggedTensor, dst: JaggedTensor | None = None, default_value: float | int | bool = 0) → JaggedTensor[source]

Inject data from a source grid batch into this grid batch in voxel space.

Supports backpropagation.

Parameters:

src_grid (GridBatch) – Source grid batch to inject data from.
src (JaggedTensor) – Source data. Shape: (batch_size, src_grid.total_voxels, *).
dst (JaggedTensor | None) – Optional destination data modified in-place, or None to create new.
default_value (float | int | bool) – Fill value for unmapped voxels when dst is None.

Returns:

dst (JaggedTensor) – Data after injection into this grid batch’s topology.

See also

Grid.inject_from()

Inject values from a dense CXYZ-ordered tensor into a JaggedTensor for this grid batch.

Supports backpropagation.

Parameters:

dense_data (torch.Tensor) – Dense tensor in CXYZ order. Shape: (batch_size, channels*, X, Y, Z).
dense_origins (NumericMaxRank1) – Dense tensor origin in voxel space, broadcastable to shape (3,), integer dtype.

Returns:

sparse_data (JaggedTensor) – Values at active voxel locations. Shape: (batch_size, total_voxels, channels*).

See also

Grid.inject_from_dense_cmajor()

Inject values from a dense XYZC-ordered tensor into a JaggedTensor for this grid batch.

Supports backpropagation.

Parameters:

dense_data (torch.Tensor) – Dense tensor in XYZC order. Shape: (batch_size, X, Y, Z, channels*).
dense_origins (NumericMaxRank1) – Dense tensor origin in voxel space, broadcastable to shape (3,), integer dtype.

Returns:

sparse_data (JaggedTensor) – Values at active voxel locations. Shape: (batch_size, total_voxels, channels*).

See also

Grid.inject_from_dense_cminor()

inject_from_ijk(src_ijk: JaggedTensor, src: JaggedTensor, dst: JaggedTensor | None = None, default_value: float | int | bool = 0)[source]

Inject data from explicit voxel coordinates into this grid batch.

Supports backpropagation.

Parameters:

src_ijk (JaggedTensor) – Source voxel coordinates. Shape: (batch_size, num_src_voxels, 3).
src (JaggedTensor) – Source data to inject. Shape: (batch_size, num_src_voxels, *).
dst (JaggedTensor | None) – Optional destination data modified in-place, or None to create new.
default_value (float | int | bool) – Fill value for unmapped voxels when dst is None.

Returns:

dst (JaggedTensor) – Data after injection into this grid batch’s topology.

See also

Grid.inject_from_ijk()

inject_to(dst_grid: GridBatch, src: JaggedTensor, dst: JaggedTensor | None = None, default_value: float | int | bool = 0) → JaggedTensor[source]

Inject data from this grid batch into a destination grid batch in voxel space.

Supports backpropagation.

Parameters:

dst_grid (GridBatch) – Destination grid batch to inject data into.
src (JaggedTensor) – Source data from this grid batch. Shape: (batch_size, total_voxels, *).
dst (JaggedTensor | None) – Optional destination data modified in-place, or None to create new.
default_value (float | int | bool) – Fill value for unmapped voxels when dst is None.

Returns:

dst (JaggedTensor) – Data after injection into the destination grid batch’s topology.

See also

Grid.inject_to()

Inject sparse voxel data from this grid batch into a dense CXYZ-ordered tensor.

Supports backpropagation.

Parameters:

sparse_data (JaggedTensor) – Sparse voxel data. Shape: (batch_size, total_voxels, channels*).
min_coord (NumericMaxRank2 | None) – Minimum voxel coordinate per grid, or None for auto.
grid_size (NumericMaxRank1 | None) – Output dense grid size, or None for auto.

Returns:

dense_data (torch.Tensor) – Dense tensor in CXYZ order. Shape: (batch_size, channels*, X, Y, Z).

See also

Grid.inject_to_dense_cmajor()

Inject sparse voxel data from this grid batch into a dense XYZC-ordered tensor.

Supports backpropagation.

Parameters:

sparse_data (JaggedTensor) – Sparse voxel data. Shape: (batch_size, total_voxels, channels*).
min_coord (NumericMaxRank2 | None) – Minimum voxel coordinate per grid, or None for auto.
grid_size (NumericMaxRank1 | None) – Output dense grid size, or None for auto.

Returns:

dense_data (torch.Tensor) – Dense tensor in XYZC order. Shape: (batch_size, X, Y, Z, channels*).

See also

Grid.inject_to_dense_cminor()

integrate_tsdf(truncation_distance: float, projection_matrices: Tensor, cam_to_world_matrices: Tensor, tsdf: JaggedTensor, weights: JaggedTensor, depth_images: Tensor, weight_images: Tensor | None = None) → tuple[GridBatch, JaggedTensor, JaggedTensor][source]

Integrate depth images into a TSDF volume for this grid batch.

Parameters:

truncation_distance (float) – Maximum TSDF truncation distance in world units.
projection_matrices (torch.Tensor) – Camera projection matrices. Shape: (batch_size, 3, 3).
cam_to_world_matrices (torch.Tensor) – Camera-to-world transforms. Shape: (batch_size, 4, 4).
tsdf (JaggedTensor) – Current TSDF values. Shape: (batch_size, total_voxels, 1).
weights (JaggedTensor) – Current integration weights. Shape: (batch_size, total_voxels, 1).
depth_images (torch.Tensor) – Depth images. Shape: (batch_size, height, width).
weight_images (torch.Tensor | None) – Per-pixel weights, or None for uniform.

Returns:

updated_grid (GridBatch) – Updated GridBatch with potentially expanded voxels.
updated_tsdf (JaggedTensor) – Updated TSDF values.
updated_weights (JaggedTensor) – Updated integration weights.

See also

Grid.integrate_tsdf()

integrate_tsdf_with_features(truncation_distance: float, projection_matrices: Tensor, cam_to_world_matrices: Tensor, tsdf: JaggedTensor, features: JaggedTensor, weights: JaggedTensor, depth_images: Tensor, feature_images: Tensor, weight_images: Tensor | None = None) → tuple[GridBatch, JaggedTensor, JaggedTensor, JaggedTensor][source]

Integrate depth and feature images into a TSDF volume for this grid batch.

Parameters:

truncation_distance (float) – Maximum TSDF truncation distance in world units.
projection_matrices (torch.Tensor) – Camera projection matrices. Shape: (batch_size, 3, 3).
cam_to_world_matrices (torch.Tensor) – Camera-to-world transforms. Shape: (batch_size, 4, 4).
tsdf (JaggedTensor) – Current TSDF values. Shape: (batch_size, total_voxels, 1).
features (JaggedTensor) – Current feature values. Shape: (batch_size, total_voxels, feature_dim).
weights (JaggedTensor) – Current integration weights. Shape: (batch_size, total_voxels, 1).
depth_images (torch.Tensor) – Depth images. Shape: (batch_size, height, width).
feature_images (torch.Tensor) – Feature images (e.g., RGB). Shape: (batch_size, height, width, feature_dim).
weight_images (torch.Tensor | None) – Per-pixel weights, or None for uniform.

Returns:

updated_grid (GridBatch) – Updated GridBatch with potentially expanded voxels.
updated_tsdf (JaggedTensor) – Updated TSDF values.
updated_weights (JaggedTensor) – Updated integration weights.
updated_features (JaggedTensor) – Updated per-voxel features.

See also

Grid.integrate_tsdf_with_features()

is_contiguous() → bool[source]

Check if this grid batch is stored contiguously in memory.

Returns:: is_contiguous (bool) – True if data is contiguous, False otherwise.

See also

Grid.is_contiguous()

is_same(other: GridBatch) → bool[source]

Check if another grid batch shares the same underlying data in memory as this grid batch.

Parameters:: other (GridBatch) – Grid batch to compare with.
Returns:: is_same (bool) – True if both share the same underlying data, False otherwise.

See also

Grid.is_same()

jagged_like(data: Tensor) → JaggedTensor[source]

Create a JaggedTensor with the same jagged structure as this grid batch.

Parameters:: data (torch.Tensor) – Dense data to wrap. Shape: (total_voxels, channels).
Returns:: jagged_data (JaggedTensor) – Data in jagged format matching this grid batch’s structure.

property jidx: Tensor: Per-voxel grid index (torch.Tensor) of shape (total_voxels,) for this grid batch.

property joffsets: Tensor: Jagged offset tensor (torch.Tensor) of shape (grid_count + 1,) defining grid boundaries.

marching_cubes(field: JaggedTensor, level: float = 0.0) → tuple[JaggedTensor, JaggedTensor, JaggedTensor][source]

Extract isosurface meshes from a scalar field on this grid batch using marching cubes.

Parameters:

field (JaggedTensor) – Scalar field values per voxel. Shape: (batch_size, total_voxels, 1).
level (float) – Isovalue at which to extract the surface.

Returns:

vertex_positions (JaggedTensor) – Mesh vertex positions. Shape: (batch_size, num_vertices_for_grid_b, 3).
face_indices (JaggedTensor) – Triangle face indices. Shape: (batch_size, num_faces_for_grid_b, 3).
vertex_normals (JaggedTensor) – Vertex normals. Shape: (batch_size, num_vertices_for_grid_b, 3).

See also

Grid.marching_cubes()

Apply max pooling to voxel data associated with this grid batch.

Supports backpropagation.

Parameters:

pool_factor (NumericMaxRank1) – Downsample factor, broadcastable to shape (3,), integer dtype.
data (JaggedTensor) – Voxel data to pool. Shape: (batch_size, total_voxels, channels).
stride (NumericMaxRank1) – Pooling stride; if 0, equals pool_factor. Broadcastable to shape (3,), integer dtype.
coarse_grid (GridBatch | None) – Optional pre-allocated coarse grid batch for output.

Returns:

pooled_data (JaggedTensor) – Pooled voxel data. Shape: (batch_size, coarse_total_voxels, channels).
coarse_grid (GridBatch) – The coarse grid batch topology after pooling.

See also

Grid.max_pool()

merged_grid(other: GridBatch) → GridBatch[source]

Return the union of this grid batch with another grid batch.

Parameters:: other (GridBatch) – Grid batch to merge with.
Returns:: merged_grid (GridBatch) – A new GridBatch containing the union of active voxels.

See also

Grid.merged_grid()

Return xyz Morton codes (Z-order curve) for active voxels in this grid batch.

Parameters:: offset (NumericMaxRank1 | None) – Optional coordinate offset before encoding.
Returns:: codes (JaggedTensor) – Morton codes. Shape: (batch_size, num_voxels_for_grid_b, 1).

See also

Grid.morton()

Return zyx Morton codes (transposed Z-order curve) for active voxels in this grid batch.

Parameters:: offset (NumericMaxRank1 | None) – Optional coordinate offset before encoding.
Returns:: codes (JaggedTensor) – Transposed Morton codes. Shape: (batch_size, num_voxels_for_grid_b, 1).

See also

Grid.morton_zyx()

neighbor_indexes(ijk: JaggedTensor, extent: int, bitshift: int = 0) → JaggedTensor[source]

Get N-ring neighbor indices for voxel coordinates in this grid batch.

Parameters:

ijk (JaggedTensor) – Voxel coordinates to find neighbors for. Shape: (batch_size, num_queries_for_grid_b, 3), integer dtype.
extent (int) – Neighborhood ring size.
bitshift (int) – Bit shift value for encoding.

Returns:

neighbor_indexes (JaggedTensor) – Neighbor linear indices (-1 for inactive). Shape: (batch_size, num_queries_for_grid_b, N).

See also

Grid.neighbor_indexes()

property num_bytes: Tensor: Memory size in bytes (torch.Tensor) of shape (grid_count,) for each grid in this grid batch.

property num_leaf_nodes: Tensor: NanoVDB leaf node count (torch.Tensor) of shape (grid_count,) for each grid in this grid batch.

property num_voxels: Tensor: Active voxel count (torch.Tensor) of shape (grid_count,) for each grid in this grid batch.

num_voxels_at(bi: int) → int[source]

Get the number of active voxels in a specific grid of this grid batch.

Parameters:: bi (int) – Batch index of the grid.
Returns:: num_voxels (int) – Number of active voxels in the specified grid.

origin_at(bi: int) → Tensor[source]

Get the world-space origin of a specific grid in this grid batch.

Parameters:: bi (int) – Batch index of the grid.
Returns:: origin (torch.Tensor) – Origin coordinates in world space. Shape: (3,).

property origins: Tensor: World-space origins (torch.Tensor) of shape (grid_count, 3) for each grid in this grid batch.

points_in_grid(points: JaggedTensor) → JaggedTensor[source]

Check if world-space points lie within active voxels of this grid batch.

Parameters:: points (JaggedTensor) – World-space points to test. Shape: (batch_size, num_points_for_grid_b, 3).
Returns:: mask (JaggedTensor) – Boolean mask of points in active voxels. Shape: (batch_size, num_points_for_grid_b).

See also

Grid.points_in_grid()

pruned_grid(mask: JaggedTensor) → GridBatch[source]

Return a pruned version of this grid batch keeping only masked voxels.

Parameters:: mask (JaggedTensor) – Boolean mask per voxel. Shape: (batch_size, total_voxels).
Returns:: pruned_grid (GridBatch) – A new GridBatch containing only voxels where mask is True.

See also

Grid.pruned_grid()

ray_implicit_intersection(ray_origins: JaggedTensor, ray_directions: JaggedTensor, grid_scalars: JaggedTensor, eps: float = 0.0) → JaggedTensor[source]

Find ray intersections with an implicit surface defined by scalar voxel data in this grid batch.

Parameters:

ray_origins (JaggedTensor) – Ray origins in world space. Shape: (batch_size, num_rays_for_grid_b, 3).
ray_directions (JaggedTensor) – Ray directions (should be normalized). Shape: (batch_size, num_rays_for_grid_b, 3).
grid_scalars (JaggedTensor) – Scalar field values per voxel. Shape: (batch_size, total_voxels, 1).
eps (float) – Epsilon for numerical stability.

Returns:

intersections (JaggedTensor) – Intersection information for each ray.

See also

Grid.ray_implicit_intersection()

rays_intersect_voxels(ray_origins: JaggedTensor, ray_directions: JaggedTensor, eps: float = 0.0) → JaggedTensor[source]

Check whether rays hit any active voxels in this grid batch.

Parameters:

ray_origins (JaggedTensor) – Ray origins in world space. Shape: (batch_size, num_rays_for_grid_b, 3).
ray_directions (JaggedTensor) – Ray directions. Shape: (batch_size, num_rays_for_grid_b, 3).
eps (float) – Epsilon for numerical stability.

Returns:

hit_mask (JaggedTensor) – Boolean mask indicating ray hits. Shape: (batch_size, num_rays_for_grid_b).

See also

Grid.rays_intersect_voxels()

Refine voxel data into higher-resolution grids by subdividing each voxel of this grid batch.

Supports backpropagation.

Parameters:

subdiv_factor (NumericMaxRank1) – Subdivision factor, broadcastable to shape (3,), integer dtype.
data (JaggedTensor) – Voxel data to refine. Shape: (batch_size, total_voxels, channels).
mask (JaggedTensor | None) – Optional boolean mask selecting which voxels to refine.
fine_grid (GridBatch | None) – Optional pre-allocated fine grid batch for output.

Returns:

refined_data (JaggedTensor) – Refined voxel data on the fine grid.
fine_grid (GridBatch) – The fine GridBatch containing the refined structure.

See also

Grid.refine()

Return a refined version of this grid batch by subdividing each voxel.

Parameters:

subdiv_factor (NumericMaxRank1) – Subdivision factor, broadcastable to shape (3,), integer dtype.
mask (JaggedTensor | None) – Optional boolean mask selecting which voxels to refine.

Returns:

refined_grid (GridBatch) – A new higher-resolution GridBatch.

See also

Grid.refined_grid()

sample_bezier(points: JaggedTensor, voxel_data: JaggedTensor) → JaggedTensor[source]

Sample voxel data at world-space points using Bezier interpolation on this grid batch.

Supports backpropagation.

Parameters:

points (JaggedTensor) – World-space sample points. Shape: (batch_size, num_points_for_grid_b, 3).
voxel_data (JaggedTensor) – Per-voxel data. Shape: (batch_size, total_voxels, channels*).

Returns:

interpolated_data (JaggedTensor) – Interpolated values. Shape: (batch_size, num_points_for_grid_b, channels*).

See also

Grid.sample_bezier()

sample_bezier_with_grad(points: JaggedTensor, voxel_data: JaggedTensor) → tuple[JaggedTensor, JaggedTensor][source]

Sample voxel data and spatial gradients at world-space points using Bezier interpolation on this grid batch.

Supports backpropagation.

Parameters:

points (JaggedTensor) – World-space sample points. Shape: (batch_size, num_points_for_grid_b, 3).
voxel_data (JaggedTensor) – Per-voxel data. Shape: (batch_size, total_voxels, channels*).

Returns:

interpolated_data (JaggedTensor) – Interpolated values. Shape: (batch_size, num_points_for_grid_b, channels*).
interpolation_gradients (JaggedTensor) – Spatial gradients. Shape: (batch_size, num_points_for_grid_b, 3, channels*).

See also

Grid.sample_bezier_with_grad()

sample_nearest(points: JaggedTensor, voxel_data: JaggedTensor) → JaggedTensor[source]

Sample voxel data at world-space points using nearest-neighbor lookup on this grid batch.

For each query point the 8 nearest voxel centers are checked and the value of the closest active one is returned. Points where none of the 8 surrounding voxel centers are active return zero, matching sample_trilinear() boundary behaviour.

Supports backpropagation w.r.t. voxel_data.

Parameters:

points (JaggedTensor) – World-space sample points. Shape: (batch_size, num_points_for_grid_b, 3).
voxel_data (JaggedTensor) – Per-voxel data. Shape: (batch_size, total_voxels, channels*).

Returns:

sampled_data (JaggedTensor) – Sampled values. Shape: (batch_size, num_points_for_grid_b, channels*).

sample_trilinear(points: JaggedTensor, voxel_data: JaggedTensor) → JaggedTensor[source]

Sample voxel data at world-space points using trilinear interpolation on this grid batch.

Supports backpropagation.

Parameters:

points (JaggedTensor) – World-space sample points. Shape: (batch_size, num_points_for_grid_b, 3).
voxel_data (JaggedTensor) – Per-voxel data. Shape: (batch_size, total_voxels, channels*).

Returns:

interpolated_data (JaggedTensor) – Interpolated values. Shape: (batch_size, num_points_for_grid_b, channels*).

See also

Grid.sample_trilinear()

sample_trilinear_with_grad(points: JaggedTensor, voxel_data: JaggedTensor) → tuple[JaggedTensor, JaggedTensor][source]

Sample voxel data and spatial gradients at world-space points using trilinear interpolation on this grid batch.

Supports backpropagation.

Parameters:

points (JaggedTensor) – World-space sample points. Shape: (batch_size, num_points_for_grid_b, 3).
voxel_data (JaggedTensor) – Per-voxel data. Shape: (batch_size, total_voxels, channels*).

Returns:

interpolated_data (JaggedTensor) – Interpolated values. Shape: (batch_size, num_points_for_grid_b, channels*).
interpolation_gradients (JaggedTensor) – Spatial gradients. Shape: (batch_size, num_points_for_grid_b, 3, channels*).

See also

Grid.sample_trilinear_with_grad()

save_nanovdb(path: str, data: JaggedTensor | None = None, names: list[str] | str | None = None, name: str | None = None, compressed: bool = False, verbose: bool = False) → None[source]

Save this grid batch and optional voxel data to a .nvdb file.

Parameters:

path (str) – File path to save to (should have .nvdb extension).
data (JaggedTensor | None) – Optional voxel data to save. Shape: (batch_size, total_voxels, channels).
names (list[str] | str | None) – Names for each grid, or a single name for all.
name (str | None) – Single name for all grids (takes precedence over names).
compressed (bool) – Whether to use Blosc compression.
verbose (bool) – Whether to print information about saved grids.

See also

Grid.save_nanovdb()

segments_along_rays(ray_origins: JaggedTensor, ray_directions: JaggedTensor, max_segments: int, eps: float = 0.0) → JaggedTensor[source]

Enumerate ray-voxel intersection segments for this grid batch.

Parameters:

ray_origins (JaggedTensor) – Ray origins in world space. Shape: (batch_size, num_rays_for_grid_b, 3).
ray_directions (JaggedTensor) – Ray directions. Shape: (batch_size, num_rays_for_grid_b, 3).
max_segments (int) – Maximum number of segments per ray.
eps (float) – Epsilon for numerical stability.

Returns:

ray_segments (JaggedTensor) – Segment start/end distances with eshape (2,).

See also

Grid.segments_along_rays()

splat_bezier(points: JaggedTensor, points_data: JaggedTensor) → JaggedTensor[source]

Splat point data onto voxels of this grid batch using Bezier interpolation weights.

Supports backpropagation.

Parameters:

points (JaggedTensor) – World-space point positions. Shape: (batch_size, num_points_for_grid_b, 3).
points_data (JaggedTensor) – Data to splat per point. Shape: (batch_size, num_points_for_grid_b, channels*).

Returns:

splatted_features (JaggedTensor) – Accumulated voxel features. Shape: (batch_size, total_voxels, channels*).

See also

Grid.splat_bezier()

splat_trilinear(points: JaggedTensor, points_data: JaggedTensor) → JaggedTensor[source]

Splat point data onto voxels of this grid batch using trilinear interpolation weights.

Supports backpropagation.

Parameters:

points (JaggedTensor) – World-space point positions. Shape: (batch_size, num_points_for_grid_b, 3).
points_data (JaggedTensor) – Data to splat per point. Shape: (batch_size, num_points_for_grid_b, channels*).

Returns:

splatted_features (JaggedTensor) – Accumulated voxel features. Shape: (batch_size, total_voxels, channels*).

See also

Grid.splat_trilinear()

Move this grid batch to a target device or match the device of a target object.

Parameters:: target (str | torch.device | torch.Tensor | JaggedTensor | Grid | GridBatch) – Device or object whose device to match.
Returns:: grid_batch (GridBatch) – A new GridBatch on the target device.

See also

Grid.to()

property total_bbox: Tensor: Voxel-space bounding box (torch.Tensor) of shape (2, 3) encompassing all grids in this grid batch.

property total_bytes: int: Total memory size in bytes (int) of all grids in this grid batch.

property total_leaf_nodes: int: Total NanoVDB leaf node count (int) across all grids in this grid batch.

property total_voxels: int: Total active voxel count (int) across all grids in this grid batch.

uniform_ray_samples(ray_origins: JaggedTensor, ray_directions: JaggedTensor, t_min: JaggedTensor, t_max: JaggedTensor, step_size: float, cone_angle: float = 0.0, include_end_segments: bool = True, return_midpoints: bool = False, eps: float = 0.0) → JaggedTensor[source]

Generate uniformly spaced samples along rays intersecting active voxels of this grid batch.

Parameters:

ray_origins (JaggedTensor) – Ray origins in world space. Shape: (batch_size, num_rays_for_grid_b, 3).
ray_directions (JaggedTensor) – Ray directions (should be normalized). Shape: (batch_size, num_rays_for_grid_b, 3).
t_min (JaggedTensor) – Minimum ray distance. Shape: (batch_size, num_rays_for_grid_b).
t_max (JaggedTensor) – Maximum ray distance. Shape: (batch_size, num_rays_for_grid_b).
step_size (float) – Distance between samples.
cone_angle (float) – Cone angle for cone tracing in radians.
include_end_segments (bool) – Whether to include partial end segments.
return_midpoints (bool) – If True, return midpoints instead of start/end pairs.
eps (float) – Epsilon for numerical stability.

Returns:

ray_samples (JaggedTensor) – Sample distances with eshape (2,) or (1,) if return_midpoints.

See also

Grid.uniform_ray_samples()

voxel_size_at(bi: int) → Tensor[source]

Get the voxel size of a specific grid in this grid batch.

Parameters:: bi (int) – Batch index of the grid.
Returns:: voxel_size (torch.Tensor) – Voxel size. Shape: (3,).

property voxel_sizes: Tensor: World-space voxel sizes (torch.Tensor) of shape (grid_count, 3) for each grid in this grid batch.

voxel_to_world(ijk: JaggedTensor) → JaggedTensor[source]

Transform voxel-space coordinates to world-space positions for this grid batch.

Supports backpropagation.

Parameters:: ijk (JaggedTensor) – Voxel-space coordinates to convert. Shape: (batch_size, num_points_for_grid_b, 3).
Returns:: world_coords (JaggedTensor) – World-space coordinates. Shape: (batch_size, num_points_for_grid_b, 3).

See also

Grid.voxel_to_world()

property voxel_to_world_matrices: Tensor: Voxel-to-world transformation matrices (torch.Tensor) of shape (grid_count, 4, 4) for this grid batch.

voxels_along_rays(ray_origins: JaggedTensor, ray_directions: JaggedTensor, max_voxels: int, eps: float = 0.0, return_ijk: bool = True, cumulative: bool = False) → tuple[JaggedTensor, JaggedTensor][source]

Enumerate active voxels intersected by rays in this grid batch via DDA traversal.

Parameters:

ray_origins (JaggedTensor) – Ray origins in world space. Shape: (batch_size, num_rays_for_grid_b, 3).
ray_directions (JaggedTensor) – Ray directions. Shape: (batch_size, num_rays_for_grid_b, 3).
max_voxels (int) – Maximum number of voxels to return per ray.
eps (float) – Epsilon for numerical stability.
return_ijk (bool) – If True, return ijk coordinates; otherwise linear indices.
cumulative (bool) – If True, return batch-cumulative indices.

Returns:

voxels (JaggedTensor) – Voxel coordinates (eshape (3,)) or linear indices per ray hit.
times (JaggedTensor) – Entry/exit distances along each ray with eshape (2,).

See also

Grid.voxels_along_rays()

world_to_voxel(points: JaggedTensor) → JaggedTensor[source]

Transform world-space coordinates to voxel-space coordinates for this grid batch.

Supports backpropagation.

Parameters:: points (JaggedTensor) – World-space positions to convert. Shape: (batch_size, num_points_for_grid_b, 3).
Returns:: voxel_points (JaggedTensor) – Voxel-space coordinates (may be fractional). Shape: (batch_size, num_points_for_grid_b, 3).

See also

Grid.world_to_voxel()

property world_to_voxel_matrices: Tensor: World-to-voxel transformation matrices (torch.Tensor) of shape (grid_count, 4, 4) for this grid batch.