qview Documentation

qview - Display cube

PURPOSE
-------
This program will display a standard ISIS cube on specific types of X
Window based workstations/terminals (devices). It can display both black
and white using a single band or a color composite using three bands.
In addition, it contains a series of tools such as pixel listing and
doctoring.

OPENING A B/W DISPLAY
---------------------
To open a display goto the "FILE" pulldown menu and select the open
display item.  This generates a "FILE SELECTION" box which allows
the user to choose a cube to load in the display. Once the cube is
selected the "LOAD OPTION" box appears which allows the user to
select MIN/MAXs and BANDS to use for loading the cube.

First select which band to display in the "RED/MONO" text field. Set the
"GREEN" and "BLUE" text fields to zero. Next select the stretch to
apply. Either NO STRETCH, AUTOMATIC, or MANUAL. NO STRETCH can only be
used for 8-bit cubes. The AUTOMATIC stretch will cause "qview" to gather
statistics from the image and use those statistics to determine minimum
and maximum pixel values. The MANUAL stretch allows the user to specify
the range of pixel values. If a MANUAL stretch is selected the user must
supply the minimum and maximum values for the MANUAL stretch in the
appropriate text fields.

When done setting the band and stretch press the OK button and a
512x512 display will be created and loaded with the cube compressed
to fit in the display.


MANIPULATING THE CUBE
---------------------
Once a cube is loaded in the display you can manipulate the
cube using the toolbar functions. Currently there are five toolbar
functions:

  Zoom function (Magnifying glass icon)
  Roam function (Four arrow icon)
  Stretch function (Warped square icon)
  List function (Text icon)
  Doctor function (MD icon)
  Measure function (Measuring tape icon)

Each tool operates using the three mouse buttons (MB1,MB2,MB3) in
the following fashion:

  ZOOM
  MB1 = Zoom in 2x
  MB2 = Zoom so 1 screen pixel represent 1 cube pixel
  MB3 = Zoom out 2x
  MB1+ = MB1 down and moving the cursor will cause a box
         to be drawn. When MB1 is released the data in the
         box will be zoomed.

  ROAM
  MB1 = Move image up/down/left/right based on pointer position on cube
  MB3 = Move pixel under pointer to center of display

  STRETCH
  MB1 = Apply automatic linear stretch using statistics of entire
        display
  MB3 = Reset stretch
  MB1+ = MB1 down and moving cursor will cause a box to be drawn. When
         MB1 is release the data in the box will be used to collect
         statistics for the stretch (local stretch)

  LIST
  MB1 = Obtain statistics and listing for a window about the pointer.

  DOCTOR
  MB1 = Apply pixel, horizontal line, start-end line, or rectangular
        edit to cube. Pixel values are changed with a user specified DN.
  MB2 = The DN value at the cursor will become the DN used in subsequent
        doctor operations.
  MB3 = Undo last edit
  MB1+ = MB1 down and moving the cursor will cause a line to be drawn.
         This is only applicable when the edit mode is start-end line.

  MEASURE
  MB1 = Holding the first mouse button down, draw a line for a linear
        measurement.  Also for the "Center" option click the first
        mouse button to get a clat,clon of feature you are measuring.

  The measurement tool has the option of saving measurement information
  in a file.  This is done by hitting the Save button in the measure
  dialog box.  The default file name is measure.dat.  The file name
  can be changed under the Options menu.  The way the lat/lon values
  are displayed can also be changes under the Options menu.  In ISIS,
  the lat/lon values can be positive or negative depending on whether
  the images is Positive longitude east or west.  The cartographic
  lat/lon values are positive with a N (north), S(south), E(east) or
  W(west) following.

  For example:    In ISIS       72.39:-179.35
                  Cartographic  72.39N:179.35W  (for a positive longitude
                                                  east)



Note that many of the tools have options which can be changed under the
options menu. For example, the zoom factor can be changed to 5 so that
the zoom tool will zoom  in/out by 5x.

CHANGING THE VIEW
-----------------
A different band can be viewed by selecting the "VIEW" option from the
"FILE" pulldown menu. This will bring up the "VIEW OPTIONS" box which
is similar to the "LOAD OPTIONS" box. Just change the band number
in the "RED/MONO" text field and press the "OK" button to view the
band.

TRACKING SAMPLE/LINE AND PIXEL VALUES
--------------------------------------
At the bottom of the display there are several fields reporting the
SAMPLE/ LINE and PIXEL value (by default the reporting is OFF). To turn
on position tracking press the toolbar function which looks like a
animal track. As the pointer moves through the display window the
sample/line and pixel values are reported. Also, if the cube has spice
and/or projection labels the latitude/longitude will be reported.
At this time, the azimuth and elevation for Mars Pathfinder IMP images
is not reported.

LOADING THREE BAND COLOR COMPOSITES
-----------------------------------
First, you must be on a 24-bit X Device. When the "LOAD OPTION" box
appears select the bands using the "RED, GREEN, and BLUE" text fields.
Then select the stretch type.  If a MANUAL stretch is selected enter
three values in the MINIMUM text field and three in the MAXIMUM text
field.  For example,

  10 30 90
  200 150 190

would imply minimums of 10 30 90 for red, green, and blue, respectively.
Similarly, 200 150 and 190 would be the maximums for red, green, and
blue.


"qview" Display Menus
---------------------

