README File for VolPack Example Programs
----------------------------------------

The programs in this directory demonstrate how to use the basic
features of the three rendering algorithms in the VolPack library.
See the vprender program for a more complete application.

For installation instructions, see the README file in the toplevel
directory of the VolPack distribution.

For a quick test of your installation, run test.csh.  The output files
are brainsmall1.ppm, brainsmall2.ppm, brainsmall3.ppm and
brainsmall4.ppm.  They should all be identical to check.ppm.

The input data (brainsmall.den) is an MRI scan of a human head,
derived from public domain data provided by SoftLab at UNC Chapel
Hill.  The original MRI scan has been scaled down to 128x128x84 voxels
using a Gaussian filter.

Three programs are provided to convert the volume data into data
structures used by VolPack, and the fourth program does the rendering.
It produces an image in PPM format.

The first program, "makevolume", takes no arguments and creates an
unclassified volume (brainsmall.rv) from the raw volume data
(brainsmall.den).  The unclassified volume includes all of the data in
brainsmall.den as well as precomputed information for shading and
classification.

The second program, "makeoctree", takes no arguments and creates a
min-max octree (brainsmall.oct) from the unclassified volume
(brainsmall.rv).  The octree can be used by the rendering program to
accelerate rendering, but it is optional.

The third program, "classifyvolume", creates a classified volume
(brainsmall.cv).  A classified volume includes an opacity with each
voxel along with information for shading.  It is stored in a format
which is optimized for fast rendering and which (usually) requires
less storage than the unclassified volume.  There are three ways to
call classifyvolume:
    1) classifyvolume
	With no arguments, classifyvolume creates brainsmall.cv from
	the unclassified volume (brainsmall.rv).
    2) classifyvolume -octree
	With the -octree flag, classifyvolume creates brainsmall.cv from
	the unclassified volume (brainsmall.rv) and the min-max octree
	(brainsmall.oct).  This method is much faster than method 1.
    3) classifyvolume -rawdata
	With the -rawdata flag, classifyvolume creates brainsmall.cv
	directly from the raw volume data (brainsmall.den).

The fourth program, "rendervolume", creates an image (brainsmall.ppm)
in PPM format.  There are three ways to call rendervolume:
    1) rendervolume
	With no arguments, rendervolume creates brainsmall.ppm from
	the unclassified volume (brainsmall.rv) using the slowest
	rendering algorithm.
    2) rendervolume -octree
	With the -octree flag, rendervolume creates brainsmall.ppm from
	the unclassified volume (brainsmall.rv) and the min-max octree
	(brainsmall.oct) using the fast classification and rendering
	algorithm.  This method is much faster than method 1.
    3) rendervolume -classified
	With the -classified flag, rendervolume creates brainsmall.ppm
	from the classified volume (brainsmall.cv) using the fastest
	rendering algorithm.  This method is even faster than method 2.
The rendervolume program can also take an optional numerical argument
which is the number of frames to render.  In this case the program
will produce output files of the form "brainsmall_{number}.ppm" where
{number} is a frame number.  The frames form a movie with a 5 degree
rotation about the vertical axis between each frame.  For example:
       rendervolume -classified 30
produces a 30 frame movie from headsmall.cv.  The file "check.ppm" is
a PPM image file which should be identical to the first frame of
output from rendervolume.  The PPM image format is recognized by many
image viewers and conversion programs.

Experiment with the programs to see the relative speed of the three
algorithms on your machine!  See the VolPack User's Guide for the
intended uses of each algorithm.

File Sizes:
    raw data (brainsmall.den):			1376318 bytes (1.3 Mb)
    unclassified volume (brainsmall.rv):	5505104 bytes (5.3 Mb)
    min-max octree (brainsmall.oct):		 136748 bytes (0.1 Mb)
    classified volume (brainsmall.cv):		3215848 bytes (3.0 Mb)
    image (brainsmall.ppm):			  65551 bytes

Finally, the program "scalevolume" demonstrates how to use the volume
resampling utilities to change the resolution of a volume.  It can be
used to upsample or downsample volumes in .den format.  See the
comment at the beginning of scalevolume.c for usage information.