OpenVDB volumetrics

This type of volumetrics can currently load an OpenVDB file (.vdb). This file format can efficiently store very detailed and large volumetrics based on a 3D grid of voxels instead of individual point particles, which makes it more efficient for storing and rendering detailed volumetrics where otherwise billions and billions of individual particles would have been needed. With the 3.1 update, Maxwell Render can now read and render these files directly. Any Maxwell material can be applied to the volumetric object, although in most cases a simple lambert is enough to create a very convincing volumetric that reacts very realistically to all lighting in the scene. Once you've set the "Field type" parameter to "Volume file based" you can load an .vdb file in the filename parameter.

OpenVDB parameters

  • the "Field Density" parameter has no influence when using OpenVDB files. The density is instead controlled via the "Base grid density" parameter.

Basic concepts

A volumetric simulation stored in the OpenVDB format can contain several 3D "grids". At the very least it will contain one "base grid" that defines the volumetric domain of the simulation. It can also contain additional grids, which is data that was calculated during the simulation. This can be temperature, velocity, acceleration, distance between particles and any other data which the simulation software can calculate. These additional grids are loaded using the "Additional Grids for UV" parameter and they can be used to construct the necessary UVs if you wish to visualize this data using a texture such as a gradient.

The extension can load grids where the data is stored either as: scalars (floats or doubles) and vectors (vec2 and vec3). Simulation data such as temperatures are usually stored as floats while velocity or acceleration are stored as vectors.

The actual detail of the volumetric OpenVDB grid does not depend on any parameter in Maxwell, it is "built in" to the grid, depending on how finely the grid cells where set during the simulation in your 3D application.


  • Base Grid: set the name of the base grid inside the VDB file that defines the volumetric domain. Usually this field is called "density". If no name is supplied here, Maxwell uses the first grid present in the file.

  • Base Grid multiplier: controls the density of the base grid. Higher values will make the volumetric appear more dense, letting less light through it.

Base grid multiplier set to 50 vs 2000
  • Additional grids for UV: here you can specify names of other grids usually found in VDB file that describe velocity or temperature, or any other data that was calculated during a simulation (such as particle distance, acceleration etc.). Use a comma to separate the different grid names. These grids can be used to map textures, usually a colored gradient, to better visualize the stored data. For example if the VDB file contains a "temperature" field, this means that the different temperatures of the simulation grid is stored in the file and you can use it to visualize these different temperatures using a blue to red gradient that uses this field as a driver to create the necessary UV map when rendering. Please see the "Texturing OpenVDB volumetrics" below for more details.

  • VEC_MOD 0 to 9 min/max: Lets you redefine the range of the corresponding vector grid, before it is normalized to 0,1 space for UV mapping. VEC_MOD_0 corresponds to the first vector grid found in the file, VEC_MOD_1 to the second one and so on.

  • FLOAT 0 to 9 min/max: Lets you redefine the range of the corresponding scalar grid, before it is normalized to 0,1 space for UV mapping. FLOAT_0 corresponds to the first float grid found in the file, FLOAT_1 to the second one and so on.

Min / Max ranges

Normally, you would look in Maxwells console panel to determine what the min/max ranges are for a certain grid, and enter those in the corresponding VEC_MOD_x, or FLOAT_x parameters.

Finding out which grids exist in an OpenVDB file

In order to find out how many grids are actually present in a VDB file, what their names are, what type of values they hold (float or vectors) and what these values are, simply load the vdb file using the MaxwellVolumetric extension and hit render. Look in the Console panel for detailed info about the data in the vdb file.

Texturing OpenVDB volumetrics


To experiment, you can use some of the VDB files found at the official download page of the OpenVDB website. In the following examples we have used the "explosion.vdb" file.


Texturing using the "base grid"

This can be textured simply by adding a regular UV set to the volumetric object (Planar, Cubic etc.) and a texture added to the material that's applied to the volumetric object. Procedural textures can also be used.

Here, the checker procedural texture was used, and a planar projector applied to the volumetric object.

Texturing using the extra grids

The first thing we need to determine is how many grids the VDB file has, and what their names are. To do this, simply load the file in your scene and click the render button from your main application, or from Studio. The intention is not to render the file at this time but simply to read what the Console panel in Maxwell tells us about the file. If the Console panel is not open, go to Window>Console and make sure it is checked.

In the above example we can see that we have a file with 3 grids. They are named: density, temperature, v (this grid probably holds the velocity information). They are of type float, float, vector respectively. Now that we know the names of the extra two grids, we can choose which one to use for generating the UVs, or in fact use both. In the "Additional grids for UV", we can write: temperature,v. This will generate two distinct UVs based on the temperature data and the velocity data. Lets use the temperature data. To be able to create UVs from this data, we must create a special type of UV set called VDB_FLOAT_00.

Open the Type dropdown and choose the UV set VDB_FLOAT_00

The UV set needs to be of type VDB Float because we are dealing with a VDB file, and the grid that's creating the UVs (the temperature grid in our case) is of type float. The reason we chose the "00" is because this is the first float grid that we are using. If we had two float grids that were generating UVs (both where specified in the Additional grids for UV parameter), and we wanted to use the second one, we would instead have chosen VDB_FLOAT_01. If there where 3 float grids specified and we wanted to use the third one, we would have chosen VDB_FLOAT_02 and so on. Please keep in mind that the count starts at 00, not 01.

Now that this special UV type has been added, we can add a texture to the material. We can leave the texture at channel 0, because we only have one UV set added to this object. In this case we added a gradient texture (please note that only the first row of pixels is used to texture the volumetric):


To accurately map the entire range of the gradient to the temperature UVs, we need to know the range of values found in the temperature grid. To do this, make sure "temperature" is written in the Additional grids for UV parameter and launch a render. In the Console panel, the values for this grid will now appear:

In the FLOAT_0 Max parameter enter the readout from the Console of the max range of the temperature grid: 0.884. We use the FLOAT_0 parameter because the temperature is the first additional grid we use, and it is of float type. The result of the gradient mapped on the volumetric:


Remapping the texture on the grid

By changing the corresponding min/max values, you can remap the gradient on the volumetric cloud, to make parts of it appear more prominently, or even make the gradient start to repeat. For example, if you set the max value to 0.2 instead of 0.884 in this case, the entire gradient will be mapped to parts of the grid that fall within the range 0.0 - 0.2. In areas of the grid that exceed that range, the grid will be repeated (if texture tiling is turned on), this time between the range 0.2-0.4, then repeated again between 0.4 -0.6, and again between 0.6 - 0.8. So we would have approximately 4 repeats in this case. On the other hand, if you set a max value double of what is stored in the grid, the actual max value of the grid will be "reached" much sooner and only the left half of the gradient will be visible on the volumetric. Finally, if you have texture tiling turned off and you use a smaller max value than the grid holds, in areas of the grid which have higher max values than what you've specified, the texture won't be repeated and instead it's the materials Reflectance 0 color which will show. The following four renders demonstrate using different max values and tiling set to on and off:


Upper left, the "true" max value of the grid was used and so the gradient was mapped in the most accurate, or predictable way. Upper right, the gradient is repeated several times. Lower left, since the max value used is double compared to what is actually stored in the grid, only half of the gradient is mapped to it. Lower right, tiling was off, and the reflectance 0 color was white - the gradient is only mapped to parts of the grid whose range is 0.0 - 0.2, and in parts with higher ranges, the reflectance 0 color becomes visible.