| Title: | Sparse Volumes with an 'OpenVDB' Runtime Interface |
|---|---|
| Description: | Creates, edits, and samples sparse volumetric grids using 'OpenVDB' <https://www.openvdb.org/>. Supports signed distance fields, constructive solid geometry, conversion between triangle meshes and volumes, file exchange, and a native runtime interface. |
| Authors: | Tyler Morgan-Wall [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-3131-3814>), Contributors to the OpenVDB Project [ctb, cph], Intel Corporation and oneTBB contributors [cph], Blosc Development Team [cph] |
| Maintainer: | Tyler Morgan-Wall <[email protected]> |
| License: | Apache License (== 2.0) |
| Version: | 13.1.0-2 |
| Built: | 2026-11-16 06:17:30 UTC |
| Source: | https://github.com/tylermorganwall/openvdbr |
Copy or release a native grid
vdb_clone(grid) vdb_close(grid)vdb_clone(grid) vdb_close(grid)
grid |
An |
Closing a handle also closes every R alias of that handle. The handle remains identifiable, but further operations report that it is closed.
vdb_clone() returns an independent deep copy. vdb_close() releases
the native storage and invisibly returns NULL; repeated closes are safe.
original = vdb_grid() copy = vdb_clone(original) vdb_set(copy, c(0, 0, 0), 1) vdb_get(original, c(0, 0, 0)) vdb_close(copy)original = vdb_grid() copy = vdb_clone(original) vdb_set(copy, c(0, 0, 0), 1) vdb_get(original, c(0, 0, 0)) vdb_close(copy)
Combine level-set surfaces
vdb_csg(a, b, operation = c("union", "intersection", "difference"))vdb_csg(a, b, operation = c("union", "intersection", "difference"))
a |
First float-valued level-set grid. |
b |
Second float-valued level-set grid with the same transform and band width. |
operation |
Default |
These are OpenVDB's level-set CSG operations. They combine signed distances; they do not resample mismatched grids or rebuild distance bands.
A new level-set grid. Both inputs remain unchanged.
Convert a signed distance field into a fog volume
vdb_fog(grid)vdb_fog(grid)
grid |
A float-valued level-set grid. |
This produces a bounded density field suitable for volumetric rendering. It retains the source transform and name and leaves the input intact.
A new fog-volume grid with density zero outside and density approaching one inside. The transition spans the input's interior narrow band.
Convert a triangle mesh into a sparse level set
vdb_from_mesh( vertices, triangles, voxel_size = 0.1, half_width = 3, name = "surface" )vdb_from_mesh( vertices, triangles, voxel_size = 0.1, half_width = 3, name = "surface" )
vertices |
Numeric matrix with three columns of world-space vertex coordinates. |
triangles |
Integer matrix with three columns of one-based vertex indices. |
voxel_size |
Default |
half_width |
Default |
name |
Default |
Use a closed, consistently oriented surface for meaningful interior signs. OpenVDB accepts world-space vertices at float precision; this function does not repair nonmanifold or self-intersecting geometry.
A float-valued level-set grid.
vertices = rbind(c(-1, -1, -1), c(1, -1, -1), c(0, 1, -1), c(0, 0, 1)) triangles = rbind(c(1, 3, 2), c(1, 2, 4), c(2, 3, 4), c(3, 1, 4)) pyramid = vdb_from_mesh(vertices, triangles, voxel_size = 0.2) vdb_sample(pyramid, c(0, 0, 0))vertices = rbind(c(-1, -1, -1), c(1, -1, -1), c(0, 1, -1), c(0, 0, 1)) triangles = rbind(c(1, 3, 2), c(1, 2, 4), c(2, 3, 4), c(3, 1, 4)) pyramid = vdb_from_mesh(vertices, triangles, voxel_size = 0.2) vdb_sample(pyramid, c(0, 0, 0))
Read exact voxel values and activation flags
vdb_get(grid, xyz)vdb_get(grid, xyz)
grid |
An |
xyz |
A coordinate triple or three-column matrix of zero-based integer voxel indices. Negative indices are allowed. |
A list containing numeric value and logical active vectors.
Store values only where they differ from a shared background. This is useful for smoke density, temperature fields, signed distances and other volumes whose bounding box would waste memory as a dense R array.
vdb_grid( background = 0, voxel_size = 1, origin = c(0, 0, 0), name = "density", type = c("float", "double") )vdb_grid( background = 0, voxel_size = 1, origin = c(0, 0, 0), name = "density", type = c("float", "double") )
background |
Default |
voxel_size |
Default |
origin |
Default |
name |
Default |
type |
Default |
Voxel indices are zero-based spatial coordinates and can be negative.
Handles have reference semantics: assigning a handle to another variable
shares the same grid. Use vdb_clone() for an independent copy. Handles
cannot be saved with saveRDS(); use vdb_write() to persist the data.
An openvdbr_grid external pointer, released automatically by garbage
collection or explicitly by vdb_close().
cloud = vdb_grid(voxel_size = 0.5) vdb_set(cloud, rbind(c(-1, 0, 0), c(0, 0, 0), c(1, 0, 0)), c(0.2, 1, 0.2)) vdb_sample(cloud, c(0.25, 0, 0)) vdb_info(cloud)cloud = vdb_grid(voxel_size = 0.5) vdb_set(cloud, rbind(c(-1, 0, 0), c(0, 0, 0), c(1, 0, 0)), c(0.2, 1, 0.2)) vdb_sample(cloud, c(0.25, 0, 0)) vdb_info(cloud)
Inspect a sparse grid
vdb_info(grid)vdb_info(grid)
grid |
An |
A list with the grid name, value type, class, active voxel count,
estimated native memory in bytes, inclusive index bounds, voxel widths,
world-space origin and scalar background. Empty grids have zero bounds;
check empty before using them. Counts are doubles to support large grids.
Non-scalar backgrounds are reported as NaN.
Collect warnings and informational diagnostics from the bundled libraries, including messages produced on worker threads. Operation failures still raise ordinary R errors (or return a status to native consumers).
vdb_messages()vdb_messages()
The queue is global to this provider. It retains up to 128 messages
of 511 bytes each, then reports a count of dropped messages. This bounds
memory on error paths and avoids console calls from worker threads.
Native consumers can drain the same queue with diagnostic_next().
A character vector of pending messages, removed from the queue.
VDB files can contain several named sparse volumes, each with its own value type, metadata and spatial transform. Inspect their names before selecting a density, temperature or signed-distance grid.
vdb_read(filename, grid = 1) vdb_grid_names(filename)vdb_read(filename, grid = 1) vdb_grid_names(filename)
filename |
Path to a VDB file. |
grid |
Default |
The bundled OpenVDB implementation includes Blosc and zlib compression. All upstream registered grid types can be read and written without conversion. Editing, scalar sampling and meshing currently support float and double scalar grids; vector and point grids can be inspected and passed through.
vdb_grid_names() returns character names without loading voxel data.
vdb_read() returns a native grid handle. Its selected grid is fully loaded
and independent of the source file, which can subsequently be moved or removed.
file = tempfile(fileext = '.vdb') shape = vdb_sphere(radius = 1, voxel_size = 0.2, name = 'surface') density = vdb_fog(shape) vdb_write(shape, file) vdb_grid_names(file) restored = vdb_read(file, 'surface') vdb_sample(restored, c(0, 0, 0)) unlink(file)file = tempfile(fileext = '.vdb') shape = vdb_sphere(radius = 1, voxel_size = 0.2, name = 'surface') density = vdb_fog(shape) vdb_write(shape, file) vdb_grid_names(file) restored = vdb_read(file, 'surface') vdb_sample(restored, c(0, 0, 0)) unlink(file)
Sample a sparse volume at arbitrary positions
vdb_sample( grid, xyz, space = c("world", "index"), interpolation = c("linear", "nearest") )vdb_sample( grid, xyz, space = c("world", "index"), interpolation = c("linear", "nearest") )
grid |
An |
xyz |
A coordinate triple or three-column numeric matrix. |
space |
Default |
interpolation |
Default |
Sampling includes stored inactive values, which are significant for signed distance fields. Trilinear interpolation uses eight neighboring voxels. The complete transform of an imported grid is respected, including rotations.
A numeric vector with one sampled value per row.
Edit sparse voxel values
vdb_set(grid, xyz, values, active = TRUE)vdb_set(grid, xyz, values, active = TRUE)
grid |
An |
xyz |
A numeric vector of length three or a matrix with three columns.
Each row is a zero-based integer coordinate |
values |
Finite voxel values, one per coordinate or a single value to repeat. |
active |
Default |
Inactive voxels can retain values different from the background. Level sets use this to represent their negative interiors compactly. Duplicate coordinates are applied in input order, so the last value wins. Validation occurs before editing; allocation failures may leave a partial edit.
The input handle, invisibly, after modifying it in place.
A level set stores distance to a surface in a narrow band. Values are negative inside and positive outside, with distant values clamped to the band width. This supports smooth surface operations without allocating a dense volume.
vdb_sphere( radius = 1, center = c(0, 0, 0), voxel_size = 0.1, half_width = 3, name = "surface" )vdb_sphere( radius = 1, center = c(0, 0, 0), voxel_size = 0.1, half_width = 3, name = "surface" )
radius |
Default |
center |
Default |
voxel_size |
Default |
half_width |
Default |
name |
Default |
A float-valued level-set grid.
# A snowman silhouette made from two sparse level sets. body = vdb_sphere(1, voxel_size = 0.15) head = vdb_sphere(0.6, center = c(0, 1.2, 0), voxel_size = 0.15) snowman = vdb_csg(body, head) axis = seq(-1.5, 2, length.out = 60) points = as.matrix(expand.grid(x = axis, y = axis, z = 0)) section = matrix(vdb_sample(snowman, points), length(axis)) graphics::contour(axis, axis, section, levels = 0, asp = 1, drawlabels = FALSE)# A snowman silhouette made from two sparse level sets. body = vdb_sphere(1, voxel_size = 0.15) head = vdb_sphere(0.6, center = c(0, 1.2, 0), voxel_size = 0.15) snowman = vdb_csg(body, head) axis = seq(-1.5, 2, length.out = 60) points = as.matrix(expand.grid(x = axis, y = axis, z = 0)) section = matrix(vdb_sample(snowman, points), length(axis)) graphics::contour(axis, axis, section, levels = 0, asp = 1, drawlabels = FALSE)
Extract a triangle mesh from a scalar volume
vdb_to_mesh(grid, isovalue = 0, adaptivity = 0)vdb_to_mesh(grid, isovalue = 0, adaptivity = 0)
grid |
A float or double scalar grid. |
isovalue |
Default |
adaptivity |
Default |
A list of vertices (three-column world-space numeric matrix) and
triangles (three-column, one-based integer indices). OpenVDB quads are
triangulated with their original winding preserved.
surface = vdb_to_mesh(vdb_sphere(voxel_size = 0.2), adaptivity = 0.2) graphics::plot(surface$vertices[, c(1, 2)], asp = 1, pch = '.', xlab = 'x', ylab = 'y')surface = vdb_to_mesh(vdb_sphere(voxel_size = 0.2), adaptivity = 0.2) graphics::plot(surface$vertices[, c(1, 2)], asp = 1, pch = '.', xlab = 'x', ylab = 'y')
OpenVDB runtime version and native interface
vdb_version() vdb_api()vdb_version() vdb_api()
Native consumers can use LinkingTo: openvdbr for the small C headers
and Imports: openvdbr to ensure the provider is loaded. On R's main thread,
call openvdbr_api_get_v1() from openvdbr/openvdbr_r.h. It retrieves
openvdbr_get_api_v1 using R_GetCCallable(). No OpenVDB linker flags or
OpenVDB C++ headers are needed by the consumer.
The table uses opaque handles and caller-owned error buffers. Read-only sampling calls can run concurrently with separate output buffers. Mutating or closing a grid must not overlap any access to that grid. File handles require exclusive access. Runtime lookup and all R API calls must remain on R's main thread. Explicitly unloading the provider DLL while handles or consumers remain alive is unsupported.
vdb_version() returns the bundled OpenVDB version.
vdb_api() returns an external pointer to the version-one C function table,
retaining the package namespace for the lifetime of the handle.
Write sparse grids to a VDB file
vdb_write(grids, filename, overwrite = FALSE)vdb_write(grids, filename, overwrite = FALSE)
grids |
A native grid or a list of native grids. Each grid retains its own name, value type, metadata and transform. |
filename |
Output path, including a |
overwrite |
Default |
The output filename, invisibly.