VISTA Quick Start Guide

Before using the material in this section you'll need to download, compile / build / install Vista.

Lets Begin..

1) Download example files - save it at the same level where vista source was saved, to unzip/extract do as follows (This will create a directory named examples)

% tar -xzf example.tar.gz

(or % gunzip examples.tar.gz then % tar -xf examples.tar)

2) Download camera files - save it at the same level where vista source was saved, to unzip/extract do as follows (This will create a directory named cameras)

% tar -xzf cameras.tar.gz

(or % gunzip camera.tar.gz then % tar -xf cameras.tar)

3) Download map files - save it at the same level where vista source was saved, to unzip/extract do as follows (This will create a directory named maps)

% tar -xzf maps.tar.gz

(or % gunzip maps.tar.gz then % tar -xf maps.tar)

4) Now create a directory named "output" This will be used later to store results.

% mkdir output

% ls

The following should be the directory structure. (All at same level.)

svt-2.0, svt_build, examples, camera, maps and output

"svt-2.0" contains downloaded untared/unzipped source code
"svt_build" contains compiled/built source code
"examples" contains untarred/unziped volume files (*.raw, *.volb)
"cameras" contains untarred/unzipped *.cam files
"maps" contains untarred/unzipped *.cmp files
"output" is empty ( used for collecting output images later)

4) Change from current directory to "examples" directory
% cd examples

5) Help on vista (To view help page)
% ../svt_build/vista/vista -h

Using Vista

The guide uses raw format files for examples which require the "-raw" flag with x, y, z dimensions along with "-minmax" flag which sets the range of the data for color mapping.
Raw files are simple binary brick of char/short/ushort/int/float.
Make sure the current directory is "examples" (% pwd this will display your present working directory)
Run Vista from build directory (ie svt_build) if you made default installation.

The cube.raw volume file has dimension of 100x100x100 and contains scalar values ranging from 0 to 99.

The cube2.raw volume file has dimension of 50x100x200 and contains scalar values ranging from 0 to 49.

The cube3.raw volume file has dimension of 100x100x100 and contains scalar values ranging from 0 to 99 and has an addition header of size 1948 bytes.

Simple Run

Test Run 
% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  cube.raw
           This creates an output image "img_00001.ppm" in current  directory (ie examples).
           Default options used for resolution is 320 x 240, 
           background color - black, camera - perspective mode
   For viewing output files on unix like platforms
   % display img_00001.ppm (Image Magic should be installed on your system)

   On windows freely available Irfan View can be used to view  ppm files.

Show Bounding Box (optional)
% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --bbox  cube.raw
           --bbox  will create a bounding box around the volume

Show Volume Grid (optional)

% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --grid cube.raw
           --grid  will create a 10 x 10 x 10 grid on  the volume (This is irrespective of volume size)

Image Options

Output Image Resolution (optional)       
% ../svt_build/vista/vista  --raw 100 100 100 --minmax 0 99 -x 800 -y 600 cube.raw 

           -x 800 -y 600  will change output resolution of image and overwrite earlier img_00001.ppm file.         
           Again use the same technique above for viewing output ppm files.
           Default: The default image resolution is 320 x 240.

view output

Output  Image Name (optional)    
% ../svt_build/vista/vista  --raw 100 100 100 --minmax 0 99  --outbase ../output/my_render_  cube.raw 

           --outbase my_render_  will create an  image in output directory with filename as my_render_00000.ppm
           Default: The default image name is img_00000.ppm or img_00000.png

Output path and Image Name

Output path and Image Formats
Vista can output in PPM, PNG,PNGA (in 8 bit (default) or 16bit) and also Zbuffer for compositing.

PNG images
% ../svt_build/vista/vista  --raw 100 100 100 --minmax 0 99  --outformat png  cube.raw 

           --outformat png  will create output image with name img_00000.png
Caution: If this does not create PNG file then your system does not have png libraries in default location. 
Look under Installation section for compiling with PNG option.

16 Bit images
% ../svt_build/vista/vista  --raw 100 100 100 --minmax 0 99  --out16bit cube.raw
          --out16bit  will create output image with 16bit per channel

