
editimage(1)                 Khoros                  editimage(1)

PROGRAM
     editimage - Interactive Image Display and Manipulation Pro-
     gram

SYNTAX
     editimage

     [-i]           input image filename

     [-ov]          overlay image filename

     [-s]           input shape mask filename

     [-c]           input clip mask filename

     [-roi_out]     output ROI filename

     [-x]           x value of upper-left corner of editimage
                    user interface

     [-y]           y value of upper-left corner of editimage
                    user interface

     [-zoom]        initial zoom factor

     [-update]      initial update time

     [-display]     host:display.screen

     [-form]        editimage form

     [-cmap_image]  image with alternate colormap filename

     [-use_cmap]    use colormap?

     [-fn]          Specifies the font for editimage (use %
                    xlsfonts for available fonts)

     [-jr file.jp]  Creates a journal recording for editimage

     [-jp file.jp]  Executes a journal playback for editimage

     [-V]           Gives the version for editimage

     [-U]           Gives the usage for editimage

     [-P]           Prompts for command line options

     [-A [file1]]   Creates the answer file called editimage.ans
                    or file1

     [-a [file1]]   Uses editimage.ans or file1 as the answer
                    file

DESCRIPTION
     editimage is an interactive image display, examination, and
     manipulation tool.  editimage accepts any Khoros VIFF file
     as input, and will convert the data type when necessary,
     though the user will be prompted to ok this conversion.
     Output images are of type byte.  Currently, editimage can
     utilize a maximum of 256 colors.  Any image that has more
     than this number of colors is converted to fit into the
     available number of colors.  Note that this conversion will
     normalize the image to the total number of colors that are
     available to be displayed on the workstation being used.

     editimage provides several display utilities;  most of these
     work with respect to the RGB, CMY, HSV, HLS, UVW, XYZ, YIQ,
     and GREY color spaces.  In order to fully understand the
     information imparted by the display utilities of editimage,
     it is important for the user to have an understanding of the
     operation of each of these color spaces, as well as a feel-
     ing for how each of the available colorspaces relate to the
     others. editimage was written with the assumption that the
     user has the knowledge necessary to correctly interpret
     visual results generated and to recognise when those results
     are not valid.  Invalid results can be generated when the
     colorspace of the image does not match the colorspace of the
     display;  however, editimage follows the philosophy that it
     is better to allow the uneducated user to generate incorrect
     results than to limit the experimenting researcher with
     rigid errorchecking.

     The DISPLAY UTILITIES provided by Editimage include:

     1)   Zooming in on an entire image or on selected regions of
          the image.

     2)   Pixel values of 5 by 5 regions may be displayed with
          respect to the current color space.

     3)   The image's look up table (LUT) may be interactively
          manipulated.

     4)   Pseudo coloring may be performed interactively.

     5)   Windowing and Thresholding may be done on an image.

     6)   For multiband images, the currently displayed band may
          be changed.

     7)   Bit images may be overlaid onto the displayed image.

     The IMAGE UTILITIES provided by Editimage include:

     1)   Input and output of images, as well as input of a
          colormap from another image to be used by the displayed
          image

     2)   Standard colormap conversions, with a choice of 11
          predefined colormaps

     3)   Region of Interest (ROI) operations with which a por-
          tion on an image may be extracted or inserted; also the
          ability to perform image processing routines on the
          specified region of interest.

     4)   Image Header Modification

     5)   Annotations that can be added to the displayed image,
          including circles, rectangles, text, polygons, and
          lines.

     When an image too large to display within the window, edi-
     timage will display a small pan window.  The white rectangle
     within the pan window indicates the area that is currently
     displayed in the display window.  You may "pan" about the
     image by pressing the mouse in the display window, holding
     the mouse button down, and moving it.  Alternatively, you
     may perform this same procedure in the little pan window;
     the rectangle indicating the area that is currently
     displayed will move  with the mouse, and the display window
     will update according to the location of the rectangle
     within the pan window.

     Command Line Options

     [-i {input image filename}]
          This is the input VIFF image to be displayed, unless
          you prefer to start editimage with no arguments, and
          enter the input VIFF image in the Input/Output pane of
          the "Image Utilities" pulldown menu. The VIFF file may
          be of any data type except complex. It will be the
          currently displayed image.  With multiband images, the
          first (0th) band is displayed by default. The CHANGE
          BANDS option on the "Display Utilities" pull-down menu
          can be used to display other bands if desired.

     [-ov {overlay image filename}
          If desired, a bit image may be specified to be over-
          layed onto the currently displayed image.  It must be a
          Khoros VIFF file of data type BIT; if the VIFF image
          passed in is NOT of type BIT, it will be automatically
          converted without prompting or warning (this is only
          done internally - the file itself will not be changed).
          ALSO: if the VIFF data file passed in is a multiband
          image, the first (0th) band will be taken as the over-
          lay.

     [-s {shape mask filename}]
          If desired, a BIT image may be provided to act as a
          shape mask.  It must be a Khoros VIFF file of data type
          BIT; if the VIFF image passed in is NOT of type BIT, it
          will be automatically converted without prompting or
          warning (this is only done internally - the file itself
          will not be changed).  ALSO: if the VIFF data file
          passed in is a multiband image, the first (0th) band
          will be taken as the shape mask.

          When an image is used as a shape mask for the currently
          displayed image, the only part of the currently
          displayed image that will be visible is that part
          defined by the pixels in the shape mask image that have
          a value of (1).  All other parts of the currently
          displayed image will "disappear", and the background
          (the part of the screen behind the image display win-
          dow) will show through.

          WARNING:  ONLY VERY SIMPLE BIT IMAGES SHOULD BE USED AS
          SHAPE MASKS.  For example, the bit image "ball.bit"
          KHOROS_HOME/data/masks is a good shape mask. As more
          complicated images are used (images with many "holes"
          in them), the program will become incredibly slow as
          the X server  has to do much additional work in order
          to map the image to the window.  NOTE: This feature
          will only work on X servers that support the shape
          extension!

     [-c {clip mask filename}]
          If desired, a bit image may be input and used as a clip
          mask.  It must be a Khoros VIFF file of data type BIT;
          if the VIFF image passed in is NOT of type BIT, it will
          be automatically converted without prompting or warning
          (this is only done internally - the file itself will
          not be changed).  ALSO: if the VIFF data file passed in
          is a multiband image, the first (0th) band will be
          taken as the clip mask.

          When an image is used as a clip mask for the currently
          displayed image, the only part of the image that will
          appear normally is that part defined by the pixels in
          the clip mask image that have a value of (1). All other
          parts of the current image will appear in the back-
          ground color of the image window (usually black).
          Images work best as clip masks when they are the same
          size as the input data.  $KHOROS_HOME/data/masks/ con-
          tains two images that make good clip masks.

     [-x {x value}, -y {y value}]
          If your window manager does not use manual placement,
          or you would like to over-ride the manual placement
          used by your window manager (this may not work with all
          window managers), specify the (x,y) location in device
          coordinates at which you would like the graphical user
          interface to appear.

     [-roi_out {output ROI filename}
          If you intend to use the Region of Interest utility
          found on the "Image Utilities" pulldown menu to output
          a Khoros VIFF file representing a particular region of
          interest, and you know in advance the name of the out-
          put file that you wish to use, you may specify that
          filename here.  When you bring up the "Region of
          Interest" subform,  the "Output Filename" parameter
          will be already filled out with your filename.

     [-zoom {initial zoom factor}]
          If you intend to use the Zoom utility found on the
          "Display Utilities" pulldown menu to zoom in on the
          currently displayed image, and you know in advance the
          zoomfactor that you wish to use (the default is 2.0),
          you may specify the zoomfactor here. When you bring up
          the "Zoom" subform, the zoomfactor will be already set
          to your desired value.  It must be specified as a
          floating point value which must be greater than zero.

     [-update {update time}]
          Suppose that while you are displaying an image with
          editimage, the Khoros VIFF file that is currently
          displayed is over-written.  When the [-update] flag is
          specified as some number greater than zero (the
          default), this indicates to editimage that it should
          automatically register the fact that the input file has
          been changed, and update the currently displayed image
          accordingly.  The value of the [-update] flag specifies
          (in seconds) how often the input file is to be checked
          for any potential modifications.    It should be speci-
          fied as a floating point value which is greater than
          zero.  When the value of the [-update] flag is zero
          (the default value), editimage will NOT check the input
          file for modifications.

     [-display {display}]
          You may execute editimage on one workstation, but
          display it on another.  If you wish to do this, you
          must specify the display on which editimage will
          appear.  It must be specified as "-display
          host:screen".

     [-form {UIS FILE}]
          If desired, you may copy the User Interface Specifica-
          tion for editimage
          (KHOROS_HOME/repos/editimage/editimage.form) and change
          the geometry specifications, labels, or defaults
          according to your personal preferences.  Now, if you
          specify "-form new.form" where new.form is your per-
          sonal UIS file, the graphical user interface of editim-
          age will be defined by your UIS file. Note: it is not
          advisable to do this unless you are very familiar with
          the syntax and definition of all lines in the UIS file.
          Furthermore, you may not add or delete any lines from
          the UIS file.  Geometry strings, labels, and defaults
          are the only fields that may be changed.  Any other
          changes will corrupt the UIS file, and editimage will
          not work.

     [-cmap_image {VIFF image w/ alternate colormap}]
          If desired, another image may be input, and its color-
          map will be used with the currently displayed image,
          instead of the currently displayed image's colormap.

     [-use_cmap {t/f}]
          While the default action of editimage is to use the
          colormap associated with the currently displayed image,
          no colormap is required to be used.  If the colormap
          associated with the currently displayed image is not
          wanted, AND the "-cmap_image filename" is not used,
          specify "-use_cmap 0", or "-use_cmap false".  In this
          case, the default colormap associated with the screen
          on which editimage is being run will be used. NOTE:
          when "Use Colormap" is specified as false, the "-
          cmap_image filename" option detailed above WILL NOT
          TAKE EFFECT.

     Version
          The "-V" argument will print out the current version of
          editimage.

     Usage
          The "-U" argument will print out the usage for editim-
          age, in much less detail than is given here.

     Interactive Prompting
          The "-P" argument will give interactive prompting for
          each of the arguments listed above.

     Creating an Answer file
          The "[-A {filename.ans}]" argument will create an
          answer file named "filename.ans" if the filename option
          is specified, or named "editimage.ans" if no filename
          is given.  An answer file stores the values specified
          of all arguments listed above.  Note: the "-A" argument
          is usually used in conjunction with the "-P" argument.

     [-a {filename.ans}]
          Use the answer file named "filename.ans" if the
          filename option is specified, or named "editimage.ans"
          if no filename is given.  Editimage will use the answer
          file to get values for all arguments listed above.  No
          other arguments should be necessary when the "-a" argu-
          ment is used.

          For much more detailed information on the editimage
          display program, see chapter 5 of the User's Manual.

REQUIRED ARGUMENTS
     none

OPTIONAL ARGUMENTS
     -i     type: infile
            desc: input image filename

     -ov    type: infile
            desc: overlay image filename

     -s     type: infile
            desc: input shape mask filename

     -c     type: infile
            desc: input clip mask filename

     -roi_out
            type: outfile
            desc: output ROI filename

     -x     type: integer
            desc: x value of upper-left corner of editimage user
            interface
            default: -1
            bounds: -1 < [-x] < 1000

     -y     type: integer
            desc: y value of upper-left corner of editimage user
            interface
            default: -1
            bounds: -1 < [-y] < 1000

     -zoom  type: float
            desc: initial zoom factor
            default: 2
            bounds: value > 0.0

     -update
            type: float
            desc: initial update time
            default: 0
            bounds: value >= 0.0

     -display
            type: string
            desc: host:display.screen
            default: null

     -form  type: string
            desc: editimage form
            default: null

     -cmap_image
            type: infile
            desc: image with alternate colormap filename

     -use_cmap
            type: boolean
            desc: use colormap?
            default: true

EXAMPLES
     % editimage -i $KHOROS_HOME/data/images/feath.xv

SEE ALSO
     intro(1), verror(3), vgparms(3), vutils(3), leditimage(3)

RESTRICTIONS
     1) editimage will only work on VIFF images.
     2) When the [-update] argument is used and the currently
     displayed image is changed when the original input file is
     over-written, the image is updated accordingly; however, as
     this process is repeated many times, the new image may have
     its  colormap corrupted by the colormap of one of the previ-
     ous images.

COPYRIGHT
     Copyright 1992, University of New Mexico.  All rights
     reserved.

Khoros                    Release: 1.0                          1

