How to : Use OsgVolume with Volumetric Data


Viewing a volume using OsgVolume


There are currently two methods of building volumes for use in Present3D or directly in OsgVolume.

These methods are determined by the source data.  If you have dicom files (.dcm) then follow the Dicom method, if you have .jpg, .tiff etc then use the Non-Dicom method. Both can be saved as .osg or .ive files and then loaded in Present3D.

So why would you use OsgVolume rather than Present3D?

  1. It can be very helpful to preview a volume before including it in your Present3D xml file
  2. If a volume isn't loading in Present3D using OsgVolume will test that it is a valid volume file.
  3. To preprocess your volumes. For example, to create volumes from non-dicom files and save as a .ive file, so that it will load faster.

For information on including volumes in Present3D go here.


Dicom Files :

To view a volume from a folder (directory) of dicom files you will use the osgvolume command.

First, in your terminal window, you will need to navigate to the directory that has the folder that you want to use...

cd main_volume_directory/directory_that contains_the_folder_of _dicom_files

Then use osgvolume to load the folder you want use :

osgvolume directory_that_has_the_dcm_files

For example, I have a directory called test_volume that has 250 sequentially numbered test_volume_xxxx.dcm files. I would therefore use

osgvolume test_volume

This will allow you to test that the dataset is working as expected before going any further. If you don't get the expected results, then open the folder and check how many files/slices there are, as your graphics card might be limiting the number of slices that can be handled to 256, 512, 1024 or larger... make a copy of the folder and reduce the number of files to each of these limits in turn, until it works. For example, the ATI 4870 on the Mac should display 1024 512x512 slices.

In certain circumstances, the slice distance may not be read correctly, this can be rectified by using the x, y or z Multiplier function as appropriate :

osgvolume test_volume --zMultiplier 1.5


Using Osirix to Prepare Files for Present3D

It is possible to prepare files in Osirix  and then Export to .jpg or .tif. Doing this does mean you loose the ability to load the folder directly in Present3D and you should use the procedure below for Non Dicom files. 

However, the advantage of this workflow, is that you can use all Osirix's tools to colour, smooth and clip the ROI and then export for use in Present3D.


Non Dicom Files :

Unlike the Dicom files where you load the directory/folder that holds the files, with the non-dicom procedure you need to be in the directory/folder  and use the --images wildcard as below :

osgvolume --images *.tif  --zMultiplier 1.5 --replace-rgb-with-luminance

where .tif is changed to the appropriate extension and the zMultiplier (could also be xMultiplier  or yMultiplier depending on the original data) is changed to suit your data slice distance.

If your files are colour, the above will display them in greyscale, to solve this change  --replace-rgb-with-luminance to --replace-alpha-with-luminance

So you would do :

osgvolume --images *.tif  --zMultiplier 1.5 --replace-alpha-with-luminance



Using osgvolume with colour transfer function 

It is possible to use a Colour Look Up  Table (CLUT) to colour your volume data to improve readability. This is done using a transfer function and requires  both the --tf (or --tf-255) command plus the name of the text file that has the list of CLUT values saved as a .tf file : 

osgvolume folder_with_dicom_files --tf


osgvolume --images *.tif  --zMultiplier 1.5 --tf-255  

Where is a text file with the appropriate CLUT values.


Saving as  .osg or .ive file :

The volume can be saved as a .osg file by adding the -o followed by the name you wish to give your new file, as follows :

osgvolume --images *.tif  --zMultiplier 1.5 -o volume.osg

Please note, that a file will also be created and this is referenced by the .osg file , so both files should be kept together. Saving as a binary .ive solves this problem as well as loading faster.

So to convert your .osg file to a .ive file do :

osgconv volume.osg volume.ive

The volume.ive or .osg can then be used in P3D using the model tag.


Using in Present3D

You can load and view the resulting volume either by creating a P3D xml file with your volume and other data or just by using present3D on the command line, so type :

present3D volume.ive

and this will load your volume. You can now use the the a, t and d keys along with mouse movement, to interact with the volume. You can also use the v key to move through the four rendering techniques.

If you want to include your volumes in Present3D then go : here for further information



Making A Script To Create A .Osg Volume file :

Create a script as below substituting .tif for the image type you are using ie: .jpg .png etc. 

To create the script open a new document in BBedit (or other text editor) and paste the following text (modified with the commands you require) into it


osgvolume --images *.tif   --zMultiplier 1.5 -o volume.osg

echo make volume complete

exit 0

and save it into the directory where your image files are, with a name like:


then change permissions of the file - use terminal and go to the directory and do:

chmod +x make_volume

Now if you type :


this will create a file called volume.osg and a volume.dss image file.  Both the .osg and .dds file will need to be used together.  One loads the volume.osg file, and this volume.osg will reference the file for you.





Other command line options


for help :  osgvolume --help

Usage: osgvolume [options] filename ...


-h or --help Display this information

-s <numSlices> Number of slices to create.

-n Create normal map for per voxel lighting.

--clip <ratio> clip volume as a ratio, 0.0 clip all, 1.0 clip none.

--compressed Enable the usage of compressed textures.

--compressed-arb Enable the usage of OpenGL ARB compressed textures.

--compressed-dxt1 Enable the usage of S3TC DXT1 compressed textures.

--compressed-dxt3 Enable the usage of S3TC DXT3 compressed textures.

--compressed-dxt5 Enable the usage of S3TC DXT5 compressed textures.

--images [filenames] Specify a stack of 2d images to build the 3d volume from.

--maxTextureSize <size> Set the texture maximum resolution in the s,t,r (x,y,z) dimensions.

--num-components <num> Set the number of components to in he target image.

--r_maxTextureSize <size> Set the texture maximum resolution in the r (z) dimension.

--s_maxTextureSize <size> Set the texture maximum resolution in the s (x) dimension.

--t_maxTextureSize <size> Set the texture maximum resolution in the t (y) dimension.

--modulate-alpha-by-luminance For each pixel multiply the alpha value by the luminance.

--replace-alpha-with-luminance For each pixel m Set the alpha value to the luminance.

--shader Use OpenGL Shading Language.

--xMultiplier <multiplier> Tex coord x mulitplier.

--yMultiplier <multiplier> Tex coord y mulitplier.

--zMultiplier <multiplier> Tex coord z mulitplier.

--xSize <size> Relative width of rendered brick.

--ySize <size> Relative length of rendered brick.

--zSize <size> Relative height of rendered brick.