Caution: You might not be able to view 16 bit images in some programs

Z Buffer
% ../svt_build/vista/vista  --raw 100 100 100 --minmax 0 99  --outzbuf cube.raw 
           --outzbuf  will create output another file with same name as image with extension *.zbuf
This can be used with VComposite program under tools directory

Output Image Formats

Background color (optional)           

% ../svt_build/vista/vista  --raw 100 100 100 --minmax 0 99 -g 0.3 0.5 0.7 1.0 cube.raw 
           -g 0.3 0.5 0.7 1.0  will change the background color to the specified color in r,g,b,a where a is the opacity of background.
           (the values should be between 0 and 1)
           The output from this will overwrite earlier img_00001.ppm file.
           Again use the same technique above for viewing output ppm files.

-g 0.3 0.5 0.7 1.0

View Options

Viewing Orientation (optional)

../svt_build/vista/vista  --raw 100 100 100 --minmax 0 99  --top cube.raw
           --top will create an image with camera position viewing the top of the cube volume. 
           Similarily other views can be rendered.
           You can specify multiple camera views with  --persp(default), --front, --left, --right, --top, --back, --bottom 
           The options are additive so if you put them all on the same command line you  will get seven images.
           Default: The perspective view of cube is default viewing position ie --persp

--top

Camera distance (optional)

../svt_build/vista/vista  --raw 100 100 100 --minmax 0 99  --camdist 5.0 --top cube.raw
           --camdist 5.0 --top will create an image with camera position at a distance 5 units away from origin from the top.
           Caution: --camdist should be specified before view angle (ie --top, --bottom)
           Note: This option could also be used with spinx,spiny and spinz options
           Default: All standard orthographic cameras are positioned at distance 2.5 from origin. 
                        Except persp which is positioned at 3.0 from origin

--camdist 5.0 --top

--top

(default camera dist)

Camera Field of View - FOV (optional)

../svt_build/vista/vista  --raw 100 100 100 --minmax 0 99  --fov 90 cube.raw
           --fov 90 will create an image with cameras field of view as 90 degress 
           Default: The default fov is 45 degrees

--fov 90

default camera

Camera Aspect Ratio (optional)

../svt_build/vista/vista  --raw 100 100 100 --minmax 0 99  --ar 1 1 cube.raw
           --ar 1 1 will create an image with aspect ratio 1:1
           Default: The default aspect ratio is 4:3

--ar 1 1

default aspect ratio

Create Custom Camera

Mesh Viewer can be used to create camera files
Cam2Vista Utility to create camera files in Maya for use with Vista

Custom Camera position            
% ../svt_build/vista/vista  --raw 100 100 100 --minmax 0 99 --camfile ../cameras/x_111.cam  cube.raw
         --camfile  ../cameras/x_111.cam will view the  volume with x axis as up axis for camera with 
         camer position at  (1,1,1) looking at origin
         (Mesh Viewer can be used to create camera files or use the standard files in "camera" directory)

--camfile ../cameras/x_111.cam

Spin around a volume
% ../svt_build/vista/vista  --raw100 100 100 --minmax 200 7500 --spinx -s 10  cube.raw 

            --spinx will create a spin around x axis of the volume 
            -s 10 will set the step as 10 degree (default step is 1).
            Result would be an image sequences consisting of 36 images.

spin on x

spin on y

Volume Options

Specify Endianness of data (LSB or MSB)
% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --lsb   cube.raw
           --lsb  will specify if the data is in Least significant Byte format(eg: Intel Architecture)
           similarily --msb will specify if the data is in Most significant Byte format (eg: IBM architecture)

Change minmax input (Shrink the minmax range)
% ../svt_build/vista/vista --raw 100 100 100 --minmax 30 70   -g 0.5 0.5 0.5 1.0 cube.raw
           --minmax 30 70  will change the way the color mapping happens. 

           -g 0.5 0.5 0.5 1.0  will change the background color to grey (r,g,b,a)
     All values below min are clamped to min and all above max are clamped to max.

--minmax 30 70

compare --minmax 0 99

Change minmax input (Expand minmax range)
% ../svt_build/vista/vista --raw 100 100 100 --minmax -25 125 cube.raw
           --minmax -25 125  will expand minmax range of values in dataset thus produce different output

