The vdb_tool program is used to create, modify and explore OpenVDB files containing voxelized (volumetric) geometry.

General usage.
$ vdb_tool -h
Usage: vdb_tool [options] <command> ...

DIRSIG OpenVDB manipulation and analysis tool

Options:
  -h/--help
	Display this help and exit.
  -v/--version
	Display build and version info and exit.
  --log_level string
	Sets the minimum logging level. Values are: debug, info, warning, error, critical, off

Commands:
  xyz
  summary
  regular_grid
  edit
  blackadar

For subcommand help: vdb_tool <command> -h

The Blackadar Tool

The blackadar tool is a port of the old, stand-alone blackadar program, which leverages an implementation of the Blackadar Plume model to generate a VDB for a bouyant stack plume. It accepts an XML filename which lists the available parameters under the <blackadarplume> tag (which may appear anywhere in the file). The PlumeOpenVDB1 demo contains a working example.

Usage for the blackadar tool.
$ vdb_tool blackadar -h
Usage: vdb_tool ... blackadar [options] filename

Positional Arguments:
  filename (required!)
	The input filename (.xml)

Options:
  -h/--help
	Display this help and exit.
  -r/--resolution float
	The voxel resolution in meters (default = 0.5).
  -s/--seed uint
	The random seed (default = 0).
  -o/--output string
	The output filename (default = '<filename>.vdb').
filename (required)

The input filename is (currently) a DIRSIG4-era XML configuration file. A description is provided here.

--resolution (optional)

The resolution that the generated plume is sampled at to be stored in the OpenVDB file. The default is 0.5 meters.

--seed (optional)

The random seed used to drive the plume simulation. Changing this seed will result in different plumes for the same inputs. The default is 0.

--output (optional)

The name of the output VDB file that is generated. The default is the input filename with a .vdb extension.

The Edit Tool

The edit tool is a port of the editting functionality of the original vdb_tool. It does some customized positional argument parsing now so that multiple operations can be strung together in the order they appear (in the FFmpeg-style that the original vdb_tool supported).

Usage for the edit tool.
$ vdb_tool edit -h
Usage: vdb_tool ... edit [options] filenames+

Positional Arguments:
  filenames
	The input filename(s) (.vdb)

Options:
  -h/--help
	Display this help and exit.
  -o/--output string
	The output filename.
  -i/--in-place
	Edit in-place.
  --clip string string string
	Remove voxels outside the given intervals. Interval format is 'A:B'. Example: --clip '1:2' '-3:' ':5.3'
  --threshold float
	Remove voxels below the given threshold.
  --translate float float float
	Translate everything by the given delta.
  --swap string
	Swap two axes, identified by letters. Example: --swap YZ.

There are four operators at the moment: threshold, translate, clip and swap. Refer to the usage above to see the syntax. Note that translate and clip accept arguments wrapped in square brackets to prevent Qt from interpreting negative numbers as options, e.g., translate -1,2,3 would error out because the command-line parser will interpret the -1 as option be we have a chance to process it.

The RegularGrid Tool

The regular_grid tool can convert an ASCII/Text RegularGrid voxel description into a VDB file. The output filename and ambient temperature are specified as options. If left unspecified, the ambient temperature is 288.15 Kelvin.

Usage for the regular_grid tool.
$ vdb_tool regular_grid -h
Usage: vdb_tool ... regular_grid [options] filename

Positional Arguments:
  filename (required!)
	The input filename

Options:
  -h/--help
	Display this help and exit.
  -o/--output string
	The output filename.
  -a/--ambient float
	The ambient temperature in Kelvin.

The Summary Tool

The summary tool is an interface to the OpenVDB human-readable-log-dumper that displays some useful information about the VDB file.

Usage for the summary tool.
$ vdb_tool summary -h
Usage: vdb_tool ... summary [options] filenames+

Positional Arguments:
  filenames
	The input filename(s) (.vdb)

Options:
  -h/--help
	Display this help and exit.
  -o/--output string
	The output filename (default stdout).
  -v/--verbosity int
	The verbosity level (default 1).

The XYZ Tool

The xyz tool is a new feature for constructing arbitrary VDBs from plain text XYZ "point cloud" style data.

Usage for the xyz tool.
$ vdb_tool xyz -h
Usage: vdb_tool ... xyz [options] filenames+

Positional Arguments:
  filenames
	The input filename(s) (.txt), each corresponding to a grid in the output VDB:
  - Line 1 is the name of the grid
  - Line 2 is the background value
  - Line N is 'X Y Z Value'

Options:
  -h/--help
	Display this help and exit.
  -o/--output string
	The output filename.

The idea is that for each grid you want in the output VDB, you have a plaintext file where the first line is the name of the grid, the second line is the background value, and all subsequent lines are formatted as xIndex, yIndex, zIndex and value, where the index triplet values must be integers (i.e., 123 and not 123.0). To collect them all into the same VDB, you just pass all of the input filenames to vdb_tool xyz with -o output.vdb (if not specified, output filename will default to the name of the first file + .vdb).