Encyclopedia of Graphics File Formats Companion/GFF_CD.ISO/software/unix/saoimage/sao1_07.tar/vms/saoimage.hlp

Text File | 1991-07-03 | 23KB | 482 lines

1 SAOimage
  SAOimage is a utility for displaying astronomical images which
  runs under the X11 window environment.  Image files can be read
  directly, or image data may be passed through a named pipe (Unix)
  or a mailbox (VMS) from IRAF display tasks.  SAOimage provides a
  large selection of options for zooming, panning, scaling, color-
  ing, pixel readback, display blinking, and region specification.
  User interactions are generally performed with the mouse.

  The SAOimage desktop includes, a main image display window, a
  button menu panel, a display magnifier, a pan and zoom reference
  image, and a color bar.  A color table graph window can be
  brought up by clicking on the color bar.
2 SYNOPSIS
  saoimage [ -display nodename:0.0 ] [ -geometry | -gd geometry ]
       [ -pros | +/-imtool | -fits | -dfits | -oif ]
       [ -u1 | -u2 | -i2 | -i4 | -r4 | -r8 [ width height ] ]
       [ -byteswap ] [ -skip bytes ]
       [ -upperleft | -lowerleft ] [ -one | -zero ] [ -rotate code ]
       [ -linear | -wrap [ wraps ] | -log [ exponent ] |
         -sqrt [ power ] | -histeq ]
       [ -min val ] [ -max val ] [ -rmin val ] [ -rmax val ]
       [ -scalebias scale bias ]
       [ -palette val ] [ -red | -green | -blue ]
       [ -vertgraph | -horizgraph ]
       [ +/-coord ] [ +/-magnifier ] [ -mag val ]
       [ -panboxav | -panboxsum | -panboxsample | -panboxmax ]
       [ -idev pipename ] [ -odev pipename ] [ -fbconfig filename ]
       [ +/-verbose ] [ -quiet ]
       [ -lprbuttons ] [ -mtf ] [ -bordercolor color ]
       [ filename | -name filename ]
