lagrange.volume¶

volume module

Classes¶

`Compression`	Compression method for VDB and NanoVDB grid IO
`Grid`
`GridClass`	Grid class tag indicating the semantic interpretation of voxel values
`Sign`	Signing method used to determine inside/outside voxels

Module Contents¶

class lagrange.volume.Compression¶

Bases: enum.Enum

Compression method for VDB and NanoVDB grid IO

Blosc = 2¶: Blosc compression.

Uncompressed = 0¶: No compression.

Zip = 1¶: Zip compression.

class lagrange.volume.Grid¶

comp_div(other)¶

Per-voxel self / other, stored in self. other is left empty.

Parameters:: other (Grid) – Grid of the same scalar type.
Return type:: None

comp_max(other)¶

Per-voxel max(self, other), stored in self. other is left empty.

Parameters:: other (Grid) – Grid of the same scalar type.
Return type:: None

comp_min(other)¶

Per-voxel min(self, other), stored in self. other is left empty.

Parameters:: other (Grid) – Grid of the same scalar type.
Return type:: None

comp_mul(other)¶

Per-voxel self * other, stored in self. other is left empty.

Parameters:: other (Grid) – Grid of the same scalar type.
Return type:: None

comp_sum(other)¶

Per-voxel self + other, stored in self. other is left empty.

Parameters:: other (Grid) – Grid of the same scalar type.
Return type:: None

csg_difference(other)¶

Replace this level set grid with the CSG difference self minus other.

Parameters:: other (Grid) – Level set grid of the same scalar type. Left empty after the call.
Return type:: None

csg_intersection(other)¶

Replace this level set grid with the CSG intersection of itself and other.

Parameters:: other (Grid) – Level set grid of the same scalar type. Left empty after the call.
Return type:: None

csg_union(other)¶

Replace this level set grid with the CSG union of itself and other.

Parameters:: other (Grid) – Level set grid of the same scalar type. Left empty after the call.
Return type:: None

densify()¶

Densify the grid by filling in inactive voxels within the active voxel bounding box.

Returns:: Densified grid.
Return type:: Grid

static from_mesh(mesh, voxel_size=-0.01, signing_method=Sign.FloodFill, dtype=numpy.float32)¶

Convert a triangle mesh to a sparse voxel grid, writing the result to a file.

Parameters:

mesh (lagrange.core.SurfaceMesh) – Input mesh. Must be a triangle mesh, a quad-mesh, or a quad-dominant mesh.
voxel_size (float) – Voxel size. Negative means relative to bbox diagonal (vs -> -vs * bbox_diag).
signing_method (Sign) – Method used to compute the sign of the distance field.
dtype (type) – Scalar type of the output grid (float32 or float64).

Returns:

Generated sparse voxel grid.

Return type:

Grid

static from_points(points, values, dtype=numpy.float32)¶

Create a sparse voxel grid from a list of voxel index coordinates and values.

Parameters:

points (Annotated[numpy.typing.NDArray[numpy.int32], dict(shape=(None, 3), order='C', device='cpu', writable=False)]) – Voxel index-space coordinates as an (N, 3) array of int32.
values (Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(None, ), order='C', device='cpu', writable=False)] | Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=(None, ), order='C', device='cpu', writable=False)]) – Values at each voxel as a 1D array of float32 or float64 of length N.
dtype (type) – Scalar type of the output grid (float32 or float64).

Returns:

Sparse voxel grid with the given values active at the given index coordinates.

Return type:

Grid

index_to_world(indices)¶

Convert a set of voxel indices to world coordinates.

Parameters:: indices (Annotated[numpy.typing.NDArray[numpy.int32], dict(shape=(None, 3), order='C', device='cpu', writable=False)] | Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(None, 3), order='C', device='cpu', writable=False)] | Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=(None, 3), order='C', device='cpu', writable=False)]) – Input voxel indices as an (N, 3) array of integers or double.
Returns:: World coordinates as an (N, 3) array of double.
Return type:: Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(None, 3), order=’F’)] | Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=(None, 3), order=’F’)]

static load(input_path_or_buffer)¶

Load a grid from a file or memory buffer.

Parameters:: input_path_or_buffer (str | os.PathLike | bytes) – Input file path (str or pathlib.Path) or memory buffer (bytes).
Returns:: Loaded grid.
Return type:: Grid

offset_in_place(offset_radius, relative=False)¶

Apply an offset to the signed distance field in-place.

Parameters:

offset_radius (float) – Offset radius. A negative value dilates the surface, a positive value erodes it.
relative (bool) – Whether the offset radius is relative to the grid voxel size.

Return type:

None

prune(tolerance=0.0)¶

Remove nodes whose values all equal the background value within the given tolerance.

Parameters:: tolerance (float) – Tolerance for pruning. Default is 0.
Return type:: None

redistance()¶

Recompute the signed distance values of the grid using a fast sweeping method.

Returns:: Redistanced grid.
Return type:: Grid

