editimage(1)

PROGRAM
editimage - Interactive Image Display and Manipulation Program

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 feeling 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 portion 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, editimage 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 overlayed 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 overlay.

[-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 window) 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 background 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/ contains 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 output 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 specified 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 Specification 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 personal UIS file, the graphical user interface of editimage 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 colormap 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 editimage, 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" argument 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 previous images.

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