Volspy is an interactive volume visualization tool. Volspy is being developed to support research involving 3D fluorescence microscopy imaging, but may be applicable to other 3D images as well. Volspy is primarily used by its authors as a framework for other projects such as Synspy, an interactive synaptic visualization and classification tool.
Volspy is experimental software that is subject to frequent changes in direction depending on the needs of the authors and their scientific collaborators.
Volspy has two usage scenarios:
- A framework for volumetric data processing tools, where a basic interactive volume rendering capability can complement custom data-processing tools.
- A standalone viewer application for quickly inspecting several common 3D image formats based on TIFF.
Volspy is developed primarily on Linux with Python 2.7 but also tested on Mac OSX. It has several requirements:
- Vispy visualization library to access OpenGL GPUs. A compatible development version is needed, such as karlcz/vispy which is a clean branch of the upstream vispy/vispy master.
- Numpy numerical library to process N-dimensional data.
- Tifffile for access to OME-TIFF and LSM microscopy file formats as well as basic 3D TIFF files containing a stack of 2D pages.
- Check out the development code from GitHub.
- Install with
python setup.py install
.
- Obtain a sample 1-4 channel 3D TIFF image such as: http://www.isi.edu/~karlcz/sample-data/zebra-d19-03b-D.ome.tiff Warning: this is a large 886 MB file!
- A 1-channel image will be interpreted as gray.
- A 2-channel image will be interpreted as red-green.
- A 3-channel image will be interpreted as red-green-blue.
- A 4-channel image will be interpreted as red-green-blue-alpha.
- Any N-channel image with more than 4 will be interpreted one channel at a time (as gray) with a command to step to the next channel.
- Launch the viewer
volspy-viewer zebra-d19-03b-D.ome.tiff
- Interact with the viewer
- Press the
ESC
key when you have had enough. - Press the
?
key to get UI help printed to console output. - Click and drag volume with primary mouse button to rotate.
- Click and drag volume with secondary mouse button to translate (pan).
- Scroll the vertical scroll wheel to move a clipping or slicing plane up and down the viewing axis.
- Press
SPACE
key to enter or exit slicing mode:- Entry to slicing mode repositions slice plane to intersect origin. Use shift modifier to retain current clip distance.
- Entry to clipping mode repositions clip plane to near clipping distance. Use shift modifier to retain current slice distance.
- Press number keys
1
to9
to change intensity gain and with shift modifier to get reciprocal gain. - Press keys
f
andF
to adjust the floor-level image intensity that is mapped to black. - Press
b
key to cycle through color blending modes:- Partial transparency
- Additive blend
- Maximum intensity projection
- Press
c
key to cycle through channels on images with more than 4 channels.
Do not be alarmed by the copious diagnostic outputs streaming out on the console. Did we mention this is experimental code?
Several environment variables can be set to modify the behavior of the volspy-viewer
tool on a run-by-run basis:
VIEW_ROTATE
specifies degrees of rotation for image about fixed X, Y, Z axis (default0,0,0
).VIEW_CHANNEL
specifies an integer channel number in range 0 to N-1 inclusive for N channel images, switching the viewer into single-channel mode and with the specified channel loaded initially. Thec
key can then be used to cycle through channels if desired. This mode is entered automatically for images with more than 4 channels.VOXEL_SAMPLE
selects volume rendering texture sampling modes fromnearest
orlinear
(default for unspecified or unrecognized values).ZYX_SLICE
selects a grid-aligned region of interest to view from the original image grid, e.g.0:10,100:200,50:800
selects a region of interest where Z<10, 100<=Y<200, and 50<=X<800. A start or stop value can be omitted to trim only the beginning or end of an axis, and both can be omitted to get the full axis, e.g.5:
,:1000
,:
. (Default slice:,:,:
contains the whole image.)ZYX_VIEW_GRID
changes the desired rendering grid spacing. Set a preferred ZYX micron spacing, e.g.0.5,0.5,0.5
which the program will try to approximate using integer bin-averaging of source voxels but it will only reduce grid resolution and never increase it. NOTE: Y and X values should be equal to avoid artifacts with current renderer. (Default grid is 0.25, 0.25, 0.25 micron.)ZYX_IMAGE_GRID
allows overriding of the actual image voxel size in case the image metadata is absent or wrong. The application also falls back to an assumed (1.0, 1.0, 1.0) micron grid if all else fails.ZNOISE_PERCENTILE
enables a sensor noise estimation by calculating the Nth percentile value along the Z axis, e.g.ZNOISE_PERCENTILE=5
estimates a 2D noise image as the 5th percentile value across the Z stack, and subtracts that noise image from every slice in the stack as a pre-filtering step. WARNING: use of this feature causes the entire image to be loaded into RAM, causing a significantly higher minimum RAM size for runs with large input images. (Default is no noise estimate.)ZNOISE_ZERO_LEVEL
controls a lower value clamp for the pre-filtered data when percentile filtering is enabled. (Default is0
.)
The ZYX_SLICE
and ZYX_VIEW_GRID
parameters have different but inter-related effects on the scope of the volumetric visualization.
- The
ZYX_VIEW_GRID
can control down-sampling of voxels in arbitrary integer ratios, e.g. to set a preferred grid resolution that can differentiate features of a given size without wasting additional storage space on irrelevant small-scale details. This can save overall RAM required to store the processed volume data by reducing the global image size. The down-sampling occurs incrementally as each sub-block is processed by the block-decomposed processing pipeline. - The
ZYX_SLICE
can arbitrarily discard voxels and thus reduce the final volume size, though discarded voxels may be temporarily present in RAM and require additional I/O bandwidth.
Please direct questions and comments to the project issue tracker at GitHub.
Volspy is made available as open source under the (new) BSD License. Please see LICENSE file for more information.
Volspy is developed in the Informatics group at the USC Information Sciences Institute. The computer science researchers involved are:
- Karl Czajkowski
- Carl Kesselman