root/gliderproc/trunk/MATLAB/opnml/VIZICQ4_1.2/vizicq4.readme

VIZICQ4_1.2 Visualization

Introduction
   This webpage describes the operation of VIZICQ4, Version 1.2.
   VIZICQ4 is a GUI-based MATLAB tool that accompanies the
   OPNML/MATLAB toolbox for the visualization of .icq4 files as
   output from the Quoddy4 series of FEM shallow water models.
   Currently, VIZICQ4 supports the horizontal slicing and vertical 
   slicing (transects) of .icq4 files.  Future versions will support 
   2-D plotting, .pth file analysis, and surface rendering (MATLAB5.3).  
   The terms "transect" and "vertical slice" are synonomous.

Purpose
   The purpose of VIZICQ4 is to provide an easy method for examining the
   field contents of Quoddy4 .icq4 files.  It is meant as a basic
   analysis tool and not as a final plotting package for
   publication-quality figures.  The core of VIZICQ4 is the 
   OPNML and FCAST toolbox routines.

Requirements:
   MATLAB  version 5.2.0+
   OPNML toolbox (retrieved any time after 1 November, 1998) 
   FCAST toolbox (version 1.2)
   
MEX file compilation:  One of the computational routines of VIZICQ4_1.2 
   is external to MATLAB,  It is called map_scalar_mex5.c, and must
   be compiled before VIZICQ4_1.2 will run.  Once the VIZICQ4 tarfile
   is untarred (tar xvf VIZIVQ4_1.2.tar), start MATLAB and cd (within
   MATLAB) to the VIZICQ4_1.2 directory.  Than, at the MATLAB prompt (>>),
   type:
      >> mex map_scalar_mex5.c
   This compiles the architecture-dependent executable, which will
   be called map_scalar_mex5.mex<arch>.  This file MUST reside in the 
   VIZICQ4_1.2 directory; do not move it out.
   