--minmax -25 125

compare --minmax 0 99

Change Volume Extents (Change shape of Volume) (not required- Automated since version 2.1)
% ../svt_build/vista/vista --raw 50 100 200 --minmax 0 49  -r 0.25 0.5 1.0  cube2.raw

      -r 0.25 0.5 1.0  will change the shape of the volume from cube to box
       Notice that this volume is not a cube it has different length,width and height 
       in order to change this proportionally, option -r needs to be used
       To calculate the x,y and z proportion take the ratio of corresponding(xyz) / max dimension 
       (i.e. 50/200 =0.25 for x, 100/200=0.5 for y, 200/200 =1.0 for z)

-r 0.25 0.5 1.0

Skip Header info 

Sometimes data contains some header info and needed to be skipped to read actual data correctly
% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --skip 1948  cube3.raw
           --skip 1948  will skip 1948 bytes in cube3.raw and then read the data

--skip 1948

Log transform on data
Sometimes data needs to be mapped in log space

% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --logmode  cube.raw
           --logmode  will skip transform the data in log space

--logmode

Compare default

Sampling of data (ABdepth)
Sometimes default sampling would produce not good results changing default settings may produce better results

% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  -a 0.1  cube.raw
           -a 0.1  will sample volume every 1/0.1 = 10th interval on each side thus results are not good

% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  -a 0.05  cube.raw
           -a 0.05 will sample volume every 1/0.05  = 20th interval on each side thus results are still not good


% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  -a 0.01  cube.raw
           -a 0.01  will sample volume every 1/0.01= 100th interval on each side 
            This time the results are good this is also the default setting

% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  -a 0.001  cube.raw
           -a 0.001  will sample volume every 1/0.001= 1000th interval on each side
           This time the results are better but rendering takes more time to complete.
           This setting is excessive and should only be used for production images 
           as the data is sampled at more intervals than actual content.
           
Rule of thumb: Use -a = 1/max dimension of data

ie if your dataset is 100 x 50 x 500 use "-a = 1/500 =0.002 "

-a 0.1

-a 0.01

(default)

-a 0.05

-a 0.001

(excessive for this data)

Color Options

Change Color ramp
% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --nogreen cube.raw

       --nogreen will change the color ramp from default to 'nogreen'. Simlarly other color ramps 
      can be used by specifying --spect or --bigspect or --nogreen or 
      --saturated or --vibrant or --y2r instead of --nogreen.

--nogreen

compare --bigspect

Inverse Color ramp
% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99 --inv --nogreen cube.raw

           --inv option can be used along with any color ramp (see above)
           This will change inverse the color ramp (ie now the colors are applied in reversed manner).

--inv --nogreen

compare --inv --bigspect

Skew Color ramp
% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99 --skew 0.25 cube.raw

           --skew 0.25 will change the balance of color ramp from 0.5(default) to 0.25 
           Notice the expansion(above 0.5) and squeezing(below 0.5) of color. 
           Essentially the  mid point of color ramp has moved to 0.25 from 0.5
           This option can be used along with any color ramps with/without inverse option.


% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99 --skew 0.75 cube.raw
           --skew 0.75 will change the balance of color ramp from 0.5(default) to 0.75

--skew 0.25

--skew 0.75

Compare default

Skip data range(s)
% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --top --skiprange 35 65  cube.raw
           --skiprange 35 65 will make the data between 35 and 65 invisible 
             (Notice the absence of data in central region of image)
           --top this sets the viewing camera to look from top of the volume.



% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  
   --top --skiprange 0 25  --skiprange2 75 99 cube.raw
           --skipval 0 25 will make the data between 0 and 25 invisible 
              (Notice the absence of data in left region of image)

           --skiprange2 75 99 will make the data between 75 and 99 invisible 
             (Notice the absence of data in right region of image)


% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  
    --top --skiprange 20 30 --skiprange2 45 60 --skiprange3 75 90 cube.raw
           --skipval 20 30 will make the data between 0 and 25 invisible

           --skiprange2 45 60 will make the data between 75 and 99 invisible
           --skiprange3 75 90 will make the data between 75 and 99 invisible
           (Notice the absence of data in three different regions of image)

