Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Note

This documentation is intended for developers working directly with the RenderMan interface or RIB files.

 


The OpenVDB Implicit Field Plugin impl_openvdb.so supports the use of OpenVDB files, either as implicit surfaces or as volumes. Two string arguments are required (a third argument is optional, as described below). The first argument is the name of the OpenVDB file. The second argument is the name of the grid which will be used as the source of the field function. This grid must be of float type, and can be either a level set (getGridClass() == openvdb::GRID_LEVEL_SET) or a fog volume (openvdb::GRID_FOG_VOLUME). If the grid is a level set, it will be converted to a fog volume where the interior voxels have a field function value of 1, the exterior voxels have a value of 0, and the narrow-band voxels have values varying linearly from 0 to 1. If the field function grid's class is not specified in the OpenVDB file, or is neither a level set nor a fog volume, an override can be supplied by appending ":levelset" or ":fogvolume" to the name of the grid.

...

Volume "blobbydso:${RMANTREE}/lib/plugins/impl_openvdb.so" [-100 100 -100 100 -100 100]
    [0 0 0] "constant string[2] blobbydso:stringargs" ["file.vdb" "density"]
     "varying float fuel" [] "varying color glow" []

fuel         float -100 -100 -100  100 100 100  200x200x200   1.8MVox 17.1MB
density      float -100 -100 -100  100 100 100  200x200x200   1.8MVox 17.1MB
glow         vec3s -100 -100 -100  100 100 100  200x200x200   1.8MVox 51.2MB

By defaultStarting with RenderMan 24.2, the plugin performs unfiltered lookups of voxel data. It can optionally also perform fully filtered lookups of voxel data in the OpenVDB file in order to avoid aliasing. Because OpenVDB does not currently support a pre-filtered hierarchical representation, internally a mipmap of voxels is maintained with downsampled levels generated on the fly as needed, as a means of accelerating the filtered lookups. Generating this mipmap will incur some overhead in time, especially if a large grid must be filtered down to only a few voxels. There is also some memory overhead to storing these mipmaps, but due to their nature the total memory should never amount to more than twice the memory needed by the base unfiltered grid.If filtering is enabled, the default width of the filter used over OpenVDB voxels favors antialiasing over detail (the DSO picks the maximum dimension of a PRMan microvoxel); this may provide a blurry result if the PRMan microvoxels are very anisotropic due to a high relative shadingrate. This blurriness can be alleviated at the cost of potential aliasing by passing an optional float argument to the DSO: this argument will be used as a multiplier on the filterwidth. The following is an example of how to pass a filterwidth of 0.5 to the DSO.takes additional parameters as a JSON string. The JSON string is supplied as an optional fourth string argument. If you do not want to specify a velocity grid but want to provide JSON parameters, you should leave the velocity grid argument as an empty string. The JSON string should be a top-level JSON dictionary containing one (or more) of the following keys:

  • filterWidth
  • velocityScale
  • densityMult
  • densityRolloff

These parameters are documented below. Here's an example of how the JSON argument can be passed to the DSO:

Volume "blobbydso:${RMANTREE}/lib/plugins/impl_openvdb.so" [-99 103.4 -41.6 49.6 -57.6 77.3]

...

 [0 0 0]
"constant string[2] blobbydso:stringargs" [
"dragon.vdb" "ls_dragon

...

" ""
"{\"filterWidth\": 0.5, \"velocityScale\": 1.0, \"densityMult\": 1.0, \"densityRolloff\": 0.0}"
]

By default, the plugin performs unfiltered lookups of voxel data. It can optionally also perform fully filtered lookups of voxel data in the OpenVDB file in order to avoid aliasing. In order to use the OpenVDB plugin's mipmapping functionality, the OpenVDB file must be processed using the vdbmake utility and the filterWidth should be set (the default value is 0, which disables mipmapping).

If filtering is enabled by setting the filterWidth to 1, the width of the filter used over OpenVDB voxels favors antialiasing over detail (the DSO picks the maximum dimension of a PRMan microvoxel); this may provide a blurry result if the PRMan microvoxels are very anisotropic due to a high relative shadingrate. Setting the filterWidth to a value smaller than 1 can alleviate the blurriness at the cost of potential aliasing.

By default, the velocity data is used directly by the plugin without any further transformation. Should the magnitude of the velocity vectors be inappropriate, a second optional float argument can be passed to the DSO which will be used the velocityScale parameter can be set in the JSON string argument. If set, the velocityScale will act as a multiplier on the velocity data. Note that if this float argument is used the filter width MUST also be specified. The following is the values in the velocity grid.

The densityMult and densityRolloff parameters can be used to perform simple density manipulations. The densityMult scales the values in the density grid, while the densityRolloff parameter applies a logarithmic falloff (with higher values providing falloff). By default, the densityMult is set to 1 (no scaling) and the densityRolloff is set to 0 (no falloff). Using these parameters is more efficient than manipulating the density values in a shader.

In versions of RenderMan before 24.2, the filterWidth and velocityScale are passed to the DSO as optional float arguments. The first float argument is the filterWidth and the second is the velocityScale. Note that if you are passing a velocityScale as a float argument, then you will also have to pass a filterWidth. Also note that passing these parameters as float arguments is deprecated in RenderMan 24.2. Here's an example of how to pass a velocity scaling argument of 0.25 to the DSO for use by a RiBlobby.the filterWidth and velocityScale as float args:

Blobby 1 [1004 0 2 0 3 1] [1 0.25] ["${RMANTREE}/lib/plugins/impl_openvdb.so"

...

 "water.vdb" "surface" "vel:fogvolume"]