resample(voxel_size)¶

Resample the grid to a new voxel size.

Parameters:: voxel_size (float) – New voxel size. Negative means relative to the input grid voxel size.
Returns:: Resampled grid.
Return type:: Grid

sample_trilinear_index_space(points)¶

Sample the grid at the given world coordinates using trilinear interpolation.

Parameters:: points (Annotated[numpy.typing.NDArray[numpy.int32], dict(shape=(None, 3), order='C', device='cpu', writable=False)] | Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(None, 3), order='C', device='cpu', writable=False)] | Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=(None, 3), order='C', device='cpu', writable=False)]) – Input index coordinates as an (N, 3) array of integers or double.
Returns:: Sampled values as an (N,) array of double.
Return type:: Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(None, ), order=’C’)] | Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=(None, ), order=’C’)]

sample_trilinear_world_space(points)¶

Sample the grid at the given world coordinates using trilinear interpolation.

Parameters:: points (Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(None, 3), order='C', device='cpu', writable=False)] | Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=(None, 3), order='C', device='cpu', writable=False)]) – Input world coordinates as an (N, 3) array of double.
Returns:: Sampled values as an (N,) array of double.
Return type:: Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(None, ), order=’C’)] | Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=(None, ), order=’C’)]

save(output_path, compression=Compression.Blosc)¶

Save the grid to a file.

Parameters:

output_path (str | os.PathLike) – Output file path (str or pathlib.Path).
compression (Compression) – Compression method to use. Default is Blosc.

Return type:

None

to_buffer(grid_type, compression=Compression.Blosc)¶

Save the grid to a memory buffer.

Parameters:

grid_type (Literal['vdb', 'nvdb']) – Output grid type, either ‘vdb’ or ‘nvdb’.
compression (Compression) – Compression method to use. Default is Blosc.

Returns:

Memory buffer (bytes).

Return type:

bytes

to_mesh(isovalue=0.0, adaptivity=0.0, relax_disoriented_triangles=True, normal_attribute_name=None)¶

Mesh the isosurface of a sparse voxel grid.

Parameters:

grid – Input grid to mesh.
isovalue (float) – Value of the isosurface.
adaptivity (float) – Surface adaptivity threshold [0 to 1]. 0 keeps the original quad mesh, while 1 simplifies the most.
relax_disoriented_triangles (bool) – Toggle relaxing disoriented triangles during adaptive meshing.
normal_attribute_name (str | None) – If provided, computes vertex normals from the volume and store them in the appropriately named attribute.

Returns:

Meshed isosurface.

Return type:

core.SurfaceMesh

world_to_index(points)¶

Convert a set of world coordinates to voxel indices.

Parameters:: points (Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(None, 3), order='C', device='cpu', writable=False)] | Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=(None, 3), order='C', device='cpu', writable=False)]) – Input world coordinates as an (N, 3) array of double.
Returns:: Voxel indices as an (N, 3) array of double.
Return type:: Annotated[numpy.typing.NDArray[numpy.float32], dict(shape=(None, 3), order=’F’)] | Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=(None, 3), order=’F’)]

property background: float | float¶

The grid background value.

Return type:: float | float

property bbox_index: Annotated[numpy.typing.NDArray[numpy.int32], dict(shape=2, 3, order='F')]¶

Return the axis-aligned bounding box of all active voxels in index space. If the grid is empty a default bbox is returned.

Return type:: Annotated[numpy.typing.NDArray[numpy.int32], dict(shape=(2, 3), order=’F’)]

property bbox_world: Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=2, 3, order='F')]¶

Return the axis-aligned bounding box of all active voxels in world space. If the grid is empty a default bbox is returned.

Return type:: Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=(2, 3), order=’F’)]

property grid_class: GridClass¶

The grid class tag.

Return type:: GridClass

property name: str¶

The grid name.

Return type:: str

property num_active_voxels: int¶

Return the number of active voxels in the grid.

Return type:: int

property transform: Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=4, 4, order='F')]¶

The grid’s index-to-world 4x4 affine transform matrix (column-vector convention).

Return type:: Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=(4, 4), order=’F’)]

property voxel_size: Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=3, order='C')]¶

Return the grid voxel size.

Return type:: Annotated[numpy.typing.NDArray[numpy.float64], dict(shape=3, order=’C’)]

class lagrange.volume.GridClass¶

Bases: enum.Enum

Grid class tag indicating the semantic interpretation of voxel values

FogVolume = 2¶: Fog volume (density values).

LevelSet = 1¶: Narrow-band signed distance field.

Staggered = 3¶: Staggered vector field.

Unknown = 0¶: Unknown or generic grid class.

class lagrange.volume.Sign¶

Bases: enum.Enum

Signing method used to determine inside/outside voxels

FloodFill = 0¶: Default voxel flood-fill method used by OpenVDB.

Unsigned = 2¶: Do not compute sign, output unsigned distance field.

WindingNumber = 1¶: Fast winding number method based on [Barill et al. 2018].