Operation:
 * GUI-Layout - VIZICQ4 consists of a main, large figure and several
   smaller figures, many buttons and menus.  Most of them are self-
   explanatory.  The main window contains two axes, only one of 
   which is visible at a time.  The first, titled "Grid Axes", 
   is the axes that contains the FEM element plot used for 
   specifying the transect end-points.  The second axes becomes
   visible after a transect is computed, and is a 3-D, rotatable
   rendering of the FEM mesh and the contents of the slices.
   The visible axes can always be toggled with the "Toggle Axes" 
   button in the top right of the main figure.

   The top of the main window contains some menus
   (File, Options, Clear, colormap).  "Options" contains axis 
   adjustments, etc.  "Clear" allows for the deletion of objects
   drawn on the "Slice Axes", like all vectors, all slices, etc...

   The bottom of the figure contains an Info: line, and Error: line
   and an EXIT button.  VIZICQ4 tries to be as informative as possible
   when an error occurs, and displays messages to recoverable problems
   (for example, "Domain Name not set" if the grid name entered could not
   be located) in these lines.

 * Loading grid and .icq4 files - The computation of slices and 
   volumes requires a FEM mesh in standard file formats.  Enter 
   a FEM domain name in the top left of the figure, with either
   a relative or absolute path (or none at all if MATLAB was started
   in a directory containing a mesh.  More likely, MATLAB was started
   in another directory, like a data directory contains several .icq4 
   files.)  Directory navigation isn't possible yet.
 
   The name of a directory containing an .icq4 file(s) can be entered
   at "Forecast Dir:".  Press return.  If there are .icq4 files
   available, a browsable menu will pop up to the right.  Double-click
   on the .icq4 filename to load.  If VIZICQ4 was started in the
   directory containing .icq4 files, just enter the name of the .icq4
   file, including the .icq4 file extension, in the "Icq4 Name:" space
   on the top right.

 * Selecting .icq4 fields - Once an .icq4 file is loaded, select a
   field to slice from the list of pushbuttons along the right side.
   Selecting a 2-D field (HMID,UMID,VMID,HOLD,UOLD,VOLD) will result
   in a warning when slice computation occurs.  These will be useable
   in later versions.  Also, ZMID and ZOLD cannot be visualized,
   although they are used in computations.  

 * Contouring the bathymetry - Enter the values of the bathymetry
   to contour in the "Z-Contours:" space.  The default is to 
   compute contours over the range of the bathymetry, at 5 
   values equally spaced between the min and max depths.
   "linspace(zmin,zmax,7)", the default, gives the following
   for the bank150 mesh;  
      -150. -128.3 -106.7  -85.  -63.3  -41.7  -20.
   Note that the first and last values are not used.  
   Any string can be entered that evaluates in MATLAB to a 
   vector.  For example, to set contour values of -120 -90
   -60 -30, enter [-120 -90 -60 -30] or [-120:30:-30].  
   Contours can be labled (press the LabC button) or deleted
   (press the DelC button).

 * Slices and Volumes - The "Slice" and "Volume" buttons in the 
   top right of the main figure provide slicing and volume
   rendering facilities (see below).  Each has the following
   in common.  At the bottom of each popup, the buttons are
   the same and provide a way to change the surface shading, 
   delete objects, turn on 3D rotation, and add a colorbar.  

 * Computing Slices - The "Slice"  button in the upper right pops a 
   "Slice parameter figure" that allows the entering of vertical and 
   horizontal parameters.   In both cases, the slice is computed
   by pressing the "Make Slice" button once the appropriate parametrs
   are specified.

   Horizontal - At this time, only the depth level can be specified.  
   Make sure that a "NEGATIVE" depth is entered; recall that the
   vertical mesh is computed as POSITIVE upward, with the flat free
   surface at z==0.  The "vectors" button can be pushed to overlay 
   the velocity at the specified level.  The vectors plotted include
   the vertical component, exagerated by the horizontal/vertical
   aspect ratio.  At this time, scaling of the vectors is not
   available.  The maximum vector length is displayed in the Info
   line.

   Vertical - Transects are specified in 2 ways. 1) Enter the
   end-points explicitly in the (X1,Y1,X2,Y2) fields.  2) 
   click on the "X-Slice", "Y-Slice", or "Arbitrary Slice" buttons.
   In this case, VIZICQ4 prompts for the user to use the mouse 
   to click on the location of one end-point (in the case of 
   "X-Slice"or "Y-Slice") or both end-points in the case of
   "Arbitrary Slice".

 * Computing Volumes - The Volumes facility in VIZICQ4 is based
   on interpolating the FEM 3D grid onto a finite-difference,
   rectangularly spaced grid.  This is not yet fully functional;
   we are awaiting the wide-spread availability of MATLAB5.3, which 
   supports volume visualization facilities.

   Current Status:
   The "Volume" button in the upper right of the figure pops up a 
   figure that allows the specification for drawing surfaces of the 
   .icq4 fields.   Specify the (x,y,z) discretization levels on the 
   left.  Press the "COMP BASIS" button to compute the 3D
   interpolation functions.  Then, press the "Map Scalar" button
   to interpolate the selected scalar .icq4 field to the FD grid.
   The "Integer Slice Locations" correspond to the integer locations
   in the FD grid to make a slice.  For example, the default 
   x-dicrestization level is 50; the default integer slice
   location in the x-coordinate is 25.  This means that the "25th"
   in the y-z plane (at FD grid x0location 25) will be sliced. 
   If the "Ix:" locations are changed to 1:5:50, then 
   the y-z slices will be made at the first, 6th, ... x-grid
   locations.  The "GO!!" buttons apply only to the coordinate
   plane to the left of the button.  The "GO ALL!!" button
   computes and displays all 3 coordinate slices. 

   The "Select Region" (right) side of the Volume Popup allows a 
   smaller region to be discretized or refined.   The default region
   is the horizontal extent of the FEM domain.  The Rotation
   facility (Rot CCW/CW buttons) is flawed and currently
   unavailable.

   If the Discretization level is changed after the basis is computed,
   the "COMP BASIS" button MUST BE PUSHED AGAIN.  VIZICQ4 does
   not properly detect the discretizaion change to alert the user
   that the basis needs to be recomputed.  This is a deficiency that 
   will be corrected in future versions. 

 * Printing - Use the File->Printing... menu option to prepare the 
   "Slice Axes" for printing, either to file or printer.  Make sure
   the "Slice" axes is the current axes by clicking on it, or by
   toggling the axes if is it not visible.

 * Error Messages - Most non-terminal errors are reported to the Error 
   Line:.  Messages to the MATLAB command window (where the >> prompt
   exists) like "Command hole in switch in vizicq4_guts" are normal.
   Error messages reported to the command window that look similar to:
   "Error in ==> /home/fcast/OPNML_MATLAB/VIZICQ4_1.2/vizicq4_guts.m"
   signify that (at the very least) VIZICQ4 has become lost,
   terminally.  It is best to EXIT and restart.

 * NOTES: 
      +) The colorbar drawn by pushing the colorbar button in the 
         Volume and Slice windows is NOT automatically redrawn
         when a new slice is added to the Slice Axes.  The user
         MUST push the button to refresh the colorbar.
      +) VIZICQ4 does not knoiw if the discretization level has 
         changed once the 3D basis is computed.  The user MUST
         push the COMP BASIS button if the discretization level
         OR region changes.
      +) The HELP buttons don't work.  This text will become the 
         help text in the next version.

 * Deficiencies - Plenty.  For starters,...
      +) Vector scaling not yet available.
      +) 2-D fields not supported.

 * BUGS - None.