

			VISU User's Guide

	
		Pierre-Louis Bossart

		Lawrence Livermore National Laboratory 
		Non-Destructive Evaluation Section 
		L-416, 7000 East Avenue
		Livermore, CA 94550, USA 

		Phone: 510-423-9350 
		Fax: 510-422-7819 
		E-mail: bossart1@llnl.gov

1. What is visu ?

visu is a modification of the tk. All the functionalities of wish are
still present in visu. However, visu provides a new widget called the
pict widget. It is an image widget, geared to gray-scale images, in
contrary with the standard photo widget which can dither color images,
but does not allow for much interaction, and can be pretty slow.

2. Installing visu

This section describes the steps to install and use the visu package.
Please see the file "license.terms" for information on usage and
redistribution of this package, and for a DISCLAIMER OF ALL
WARRANTIES.  This work was partially funded by the U.S. Department of
Energy under Contract No. W-7405-ENG-48. Release of this unclassified
code was approved by LLNL ADPR&I Office under Code Release No. 960012.


First, you will need to install Tcl and Tk, as the pict widget
provided with visu relies upon the tk libraries. As of January 10,
1996, visu relies on tcl7.4 and tk4.0. It may or may not work with
future versions.


A. set the VISU_ENV environment variable to the directory where you
installed visu and add it to your path:

	setenv VISU_ENV /rb/bossart/visu 
	set path = ( $ path $VISU_ENV)

B. Uncompress and untar the distribution file. 
	zcat visu-1.0.tar.gz | tar -xvf -


		$VISU_ENV
	     ______|_____
            |      |    |
         library  man  src
                        |
                      shared
C. Run ./configure

   Go into the "visu" directory 

	cd $VISU_ENV

   and run the auto-configuration script "./configure"

	./configure 

   * If you want to use gcc, it's "./configure -with-gcc"

	./configure -with-gcc

   * By default, visu, libVISU.a, the library files, and
     manual pages will be installed in "/usr/local/pkg/tcl/visu".  You can 
     change this by giving the -prefix option to ./configure.

	./configure -prefix=/depot/stuff/visu
    
  You may be queried for the location of the Tcl and Tk libraries, if
  "configure" can't find them in the standard locations.

  The configure script creates an include file "src/visuConfig.h".
  It will also generate new Makefiles from their respective templates 
  (Makefile.in).

	Makefile.in 	        ==> Makefile
	src/Makefile.in	        ==> src/Makefile
	src/shared/Makefile.in	==> src/shared/Makefile
	man/Makefile.in		==> man/Makefile
	library/Makefile.in	==> library/Makefile

  If "configure" can't find something (e.g. it can't find the X libraries),
  edit the file "config.status" and run it.

	./config.status

  Otherwise, you'll have to edit the Makefiles files by hand.


D. Compile visu.

	make 

E. test visu,

F. Installing visu

   The following directories will be created when visu is installed.  
   By default, the top directory is /usr/local/pkg/tcl/visu.  

       _____________|__________
       |      |        |      |  
      bin    lib     library man
     
   You can change the top directory by supplying the -prefix option to
   ./configure.

G. Creating a shared library.

   This is currently available on the following systems (I did not test
	this however, but the configuration files come from the BLT 
	application and should be reliable...)

	SunOS 4.x
	SunOS 5.x
	HP-UX 9.01

   From the "$VISU_ENV" directory:

	make sharedlib

   This will create a shared library in the directory src/shared.


H. If you did not recompile against the tcl libraries on your system, and
only downloaded the executables, you will need to set the TK_LIBRARY
environment variable, which points to tk configuration files. On my
system, you would do

	setenv TK_LIBRARY /usr/local/pkg/tcl/lib/tk4.0

I. Send bugs reports, correspondence, etc. to:

	bossart@redhook.llnl.gov
	


3. Using visu

A. File format and data types:

The pict widget can be used to visualize images of the following types:
	unsigned char, short, int or float;

For unsigned char images, there will be no normalization: the images
are mapped to the interval [0-255]. For other images, the images need
to be normalized.  You can set the user max and user min values in
order to choose a proper dynamic range. If the values in the image
exceeds the user-specified ones, the dynamic range will be computed
from the image values, regardless of what the user typed in. The min
and max value show the actual dynamic range of the images.

visu supports the following file formats, with some restrictions:
VIEW (local LLNL format)
KHOROS1 (the map and location information are not read)
GIF (reads color image as gray-scale)
PPM/PGM (reads color image as gray-scale)

B. Display
 
visu assumes that only one image is "active" at a given time. For
example, if you read a new slice from the disk, the "active" window
will be updated.  A window becomes active by a mouse-click over the
image. The active image can be accessed from the command line by using
the curr_img global variable.

C. Colormaps and overlays:

visu allows one to perform colormap manipulations and interactive
threshold.  You can use one of the predefined colormaps to visualize
your gray-scale images in colors. The color tool lets you stretch or
compress the colormap in a non-linear way, e.g. when the transitions
between regions are not very important.  Note that the data is not
changed when you change the colormap; only the colors displayed will
be affected.

Each image displayed may use either one of these colormap type:
	0 (Shared): This is primarily for compatibility with the VIEW
	software written at LLNL. I recommend not to use this
	functionnality. If you do, be sure you exit nicely...
	
	1 (Default Colormap): this is the default standard colormap.
	
	2 (Shareable Private): A shareable colormap, different however from
	the default one.
	
	3 (Private Colormap): A non-shareable private colormap.

The colormap type can be set either with the mouse in the New menu, or
by setting the global variable Private_Colormap before you display the
image.  Depending on which type was used when the image was first
displayed, the colors may or may not be be changed by a colormap
stretch / threshold. Make sure the window is active before you do any
color manipulation.

C. Overlays:

