VDB Export

From Terragen Documentation from Planetside Software
Revision as of 16:23, 2 November 2022 by Redmaw (talk | contribs) (Added example image for VDB Export feature.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Beginning with Terragen 4.3, the Linux build of Terragen Professional can export cloud layers to VDB files from the command line. The exported VDBs are voxelised representations of cloud density.

NEW: Beginning with Terragen 4.6.11, VDBs can be exported in the UI from the Node Network. Open the right-click/context menu for a cloud node and select "Export VDB File...". This is currently limited to Terragen Creative and Terragen Professional.

VDBs can be exported from layers of type Cloud Layer V2, Cloud Layer V3 and Easy Cloud. The exporter works on whole cloud layers, but it can only export one layer at a time. If you want to export more than one cloud layer, export one VDB file for each layer.

VDB Export feature from an Easy Cloud.

Versions and Platforms[edit]

  • Windows: Terragen Professional 4.6 and above, Terragen Creative 4.6 and above
  • Linux: Terragen Professional 4.3 and above

Exported Region[edit]

The region to be exported is defined by the "localisation" parameters on the Main tab of the cloud layer.

Easy Clouds are always "localised" cloud layers. That means they are limited to a finite region of space which is controlled by the altitude, depth and "radius of localisation".

Cloud Layer V2 and Cloud Layer V3 do not need to be localised for rendering, but if you export them to a VDB file you need to pay attention to the localisation parameters. They define the region of space that will be exported, regardless of whether 'localise' is enabled.

We recommend that you only use the exporter for cloud layers which are localised, because exporting of non-localised layers is tested less often so there are more likely to be bugs related to this.


The resolution of the voxel buffer is controlled on the Optimisation tab of your cloud layer, using the "millions of voxels" parameter. The main use of these settings is for optimising rendering, but the VDB exporter borrows these numbers when it generates the voxel buffer. The XYZ voxel buffer size shown below the "millions of voxels" parameter is just an approximation, because the curvature of the planet requires that the VDB exporter work slightly differently from the built-in voxel buffer for rendering. However, the approximation gives you a good idea of how much calculation needs to be done to generate the VDB file.

The export process takes some time to finish, and can produce very large files. The size of the VDB file of course depends on the voxel resolution you specify, but it's also affected by how much empty space there is in the volume.

Export from the UI[edit]

Right-click/context-click on a cloud node in the Node Network and select "Export VDB File...", choose an output filename and select "Save". The voxel generation process will begin and a progress window will appear. When it has completed generating the voxel buffer it will save the buffer to the file. This is currently limited to Terragen Creative and Terragen Professional.

Command Line Export[edit]

To export a cloud layer from the command line, use the following:


   tgdcli.exe -p project.tgd -exportvdb "Name of cloud layer" filename.vdb -threads numthreads


   ./terragen -p project.tgd -exportvdb "Name of cloud layer" filename.vdb -threads numthreads

The cloud name needs to be in quotes if there are spaces in its name. Usually there are.

The use of the -threads command line option is optional, and can be inserted anywhere in the command line as long as it is followed by an integer number and doesn't break apart any other argument groups. If you don't use the -threads option, Terragen will use as many logical cores as it thinks are available on your computer. Builds earlier than 4.3.16 can only use one thread to export.

Multi-Threaded Performance[edit]

At the time of writing (build 4.3.16) the exporter has not been fully optimised for multi-threading, but it works. We've noticed that performance drops off as the number of threads increases, and the fastest export times may be at a relatively low number of threads. Therefore we strongly recommend that you use the -threads option and experiment with different thread counts to see what works best for your scene and your hardware.

What About Mac?[edit]

We plan to add this feature to Mac builds in the near future.

Send Us Feedback[edit]

The VDB exporter is a relatively new feature. So please let us know how you are using it, and send us suggestions for how we can improve it.

A parameter is an individual setting in a node parameter view which controls some aspect of the node.