2 OPTIONS
  -blue Set the color of all graphics to be blue.  Some inexpensive
        systems use a monochrome monitor connected to one of the
        three color outputs on the computer.  That color must be
        specified to make the graphics visible.

  -bordercolor colorname
        Specify the color of all subwindow borders.  The color name
        must be a recognized X color (there are many).  This is a
        style issue.  -bc may be used instead of -bordercolor.

  -byteswap
        Switch the bytes order between big-endian and little-endian
        order.  This may be needed where data has been copied from
        another machine or if there is some confusion about the
        FITS file format.  This switch toggles the previous set-
        ting.  -bswap may be used instead of -byteswap.

  +/-coord
        Set the coordinate tracking state initially on or off.  In
        coordinate tracking, the coordinates of the mouse and value
        of the pixel under it are printed in the upper-left text
        area, above the main display window.  +/-ct can be used
        instead of +/-coord.

  -display nodename:0.0
        Specify the name of the X display server.  This makes it
        possible to run the SAOimage program on a machine other
        than the one connected to your display screen, with no
        difference in appearance or use.  By default, SAOimage gets
        the server name from the DISPLAY environment variable.  See
        the xhost manual page for more details.  The display server
        cannot be changed once SAOimage is running.  -display may
        be abbreviated -d.

  -dfits
        Image file is a FITS file (see -fits), but in unexpected
        byteswapped order.  The FITS standard is not swapped, but
        some naive VAX applications may swap it (see -bswap).

  -fbconfig filename
        Specify an alternate frame buffer configuration file for
        use with IRAF.  By default, the file installed with SAOim-
        age (/usr/local/lib/imtoolrc) is used.

  -fits Image file is a FITS file.  If the image filename ends in
        .fits, this switch is not necessary.  Only T=SIMPLE array
        types are supported.  The header BITPIX card must be 8
        (unsigned byte), 16 (signed short), 32 (signed int), -32
        (float), -64 (double), or -16 (unsigned short).  (The last
        two are not recognized standards).  IEEE floats are not
        converted if that is not the machine format.

  -gd geometry
        Specify the size of the image display subwindow and/or the
        screen position of SAOimage.  The format is a standard X
        geometry statement.  This switch works like -geometry,
        except that width and height (if given) are applied to the
        display subwindow.  The overall SAOimage window is sized
        accordingly.

  -geometry geometry
        Specify the size and/or the screen position of SAOimage.
        The format is a standard X geometry statement.  Both size
        and position may be specified, or only the size or the
        position.  Width and height refer to the dimensions of
        SAOimage's desktop window (see -gd for sizing just the
        image display window).  +x and +y refer to the upper left
        corner in screen coordinates.  -x positions the right edge
        from the right edge of the screen.  -y would positions the
        lower edge from the bottom of the screen.  Width and height
        below a minimum size are defaulted to the minimum.  Speci-
        fying the default minimum size (-geometry 0x0) also
        triggers SAOimage to use smaller dimensions for its inter-
        nal windows.  Once SAOimage is running, use the window
        manager's normal size and move mechanisms to make adjust-
        ments to SAOimage's main window.  -geometry may be abbrevi-
        ated -g.

  -green
        Set the color of all graphics to be green.  See -blue.

  -histeq
        Set the scaling mode for histogram equalization.

  -horizgraph
        Use a horizontal auxiliary color graph window, with a color
        bar along the bottom.  See -vertgraph.  -hg can be used as
        a shorthand for -horizgraph.

  -i2 width height
        Image file is a signed short integer array file of the
        given dimensions.  If the file is square and has no added
        padding, the dimensions are not necessary.  -shortarray
        width height has the same function.

  -i4 width height
        Image file is a signed long integer array file of the given
        dimensions.  If the file is square and has no added pad-
        ding, the dimensions are not necessary.  -longarray width
        height has the same function.

  -idev pipename
        Specify the name of the named pipe used for listening.  The
        default is /dev/imt1o, which is the default used by IRAF.
        See -odev.

  +/-imtool
        Open/close the named input pipe connection and wait for
        input from IRAF.  When open, SAOimage emulates IRAF's
        imtool.  IRAF's image loading and cursor read-back func-
        tions are supported.  Unlike imtool, SAOimage has only one
        frame buffer; IRAF's frame buffer numbers are ignored.
        Listening on the pipe is possible even while reading image
        files directly.  The connection may be opened, closed, or
        re-opened at any time.  When supported, the default mode is
        commonly to start with the IRAF connection open.  See
        -idev, -odev, and -pros.

  -linear
        Set the scaling mode to linear.

  -log [exponent for exponential curve]
        Set the scaling mode to log (exponential), and set the
        exponent for the curve function e sup n if given.

  -lowerleft
        First pixel in file represents the lower left of the image,
        assuming the lines of input run left to right on the
        screen.  This is the IRAF standard and the SAOimage
        default.  See -rotate, -upperleft, and -zero.  -lowerleft
        may be abbreviated -ll.

  -lprbuttons
        Include the button menu in the hardcopy image (only on
        color workstations).  The default on color workstations
        includes the area above the button panel, but excludes the
        buttons.

  -mag magnification
        Set the magnification factor of the magnifier.  This factor
        relates the magnifier to the magnification of the display
        window.  The default is 4; the magnifier magnifies the
        image to 4 times the magnification of the main display win-
        dow (but never less than zoom 1 of the original data).

  +/-magnifier
        Set the magnifier tracking state initially on or off.  With
        magnifier tracking, the magnifier window is continuously
        updated to show a magnification of the image the image
        under the mouse.  +/-mt can be used instead of +/-
        magnifier.

  -max [max val]
        Set the maximum for the image value range used to compute
        scaling.  The default is to take the maximum from the image
        shown in the display window.  -max with no value resets the
        default.  If the maximum value in the displayed image is
        lower than the given maximum, the image's maximum vale is
        used for the scaling range.

  -min [min val]
        Set the minimum for the image value range used to compute
        scaling.  The default is to take the minimum from the image
        shown in the display window. -min with no value resets the
        default.  If the minimum value in the displayed image is
        higher than the given minimum, the image's minimum vale is
        used for the scaling range.

  -mtf  Give the button panel a chiseled look popularized by HP's
        widget set.  This appearance may contrast less with other
        applications being used at the same time.

  -name filename
        This switch is only needed if the filename starts with a
        number or might otherwise be recognized as a switch.

  -odev pipename
        Specify the name of the named pipe used for sending feed-
        back.  The default is /dev/imt1i, which is the default used
        by IRAF.  See -idev.

  -oif  Image file is an IRAF image header file in OIF format.  If
        the image filename ends in .imh, this switch is not neces-
        sary.  IRAF STF and QPOE formats are not supported.  Com-
        plex data cannot be handled.  The data must have at least 2
        dimensions.  Only the first plane of multidimensional
        images is read.  The data file is read directly by SAOimage
        (see -imtool and -pros).

  -one  The file coordinate of the first pixel is (1,1).  The real
        coordinates of the center of the first pixel are (1.0,1.0).
        This is the IRAF standard and the default for SAOimage.
        The second pixel is (2,1).  See -zero.

  -palette number
        Specify the number of read/write color cells to reserve.
        On color workstations, SAOimage reserves color cells in the
        default colormap for its own use. SAOimage reserves as many
        color cells as it can get, up to the number given (the
        default is 200).  If the number given is negative, SAOimage
        comes up in overlay mode, using 1/2 + 2 of the color cells
        for overlays and graphics.  In verbose mode (see -verbose),
        SAOimage tells you how many cells it is able to use for
        display colors.  This number can be re-entered at run-time,
        unless -palette 1 is given, in which case SAOimage stays in
        halftone mode.  -p is an acceptable shorthand for -palette.

  -panboxav | -panboxsum | -panboxsamp | -panboxmax
        These switches select the kind of image reduction used to
        fit a picture of the entire image into the pan window.
        Each pixel is computed from a block of image pixels by
        averaging, summing, sampling, or taking the maximum.  The
        default is to show the maximum from each block.  When zoom-
        ing in the main display involves reduction, subsampling is
        always used.

  -pros Virtually identical to the +imtool switch.  The difference
        occurs when the user writes the saved regions to a disk
        file.  imtool emulation includes writing only an IRAF list
        file giving center coordinates only.  With -pros,
        SAOimage's normal region descriptor file will be written in
        place of the simpler list file.  One may switch between
        this mode and +imtool, or close the IRAF connection with
        -imtool.

  -quiet
        Disable verbose mode;-q may also be used.  See -verbose.

  -r4 width height
        Image file is a real*4 array file of the given dimensions.
        If the file is square and has no added padding, the dimen-
        sions are not necessary.  -floatarray width height has the
        same function.

  -r8 width height
        Image file is a real*8 array file of the given dimensions.
        If the file is square and has no added padding, the dimen-
        sions are not necessary.  -doublearray width height has the
        same function.

  -red  Set the color of all graphics to be red.  See -blue.

  -rmax [max val]
        Set maximum value for reading from the image file.  This
        value is used as the maximum value when images are pre-
        scaled to fit the 16 bit (signed short) working buffer.

  -rmin [min val]
        Set minimum value for reading from the image file.  This
        value is used as the minimum value when images are pre-
        scaled to fit the 16 bit (signed short) working buffer.

  -rotate 1,2,or 3
        Rotate the image 90, 180, or 270 degrees (respectively)
        before displaying it.  Rotation is applied after conversion
        to a lower left coordinate system (-ll) if such conversion
        is also requested.  This is useful for images when the CCD
        was not mounted North-up.  -rot can be used as a shorthand
        for -rotate.

  -scalebias scale bias
        The data in the image file should be scaled and biased to
        get the true image value (TrueValue = (scale * FileValue) +
        bias).  This cannot be used with the -fits image type
        (scale and bias are in the FITS header), nor with -imtool
        or -pros (they are passed by IRAF).  -sb is a shorthand for
        -scalebias.

  -skip bytes
        Skip over the given number of bytes at the head of the file
        before reading   data.  This is used to skip header infor-
        mation or the first image if two images are stored in one
        file.  -header and -sk are aliases for -skip.

  -sqrt [inverse of exponent for geometric curve]
        Set the scaling function to square root (geometric), and
        set the inverse of the exponent for the x sup {1/n} curve,
        if given.

  -u1 width height
        Image file is an unsigned byte array file of the given
        dimensions.  If the file is square and has no added pad-
        ding, the dimensions are not necessary.  -chararray width
        height has the same function.

  -u2 width height
        Image file is a unsigned short integer array file of the
        given dimensions.  If the file is square and has no added
        padding, the dimensions are not necessary.  -ushortarray
        width height has the same function.

  -upperleft
        First pixel in file represents the upper left of the image,
        assuming the lines of input run left to right on the screen
        (see -rotate and -lowerleft).  This switch does not over-
        ride IRAF WCS image coordinates.  -upperleft may be abbre-
        viated -ul.

  +/-verbose
        Set verbose mode on or off.  In verbose mode, informative
        statements are printed to the terminal window when various
        actions are taken.  The default mode is to be verbose.
        +/-v can be used instead of +/-verbose.

  -vertgraph
        Use a vertical auxiliary color graph window, with a color
        bar along the left side.  See -horizgraph.  -vg can be used
        as a shorthand for -vertgraph.

  -wrap [number of wraps within scaling range]
        Set the scaling mode to wrapped linear, and set the number
        of wraps for this mode, if given.

  -zero The file coordinate of the first pixel is (0,0).  The real
        coordinates of the center of the first pixel are (0.5,0.5)
        which makes the very edge (0,0).  This is the standard
        coordinate system for image displays, but not the default
        for SAOimage.  The second pixel is indexed (1,0).  See
        -one.
