

            Imagetool_menus                                 February 1988




            CONTENTS


            The Main Menus
                 The Image Menu
                 The Edit Menu
                 The Palette Menu
                 The Zoom Menu
                 The Graph Menu
                 The FTP Menu
                 The Help Menu
                 The Option Menu


            THE MAIN MENUS

            The following sections describe in detail the  functionality
            of each option in the main menus and how to use them.



            The IMAGE Menu

            The IMAGE menu implements disk I/O operations.  The  options
            on this menu allow you to load an image file from disk, save
            from screen to a raster file, animate  from  a  sequence  of
            images,  or  store up to 10 frames (with different palettes,
            optional) into a memory stack.

            LOAD      To load an image from a raw  raster  file  (for  a
                      description  of  file formats, see the File Format
                      help file), enter the file name at the  text  item
                      labelled  "Image", and the image dimensions at the
                      items labelled "Xdim" and "Ydim"  on  the  control
                      panel.   Then  select  LOAD on the IMAGE menu, and
                      the image will appear on the canvas.   If  you  do
                      not  enter  the correct image dimensions, you will
                      probably see some garbage on the screen.

                      NOTE: Wildcard characters can be  used  for  image
                      file names.

                      You may choose to load an image file in one of the
                      raster   file   formats  supported  by  Imagetool.
                      Imagetool  version  1.0  supports  Raw  format  (a
                      stream  of  binary, no header; one byte per pixel,
                      row by row, left to right) and the floating  point
                      format  (Sun  floating  point  format  -  4bytes).
                      Future versions of Imagetool will support the NCSA
                      raster file format.

                      To choose a  specific  format  for  file  loading,
                      select the IMAGE menu item LOAD, pull right to pup
                      up the format  submenu,  and  select  the  desired
                      format.

                      NOTE:  When  floating  point   format   is   used,
                      Imagetool  reads  in  the  original  data file (in
                      floating point format), converts it to a raw image
                      file (one byte per pixel, values ranging from 0 to
                      255)  utilizing  scaling  information   the   user
                      provides  in  a dialog box which appears, and then
                      displays  it  on   the   screen.    It   takes   a
                      considerable amount of CPU time to do the floating
                      point-to-integer conversion. It is  advisory  that
                      the   user   save  the  converted  image  under  a
                      different name for fast reference later on.

            SAVE      This option allows you to save a single  image,  a
                      composite  image, or a selected region of an image
                      to a disk file. To select a region of the  canvas,
                      simply  drag  out  a  box by depressing the middle
                      mouse button as you move the cursor.  By  choosing
                      SAVE,  the  selected  region (otherwise the entire
                      image recently loaded)  will  be  written  to  the
                      disk.  Once  you  select the SAVE option, a dialog
                      box will appear asking for the  file  name  to  be
                      created.  You  may enter a character string ending
                      with a return key (or select  the  OK  button)  to
                      proceed,   or   click  on  the  CANCEL  button  to
                      interrupt  the  operation.  Upon   completion,   a
                      message  will  appear  in  the tty window (the top
                      subwindow) telling  you  the  name  of  the  newly
                      created file with the exact dimensions appended.
                      Similar to the LOAD option, you may choose to save
                      the  image  in  a specific raster format.  Version
                      1.0 supports only the raw binary format.

            ANIMATE   To animate a sequence of images, you must  specify
                      a  character  string  that represents the sequence
                      containing wild card characters  (such  as  *,  ?,
                      etc.,  all  Unix  conventions  on wildcards apply)
                      along with the correct dimensions.  For  instance,
                      "denab*"  and "denab?[1357]*" are legal character
                      strings that resolve to multiple images.

                      As soon as the animation  begins,  four  temporary
                      buttons will appear on the control panel. They are
                      PAUSE, LAST, NEXT, +, and --.  PAUSE is  a  toggle
                      button  with  which  you  can  stop and resume the
                      animation.  After you pause the animation, you may
                      click  on  LAST or NEXT to single step through the
                      frames (backward and forward). + and -- adjust the
                      animation speed (increasing and decreasing).
                      To quit animation at any time, click on the CANCEL
                      button.

                      This option also provides you  with  zoomed  (2x2)
                      animation. Use it only on small size images.

            STACK     The STACK option allows the user to store up to 10
                      frames  (possibly  with different palettes) into a
                      memory stack so that you can quickly flip  through
                      them for examination or comparison.

                      As soon as  you  select  the  option  STACK,  four
                      temporary   choice  buttons  will  appear  on  the
                      control panel.

                      NOTE: The user can make a selection from a  choice
                      button  either  by  selecting  the  desired choice
                      directly, i.e. by selecting  from  the  associated
                      menu  with the right mouse button, or by selecting
                      the button label with the left mouse button, which
                      causes  the  current choice to advance to the next
                      choice (or backup to the previous  choice  if  the
                      shift key is pressed while selecting).

                      You may select on the  STORE  button  to  store  a
                      frame  into  the next available slot on the stack,
                      or choose a specific empty slot.  After  you  fill
                      the  slots with image frames, you may examine them
                      by clicking the choice button SHOW. Use the DELETE
                      button to clear an entry in the stack, or FLUSH to
                      clean up  the  whole  stack.  To  exit  the  STACK
                      operation, press the button Cancel.

            PRINT     Make color hard copy of the canvas or  a  selected
                      region.


            The EDIT Menu

            This menu enables you to edit an image on the  canvas.   You
            may  cut  (copy)  a  region  of  the  canvas and paste it to
            another part of the canvas,  or  clear  any  region  of  the
            canvas. Together with the SAVE option in the IMAGE menu, you
            are able to do sophisticated image composition.

            First, define a region to be edited (draw a box by  dragging
            with the middle mouse button down), select the option CUT or
            COPY from the EDIT menu, which will copy the selected region
            onto  an  in-core  clipboard.  To  paste  whatever is on the
            clipboard to canvas, select the option PASTE, hold down  the
            middle  mouse  button on the canvas, and drag to the desired
            position, and finally  release  the  button.  Until  you  do
            another  cut or copy, what is on the clipboard remains there
            (i.e. you may do multiple pastes).

            You may also clear any  part  of  the  canvas  you  want  by
            selecting  the  region then choose the option CLEAR from the
            EDIT menu.


            The PALETTE Menu

            This menu enables you to control  the  color  look-up  table
            (CLUT)  in  various  ways.   The options in the PALETTE menu
            include palette load,  restore,  display,  modify  (contour,
            fiddle, rotate and transpose), and save.

            NOTE:  Palette  files  are  binary  (8  bits   per   entry),
            containing 256 red entries, next 256 green entries, then 256
            blue entries. This makes all palette files exactly 768 bytes
            long.   By convention, the names of all palette files end in
            ".pal".  When entering a palette name on the control  panel,
            you may omit ".pal".  Imagetool only recognizes files ending
            in  ".pal"  as  palettes.  For   example,   if   you   enter
            /image/pals/denbd  as  the  palette  name while you may have
            other  image  files  as  denbd*,  Imagetool  will  look  for
            /image/pals/denbd.pal as the palette.

            LOAD      To load a palette, enter palette file name at  the
                      text  item  labelled Palette on the control panel,
                      and then select the LOAD option from  the  PALETTE
                      menu.

            RESTORE   RESTORE will reload the previous palette used.  In
                      fact,  Imagetool  only keeps track of two palettes
                      most recently loaded.

            SHOW      This option display a palette as  a  512x50  color
                      bar  on  the  canvas.  Unless the user indicates a
                      specific location where to  draw  the  color  bar,
                      Imagetool will display it under the image recently
                      loaded. You can pick a position  by  pressing  the
                      left mouse button.

            The  following  three  options  CONTOUR,  FIDDLE,  TRANSPOSE
            manipulate  the  CLUT. You can make a color contour palette,
            modify an existing palette with a linear transformation,  or
            take  an inverse of the original palette. The changes to the
            CLUT are seen immediately as you move the mouse.  The option
            SAVE  in  the  PALETTE  menu,  allows  you to store this new
            palette onto disk.

            CONTOUR   When selecting CONTOUR from the PALETTE menu,  you
                      are  in  the palette contouring mode. To exit this
                      mode, press the right  mouse  button.  To  make  a
                      contour  palette,  it  is  good  to have a palette
                      color bar or an image  displayed  on  the  canvas.
                      With  the  left  mouse button down, you may pick a
                      color and change it to  white.  Holding  down  the
                      left mouse button and move it across the color bar
                      or the image, you are able to see  the  contouring
                      effect.  While  pressing  the middle mouse button,
                      you can white out a range of colors  as  you  drag
                      the mouse.

            FIDDLE    FIDDLE  does  a  linear  transformation   on   the
                      original  palette  while  you are moving the mouse
                      across the canvas. Similar to CONTOUR, you are  in
                      a  fiddling  mode  when  you select FIDDLE option.
                      The right mouse button will get you  out  of  this
                      mode. Keep the left mouse button down while moving
                      the mouse. You can expand or squeeze  the  palette
                      by  moving  the  cursor  up or down vertically, or
                      shift the palette to the left or right  by  moving
                      the  cursor  horizontally, or just move the cursor
                      across the canvas to get a combination of all  the
                      effect.  You  also  can  rotate  a  palette (or an
                      intermediate one) by holding down the middle mouse
                      button;  release  the  button  when  you  want the
                      rotation to stop. As you see  a  new  palette  you
                      want, save it with SAVE option of this menu.

            TRANSPOSE This is to  obtain  the  inverse  of  an  original
                      palette.

            SAVE      After modifying a palette, you can save  it  (what
                      you  see  on  the canvas) as a new palette file on
                      disk. Select SAVE from  this  menu.  You  will  be
                      first asked whether you want to save a palette. If
                      yes, type in some name string for the new  palette
                      file.  Or  select  CANCEL  button  to skip. If the
                      given file name does not end in ".pal", it will be
                      appended  with  ".pal".   You  will be asked again
                      whether you want to save the current image  as  it
                      looks  on  the  canvas.  If  you answer yes, a new
                      image will be stored with transformed color values
                      such that if this image is loaded back later under
                      the original palette, the one before you  modified
                      it,  the  image  will  look the same as if it were
                      fiddled. Again, give a file name if  you  want  to
                      save the current image, or cancel the operation.

            CREATE    This  is  not  supported  in   the   version   1.0
                      Imagetool.


            The ZOOM Menu

            The  options  on   this   menu   provide   image   expansion
            capabilities.

            PIXEL     This  option  performs  a  2x2   pixel   expansion
                      (implemented  by pixel replication) on the current
                      image or a selected region. To zoom  a  particular
                      region,  you must first define a region (drawing a
                      box with the  middle  mouse  button)  then  select
                      PIXEL  from the ZOOM menu. You are also able to do
                      multiple ZOOMs by selecting PIXEL more than once.

            EXPAND    This also performs the pixel expansion as in PIXEL
                      except  that it takes two expansion factors (for x
                      and y direction) from  the  user.   The  user  may
                      enter  two integer expansion factors when prompted
                      with the factor dialog box.

            INTERP    This option zooms (2x2) an  image  or  a  selected
                      region  by  doing  a  linear  interpolation on the
                      pixels. You may also do multiple INTERPs.

            UNDO      This  option  will  undo  the  previous  expansion
                      (PIXEL,  EXPAND,  INTERP).  It can be applied more
                      than once until the current image size  equals  to
                      that of the original image before any expansion.

                      NOTE: When mixed expansion has been performed, for
                      example,  PIXEL  (2x2),  EXPAND (3x4), PIXEL (2x2)
                      were performed in such order, multiple UNDOs  will
                      not  bring the expanded image back to the original
                      dimension because  only  one  last  expansion  was
                      recorded.


            The GRAPH Menu

            Using the graphing functions of this menu, you may plot line
            graphs, two-dimensional contour graphs, or three-dimensional
            graphs from a color image.   When  you  select  any  of  the
            options  XY,  CONTOUR  and 3-D, a separate graph window will
            appear.  Use the buttons in the graph window to draw, clear,
            print  (from  a  laser  printer), and so on. Select the DONE
            button to close the graph window and exit the graph mode.

            XY        Selecting the option XY brings you to a line graph
                      mode.   You  will see a separate graph window with
                      buttons SCALE, DRAW, CLEAR, PRINT, DONE on it.  To
                      plot the data values (not the color index) along a
                      straight line across any part of  an  image  as  a
                      line  graph,  you  first  slice  on  the  image by
                      dragging the left mouse button,  then  select  the
                      DRAW  button  in  the  graph  window. In the graph
                      window, you also select CLEAR to  erase  the  plot
                      canvas,  PRINT to get a hard copy of what you have
                      drawn. PRINT sends a postscript file  to  a  laser
                      printer  whose  name  you must define in Imagetool
                      either using the menu OPTIONS or  entering  it  in
                      the  dialog box appeared when selecting PRINT.  At
                      the text item labelled  Title,  you  may  enter  a
                      subject  title  which  will  be  imposed  onto the
                      graph.

                      You may notice that a small scaling info box  pops
                      up  when  you  bring  up  the  XY graph window. It
                      allows you to enter some scaling information:  the
                      X  and  Y  coordinate  limits of your image (xmin,
                      xmax, ymin, ymax), the minimum and maximum  values
                      you  used  when converting the data file to raster
                      file (gmin, gmax);  specifying  either  linear  or
                      logarithmic  as  the  scaling  type.  Click  on OK
                      button to confirm the setting.  Otherwise,  cancel
                      the  box.  Imagetool  will  notify you the current
                      scale setting by printing the values  in  the  tty
                      window.  During  the graph session, you may change
                      the scale setting by selecting the SCALE button.

            CONTOUR   To plot a two-dimensional contour  graph  from  an
                      image  or  a  selected  region, you must enter the
                      contour  levels  at  the  item  labelled   Contour
                      levels.  The  contour  levels  are  specified as a
                      sequence of integers ranging from 0  to  255  (the
                      color table index) and separated by a space.

            3-D       Similar to the above contour  graphing.  Use  Yaw,
                      Pitch  and  Roll  to adjust the orientation of the
                      3-D object.


            The FTP Menu

            The FTP menu provides  the  capability  to  animate  from  a
            remote  application.   The  basic  idea  is  that  Imagetool
            automatically transfers the output raster files periodically
            from the remote site on which the application is running and
            generating raster files, and then loads the raster  file  to
            the  Imagetool  canvas.  This is implemented as an animation
            loop until the user terminates the loop.

            Before you start the animation loop, you  must  establish  a
            FTP  connection  by  selecting CONNECT from the FTP menu and
            typing in the login name and password as usual.

            To begin the automatic file transfer, select  the  GET  LOOP
            menu  item.   You  will  first  be  prompted to fill in some
            option values. You  may  specify  the  file  name  increment
            (integer),  the  time  interval  between  two  transfers (in
            seconds), and indicate  whether  you  want  the  transferred
            image expanded before loaded to the canvas.

            NOTE: The time it takes to transfer a raster file  from  the
            remote  site  depends on the network traffic at that moment.
            If the interval is set smaller than  the  time  required  to
            complete  a  transfer, you may receive fewer bytes than that
            the image should have. If this is the case,  Imagetool  will
            try  to get the same image again before going on to the next
            one.  If this continues for two or three times,  you  should
            pause  the  loop  by selecting STOP from this menu, increase
            the time interval, and resume the loop by selecting GET LOOP
            again.


            The HELP Menu

            This menu allows you to read help files in a  separate  text
            window  the  while  you  are using Imagetool.  The available
            help   files   at   this   point    are    imagetool_basics,
            imagetool_menus,  imagetool_button,  imagetool_examples, and
            imagetool_errors.

            There is also a Bug Report option on this menu. When  it  is
            selected,  a  text  window  will pop up where you  may enter
            your bug report.  After you complete your bug report,  click
            on  the  DELIVER  button  to  send the text to the Imagetool
            author, and the DONE button to close the window.


            The OPTION Menu

            The  user  can   use   this   menu   to   set   up   certain
            options/defaults for use with Imagetool.

            Default File   Users may  set  up  some  default  paths  for
                           Imagetool  so  that they do not have to reset
                           these  parameters  each   time   they   start
                           Imagetool.   The first time you run Imagetool
                           (assuming that you do not have a  file  named
                           ".imagetool_defaults"     in     your    home
                           directory), a dialog box will  appear  asking
                           whether  you  need  to  set  up the defaults.
                           Answer yes. Type in the complete  path  names
                           for  the directories that contains your image
                           files,  palette  files,  and  Imagetool  help
                           files.  You  also  have an option to save all
                           the defaults to a file for  later  reference.
                           During  an  Imagetool session, you can change
                           the defaults by selecting the OPTIONS menu.

            Default Printer
                           Specify the name of the laser printer for the
                           current Imagetool session.

            Reversed Image In general, we assume that a raster image  is
                           (0, 0) oriented at the upper left corner, row
                           by row, from left to right. With the Reversed
                           Image  flag  set,  an  image will be taken as
                           being oriented at the lower left corner.

            Dark Background
                           This  sets  Imagetool  window   to   a   dark
                           background.

