Provided by: libopenvdb-tools_10.0.1-1ubuntu1_amd64 
NAME
vdb_tool - perform a use-defined sequence of tasks
SYNOPSIS
This command-line tool, dubbed vdb_tool, can combine any number of the of high-level tools
available in openvdb/tools. For instance, it can convert a sequence of polygon meshes and
particles to level sets, and perform a large number of operations on these level set
surfaces. It can also generate adaptive polygon meshes from level sets, ray-trace images
and export particles, meshes or VDBs to disk or even stream VDBs to STDOUT so other tools
can render them (using pipelining). We denote the operations **actions**, and their
arguments **options**. Any sequence of **actions** and their **options** can be exported
and imported to configuration files, which allows convenient reuse. This command-line tool
also supports a string-evaluation language that can be used to define procedural
expressions for options of the actions. Currently the following list of actions are
supported:
| Action | Description |
|-------|-------|
| **for/end** | Defines the scope of a for-loop with a range for a loop-variable |
| **each/end** | Defines the scope of an each-loop with a list for a loop-variable |
| **if/end** | If-statement used to enable/disable actions |
| **eval** | Evaluate an expression written in our Reverse Polish Notation (see below) |
| **config** | Load a configuration file and add the actions for processing |
| **default** | Set default values used by all subsequent actions |
| **read** | Read mesh, points and level sets as obj, ply, abc, stl, pts, vdb or nvdb
files |
| **write** | Write a polygon mesh, points or level set as a obj, ply, stl, abc or vdb
file |
| **vdb2points** | Extracts points from a VDB grid |
| **mesh2ls** | Convert a polygon mesh to a narrow-band level set |
| **points2ls** | Convert points into a narrow-band level set |
| **points2vdb** | Converts points into a VDB PointDataGrid |
| **iso2ls** | Convert an iso-surface of a scalar field into a level set |
| **ls2fog** | Convert a level set into a fog volume |
| **segment** | Segment level set and float grids into its disconnected parts |
| **sphere** | Create a narrow-band level set of a sphere |
| **platonic** | Create a narrow-band level set of a tetrahedron(4), cube(6),
octahedron(8), dodecahedron(12) or icosahedron(2) |
| **dilate** | Dilate a level set surface |
| **erode** | Erode a level set surface |
| **open** | Morphological opening of a level set surface |
| **close** | Morphological closing of a level set surface |
| **gauss** | Gaussian convolution of a level set surface, i.e. surface smoothing |
| **mean** | Mean-value filtering of a level set surface |
| **median** | Median-value filtering of a level set surface |
| **union** | Union of two narrow-band level sets |
| **intersection** | Intersection of two narrow-band level sets |
| **difference** | Difference of two narrow-band level sets |
| **prune** | Prune the VDB tree of a narrow-band level set |
| **flood** | Signed flood-fill of a narrow-band level set |
| **cpt** | Closest point transform of a narrow-band level set |
| **grad**| Gradient vector of a scalar VDB |
| **curl** | Curl of a vector VDB |
| **div** | Compute the divergence of a vector VDB |
| **curvature** | Mean curvature of a scalar VDB |
| **length** | Compute the magnitude of a vector VDB |
| **min** | Composite two grid by means of min |
| **max** | Composite two grid by means of max |
| **sum** | Composite two grid by means of sum |
| **multires** | Compute multi-resolution grids |
| **enright** | Advects a level set in a periodic and divergence-free velocity field.
Primarily intended for benchmarks |
| **expand** | Expand the narrow band of a level set |
| **resample** | Re-sample a scalar VDB grid |
| **transform** | Apply affine transformations to VDB grids |
| **ls2mesh** | Convert a level set surface into an adaptive polygon mesh surface |
| **clip** | Clips one VDB grid with another VDB grid or a bbox or frustum |
| **render**| Render and save an image of a level set or fog VDB |
| **clear** | Deletes cached VDB grids and geometry from memory |
| **print** | Print information about the cached geometries and VDBs |
DESCRIPTION
This command-line tool can perform a use-defined, and possibly non-linear, sequence of
high-level tasks available in openvdb. For instance, it can convert polygon meshes and
particles to level sets, and subsequently perform a large number of operations on these
level set surfaces. It can also generate adaptive polygon meshes from level sets, write
them to disk and even render them to image files.
Version: 10.6.1 Surface points: vdb_tool -read points.[obj/ply/stl/pts] -points2ls d=256
r=2.0 w=3 -dilate r=2 -gauss i=1 w=1 -erode r=2 -ls2m a=0.25 -write output.[ply/obj/stl]
Convert mesh: vdb_tool -read mesh.[ply/obj] -mesh2ls d=256 -write output.vdb config.txt
Config example: vdb_tool -config config.txt
-clear Deletes geometry, VDB grids and local variables
geo *|0,1,... List of geometries to delete (defaults to all)
vdb *|0,1,... List of VDB grids to delete (defaults to all)
variables
1|0|true|false Clear all the local variables (defaults to off)
-clip Clip a VDB grid against another grid, a bbox or frustum
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
bbox (0,0,0),(1,1,1) Min and max of the world-space bounding-box used for clipping.
Defaults to empty, i.e. disabled
taper 1 Taper of the frustum (requires bbox and depth to be specified). Defaults to -1,
i.e. disabled
depth 1 Depth in world units of the frustum (requires bbox and taper to be specified).
Defaults to -1, i.e. disabled
mask 1 Age (i.e. stack index) of a mask VDB used for clipping. Defaults to -1, i.e.
disabled
-close Morphological closing, i.e. dilation followed by erosion, of level
set surface by a fixed radius
radius 1.0 Radius in voxel units by which the surface is closed
space 1|2|3|5 Order of the spatial discretization (defaults to 5, i.e. WENO)
time 1|2|3 Order of the temporal discretization (defaults to 1, i.e. explicit Euler)
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
-config,-c Import and process one or more configuration files
files config1.txt,config2.txt... List of configuration files to load and execute
execute
1|0|true|false Toggle wether to execute the actions in the config file
update 1|0|true|false Toggle wether to update the version number of the config file
-cpt Generate a vector grid with the closest-point-transform to a level
set surface
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
-curl Generate a vector grid with the curl of another vector grid
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
-curvature Generate scalar grid with the mean curvature of a level set surface
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
-debug Print debugging information to the terminal
-default Define default values to be used by subsequent actions
dim 256 Default grid resolution along the longest axis
voxel 0.01 Default voxel size in world units. A value of zero indicates that dim is used
to derive the voxel size.
width 3.0 Default narrow-band width of level sets in voxel units
time 1|2|3 Default temporal discretization order
space 1|2|3|5 Default spatial discretization order
keep 1|0|true|false By default delete the input
-difference CSG difference of two level sets surfaces
vdb 0,1 Ages (i.e. stack indices) of the two VDB grids to difference. Defaults to 0,1,
i.e. two most recently inserted VDBs.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
prune true Toggle wether to prune the tree after the boolean operation (enabled by
default)
rebuild
true Toggle wether to re-build the level set after the boolean operation (enabled
by default)
-dilate Erode level set surface by a fixed radius
radius 1.0 Radius in voxel units by which the surface is dilated
space 1|2|3|5 Order of the spatial discretization (defaults to 5, i.e. WENO)
time 1|2|3 Order of the temporal discretization (defaults to 1, i.e. explicit Euler)
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
-div Generate a scalar grid with the divergence of a vector grid
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
-each Start of each-loop over a user-defined loop variable and list of
values.
s sphere,bunny,... Defined name of loop variable and list of its values.
-end Marks the end scope of "-for,-each,and -if" control actions
-enright Performs Enright advection benchmark test on a level set
translate
(0.0,0.0,0.0) Defines the origin of the Enright velocity field
scale 1.0 Defined the scale of the Enright velocity field
dt 0.05 Time-step the input level set is advected
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
-erode Erode level set surface by a fixed radius
radius 1.0 Radius in voxel units by which the surface is eroded
space 1|2|3|5 Order of the spatial discretization (defaults to 5, i.e. WENO)
time 1|2|3 Order of the temporal discretization (defaults to 1, i.e. explicit Euler)
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
-eval Evaluate string expression
str {1:2:+} One or more strings to be processed by the stack-oriented programming
language. Non-empty string outputs are printed to the terminal
help *|+,-,... Print a list of all or specified list operations each with brief
documentation
-examples Print examples to the terminal and terminate
-expand Expand narrow band of level set
dilate 1 Number of integer voxels that the narrow band of the input SDF will be dilated
iter 1 Number of iterations of the fast sweeping algorithm (each using 8 sweeps)
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
-flood Signed-flood filling of a level set VDB
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB
-for Start of for-loop over a user-defined loop variable and range.
i 0,9|i=0,9,2 Define name of loop variable and its range.
-gauss Gaussian convolution of a level set surface
iter 1 Number of iterations are that the filter is applied
space 1|2|3|5 Order of the spatial discretization (defaults to 5, i.e. WENO)
time 1|2|3 Order of the temporal discretization (defaults to 1, i.e. explicit Euler)
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
size 1 Size of filter in voxel units
-grad Generate a vector grid with the gradient of a scalar grid
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
-help,-h Print documentation for one, multiple or all available actions
actions
read,write,... List of actions to document. If the list is empty documentation is
printed for all available actions and if other actions proceed this action,
documentation is printed for those actions only
exit 1|0|true|false Toggle wether to terminate after this action or not
brief 1|0|true|false Toggle brief or detailed documentation
-if Start of if-scope. If the value of its option, named test, evaluates
to false the entire scope is skipped
test 0|1|false|true Boolean value used to test if-statement
-intersection CSG intersection of two level sets surfaces
vdb 0,1 Ages (i.e. stack indices) of the two VDB grids to intersect. Defaults to 0,1,
i.e. two most recently inserted VDBs.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
prune true Toggle wether to prune the tree after the boolean operation (enabled by
default)
rebuild
true Toggle wether to re-build the level set after the boolean operation (enabled
by default)
-iso2ls,-i2l Convert an iso-surface of a scalar field into a level set (i.e.
SDF)
vdb 0,1 Age (i.e. stack index) of the VDB grid to be processed and an optional
reference grid. Defaults to 0, i.e. most recently inserted VDB.
iso 0.0 Value of the iso-surface from which to compute the level set
voxel 0.0 Voxel size in world units (defaults to zero, i.e the transform out the output
matches the input)
width 3.0 Half-width in voxel units of the output narrow-band level set (defaults to 3
units on either side of the zero-crossing)
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
name iso2ls_input Specify the name of the resulting VDB (by default it's derived from
the input VDB)
-length Generate a scalar grid with the magnitude of a vector grid
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
-ls2fog,-l2f Convert a level set VDB into a VDB with a fog volume, i.e. normalized
density.
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
name ls2fog_input Specify the name of the resulting VDB (by default it's derived from
the input VDB)
-ls2mesh,-l2m Convert a level set to an adaptive polygon mesh
adapt 0.9 Normalized metric for the adaptive meshing. 0 is uniform and 1 is fully
adaptive mesh. Defaults to 0.
iso 0.1 Iso-value used to define the implicit surface. Defaults to zero.
vdb 0 Age (i.e. stack index) of the level set VDB grid to be meshed. Defaults to 0,
i.e. most recently inserted VDB.
mask 1 Age (i.e. stack index) of the level set VDB grid used as a surface mask during
meshing. Defaults to -1, i.e. it's disabled.
invert 1|0|true|false Boolean toggle to mesh the complement of the mask. Defaults to false
and ignored if no mask is specified.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing. The mask is never removed!
name ls2mesh_input Specify the name of the resulting vdb (by default it's derived from
the input VDB)
-max Given grids A and B, compute max(a, b) per voxel
vdb 0,1 Ages (i.e. stack indices) of the two VDB grids to composit. Defaults to 0,1,
i.e. two most recently inserted VDBs.
keep 1|0|true|false Toggle wether the input VDBs is preserved or deleted after the
processing
-mean Mean value filtering of a level set surface
iter 1 Number of iterations are that the filter is applied
space 1|2|3|5 Order of the spatial discretization (defaults to 5, i.e. WENO)
time 1|2|3 Order of the temporal discretization (defaults to 1, i.e. explicit Euler)
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
size 1 Size of filter in voxel units
-median Median value filtering of a level set surface
iter 1 Number of iterations are that the filter is applied
space 1|2|3|5 Order of the spatial discretization (defaults to 5, i.e. WENO)
time 1|2|3 Order of the temporal discretization (defaults to 1, i.e. explicit Euler)
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
size 1 Size of filter in voxel units
-mesh2ls,-m2ls Convert a polygon mesh into a narrow-band level set, i.e. a narrow-band
signed distance to a polygon mesh
dim 256 Largest dimension in voxel units of the mesh bbox (defaults to 256). If "vdb"
or "voxel" is defined then "dim" is ignored
voxel 0.01 Voxel size in world units (by defaults "dim" is used to derive "voxel"). If
specified this option takes precedence over "dim"
width 3.0 Half-width in voxel units of the output narrow-band level set (defaults to 3
units on either side of the zero-crossing)
geo 0 Age (i.e. stack index) of the geometry to be processed. Defaults to 0, i.e. most
recently inserted geometry.
vdb 0 Age (i.e. stack index) of reference grid used to define the transform. Defaults
to -1, i.e. disabled. If specified this option takes precedence over "dim" and
"voxel"!
keep 1|0|true|false Toggle wether the input geometry is preserved or deleted after the
conversion
name mesh2ls_input Specify the name of the resulting vdb (by default it's derived from
the input geometry)
-min Given grids A and B, compute min(a, b) per voxel
vdb 0,1 Ages (i.e. stack indices) of the two VDB grids to composit. Defaults to 0,1,
i.e. two most recently inserted VDBs.
keep 1|0|true|false Toggle wether the input VDBs is preserved or deleted after the
processing
-multires Construct a LoD sequences of VDB trees with powers of two refinements
levels 2 Number of multi-resolution grids in the output LoD sequence
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
-open Morphological opening, i.e. erosion followed by dilation, of a level
set surface by a fixed radius
radius 1.0 Radius in voxel units by which the surface is opened
space 1|2|3|5 Order of the spatial discretization (defaults to 5, i.e. WENO)
time 1|2|3 Order of the temporal discretization (defaults to 1, i.e. explicit Euler)
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
-platonic Create a level set shape with the specified number of polygon faces
dim 256 Largest dimension in voxel units of the bbox of all the shape (defaults to
256). In "voxel" is defined "dim" is ignored
voxel 0.01 Voxel size in world units (by defaults "dim" is used to derive "voxel"). If
specified this option takes precedence over "dim"
faces {4|6|8|12|20} Number of polygon faces of the shape to generate the level set VDB
from
scale 1.0 Scale of the shape in world units. E.g. if faces=6 and scale=1.0 the result is
a unit cube
center (0.0,0.0,0.0) Center of the shape in world units. defaults to the origin
width 3.0 Half-width in voxel units of the output narrow-band level set (defaults to 3
units on either side of the zero-crossing)
name Tetrahedron Specify the name of the resulting VDB (by default it's derived from
face count)
-points2ls,-p2l Convert geometry points into a narrow-band level set
dim 256 Largest dimension in voxel units of the bbox of all the points (defaults to
256). In "voxel" is defined "dim" is ignored
voxel 0.01 Voxel size in world units (by defaults "dim" is used to derive "voxel"). If
specified this option takes precedence over "dim"
width 3.0 Half-width in voxel units of the output narrow-band level set (defaults to 3
units on either side of the zero-crossing)
radius 2.0 Radius in voxel units of the input points
geo 0 Age (i.e. stack index) of the geometry to be processed. Defaults to 0, i.e. most
recently inserted geometry.
keep 1|0|true|false Toggle wether the input points are preserved or deleted after the
processing
name points2ls_input Specify the name of the resulting VDB (by default it's derived from
the input points)
-points2vdb,-p2v Encode geometry points into a VDB grid
geo 0 Age (i.e. stack index) of the geometry to be processed. Defaults to 0, i.e. most
recently inserted geometry.
keep 1|0|true|false Toggle wether the input points are preserved or deleted after the
processing
ppv 8 The number of points per voxel in the output VDB grid (defaults to 8)
bits 16|8|32 The number of bits used to represent a single point in the VDB grid
(defaults to 16, i.e. half precision)
name points_2vdb_input Specify the name of the resulting VDB (by default it's derived
from the input geometry)
-print,-p Prints information to the terminal about the current stack of VDB
grids and Geometry
vdb * Print information about VDB grids
geo * Print information about geometries
mem 0|1|false|true Print a list of all stored variables
-prune Prune away inactive values in a VDB grid
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB
-quiet Disable printing to the terminal
-read,-i Read one or more geometry or VDB files from disk or STDIN.
files {file|stdin}.{abc|obj|ply|stl|vdb} List of files or the input stream, e.g.
file.vdb,stdin.vdb. Note that "files=" is optional since any argument without "="
is intrepreted as a file and appended to "files"
grids *|grid_name,... List of VDB grids name to be imported (defaults to "*", i.e.
import all available grids)
delayed
1|0|true|false Toggle delayed loading of VDB grids (enabled by default). This
option is ignored by other file types
-render Ray-tracing of level set surfaces and volume rendering of fog volumes
files output.{jpg|png|ppm|exr} File used to save the rendered image to disk
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
rendering
camera persp|ortho Perspective or orthographic camera
aperture
41.2136 Width in mm of the frame of a perspective camera, i.e., the visible field
(defaults to 41.2136mm)
focal 50 Focal length of a perspective camera in mm (defaults to 50mm)
isovalue
0.0 Iso-value use during ray-intersection of level set surfaces
samples
1 Number of samples (rays) per pixel
image 1920x1080 Image size defined in terms of pixel resolution
translate
(0,0,0) Translation of the camera in world-space units, applied after rotation
rotate (0,0,0) Rotation in degrees of the camera in world space (applied in x, y, z order)
target Target point in world pace that the camera will point at (if undefined target is
set to the center of the bbox of the grid)
up (0,1,0) Vector that should point up after rotation with lookat
lookat true Rotate the camera so it looks at the center of the shape uses up as the
horizontal direction
near 0.001 Depth of the near clipping plane in world-space units
far 3.4e+38 Depth of the far clipping plane in world-space units
shader diffuse|normal|position|matte Shader type; either "diffuse", "matte", "normal" or
"position"
light (0.3,0.3,0.0),(0.7,0.7,0.7) Light source direction and optional color
frame 1.0 Orthographic camera frame width in world units
cutoff 0.005 Density and transmittance cutoff value (ignored for level sets)
gain 0.2 Amount of scatter along the shadow ray (ignored for level sets)
absorb (0.1,0.1,0.1) Absorption coefficients for RGB (ignored for level sets)
scatter
(1.5,1.5,1.5) Scattering coefficients for RGB (ignored for level sets)
step 1.0,3.0 Step size in voxels for integration along the primary ray (ignored for
level sets)
colorgrid
1 Age of a vec3s VDB grid to be used to set material colors. Defaults to -1, i.e.
disabled
-resample Resample one VDB grid into another VDB grid or a transformation
of the input grid
vdb 0,1 Pair of input and optional output grids (i.e. stack index) to be processed.
Defaults to 0,1, i.e. most recent VDB is resampled to match the transform of the
second to most recent VDB.
scale 0 Scale use to transform the input grid (ignored if two grids are specified with
vdb)
translate
(0,0,0) Translation use to transform the input grid (ignored if two grids are
specified with vdb)
order 1 Order of the polynomial interpolation kernel used during resampling
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
-scatter Scatter point into the active values of an input VDB grid
count 0 Fixed number of points to randomly scatter (disabled by default)
density
0.0 Uniform density of points per active voxel (disabled by default)
ppv 8 Number of points per active voxel (defaults to 8)
vdb 0 Age (i.e. stack index) of the VDB grid to be scatter points into. Defaults to 0,
i.e. most recently inserted VDB
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
name scatter_input Specify the name of the resulting points (by default it's derived
from the input VDB)
-segment Segment an input VDB into a list if topologically disconnected VDB
grids
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
-sphere Create a level set sphere, i.e. a narrow-band signed distance to
a sphere
dim 256 Largest dimension in voxel units of the sphere (defaults to 256). If "voxel" is
defined "dim" is ignored
voxel 0.0 Voxel size in world units (by defaults "dim" is used to derive "voxel"). If
specified this option takes precedence over "dim". Defaults to 0.0, i.e. this
option is disabled
radius 1.0 Radius of sphere in world units
center (0.0,0.0,0.0) Center of sphere in world units
width 3.0 Half-width in voxel units of the output narrow-band level set (defaults to 3
units on either side of the zero-crossing)
name sphere Name assigned to the level set sphere
-sum Given grids A and B, compute sum(a, b) per voxel
vdb 0,1 Ages (i.e. stack indices) of the two VDB grids to composit. Defaults to 0,1,
i.e. two most recently inserted VDBs.
keep 1|0|true|false Toggle wether the input VDBs is preserved or deleted after the
processing
-transform Apply affine transformations (uniform scale -> rotation -> translation)
to a VDB grids and geometry
rotate (0.0,0.0,0.0) Rotation in radians around x,y,z axis
translate
(0.0,0.0,0.0) Translation in world units along x,y,z axis
scale 1.0 Uniform scaling in world units
vdb 0,2,.. Age (i.e. stack index) of the VDB grid to be processed. Defaults to empty.
geo 0,2,.. Age (i.e. stack index) of the Geometry to be processed. Defaults to empty.
keep 1|0|true|false Toggle wether the input VDB is preserved or overwritten
-union CSG union of two level sets surfaces
vdb 0,1 Ages (i.e. stack indices) of the two VDB grids to union. Defaults to 0,1, i.e.
two most recently inserted VDBs.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
prune true Toggle wether to prune the tree after the boolean operation (enabled by
default)
rebuild
true Toggle wether to re-build the level set after the boolean operation (enabled
by default)
-vdb2points,-v2p Extract points encoded in a VDB to points in a geometry format
vdb 0 Age (i.e. stack index) of the VDB grid to be processed. Defaults to 0, i.e. most
recently inserted VDB.
keep 1|0|true|false Toggle wether the input VDB is preserved or deleted after the
processing
name vdb2points_input Specify the name of the resulting points (by default it's derived
from the input VDB)
-verbose Print timing information to the terminal
-version Write timing information to the terminal
-write,-o Write list of geometry, VDB or config files to disk or STDOUT
files {file|stdout}.{obj|ply|stl|vdb|nvdb} List of files or the output stream, e.g.
file.vdb or stdin.vdb. Note that "files=" is optional since any argument without
the "=" character is intrepreted as a file and appended to "files".
geo 0|1... Geometry to write (defaults to "0" which is the latest).
vdb 0,1,... List of VDB grids to write (defaults to "*", i.e. all available grids).
keep 1|0|true|false Toggle wether to preserved or deleted geometry and grids after they
have been written.
codec none|zip|blosc|active Compression codec for the file or stream
bits 32|16|8|4|N Bit-width of floating point numbers during quantization of VDB and
NanoVDB grids, i.e. 32 is full, 16, is half (defaults to 32). NanoVDB also supports
8, 4 and N which is adaptive bit-width
dither 1|0|true|false Toggle dithering of quantized NanoVDB grids (disabled by default)
absolute
1|0|true|false Toggle absolute or relative error tolerance during quantization of
NanoVDBs. Only used if bits=N. Defaults to absolute
tolerance
1.0 Absolute or relative error tolerance used during quantization of NanoVDBs. Only
used if bits=N.
stats none|bbox|extrema|all Specify the statistics to compute for NanoVDBs.
checksum
none|partial|full Specify the type of checksum to compute for NanoVDBs
Note that actions always start with one or more "-", and (except for file names) its
options always contain a "=" and an optional number of characters used for identification,
e.g. "-erode r=2" is identical to "-erode radius=2.0" but "-erode rr=2" will produce an
error since "rr" does not match the first two character of "radius". Also note that this
tool maintains two lists of primitives, namely geometry (i.e. points and meshes) and level
sets. They can be referenced with "geo=n" and "vdb=n" where the integer "n" refers to age
(i.e stack index) of the primitive with "n=0" meaning most recent. E.g. -mesh2ls g=1"
means convert the second to last geometry (here polygon mesh) to a level set. Likewise
"-gauss v=0" means perform a gaussian filter on the most recent level set (default).
SUPPORTED FILE FORMATS
| Extension | Actions | Description |
|-------|-------|-------|
| vdb | read and write | OpenVDB sparse volume files with float, Vec3f and points |
| obj | read and write | ASCII OBJ mesh files with triangle, quad or points |
| ply | read and write | Binary and ASCII PLY mesh files with triangle, quad or points |
| stl | read and write | Binary STL mesh files with triangles |
| pts | read | ASCII PTS points files with one or more point clouds |
| abc | optional read and write | Alembic binary mesh files |
| nvdb| optional read and write | NanoVDB file with voxels or points |
| txt | read and write | ASCII configuration file for this tool |
| ppm | write | Binary PPM image file |
| png | optional write | Binary PNG image file |
| jpg | optional write | Binary JPEG image file |
| exr | optional write | Binary OpenEXR image file |
TERMINOLOGY
We introduce terms: **actions**, **options**, **expressions**, and **instructions**.
Actions are high-level openvdb tools, which each have unique options, e.g. -mesh2ls geo=1
voxel=0.1, where "-mesh2ls" is an action with two options "geo" and "voxel". Expressions
are strings of code with one or more low-level instructions in our stack-based programming
language (see below). These expressions start with "{" and ends with "}", and ":" is used
to separate values and instructions. E.g. {1:2:+} is an expression with two values (1 and
2) and one instruction "+", and it reduces to the string value "3". See section on the
"Stack-based string expressions" below for more details.
Note that **actions** always start with one or more "-" and (except for file names) its
associated **options** always contain a "=" and an optional number of leading characters
used for identification, e.g. "-erode r=2" is identical to "-erode radius=2.0", but
"-erode rr=2" will produce an error since "rr" does not match the first two characters of
any option associated with the action "erode".
Note that this tool maintains two stacks of primitives, namely geometry (i.e. points and
polygon meshes) and VDB volumes (that may contain voxels or points). They can be
referenced respectively with "geo=n" and "vdb=n" where the integer "n" refers to "age" of
the primitive, i.e. its order on the stack. That is, "n=0" means the most recently added
primitive and "n=1" means the second primitive added to the internal stack. So, "-mesh2ls
g=1" means convert the second to last geometry (here a polygon mesh) to a level set. If no
other VDB grid exists this output level set can subsequently be referenced as "vdb=0".
Thus, "-gauss v=0" means perform a gaussian filter on the most recently added level set
VDB. By default the most recent geometry, i.e. "g=0, or most recent level set, i.e. "v=0",
is selected for processing.
STACK-BASED STRING EXPRESSIONS
This tool supports its own light-weight stack-oriented programming language that is (very
loosely) inspired by Forth. Specifically, it uses Reverse Polish Notation (RPN) to define
instructions that are evaluated during paring of the command-line arguments (options to be
precise). All such expressions start with the character "{", ends with "}", and arguments
are separated by ":". Variables starting with " are substituted by its (previously)
defined values, and variables starting with "@" are stored in memory. So, "{1:2:+:@x}" is
conceptually equivalent to "x = 1 + 2". Conversely, "{:++}" is conceptually equivalent "2
+ 1 = 3" since "x=2" was already saved to memory. This is especially useful in combination
loops, e.g. "-quiet -for i=1,3,1 -eval {:++} -end" will print 2 and 3 to the terminal.
Branching is also supported, e.g. "radius={$x:1:>:if(0.5:sin?0.3:cos)}" is conceptually
equal to "if (x>1) radius=sin(0.5) else radius=cos(0.3)". See the root-searching example
below or run vdb_tool -eval help="*" to see a list of all instructions currently supported
by this scripting language. Note that since this language uses characters that are
interpreted by most shells it is necessary to use single quotes around strings! This is of
course not the case when using config files.
EXAMPLES
## Getting help on all actions and their options
```
vdb_tool -help
```
## Getting help on specific actions and their options
```
vdb_tool -help read write
```
## Getting help on all instructions
```
vdb_tool -eval help="*"
```
## Getting help on specific instructions
```
vdb_tool -eval help=if,switch
```
## Hello-world example Create a level set sphere and save it to a file
```
vdb_tool -sphere -write sphere.vdb
``` ## Hello-world example with option Same example but with options to save the file in
half-float precision
```
vdb_tool -sphere -write bits=16 sphere.vdb
```
## Converting a mesh into a level set Convert a polygon mesh file into a narrow-band level
and save it to a file
```
vdb_tool -read mesh.obj -mesh2ls -write level_set.vdb
```
## Read multiple files Convert a polygon mesh file into a narrow-band level with a
transform that matches a reference vdb
```
vdb_tool -read mesh.obj,reference.vdb -mesh2ls vdb=0 -write level_set.vdb
```
## Convert a sequence of files Convert 5 polygon mesh files, "mesh_00{1,2,3,4,5}.obj",
into separate narrow-band levels and save them to the files "level_set_0{1,2,3,4,5}.vdb".
Note that the value of loop variables is accessible with a preceding "$" character and
that the end of the for-loop (here 6) is exclusive.The instruction "pad0" add zero-padding
and takes two arguments, the string to pad and the desired length after padding.
```
vdb_tool -for n=1,6 -read mesh_'{$n:3:pad0}'.obj -mesh2ls -write
level_set_'{$n:2:pad0}'.vdb -end
```
## Loop over specific files Convert 5 polygon mesh files, "bunny.obj,teapot.ply,car.stl",
into the Alembic files "mesh_0{1,2,3,4,5}.vdb". Note that all loop variables have a
matching counter defined with a preceding "#" character.
```
vdb_tool -each file=bunny.obj,teapot.ply,car.stl -read '{$file}' -write
mesh_'{$#file:1:+:2:pad0}'.abc -end
```
## Define voxel size from a loop-variable Generate 5 sphere with different voxel sizes and
save them all into a single vdb file
```
vdb_tool -for v=0.01,0.06,0.01 -sphere voxel='{$v}' name=sphere_%v -end -write vdb="*"
spheres.vdb
```
## Specify which grids to write into a single file Generate 4 spheres named after their
stack id, i.e. 3,2,1,0, and write only grid 0 and 2 to a file
```
vdb_tool -for i=0,5 -sphere name='{4:$i:-}' -end -write vdb=2,0 tmp.vdb
```
## Define options with simple math expression Read both a vdb and mesh file and convert
the mesh to a vdb with twice the voxel size of the input vdb.
```
vdb_tool -read bunny.vdb dragon.ply -mesh2ls voxel='{0:voxelSize:2:*}' -print
```
## Define options with complex math expressions Generate spheres that are rotating along a
parametric circle
```
vdb_tool -for degree=0,360,10 -eval '{$degree:d2r:@radian}' -sphere
center='({$radian:cos},{$radian:sin},0)' name=sphere_'{$degree}' -end -write vdb="*"
spheres.vdb
```
## Meshing of particles Converts input points in the file points.[obj|ply|abc|pts] to a
level set, perform level set actions, and written to it the file surface.vdb:
```
vdb_tool -read points.[obj|ply|abc|pts] -points2ls -dilate -gauss -erode -write
surface.vdb
```
## Changing global default options Example with many properties of scalar and vector
fields
```
vdb_tool -default keep=true -sphere -curvature -grad -curl -div -length v=1 -debug
```
## If-statement to isolate level sets Read multiple grids, and render only level set grids
```
vdb_tool -read boat_points.vdb -for v=0,'{gridCount}' -if '{$v:isLS}' -render vdb='{$v}'
-end -end
```
## Use shell-script to define list of files Find and render thumbnails of all level sets
in an entire directory structure
```
vdb_tool -each file=`find ~/dev/data -name '*.vdb'` -read '{$file}' -for
grid=0,'{gridCount}' -if '{$grid:isLS}' -render vdb='{$grid}'
thumbnail_'{$grid:gridName}'.ppm image=256x256 keep=1 -end -end -clear -end
``` Most of the arguments should be self-explanatory, but at least two deserve an
explanation: -render has the option keep=1 because otherwise rendered grids are removed
from the stack which invalidates {gridCount}, and -clear is added to avoid accumulating
all grids as multiple files are loaded.
--- # Pipelining:
vdb_tool supports unix-style pipelining, which is especially useful for interactive
viewing. Specifically, vdb_tool can read VDB grids from stdin or write VDB grid to stdout.
Here are some examples:
## Redirection of stdout and stdin:
```
vdb_tool -sphere -o stdout.vdb > sphere.vdb
vdb_tool -i stdin.vdb -print < bunny.vdb
cat bunny.vdb | vdb_tool -i stdin.vdb -print
vdb_tool -sphere -o stdout.vdb | gzip > sphere.vdb.gz
gzip -dc sphere.vdb.gz | vdb_tool -i stdin.vdb -print
```
## Pipelining multiple instances of vdb_tool
```
vdb_tool -sphere -o stdout.vdb | vdb_tool -i stdin.vdb -dilate -o stdout.vdb > sphere.vdb
``` or with explicit semantics
```
vdb_tool -sphere -o stdout.vdb | vdb_tool -i stdin.vdb -dilate -o stdout.vdb > sphere.vdb
``` Note that the example above is slow due to serialization of the VDB grid.
```
vdb_tool -sphere -dilate -o stdout.vdb > sphere.vdb
``` or with explicit semantics
```
vdb_tool -sphere -dilate -o stdout.vdb > sphere.vdb
```
## Pipelining vdb_tool with vdb_view for interactive viewing
```
vdb_tool -sphere -dilate -o stdout.vdb | vdb_view
```
## View a sequence of scaling, rotating, and translated tetrahedra
```
vdb_tool -for t=0,6.28,0.2 -platonic f=4 -transform vdb=0 scale='{$t:sin:2:+}'
rotate='(0,0,{$t})' translate='({$t:cos:5:*},{$t:sin:5:*},0)' -end -o stdout.vdb |
vdb_view
```
## View a sequence of spheres deformed in an analytical fluid field
```
vdb_tool -sphere d=80 r=0.15 c=0.35,0.35,0.35 -for i=1,20 -enright dt=0.05 k=1 -end -o
stdout.vdb | vdb_view
```
## View a sequence of octahedrons deformed in an analytical fluid field
```
vdb_tool -platonic d=128 f=8 s=0.15 c=0.35,0.35,0.35 -for i=1,20 -enright dt=0.05 k=1
-end -o stdout.vdb | vdb_view
```
## Production example of meshing of fluid particles Generate adaptive meshes from a
sequence of points files, points_0[200,299].vdb, and use mesh_mask.obj to clip off
boundaries. Points are first rasterized as level set spheres, then dilates, filtered and
eroded and finally meshed using the mask.
```
vdb_tool -read mesh_mask.obj -mesh2ls voxel=0.1 width=3 -for n=200,300,1 -read
points_{$n:4:pad0}.vdb -vdb2points -points2ls voxel=0.035 radius=2.142 width=3 -dilate
radius=2.5 space=5 time=1 -gauss iter=2 space=5 time=1 size=1 -erode radius=2.5 space=5
time=1 -ls2mesh vdb=0 mask=1 adapt=0.005 -write mesh_{$n:4:pad0}.abc -end
```
## Production example with complex math Union 200 level set spheres scattered in a spiral
pattern and ray-trace them into an image
```
vdb_tool -for n=0,200,1 -eval '{$n:137.5:*:@deg}' -eval '{$deg:d2r:@radian}' -eval
'{$radian:cos:@x}' -eval '{$radian:sin:@y}' -eval '{$n:sqrt:@r}' -eval '{$r:5:+:@r_sum}'
-eval '{$r_sum:0.25:pow:@pow_r}' -sphere voxel=0.1 radius='{$pow_r:0.5:*}'
center='({$r:$x:*},{$r:$y:*},0)' -if '{$n:0:>}' -union -end -end -render spiral.ppm
image=1024x1024 translate='(0,0,40)'
```
AUTHOR
This manual page was written by Mathieu Malaterre <malat@debian.org> for the Debian
GNU/Linux system (but may be used by others).