VolViewerUserManual

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 four mechanisms:

• Using the FILE dropdown menu.
• Using the Drag&Drop event.
• Setting a default file to load in the settings.ini file
• Parsing a directory name as a command line parameter

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.

The Settings.ini file

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.

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:

file_default_filename=""

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:
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.

Translation

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.

Toolbars

Viewing

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

Tools

• 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.

Settings

• 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

Command Line Arguments

Below is a list of command line arguments supported by the VolViewer application:

General

voldir=XXXXX            //To specify a local directory containing an image stack 
msr=XXXXX              //To specify a local MSR file (measurement geometry object) to load
tfunc=XXXXX            //To specilfy a local TFN file (transfer function) to load
slc=XXXXX               //To specify a local SLC file (clipping planes) to load
auto_close=1           //Tell the application to automatically close once all command line arguments are executed
auto_hide=1            //Tell the application to hide and run in a gui less mode

Movies

movie_rotate(sampling, savefolder, x, y, z, angle)                  //To create a rotation movie from an image

• sampling: is the angle step size
• savefolder: is the folder we wish to save frames to
• x,y,z: either 0 or 1 to enable rotation around that axis
• angle: the angle to rotate about

movie_rock(sampling, savefolder, angle)                               //To create a rock movie from an image 

• sampling: is the angle step size
• savefolder: is the folder we wish to save frames to
• angle: the angle to rock by (+angle to -angle)

Projections

set_view( x, y, z)                                                         //Set the default view of the volume as euler angles
render=1                                                                    //Creates a png of the volume in the root folder

OMERO

omero_server=XXXXX               //To specify the url of an omero server
omero_username=XXXXX          //To specify a username to connect to the omero server
omero_password=XXXXX          //To specify the password for the given username to connect to the omero server
omero_sessionid=XXXXX          //To specify a session id to join on the omero server
omero_port=XXXXX                //To specify the port of the omero server
omero_imageid=XXXXX           //To specify the image id on the omero server we wish to load in volviewer