VDB_TOOL(1)

📦
version 10.0.1 · 6 versions
, in ubuntu stonking

Hiii bestie!! 💖 Welcome to vdb_tool(1) — the User Commands manual page for the most iconic command-line tool in all of openvdb. No cap. This tool is literally a whole vibe: you give it a sequence of tasks, and it slays. Let's get into it. ✨

NAME 🎀

vdb_tool — perform a use-defined sequence of tasks 💅

SYNOPSIS 🦋

Okay so, this command-line tool, dubbed vdb_tool, can combine any number of the 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:

  • 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 — the order of the temporal discretization 🕰️ defaults to 1, which is the explicit Euler vibe.
    • vdb 0 — the age (aka the stack index 🥞) of the VDB grid you want processed. Defaults to 0, i.e. the most recently inserted VDB, the freshest one, the main character 👑.
  • -eval — evaluate a string expression ✨
    • str {1:2:+} — one or more strings for the stack-oriented programming language to chew on 🧠. Any non-empty string output gets printed straight to your terminal.
  • help *|+,-,... — print a list of all the list operations, or just the ones you name, each with a little brief documentation attached 📖
  • -examples — prints examples to the terminal and then terminates, bye bestie 👋
  • -expand — expand the narrow band of a level set 🎈
    • dilate 1 — how many integer voxels the narrow band of the input SDF gets dilated.
    • iter 1 — number of iterations of the fast sweeping algorithm (every single one uses 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 — toggles whether 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 a for-loop over a user-defined loop variable and range 🔄
    • i 0,9|i=0,9,2 — define the name of the loop variable and its range.
  • -gauss — Gaussian convolution of a level set surface 🫧 soft blur energy
    • iter 1 — how many iterations the filter gets 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 the filter, in voxel units.
  • -grad — generate a vector grid holding 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 — toggles whether the input VDB is preserved or deleted after the processing.
  • -help, -h — print documentation for one, multiple or all available actions 📚
    • actions read,write,... — the list of actions you want documented. If the list is empty, documentation is printed for all available actions, and if other actions come before this one, documentation is printed for those actions only.
    • exit 1|0|true|false — toggles whether to terminate after this action or not 🚪
    • brief 1|0|true|false — toggles between brief or detailed documentation.
  • -if — start of an if-scope 🧚 If the value of its option, named test, evaluates to false, the entire scope is skipped, periodt.
    • test 0|1|false|true — the boolean value used to test the if-statement.
  • -intersection — CSG intersection of two level sets surfaces ✂️ two shapes walk in, their overlap walks out
    • vdb 0,1 — ages (i.e. stack indices) of the two VDB grids to intersect. Defaults to 0,1, i.e. the two most recently inserted VDBs.
    • keep 1|0|true|false — toggles whether the input VDB is preserved or deleted after the processing.
    • prune true — toggles whether to prune the tree after the boolean operation (enabled by default) 🌳
    • rebuild true — toggles whether 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. an SDF) 🦋
    • vdb 0,1 — age (i.e. stack index) of the VDB grid to be processed, plus an optional reference grid. Defaults to 0, i.e. most recently inserted VDB.
    • iso 0.0 — value of the iso-surface to compute the level set from.
    • voxel 0.0 — voxel size in world units (defaults to zero, i.e. the transform of 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 — toggles whether 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 holding 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 — toggles whether 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 — toggles whether 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 a uniform mesh and 1 is a fully adaptive mesh. The page says it defaults to 0 🙈 (we're just the messenger, no cap).
    • 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 is ignored if no mask is specified.
    • keep 1|0|true|false — toggles whether 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. the two most recently inserted VDBs.
    • keep 1|0|true|false — toggles whether the input VDBs are preserved or deleted after the processing.
  • -mean — mean value filtering of a level set surface 🧴
    • iter 1 — how many iterations the filter gets 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 the filter, in voxel units.
  • -median — median value filtering of a level set surface 🌾
    • iter 1 — how many iterations the filter gets 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 the 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 default dim is used to derive voxel). If you specify it, 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 the 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 — toggles whether 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. the two most recently inserted VDBs.
    • keep 1|0|true|false — toggles whether the input VDBs are preserved or deleted after the processing.
  • -multires — construct a LoD sequence 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 — toggles whether 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 🎲 solids are literally the moment
    • dim 256 — largest dimension in voxel units of the bbox of all the shape (defaults to 256). If voxel is defined, dim is ignored.
    • voxel 0.01 — voxel size in world units (by default 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 the 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). If voxel is defined, dim is ignored.
    • voxel 0.01 — voxel size in world units (by default dim is used to derive voxel). If specified, this option takes precedence over dim.

…aaaaand the rest of that one's knobs, bestie:

  • 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 (a.k.a. stack index) of the geometry you want processed. Defaults to 0, i.e. the most recently inserted geometry. periodt.
  • keep — 1|0|true|false. Toggles whether the input points are preserved or deleted after the processing.
  • name — points2ls_input. Sets the name of the resulting VDB (by default it gets derived from the input points). ✨
  • -points2vdb, -p2v — Encode geometry points into a VDB grid. Turning those lil point clouds into grid content, iconic 💅
    • 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. Toggles whether 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. 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. A little peek behind the curtain 🔍
    • 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. Marie Kondo-ing your tree, no cap 🧹
    • 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. Shhh. silence is golden and so are you 🤫
  • -read, -i — Read one or more geometry or VDB files from disk or STDIN. Incoming!!! 🛬
    • 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 interpreted as a file and appended to "files".
    • grids — *|grid_name,.... List of VDB grids names 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. Camera. Lights. Cinema. main character energy fr fr 🎬
    • 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. Toggles whether 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 used 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 space 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, using 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. glow-up via math 🦋
    • 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-most recent VDB.
    • scale — 0. Scale used to transform the input grid (ignored if two grids are specified with vdb).
    • translate — (0,0,0). Translation used 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. Toggles whether the input VDB is preserved or deleted after the processing.
  • -scatter — Scatter points into the active values of an input VDB grid. Confetti but make it voxels 🎊
    • 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 scatter points into. Defaults to 0, i.e. most recently inserted VDB.
    • keep — 1|0|true|false. Toggles whether the input VDB is preserved or deleted after the processing.
    • name — scatter_input. The name of the resulting points (by default it's derived from the input VDB).
  • -segment — Segment an input VDB into a list of topologically disconnected VDB grids. Splitting the friend group 💔
    • 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. Toggles whether 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. The perfect lil ball 🔮
    • 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 default "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. Math girlies rise 🧮
    • 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. Toggles whether the input VDBs are preserved or deleted after the processing.
  • -transform — Apply affine transformations (uniform scale -> rotation -> translation) to a VDB grid and geometry. The order matters, bestie, respect the pipeline 🌀
    • 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. Toggles whether the input VDB is preserved or overwritten.
  • -union — CSG union of two level set surfaces. Two shapes become one, we love a merge 🫶
    • 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. Toggles whether the input VDB is preserved or deleted after the processing.
    • prune — true. Toggle whether to prune the tree after the boolean operation (enabled by default).
    • rebuild — true. Toggle whether 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. Reverse UNO 😌
    • 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. Toggles whether the input VDB is preserved or deleted after the processing.
    • name — vdb2points_input. The name of the resulting points (by default it's derived from the input VDB).
  • -verbose — Print timing information to the terminal. Stats girlie behavior 📊
  • -version — Write timing information to the terminal.
  • -write, -o — Write a list of geometry, VDB or config files to disk or STDOUT. Save your work, bestie, you will regret it otherwise 😭
    • 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 interpreted 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. Toggles whether to preserve or delete 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.

Also quick thing, bestie — actions always start with one or more -, and (the one exception being file names) their options always contain a = plus an optional number of leading characters you can type for identification. So -erode r=2 is literally identical to -erode radius=2.0, but -erode rr=2? 💀 nope, that one errors out, because rr doesn't match the first two characters of any option that hangs out with the erode action.

Also fyi this tool keeps 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 the age (i.e. the 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 🌈

Okay so here's the whole roster of file formats this tool speaks, and which direction it speaks them in 👇

  • 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 only. 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 only. Binary PPM image file
  • png — optional write only. Binary PNG image file
  • jpg — optional write only. Binary JPEG image file
  • exr — optional write only. Binary OpenEXR image file ✨
Heads up bestie: the ones marked optional are only there if your build was compiled with them, so don't come for me if abc, nvdb, png, jpg or exr are ghosting you 🙈

💅 TERMINOLOGY

Introducing four words we're gonna use constantly, so let's get them straight: actions, options, expressions, and instructions.

  • Actions are the high-level openvdb tools, and each one has its own unique set of options. Exhibit A: -mesh2ls geo=1 voxel=0.1 — here -mesh2ls is the action, and geo and voxel are its two options. 👑
  • Expressions are strings of code with one or more low-level instructions in our stack-based programming language (more on that below). They start with { and end with }, and : is the separator between values and instructions. For example, {1:2:+} is an expression holding two values (1 and 2) and one instruction +, and it reduces down to the string value "3". Go look at the Stack-based string expressions section below for the whole tea ☕

Now, the notes, because they matter:

actions always start with one or more -, and (file names being the exception, as always) their associated options always contain a = and an optional number of leading characters used for identification. So -erode r=2 is identical to -erode radius=2.0, but -erode rr=2 will produce an error — because rr does not match the first two characters of any option associated with the action erode. No cap, that's just how it is. 😭

And this tool maintains two stacks of primitives: geometry (i.e. points and polygon meshes) and VDB volumes (which may contain voxels or points). You reference them with geo=n and vdb=n respectively, where the integer n is the age of the primitive — meaning its order on the stack. So n=0 is the most recently added primitive, and n=1 is 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. And if no other VDB grid exists, that output level set can subsequently be referenced as vdb=0. Which means -gauss v=0 is "perform a gaussian filter on the most recently added level set VDB." By default, the most recent geometry — i.e. g=0 — or the most recent level set — i.e. v=0 — is the one selected for processing. Convenient, right?? 🌸

🦋 STACK-BASED STRING EXPRESSIONS

Okay this is the fun part, stay with me. 💜

This tool has its very 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 get evaluated while the command-line arguments are being parsed — options to be precise.

The rules of the vibe:

  • All such expressions start with the character { and end with }. 🎀
  • Arguments are separated by :.
  • Variables starting with $ are substituted by their (previously) defined values.
  • Variables starting with @ are stored in memory.

So {1:2:+:@x} is conceptually equivalent to x = 1 + 2. Conversely, {:++} is conceptually equivalent to 2 + 1 = 3, since x=2 was already saved to memory. 🔥

This is especially useful in combination with loops, e.g.

-quiet -for i=1,3,1 -eval {:++} -end

will print 2 and 3 to the terminal. Branching is supported too, 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). main character energy honestly ⭐

Go see the root-searching example below, or just run

vdb_tool -eval help="*"

to get a list of all instructions currently supported by this scripting language. 🫶

⚠️ Warning bestie, real talk: since this language uses characters that most shells interpret, it is necessary to use single quotes around strings! This is of course not the case when using config files. Don't get caught lacking by your shell 🙈

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. 💀 (no cap, that keep=1 is doing SO much work here)

🦋 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).

and that's the whole thing bestie, we did it 🎉 this was vdb_tool version 10.0.1, dated August 2026, and it lives at VDB_TOOL(1). go forth and pipeline, ily, bye 💖✨

📦 where this page comes from