The input and output files should both be vdb files. The grids are the list of grids that should have mipmaps generated. Standard usage would probably be to provide a vdb file and give all of the grids so that they are all mipmapped, but per-grid decisions can also be made. Grids that are not included in the list will be written to the output file as they are in the input file.
The metadata argument allows for metadata from the original grids to be copied to the coarse mipmap grids that are generated. All of the strictly necessary metadata is generated automatically, so there isn't a specific requirement here unless GridGroups are being used. Beyond that, I assumed it might be useful to copy metadata in case there are tools that use grid metadata down the line.
vdbmake is a tool that reads as input an OpenVDB file and writes out an OpenVDB file. All grids are copied from the input and written to the output, with some or all of those grids augmented with mipmap information and minmax information. The output file is optimized for use with aggregate volumes.
Mipmapping is a standard technique used to improve texture aliasing and rendering performance by automatically choosing an appropriate texture resolution level from a pyramid based on viewing size and angle of the texture on screen. This technique can also be applied to volumetric data comprised of voxels: in much the same way that a 2D mipmap pyramid level contains texels that are averages of four finer texels, a 3D mipmap pyramid level contains voxels that are each averaged from eight finer voxels. Mipmapping a volume asset will increase its disk space significantly, and may increase memory during rendering somewhat if the finest voxels are appropriately sized to the level of detail required for the camera; however, if the voxels are much finer in detail than the camera settings require, mipmapping can save significant RAM and render time because the renderer will only load coarser averaged voxels instead.
By default, when specifying:
> vdbmake input.vdb output.vdb
all grids from the input file input.vdb are read and processed to generate additional mipmap information. vdbmake optionally allows for a list of a subset of the grids to be specified as the last set of arguments:
> vdbmake input.vdb output.vdb density v
Grids on this list (in this case, "density" and "v") will have mipmap information generated, while grids that are not on this list will simply be copied to the output file.
The number of pyramid levels can be controlled by specifying the -n parameter, which takes an integer specifying the additional number of mipmap pyramid levels to generate.
The minmax information that is generated by vdbmake is used in conjunction with volumes that have Attribute "volume" "int dsominmax" [1] to greatly accelerate time to first pixel for aggregate volumes. The additional information takes the form of a dual mipmap pyramid that contains the minimum and maximum values of the source grid. By default, any float grids in the input file that are processed for mipmapping will also have generate minmax information. As a space optimization, the optional -minmax parameter can be used to specify the name of the source grid that contains the density information; grids that do not match this name may get mipmapped but will not generate the additional dual minmax pyramid dataFor GridGroups, the work is a bit involved. First, the original grids will have to have a label corresponding to the name of the group (e.g. cluster_0) and an integer `index` that is unique to the grid. Both of those metadata keys also need to be copied to the coarse grids using the meta argument (-meta label -meta index).