2 USAGE
  Refer to the SAOimage User Manual for detailed descriptions of
  all functions.

  Most control actions take place within the context of a mode.
  Modes are selected by clicking on menu buttons in the top row of
  the button panel.  Each menu mode brings up its own submenu but-
  tons (the lower row in the button panel) for mode specific selec-
  tions.  Actions and submodes are selected by clicking on buttons
  in the submenu row of the menu panel.

  The mouse controls specific functions in both the main display
  window and the pan/zoom window.  In the main display window, the
  function of the mouse is determined by the mode and submode
  selections from the button menu.  The function can also be recog-
  nized by the appearance of the mouse pointer icon.

  The button interface is designed to be user friendly.  The user
  is encouraged to try any and all buttons to become familiar with
  their functions.  To exit, use the QUIT button in the etc submenu
  (click on etc, then click on QUIT).
3 Reading images
  To read an image directly from a file, give its name anywhere on
  the command line.  The -name switch is needed only when the image
  file name could be mistaken for a number or switch.  SAOimage
  recognizes the .fits and .imh filename suffixes as belonging to
  FITS and IRAF OIF files.  All other file types must be specified
  by an appropriate file type switch.

  Raw array file types must be specified by an array data type
  switch (-u1, -u2, -i2, -i4, -r4, -r8) followed by width and
  height dimensions.  To skip over a file header, use the -sk
  switch followed by the number of bytes.  This can also be used to
  skip over entire images, if more than one are stored in the same
  file.
