******************************************** * Virvo - Virtual Reality Volume Rendering * ******************************************** Author ------ Jürgen P. Schulze Brown University Department of Computer Science Providence, RI 02912 USA Virvo URL: http://www.cs.brown.edu/people/schulze/virvo/ Description ----------- The Virvo package contains two tools for interactive direct volume rendering: - DeskVOX is a volume viewer with a graphical user interface. - VConv is a command line volume file conversion tool. The volumes are rendered with a variety of graphics hardware accelerated algorithms based on 2D and 3D textures. System Requirements ------------------- - Required: A Windows or Linux based computer. - Recommended: Nvidia GeForce3 or higher, or equivalent ATI graphics card. - Optimum: Nvidia GeforceFX graphics card. Files in VOX Package -------------------- readme.txt This information file bin\win DeskVOX and VConv executables and required DLLs for Windows bin\linux DeskVOX and VConv for Linux examples\ sample volume files and movie scripts Using the Virvo Tools --------------------- - DeskVOX: Mouse button assignment in output window: - Left button: rotate - Middle button: pan - Right button: scale - VConv: 'vconv -help' gives detailed information about its parameters. Tip when running under Windows ------------------------------ Volume files can be passed to the program by drag-and-drop to the program icon. If you create an entry in the Explorer's View/Options/FileType list for xvf and rvf files, you can display volume files by double-clicking on them. Supported Volume File Formats ----------------------------- .dat: Raw volume data without any header. The data can have 1,2,3, or 4 byte per voxel. The program tries to find the volume dimensions automatically, but you can help by giving them in the file name, e.g. "cthead256x256x64.dat" for a 256 x 256 x 64 voxels dataset. Data order: starting from top-left-front, going right first, then down, then back. All bytes of each voxel must be stored consecutively, starting with the most significant byte or in RGBA order, depending on the data type. .rvf: Virvo format for 'raw volume data'. This format can easily be created by hand from any voxel data array on disk by just adding the appropriate header. Header: 3 x 2 Bytes (big endian) = volume width/height/depth (voxels) Example for a 256x128x127 volume (hex values): 01 00 00 80 00 7F Volume data format: 8 bit per voxel Data order: starting from top-left-front, going right first, then down, then back .xvf: Virvo format for 'extended volume data'. This format can handle more complex data but is still rather easy to describe. It features: multiple volume datasets (time steps) in one file, and the storage of multiple transfer functions. The data format is not restricted to 8 bit per voxel but can be 8, 16, 24 or 32 bits per voxel. Here is the file format specification (byte order: most significant first): Header: Offset Bytes Data Type Description --------------------------------------------------------------- 0 9 char file ID string: "VIRVO-XVF" 9 2 unsigned short offset to beginning of data area, from top of file [bytes] 11 2 x 4 unsigned int width and height of volume [voxels] 19 4 unsigned int number of slices per time step 23 4 unsigned int number of frames in volume animation (time steps) 27 1 unsigned char bytes per voxel (for details see vvvoldesc.h) 28 3 x 4 float real world voxel size (width, height, depth) [mm] 40 4 float length of a time step in the volume animation [seconds] 44 2 x 4 float physical data range covered by voxel data (minimum, maximum) 52 3 x 4 float real world location of volume center (x,y,z) [mm] 64 1 unsigned char storage type (for details see vvvoldesc.h) 65 1 unsigned char compression type (0=uncompressed, 1=RLE) 66 2 unsigned short number of transfer functions 68 2 unsigned short type of transfer function: 0 = 4 x 256 Byte, 1 = list of control pins 70 2 unsigned int icon size: width (=height) [pixels] Data area: Data starts at "offset to data area". Voxel order: voxel at top left front first, then to right, then to bottom, then to back, then frames. All bytes of each voxel are stored successively. In RLE encoding mode, a 4 byte big endian value precedes each frame, telling the number of RLE encoded bytes that will follow. If this value is zero, the frame is stored without encoding. Now follow the transfer functions. Each transfer function of type 0 consists of: - Zero terminated description string - Transfer function data in RGBA format: First all R's, then all G's, etc. Each R/G/B/A entry is coded as one unsigned byte. The table length depends on the number of bits per voxel: 8 bits per voxel => 4 * 256 bytes (RGBA) 16 bits per voxel => 4 * 4096 bytes (RGBA) 24 bits per voxel => 3 * 256 bytes (alpha conversion for RGB) 32 bits per voxel => 1 * 256 bytes (alpha conversion for density) - Transfer function in pin format: Each pin consists of 9 float values. The list is terminated by a set of -1.0 values. Hints: The big endian hexadecimal representations of some important floating point values are: 1.0 = 3F 80 00 00 -1.0 = BF 80 00 00 .avf: Virvo format for 'ASCII volume data'. The files are expected to be in ASCII format. They consist of a header and a data section: Header: In the header, several lines give information about the data format. Each consists of an identifier and a value, separated by whitespace. Each line can contain one identifier and one value. This file format cannot store transfer functions. At any point in the file comments starting with '#' are allowed, they cover the rest of the current line. The following abbreviations are used: for integer values for floating point values for an options list The following lines are required: WIDTH the width of the volume [voxels] HEIGHT the height of the volume [voxels] SLICES the number of slices in the volume [voxels] The following lines are optional. If they are missing, default values are used. FRAMES number of data sets contained in the file (default: 1) MIN minimum data value, smaller values will be constrained to this value (default: 0.0) MAX maximum data value, larger values will be constrained to this value (default: 1.0) BPC number of bytes per channel (default: 1) CHANNELS number of channels per voxel (default: 1) Example for RGB data: BPM=1, CHANNELS=3 XDIST the sample distance in x direction (-> width) [mm] (default: 1.0) YDIST the sample distance in y direction (-> height) [mm] (default: 1.0) ZDIST the sample distance in z direction (-> slices) [mm] (default: 1.0) TIME the length of each time step for transient data [s] (default: 1.0) Data area: The data area starts right after the header. The voxel data values are listed, separated by whitespace and/or end-of-line markers. Both float and integer values are accepted. Voxel order: voxel at top left front first, then to right, then to bottom, then to back, then frames. All elements of each voxel (RGB, RGBA) are stored consecutively. Sample file: WIDTH 4 HEIGHT 3 SLICES 2 FRAMES 1 MIN 0.0 MAX 1.0 FORMAT SCALAR8 # 8 bit data XDIST 1.0 YDIST 1.0 ZDIST 1.0 TIME 1.0 0.9 0.9 0.9 0.9 0.9 0.2 0.3 0.9 0.9 0.2 0.4 0.9 0.8 0.8 0.8 0.8 0.8 0.1 0.1 0.8 0.8 0.0 0.0 0.8 .tif, .tiff: 3D TIF File format. Virvo can only read files of this format, it cannot write them. Supported 2D Slice File Formats ------------------------------- .rgb: SGI RGB image file (8 bit grayscale only) .fre, .fro: Visible Human CT data file .pd, .t1, .t2, .loc: Visible Human MRI file .raw: Visible Human RGB (anatomy) file .pgm: Portable Graymap file (binary version only) .dcm: DICOM image file To save the current Virvo volume to disk you can use the 'Save Volume Data' menu item and give the filename the desired name. The saved format depends on the given filename extension. When loading, the file format is recognized by the given extension again. Movie Scripts ------------- The Virvo shell allows the user to generate movies with changing camera positions by loading ASCII movie script files (.vms). The following movie script commands are recognized: trans AXIS DIST Translates the data set by DIST in the AXIS axis. AXIS can be x, y, or z. rot AXIS ANGLE Rotates the data set by ANGLE degrees about the AXIS axis. AXIS can be x, y, or z. scale FACTOR Scales the data set by a factor of FACTOR. A value of 1.0 means no scaling. Values greater than 1.0 enlarge the data set, values smaller than 1.0 make it smaller. timestep INDEX Display time step number INDEX in a volume animation. The first time step has index 0. nextstep Display the next time step of a volume animation. Will switch to the first step after the last. prevstep Display the previous time step in a volume animation. Will switch to the last step after the first. setpeak POS WIDTH Set a peak pin with WIDTH width [0..1] to POS [0..1]. This will overwrite all previously defined alpha pins. movepeak DISTANCE Move alpha peak by DISTANCE. The total alpha range has extension 1.0, so a DISTANCE value of 0.1 would move the peak by 1/10th of the value range to the right. setquality QUALITY Set rendering quality. 0 is worst, 1 is default, higher is better changequality RELATIVE_QUALITY Changes the quality setting by a relative value. Quality value cannot get smaller than zero. show Displays the data set using the current settings. Here is an example movie script file: scale 1.2 # scale object by factor 1.2 rot x 20 # rotate 20 degrees about the x axis rot y 25 # rotate 25 degrees about y axis timestep 0 # switch to first time step show # display dataset timestep 1 # switch to second time step show # display dataset repeat 10 # repeat the following 10 times rot z 2 # rotate 2 degrees about z axis rot x 1 # rotate 1 degree about x axis show # display dataset endrep # terminate repeat loop rot z 10 # rotate 10 degrees about z axis show # display dataset setpeak 0.0 0.1 # define peak at the lowest scalar value with width 0.1 show # display dataset repeat 5 # repeat the following 5 times movepeak 0.1 # move peak to the right by 1/10th of the scalar value range show # display dataset endrep # terminate repeat loop Troubleshooting --------------- - ARToolkit mode: when icon is unchecked, system crashes Known bug, working on it. Versions History ---------------- Nr. Date Details ------------------------------------------------------------------------------ 1.0 99-11-11 1.1 99-11-17 released for SC99 1.2 99-11-18 released for SC99 1.3 00-02-15 1.4 00-02-28 1.5 00-03-13 1.6 00-05-25 released for SFB 382 review 1.7 00-06-19 socket connection updated 1.8 00-07-06 windows port done 1.9 00-12-11 new transfer function definition 1.91 01-03-13 - new software rendering algorithm - doxygen-style source code documentation 1.92 01-03-16 - new program names: vshell, vview, vconv - updated directory structure 1.93 01-03-30 - more detailed error messages at program start - selectable interpolation mode: linear/nearest neighbor - new rendering algorithm (based on shear-warp factorization) - new viewer choice in VShell 1.94 01-04-23 - new volume file format: AVF 1.95 01-05-03 - boundary box now drawn correctly with all renderers - user defined background color - VF file format features run length encoding of the volume data (8 bit scalars only) - new VConv command line parameters: flip, rotate, dist, crop, bits, resize, scale, sphere, interpolation, swap, shift, bitshift, transfunc - new VView command line parameters: renderer, size, perspective, boundaries, stereo, orientation, fps, transfunc 1.96 01-10-18 - adjustable image quality in VView - new PPM image file loader - enhanced DICOM file loader - new alpha pin type: hat pin - discrete colors in transfer function 1.97 02-09-04 - VView now features auto-rotation when the mouse button is released while in motion - new remote renderer on the basis of the shear-warp algorithm introduced: VRemote. Uses MPI for parallelization. - new socket library features timeouts and more reliable connections - TCP volume transfer now uses new data format: RVF and XVF binary formats can be used instead of complicated previous format - VConv: croptime parameter added for extraction of time steps in volume animation - VShell: Reload button added to Movie Script window - New movie script format which allows loops. Old movie scripts will not work anymore. - VShell now uses Java 1.3.1. - XVF files now support RLE encoding by default by incorporating routines from the previous VF format - VShell: slice viewer supports multiple slicing directions and optionally uses the transfer function for the images 1.98 03-06-24 - VConv: new -stat option for volume data statistics - VConv: new -fillrange option for optimized scalar data range - VConv: new -dicomrename option to rename DICOM files according to header information - VConv: new option -nocompress to save xvf files without RLE compression (compatible to earlier format) - VConv: new option -time to set the time step duration - VConv: multiple slice files or time steps must now be loaded with -files instead of -timesteps. Collections of slice files will no longer be read automatically. - VConv: new -deinterlace option to correct interlaced slices - VConv: new -pos option to set the position of the volume - VConv: new -hist option to print histogram information - VConv: new -zoom option to zoom data range - VConv: new -sign option to toggle sign of data values - VConv: new -blend option to blend two volumes together - VView: animation speed now adjustable - VView: replaced 'random peak' transfer function option with a peak which can be shifted left and right in the transfer function domain - VShell: new screenshot feature in File menu - New reader for BrainVoyager VMR and VTC files - New reader for Gordon Kindlmann's Teem volume files - Read and write support for NRRD files (Gordon Kindlmann's Teem format) - Performance measurements under Windows now much more exact with QueryPerformance API 1.99b - This is the first version released after I changed from the University of Stuttgart to Brown University - The XVF and NRRD file formats can now store multi-modal data - VConv: new -channels parameter to change the number of data channels - uncompressed 2D TIFF images can now be read - register combiners are now default algorithm for indexed mode - VShell: shows real data value in addition to data value in TFE - VShell: new menu item: File/Load Slices: creates volume from 2D slice images - VConv: -line renamed to -drawline - VConv: new command -drawbox to draw a solid 3D box in a volume - XVF files now support an icon - VConv: new parameters: -makeicon, -seticon, -geticon - Got rid of user interfaces for the shear-warp and remote renderers for the sake of a simpler API. Will put them back in once they have an edge over GPU based approaches. - VView: new parameter -voxeltype to set the rendering algorithm - VView: new right-button menu: voxel representation 1.991b - Now supports multiple channels of types: 8 bit, 16 bit, float - Optionally uses pixel shader for RGB volumes (requires GeForce FX) for real-time transfer function editing - VConv: added -swapChannels command - Renamed 'modality' to 'channel' for clarity's sake. - VConv: renamed -zoom to -zoomdata and added channel parameter - VConv: renamed -bits to -bpc - VConv: new command -makevolume to compute volume data 2.00b - Major version change to 2.0: GUI is now based no FOX Toolkit, rather than Java. This gives much higher reliability and easier installation. - New support for floating point data sets (float data type) - GUI support to change range of floating point data to be rendered. Distribution ------------ You may copy and distribute this program as you like, provided that the distribution files remain unaltered and complete. No one except the author is allowed to accept money for this software. Using parts or all of the program in other projects, or modification of the distribution is prohibited, unless explicitly allowed by the author. Any type of re-engineering of the compiled code is also prohibited. Some excerpts of the source code can be downloaded from: http://www.hlrs.de/people/schulze/spinoff/ If you are interested in other parts of the source code, please send an email to the author. Acknowledgements ---------------- I would like to thank the following people (in no particular order): - Philippe Lacroute from Stanford University for implementing the shear-warp algorithm and making his API publicly available as the Volpack library. - Roland Niemeier for the implementation of clipping planes and a first version of the perspective projection algorithm. I also thank him for his extensive effort in explaining his algorithms and source code to me. - Daniel Weiskopf for the spherical textures renderer and also for helping me understand volume rendering and OpenGL issues. - Sven Wergandt for writing the volume file format routines. His RLE encoding is very useful to save storage space. - Uwe Woessner for, among countless other things, adapting the COVISE system to make the Virvo VR plugin work. He and I also developed a virtual reality transfer function editor which is described in our IPTW/EGVE 2001 conference paper. - Ulrich Lang, my advisor in Stuttgart, who always pointed me in the right directions and helped me keep the big picture when I got lost in detail. - Marc Schreier for providing excellent user feedback on the Virvo distribution and for marvellous volume data sets, as well as for the TGA file loader. - Guenter Knittel for pointing me to the QueryPerformance API - Alexander Rice for the pixel shader integration, as well as porting the VShell Java GUI to FOX Toolkit. Disclaimer ---------- DISCLAIMER OF WARRANTY: THE PROGRAM AND/OR THE SOURCE CODE IS PROVIDED "AS IS." ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS ARE DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. SHOULD THE SOFTWARE PROVE DEFECTIVE IN ANY RESPECT, NOBODY ASSUMES ANY COST OR LIABILITY FOR SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY IS AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY COVERED CODE IS AUTHORIZED HEREUNDER EXCEPT SUBJECT TO THIS DISCLAIMER. LIMITATION OF LIABILITY: UNDER NO CIRCUMSTANCES NOR LEGAL THEORY, WHETHER TORT (INCLUDING, WITHOUT LIMITATION, NEGLIGENCE OR STRICT LIABILITY), CONTRACT, OR OTHERWISE, WILL ANYONE BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, LOSS OF DATA, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF SUCH PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. INDEMNITY: THE USER OF THIS SOFTWARE SHALL BE SOLELY RESPONSIBLE FOR DAMAGES ARISING, DIRECTLY OR INDIRECTLY, OUT OF ITS UTILIZATION OF RIGHTS UNDER THIS LICENSE. THE USER WILL DEFEND, INDEMNIFY AND HOLD HARMLESS EVERYBODY FROM AND AGAINST ANY LOSS, LIABILITY, DAMAGES, COSTS OR EXPENSES (INCLUDING THE PAYMENT OF REASONABLE ATTORNEYS FEES) ARISING OUT OF THE USER'S USE, MODIFICATION, REPRODUCTION AND DISTRIBUTION OF THE COVERED CODE OR OUT OF ANY REPRESENTATION OR WARRANTY MADE BY THE USER. SOURCE CODE: THE ORIGINAL SOURCE CODE WAS DEVELOPED BY JURGEN P. SCHULZE AT THE UNIVERSITY OF STUTTGART (GERMANY) AND BROWN UNIVERSITY (PROVIDENCE, RI, USA). THE SOURCE CODE IS COPYRIGHT (C) 1999-2004 BY JURGEN P. SCHULZE. COPYRIGHT IN ANY PORTIONS CREATED BY THIRD PARTIES IS AS INDICATED ELSEWHERE HEREIN. ALL RIGHTS RESERVED.