The color allocation can be used to display "semi-transparent"
overlays.  This is a feature that was found very useful in our
interactive segmentation work. There is a restriction however: You
will need to display the window with a Private_Colormap, so that you
can use more color cells that with the default colormap.

Before you overlay anything over the active image, you will need to
enable the overlays. Do not worry about the color flash, it is
perfectly normal and cannot be avoided. Then you have a choice of

	drawing a polygon :
		Button-1 pressed adds a vertex, 
		Button-2 removes the last vertex, 
		Button-3 closes and fills the polygon.
	painting pixels:
		B1-Motion changes pixel colors (the brush size and 
			type can be changed interactively)
		Button 3 disables painting.
	drawing free-hand:
		Button-1 adds a vertex and draws a straight line
			from the previous vertex.
		B1-Motion draws a free-form curve.
		Button-2 removes the last vertices.	
		Button-3 closes and fills the free-form curve.	 
	
In addition, you can overlay another image on top on the active image.
The image to be overlayed is called a mask. The scripts assume that
the mask image is named mask_img. Here is a summary of the
mask-related operations.

	Create mask: creates a pict image, set its name. The number of 
		slices and current-slice are set to the same values as 
		the ones for the active image.
	Get mask: Copies the active image overlays into mask_img.
	Disp mask: Display mask_img.
	Set mask: sets/changes which image is currently considered 
		as the mask.
	Put mask: copies the mask and overlays it over the active image.
	Save mask: saves the mask on disk.
	
Visu lets you set the Graphic Context values with the mouse. For
example, if you overlay two polygons with the GC set to xor, their
intersection will appear blank. Setting the GC to clear lets you
delete overlay pixels.


4. Summary of commands for the pict widget

image create pict <options>
	
	Creates an image
	options:
	-data <string>
		specify contents of image in a supported format.
	-file <fileName>
		Gives name of file whose contents define the image
		in supported format.
	-format <formatName>
		Specify format for data specified with the -data or
		-file options. In the visu extension, only the GIF/
		PPM/PGM/VIFF/VIEW formats are supported.
	-height <number>
		Specifies pixel height of the image.
	-width <number>
		Specifies pixel width of the image.
	
<imageName> blank
	Blanks the image so that it has no data and is completely
	transparent.

<imageName> copy <sourceImage> <options>
	Copy region from <sourceImage> to <imageName> using given 
	options:

	-from x1 y1 x2 y2
		Specifies rectangular region of sourceImage to be copied.
	-to x1 y1 x2 y2	
		Specifies rectangular region of sourceImage to be affected.
	-shrink
		Will clip target to copied region is in bottom-right corner.
	-zoom x y
		Magnifies source region by x y in respective directions.
	-subsample x y
		Subsamples source region by x y in respective directions.

	
<imageName> get x y
	Returns actual pixel value (not normalized for display) at pixel x y.
	
<imageName> put <data> -to x1 y1 x2 y2
	Sets pixels values as 2D array data for region x1 y1 x2 y2.
	
<imageName> read <fileName> <options>
	Reads image data from file <fileName> into image using given options.
	
	-format <formatName>
		Specifies image format of file.
	-from x1 y1 x2 y2
		Specifies a rectangular of the image file to copy from.
	-shrink
		Will clip image so copied region is in bottom-right corner.
	-to x y
		Specifies coords of the top left corner in image to copy into.
	
<imageName> rdbinary -file  <fileName> <options>
	Reads binary image data from file <fileName> into image using given options.
	
	-from x1 y1 x2 y2
		Specifies a rectangular of the image file to copy from.
	-width w  Specify width/height/nb_slices of the data.
	-height h
	-nb_slices nb
	-skip s  Number of bytes to be skipped from file beginning
	-type [byte|short|int|real]

<imageName> redither
	Redithers the image.
	
<imageName> write <fileName> <options>
	Writes image data into file <fileName> (only VIEW and PGM supported)

	-format <formatName>
		Specifies image format for the output file.

	-from x1 y1 x2 y2
		Specifies a rectangular of the image to copy from.

<imageName> range min max
	
	Sets a minimum and maximum value for images. Side effects only
	for non-byte images. Useful to compare short, int or float images
	that don't have the same dynamic range. It is the user's 
	responsability to ensure the range specified is larger than the 
	actual range.

<imageName> getmin
<imageName> getmax
	Return the minimum and maximum values of the image.

<imageName> overlay enable
<imageName> overlay disable
<imageName> overlay setgc [or|xor|and|set|clear|set]
<imageName> overlay line x0 y0 x1 y1 [x2 y2]
<imageName> overlay fill x0 y0 .... xn yn
<imageName> overlay rectangle x y width height
<imageName> overlay ellipse x y width height
<imagename> overlay putmask <maskName>
<maskName>  overlay getmask <imageName>

5. Summary of high-level commands

when using visu interactively, you can use the same commands as with the
photo widget. However, i recommend you use the following
commands :

rdfile <filename> <variable> <options> 
rdbinary <filename> <variable> <options>
wrfile $f [name] <options>	

rdslice <variable> <slice_number>
	variable needs to be created first 
disp <variable> 
	displays the image
copy <source> <dest> <options> 
	copies the source to the dest. Creates the dest if necessary
normalize <loval> <hival>
	set the current image dynamic range.
zoom <variable> <zx> <zy> <subx> <suby>
	scales an image (the window is scaled as well)
colorbar
	creates a horizontal colorbar
movie <variable> <first> <nb_slices>
	go through the slices along the z axis from <first> to 
	<first+nb_slices>
delete <imageName>
	destroys the image, the window in which it is displayed and
	unsets the variable.
control_panel
	creates the main control window
make_palette
	Creates the palette control window
make_overlay
	creates the overlay control window

 
 
  