3 Use with IRAF
  To emulate imtool and communicate with IRAF tasks, use either the
  -imtool or -pros switch.  The two switches indicate which file
  format to use in recording saved cursors or regions.  With
  -imtool, an IRAF list file containing only center coordinates is
  used (like that of imtool).  With -pros, a file containing a full
  description of the saved cursors and their dimensions is used.
  The latter file can be read by tasks in the IRAF PROS spatial
  package for making image masks and performing image analyses.
  Both file types are ASCII and can be read and edited by the user.
  In either case, the file is not actually written until the user
  clicks on the write button in the region submenu.  Both file
  types can be read back to reproduce the saved cursors.
3 New command input
  A new command line can be entered at any time, by selecting the
  new button in the etc submenu or striking the N key on the key-
  board.  This allows the user to read in new images, change in and
  out of -imtool or pros mode, set new scaling parameters, or
  change the number of reserved display color cells.  Most command
  line switches (except -d, -g, -gd, -red, -green, -blue, and
  -vertgraph) will be accepted at any time.

  When a new command line is requested, the previous command line
  is presented in an emacs-like popup editor for editing.  Ctrl-N
  clears the previous line.  Striking the RETURN key enters the
  line in the popup window as the new command.  Ctrl-C returns with
  no action taken.
3 Using the mouse
  Most mouse interactions are based on mouse dragging (holding a
  button down while moving the mouse).  The user should try
  clicking and/or dragging the mouse in each subwindow to become
  familiar with its functions.  Modes selected in the button panel
  determine the response to the mouse buttons in the main display
  window.

  In Scale mode, the mouse buttons control blinking of displays
  (saved by clicking with the same mouse button in the blink sub-
  menu button).

  In Color mode, mouse dragging stretches and shifts the color map
  as per the contrast/bias, threshold/saturation, and gamma submenu
  selections.

  In the color graph window, color table vertexes may be added or
  moved by clicking or dragging with the LEFT (red), MIDDLE
  (green), or RIGHT (blue) mouse buttons.  The graph will update
  continuously only if tracking is turned on.

  In Cursor mode, the mouse controls the size and locations of cur-
  sors.  The rule is: LEFT button for position, MIDDLE button for
  size, and RIGHT button for angle or deletion (depending on the
  cursor).
