     SAOIMAGE(1)                                                     SAOIMAGE(1)
                                     3 July 1991

     NAME
          SAOimage - X11 window based, interactive, color or halftone image
          display program for astronomical images

     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 ]

     DESCRIPTION
          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, coloring, 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.

     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 setting.  -bswap

                                        - 1 -           Formatted:  May 12, 2000

     SAOIMAGE(1)                                                     SAOIMAGE(1)
                                     3 July 1991

                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 SAOimage
                (/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

                                        - 2 -           Formatted:  May 12, 2000

     SAOIMAGE(1)                                                     SAOIMAGE(1)
                                     3 July 1991

                would positions the lower edge from the bottom of the screen.
                Width and height below a minimum size are defaulted to the
                minimum.  Specifying the default minimum size (-geometry 0x0)
                also triggers SAOimage to use smaller dimensions for its
                internal windows.  Once SAOimage is running, use the window
                manager's normal size and move mechanisms to make adjustments to
                SAOimage's main window.  -geometry may be abbreviated -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 padding, 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 functions 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.

                                        - 3 -           Formatted:  May 12, 2000

     SAOIMAGE(1)                                                     SAOIMAGE(1)
                                     3 July 1991

          -log [exponent for exponential curve]
                Set the scaling mode to log (exponential), and set the exponent
                for the curve function en 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 window (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

                                        - 4 -           Formatted:  May 12, 2000

     SAOIMAGE(1)                                                     SAOIMAGE(1)
                                     3 July 1991

                or might otherwise be recognized as a switch.

          -odev pipename
                Specify the name of the named pipe used for sending feedback.
                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 necessary.  IRAF
                STF and QPOE formats are not supported.  Complex 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 zooming 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.

                                        - 5 -           Formatted:  May 12, 2000

     SAOIMAGE(1)                                                     SAOIMAGE(1)
                                     3 July 1991

          -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 dimensions 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 dimensions 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 information
                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 x1/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 padding, the
                dimensions are not necessary.  -chararray width height has the
                same function.

                                        - 6 -           Formatted:  May 12, 2000

     SAOIMAGE(1)                                                     SAOIMAGE(1)
                                     3 July 1991

          -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 override IRAF WCS
                image coordinates.  -upperleft may be abbreviated -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.

     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 buttons
          (the lower row in the button panel) for mode specific selections.
          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
          recognized 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).

                                        - 7 -           Formatted:  May 12, 2000

     SAOIMAGE(1)                                                     SAOIMAGE(1)
                                     3 July 1991

        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.

        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.

        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 keyboard.  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.

        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 submenu 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

                                        - 8 -           Formatted:  May 12, 2000

     SAOIMAGE(1)                                                     SAOIMAGE(1)
                                     3 July 1991

          turned on.  In Cursor mode, the mouse controls the size and locations
          of cursors.  The rule is: LEFT button for position, MIDDLE button for
          size, and RIGHT button for angle or deletion (depending on the
          cursor).

        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 MIDDLE button
          adds or resizes an annulus, while the RIGHT button deletes annuli.
          For manipulating cursors, the ovlay selection in the Color submenu,
          enables the cursor to track smoothly as an overlay graphic.  The
          region submenu button brings up another submenu with selections to
          display, review, and edit the saved regions, and read from or write to
          disk files.

        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.

        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 movement of the pointer
          in any window.  The SHIFT and SHIFT LOCK keys will reverse the
          magnifier window, color graph window and coordinate 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.

     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.

                                        - 9 -           Formatted:  May 12, 2000