Copyright (c) 2005, Stanford University All rights reserved. RAPTOR README file http://graphics.stanford.edu/raptor Outline: How to build Requirements How to run Rendering window options and interaction Dataset information Transfer function information Known limitations Shaders Notes --------------------------------------------------------------------------- How to build: Building Raptor requires a full Chromium source tree, CR 1.8 for this release. See http://chromium.sourceforge.net for more information. 1) Build Chromium. 2) Unzip the source inside the cr/progs directory 3) Run make from within /cr/progs/raptor --------------------------------------------------------------------------- Requirements: Raptor requires hardware/driver support for ARB_fragment_program, ARB_vertex_program, and EXT_texture3D. -------------------------------------------------------------------------- How to run: By default, Raptor will run in single node mode and center any volume loaded. Enabling cluster mode will be discussed shortly. The command line looks like this: raptor [CR] = the volume description file provided with the dataset = the path to the shaders *.vp and *.fp Raptor will use = the transfer description file provided with the 2D transfer function = The position in the data in x to start from = The position in the data in y to start from = The position in the data in z to start from = The amount of the dataset to load in x = The amount of the dataset to load in y = The amount of the dataset to load in z [CR] = Add this flag to the end of the command line to enable running in multi-node mode with Chromium Single node (local display) example: 'raptor /spire/raptor/middle.dat /software/cr/progs/raptor /spire/raptor/base.dat 128 128 0 256 256 256' will load the volume described in middle.dat, the lit_volume.fp and vol_vertex.cp from /software/cr/progs/raptor, the 2D transfer function described in base.dat. Raptor will load the chunk of the volume starting at 128x128x0, and will load a 256^3 volume in total. You can get this example dataset, middle.tar.gz, from the Raptor homepage listed above. Multi node example: See raptor_2.conf and raptor_4.conf for examples on how to do this with Chromium and CRUT. See the Known Limitations section for an explanation on why the volume blocks are overlapped by on voxel on each side. NOTE: At the moment, the binaryswap SPU is the only compositing SPU that can enforce ordering on the blending for final display. -------------------------------------------------------------------------- Rendering window options: 'r' will reset view position and rendering options to defaults 'o' will change the rendering mode to orthographic 'p' will change the rendering mode to perspective (default) 'q' will exit ',' will decrease the number of slice planes '.' will increase the number of slice planes 't' will change the left mouse button function between translate and rotate Interaction: Left mouse button - rotate Middle mouse button - translate in Z Right mouse button - translate in X and Y -------------------------------------------------------------------------- Dataset information: The datasets Raptor currently handles are 16-bit unsigned short. The data layout assumed is XYZ order. Basically, if you can all of the raw CT slices together, you will get the correct layout order. Each dataset must provide a description file. This file give the location of the dataset, it's dimensions, voxel spacing, and tells raptor if byte swapping is required. For example, the description file for middle.vol looks like this: #location of raw data file datafile: /spire/raptor/torso.vol # offset to data in case there is a header offset: 0 # dimensions of the data width: 512 height: 512 depth: 256 # the dimensions of each voxel vox_width: 0.6 vox_height: 0.6 vox_depth: 1.2 # do we need to byte swap the data on read? byte_swap: true ----------------------------------------------------------------- Transfer file information: Each 2D transfer file has a description file similar to the one above for volume data. Here is an example for base.xfer # location of raw xfer file datafile: /spire/raptor/base.xfer # size of xfer file width: 256 height: 256 # these scale the 16 bit volume density to map # 0-2000 to 0-1 gradient_scale: 32.7675 density_scale: 32.7675 ---------------------------------------------------------------- Known limitations: 1) Currently, there is no graphics hardware that supports non power-of-two 3D textures, so all rendered datasets must be a power-of-two in each dimension 2) The 2D transfer functions currently supported must also be a power-of-two in X and Y. 3) For the parallel version to composite correctly, you must overlap the blocks by one voxel on each side. This is currently required to make the sampling planes line up between multiple nodes. 4) This version does not support precomputed gradients, and thus computes them on the fly in the shader. ------------------------------------------------------------- Shaders: Raptor currently comes with s simple Blinn-Phong shading model. vol_vertex.vp is the vertex program, and lit_volume.fp is the fragment program. vol_vertex.vp: This basically maps the incoming vertex to texture space and generates texture coordinates used during central/forward differencing for gradient calculation. lit_volume.fp: This is where the meat is. It does gradient calculation using central differencing by default. However, you can comment out the central differencing code and comment in the forward differencing code to sacrifice accuracy for performance. Using the volume density and gradient magnitude at the current position, it then does a lookup into a 2D transfer function. It then does basic Blinn-Phong two-sided lighting. -------------------------------------------------------------- Notes: 1) This software has only been tested with clusters running ATI 9700 and higher hardware. It also seems to work with Nvidia Geforce FX based systems. However, mixing ATI and Nvidia systems in a cluster or between the cluster and display node(s) does not currently work correctly with Chromium. 2) This application give a good example of how to integrate an application with Chromium and CRUT. For more information, assistance, or submitting bugs found with Raptor, contact Mike Houston (mhouston@graphics.stanford.edu). For more information or assistance with Chromium, try the Chromium mailing lists chromium-dev@lists.sourceforge.net and chromium-users@lists.sourceforge.net.