3 Cursors
  For box and ellipse cursors, MIDDLE button sizing is restricted
  depending on whether dragging started on a side or near a corner.

  With the point cursor, the LEFT and MIDDLE buttons save the
  current mouse pointer position with a + or - indication, while
  the RIGHT button deletes saved points.

  For the polygon cursor, the MIDDLE button adds or moves a single
  vertex, while the RIGHT button will delete vertexes.  The LEFT
  button moves the whole polygon.

  When annuli is set for a box, circle, or ellipse cursor, the MID-
  DLE button adds or resizes an annulus, while the RIGHT button
  deletes annuli.

  For manipulating cursors, the ovlay selection in the Color sub-
  menu, enables the cursor to track smoothly as an overlay graphic.
  The region submenu button brings up another submenu with selec-
  tions to display, review, and edit the saved regions, and read
  from or write to disk files.
3 Pan and zoom
  In Pan mode, and in the pan window (regardless of mode), the LEFT
  button selects the center of the image, while the MIDDLE button
  selects the edge of the display, zoomed from the given center.
  When either function is dragged, the rectangle in the pan window
  shows the area that would appear in the display when the button
  is released.
3 Keys
  In the cursor mode, the S and E keys, save the current cursor in
  a region list, while the D and DELETE keys can be used to forget
  a region.  At any time, with the pointer in the display or pan
  windows, the T key prints a table of pixel values at the pointer
  position to stdout.  The 4 arrow keys can be used for fine move-
  ment of the pointer in any window.  The SHIFT and SHIFT LOCK keys
  will reverse the magnifier window, color graph window and coordi-
  nate tracking status.  The N key summons the pop-up editor for
  new command input.  The A key raises and redraws all of
  SAOimage's windows.
2 BUGS
  SAOimage does not allocate its own colormap and thus fails with
  static color (i.e. NeWS) window managers.  X resource settings of
  a user's default preferences are not read.