Difference between revisions of "VolViewerUserManual"

From BanghamLab
Jump to navigation Jump to search
Line 23: Line 23:
==Loading Data==
==Loading Data==
To load data into the viewer, this can be achieved by one of four mechanisms:
To load data into the viewer, this can be achieved by one of three mechanisms:
* Using the '''FILE''' dropdown menu.
* Using the '''FILE''' dropdown menu.
* Using the '''Drag&Drop''' event.
* Using the '''Drag&Drop''' event.
* Setting a default file to load in the '''settings.ini''' file
* Using the '''scripting interface'''
* Parsing a directory name as a '''command line parameter'''
===The File Dropdown Menu===
===The File Dropdown Menu===
Line 47: Line 46:
The Drag&Drop accepts drops of either; a single image file in you stack, a .dat file or a .raw file.
The Drag&Drop accepts drops of either; a single image file in you stack, a .dat file or a .raw file.
===The Settings.ini file===
===Scripting Interface===
The viewer also supports loading of data via the settings.ini file. The settings.ini file can be found in the root of the viewer folder. The settings.ini file contains many parameters to control the default behaviour of the viewer, all parameters have comments explaining what they do.
See [http://dmbi.nbi.bbsrc.ac.uk/index.php/VolViewerScriptsAPI this] site for more information.
With regards to data loading, you are able to setup a file the viewer will load automatically every time you launch it. This is particularly useful if you plan on using the viewer to display data during a talk/presentation.
The entry you need to modify in the settings.ini file is:
You can specify the default file to load inside the "" marks. This can be an absolute file path, ie: "C:\MyStuff\SomeDirName\Data\CylindersRGB.dat" or a relative file path ie: "Data\CylindersRGB.dat"
===Command Line Parameter===
It is also possible to parse a file as a command line parameter for the viewer to load. For example under windows you may want to create a .bat file and call the viewer as follows:
VolViewer voldir="%CD%\Data\seedling\Slice000.png"
This will load the image stack who's first file is Slice000.png. One useful tip for windows users is that the %CD% command gets the path of your current working directory.
  '''*Exercise 1:'''
  '''*Exercise 1:'''

Latest revision as of 11:25, 27 March 2012

Quick Guide

Loading Volume Data

The viewer supports two types of file formats for loading volume data. It also supports four different ways to actually load data into the viewer. See the subsections for more information about the file formats and data loading mechanisms.

Supported File Formats

Image Stacks

The viewer supports image stacks in the following file formats: PNG, BMP, TIFF, JPG. For data that does not have equal spacing in the X,Y,Z dimensions, ie: confocal data, you may also create a text file called voxelspacing.txt to specify the voxel spacing independently for each axis. This file needs to be in the same folder as where your image stack files are. This text file takes the following format:

x 0.488281
y 0.488281
z 1.506024

Note that an image stack is a series of 2D images for each z-series of your stack. The images can be 8bit grey scale or 8bit RGB.

Raw Volume

Raw volumes are supported, these volumes are made up of two files, a .raw and a .dat file. The .raw file is the volume values. These values are stored in binary format, and the voxel values are ordered as R/G/B triplets and in X,Y,Z traversal order. The .dat file with the same filename as the .raw file contains the metadata of the volume. This metadata is the extra information you need to be able to load the volume. This data is X,Y,Z dimensions and the data type.

Loading Data

To load data into the viewer, this can be achieved by one of three mechanisms:

  • Using the FILE dropdown menu.
  • Using the Drag&Drop event.
  • Using the scripting interface

The File Dropdown Menu

The easiest method to load data is to do this via the FILE dropdown menu.

Once you select either a stack or a raw volume you will be presented with a file dialogue which you can point to the file you want to load. Note that when loading an image stack you can point the viewer to any file in your stack, it does not have to be the first image of the stack.

Note there are keyboard short-cuts to facilitate the loading of volume data:

* CTRL + R: load a raw volume
* CTRL + S: load an image stack

The Drag&Drop Event

With the Drag&Drop event you can load data into the viewer by simply dragging one of the supported files to the main rendering window. See the figure below.

The Drag&Drop accepts drops of either; a single image file in you stack, a .dat file or a .raw file.

Scripting Interface

See this site for more information.

*Exercise 1:
Try loading a volume by downloading the sample volume here and using the drag and drop method.

Saving Volume Data

The viewer allows you to save your volume data either as a .RAW binary file or a stack of PNG images. This is achieved by using the FILE dropdown menu and choosing the SAVE option. Note that when saving a PNG image stack you will be asked to point the viewer to a directory that it store the volume stack.

Interacting with the Volume

Once a volume is loaded you can interact with the volume by rotating it, moving it (translating), or zooming in and out. This is achieved via the mouse.

Arcball Rotation

To rotate a volume you use the left mouse button. Click on the centre (more or less) of the view screen and without releasing the left mouse button drag the volume in your desired direction you wish to rotate it. See the figure below for more details.

Zooming In/Out

Zooming in and out is achieved using the right mouse button. You can zoom in by clicking and not releasing the right mouse button and moving the mouse down. Or to zoom out you click the right mouse button and without releasing move the mouse up.


To move or translate a volume you use the middle mouse button. Translation is achieved by clicking and keeping pressed the middle mouse button, then by either moving left, right, up or down you are able to move the volume. To stop translation simply release the middle mouse button.

(NB) Currently the centre of rotation is not affected by the translation, and the volume will still rotate about it's centre even after translation. The ability to change this behaviour will be introduced in a future release.

*Exercise 2:
Try rotating and zooming the volume.




This toolbar allows you to control various viewing options.

  • I: Toggles the volume greyscale channel
  • R: Toggles the volume red channel
  • G: Toggles the volume green channel
  • B: Toggles the volume blue channel
  • S: Toggles the iso-surface (if computed)
  • mip: Toggles the Maximum Intensity Projection mode
  • BG: Allows you to specify the background colour
  • 3D: Allows you to enable stereo rendering (requires a 3D screen)
  • camera icon: Takes a screen grab of the current view and prompts you with a save file dialogue.
  • qual: Various viewing quality presets.
  • view: Various view direction presets.
  • on/off: Various viewing toggles.
*Exercise 3:
Enable/Disable the red channel
Toggle the MIP rendering mode
Use the view menu to view your data from the LEFT orientation.
Use the on/off menu to toggle the axis



  • graph icon: Brings up the transfer function widget.
  • crop icon: Brings up the crop widget.
  • clipping plane icon: Brings up the clipping widget.
  • measure icon: Brings up the measure widget.
  • surface icon: Brings up the iso-surface widget.
  • filter icon: Brings up the filter widget.
*Exercise 4:
Open the transfer function widget and adjust the opacity and threshold the volume.
Open the clipping widget to clip the volume
Open the filter widget to apply some Gaussian smoothing to your volume.



  • visual bookmarks icon: Allows you to save an orientation, clip state and transfer function state of your volume as a bookmark
  • movie icon: Allows you to save movie frames for your volume.
  • lighting icon: Allows you to apply lighting to your volume data.
  • settings icon: Allows you to control various performance and quality setting
*Exercise 5:
Use the visual bookmarks to save two different views of you volume, and toggle between them by double clicking the thumbnails.
Use the movie icon to save the frames for a movie