--skiprange 35 65

--skiprange 0 25

--skiprange2 75 99

--skiprange 20 30

--skiprange2 45 60

--skiprange3 75 90

Compare --top

(no skipping)

Constant Opacity on whole data

% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --top --opacity 1.0 cube.raw
           --opacity 1.0 will render  the data  with complete opacity the render time 
                                would be very less as rays terminate quickly

           --top this sets the viewing camera to look from top of the volume.
This is sometimes desired when you are interested in the surface only

% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --top --opacity 0.01 cube.raw
           --opacity 0.01  will render  the data  with 0.01 opacity the render time would be more than above 
                                  as the cube is made fairly translucent

           --top this sets the viewing camera to look from top of the volume.

--opacity 1 0

--opacity 0.01

Compare --top (auto opacity control)

Custom Opacity on data range
% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --top --oprangeval 0 50 0.01 cube.raw
           --oprangeval 0 50  will render  the data between 0 and 50 with opacity 0.01 
Caution: The opacity value is tricky to use good thumb of rule where
             transparency is desired = 1/max dimension =1/100 in this case
             (Notice the translucency  of data in left  region of image)
           --top this sets the viewing camera to look from top of the volume.


% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --top --oprangeval 15 85  0.01 cube.raw
           --oprangeval 0 50  will render  the data between 15 and 85 with opacity 0.01 
             (Notice the translucency  of data in central  region of image)

--oprangeval 0 50 0.01

--oprangeval 15 85 0.01

Compare --top (no opacity control)

Custom Color Map (or Transfer Function)
The basic idea here is to control the mapping of color and opacity  in a desired manner. 
Look at these  files  and corresponding explaination

Map1

Map2

Map3

1
2
3
4
5
6
7
8
9
10
11
12

ColorMapKnots: 3
Knot:  0.0  1.0   0.0  0.0
Knot: 50.0  0.0  1.0  0.0
Knot: 99.0  0.0  0.0  1.0

1
2
3
4
5
6
7
8
9
10
11
12

ColorMapKnots: 3
Knot:  0.0  1.0   0.0  0.0
Knot: 50.0  0.0  1.0  0.0
Knot: 99.0  0.0  0.0  1.0
OpacityMapPoints: 3
Point:  0.0   0.00
Point: 50.0   0.05
Point: 99.0   0.00

1
2
3
4
5
6
7
8
9
10
11
12

ColorMapKnots: 5
Knot:  0.0   1.0   0.0  0.0
Knot: 25.0   0.0  1.0  0.0
Knot: 50.0   0.0  0.0  1.0
Knot: 75.0   0.0  1.0  1.0
Knot: 99.0   1.0  0.0  1.0
OpacityMapPoints: 4
Point:   0.0   0.01
Point:  50.0   0.05
Point:  75.0   0.00
Point:  99.0   0.05

Line1 specifies number of colors used in this map ie 3

Line2-4 specifies data value and corresponding color in RGB ( 0.0 to 1.0)

(ie for data value 0.0 red color is assigned for datavalue 50 green color is assigned, the values in between are mix of these two colors)

Only colors are being assigned in this file

Line1 specifies number of colors used in this map ie 3

Line2-4 same way specifies data and assigns colors in RGB

Line5 specifies the number of opacity points used in this map ie 3

Line6-9 specifies datavalue and corresponding opacity desired

Added more colors knots and colors

Added more opacity points and opacities

% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --tmapfile ../maps/map1.cmp cube.raw
           --tmapfile ../maps/map1.cmp will render  the data using the transfer function file map1

% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --tmapfile ../maps/map2.cmp cube.raw
           --tmapfile ../maps/map2.cmp will render  the data using the transfer function file map2


% ../svt_build/vista/vista --raw 100 100 100 --minmax 0 99  --tmapfile ../maps/map3.cmp cube.raw
           --tmapfile ../maps/map3.cmp will render  the data using the transfer function file map3

Map1

Map2

Map3

Map1 with grey background

Map2 with grey background

Map3 with grey background