File Menu
  View - Allows a new band to be viewed or allows the stretch to be
         changed.

  Close display - Closes current "qview" display window.

  Close all displays - Closes all "qview" display windows

Options Menu
  Zoom Options - Allows the zoom factor to be changed.

  Roam Options - Allows the percentage of the image moved during the
                 roam operation to be changed.

  Stretch Options - Allows the low and high stretch percentages
                    to be changed.

  List Options - Option to list core data or backplane data,
                 change the number of samples and lines listed and
                 allows the file name where the listing is saved to
                 be changed.

  Doctor Options - Option to define doctor function defaults such
                   as the type of editing (point,line,etc.) and
                   what value to replace pixels with.

  Display size - Lists the number of lines and samples in the
                 display window.

  Note there is a file, $ISISDATA/qview-defaults, which
  can be modified to allow for user defined values for all of
  the above options.  The file is read at startup time of "qview"
  and overrides any internal defaults.  Please see the
  documentation in the file for additional information.

Show Menu
  Image Information - Lists statistics about the image displayed
                      such as image size, bit type, etc.

  Histogram - List image data statistics and a tabular histogram.

  Photo Statistics - If the image displayed has spice information,
                     photometry statistics will be listed as the
                     cursor is moved around the image.

Applications Menu
  Browse - Brings up a dialog box which allows images to be chosen
           and displayed quickly in the display window.

  Limbfit - Measures control points along the limb of an image and
            finds a best fit circle through the points to define
            the plane size and positon.  New camera angles are
            calculated and written to the labels.  Control points
            may be saved to a data file.  To mark a control point
            move cursor to location you want to choose and hold
            the Control key while clicking the first mouse button.
            This will allow you to use the mouse for the other
            toolbar functions such as zoom and stretch.  The planet
            radius calculated is written to the file "radii.dat".

  Reseau - This tool allows you to fine tune the location of the
           reseaus located in the labels in the keywords,
           RESEAU_SAMPLE and RESEAU_LINE.  When this application
	   is opened, a red box will be drawn around each reseau
	   on the displayed image using the locations in the
	   labels.  A dialog box will also be displayed showing
	   reseau information.  To change a reseau location, place
	   the cursor where the reseau is actually located, and
	   press Cntrl-1st mouse button.  This new location will
	   be written to the dialog box.  To save this new location
	   (not written to labels yet), Click on the "Save" button
	   in the dialog box or press Cntrl-middle mouse button.
	   Proceed to the next reseau.  The new reseau locations
	   will not be written to the image labels until you Exit
	   the reseau dialog box.

  Record - This tool allows you to assign a unique ID to points in
           an image file and record the ID, Sample, and Line
	   information to a text file. This tool was originally
	   developed for use with the Lunar Orbiter project so that
	   fiducial points could be easily recorded. When you choose
	   the Record option from the Applications menu, a file
	   selection dialog will appear. You can either choose an
	   existing file or create a new one. After choosing the file,
	   a dialog box will appear that lists all (if any) points
	   from the input file. A red X will be placed on the image
	   file at the location of each point that has been recorded.
	   To add, delete, or replace a recorded point, place the
	   cursor on the point of interest within the image display
	   window. Then press the "R" key (upper or lower case doesn't
	   matter). A dialog window will appear asking for an ID.
	   Enter the ID and press one of the buttons on the bottom of
	   the window that applies to the action you want to take.
	   When you are finished recording points, press the Exit
	   button in the window that shows recorded points.


Main "qview" dialog box toolbar
-------------------------------
Link - Allows displays to be linked together resulting in zoom and
       roam operations performed on all displays linked
       together.  Displays that are to be "blinked" need to be
       "linked" first.

Blink - If displays are "linked" together, this tool will alternate
        the display of the "linked" images in a single display window.

Register - This option is a very simple attempt to bring PICS TVREG
           capabilities into "qview".  Two images must be loaded and
	   linked in displays 1 & 2.  You should load the cubes with
           an automatic or manual stretch. Check off the register
           option and give a file name for saving control.  Using
           the zoom/roam tools along with the blink option you can
           line up features in both displays.  Once you have a
           feature registered, put the pointer on it in display 1
           and press the "s" key.  A window will pop up to allow
           you to name the control point.  If it doesn't then either
	   the "s" key wasn't pressed in display 1 or display 1 was
           not active.  Continue picking as many control as desired
           and when completed the control file can be used as input
           to random or warp2.


TAE Options
-----------
Displays may also be opened from the TAE command line or
by tutoring "qview" in TAE and using the parameter FROM.  Upto
6 images may be opened at one time.  This option will only display
the first band of multi-band images.  You can also specify a min/max
on the TAE command line by using the MIN and MAX parameters.  If the
MIN and MAX parameters are not used, an automatic stretch will be
performed on the image.


Programmers: Jeff Anderson, Tracie Sucharski, U.S.G.S., Flagstaff

Input cube file name
  (default extension is .cub)

--

Manual stretch minimum

--

Manual stretch maximum

--

ADDITIONAL NOTES:

Parm	Description
FROM	Input cube file name. If the file extension is omitted, then ".cub" will be assumed.
MIN	Minimum values used in the manual stretch. This corresponds to the values entered in the from parameter. For example, from=(test1.cub,test2.cub) min=(0,20) max=(0,150) The minimum/maximum values for test1.cub would be set to 0,0 which tells "qview" to calculate the stretch. The minimum/maximum values for test2.cub would be set to 20,150 respectively.