Help for EDIMAGE

PURPOSE


    "edimage" is an interactive program that performs editing of gray scale
or color byte images.  Image are displayed and edited on a monitor.
Images may be painted with a brush, parts copied and filled, lines drawn,
and text annotation added.


EXECUTION


    Before running "edimage" the appropriate display device must be
allocated.  "edimage" starts out by copying the input image(s) to the
output image(s), if they exist.  If color images are to be edited
then there must be three input images (in red, green, blue order)
and the 'COLOR keyword must be specified.  The default is to edit
one image in gray scale mode.  The Vicar size field is used to copy
a window from the input image to the output image and only edit the
window area.  There may be extra input and output files: these are
used for IBIS graphics files and color lookup tables.
    By default "edimage" will clear the image planes before the session
begins(SCREEN="CLEAR"). The 'NOCLR keywork preserves whatever was on the image
planes before "edimage" was invoked;  This can be used to piece together a lot
of unrelated images displayed previously with IDX, etc. 

    The TEST keyword allows "edimage" to be run in a test mode.  (See under the
help for the TEST parameter.)

Examples:

  edimage  INPUT.IMG  OUTPUT.IMG  SIZE=(1500,1,1000,2500)

  edimage  (IM.R,IM.G,IM.B,POLY.GRA)  (IM2.R,IM2.G,IM2.B)  'COLOR

  edimage  (IM.R,IM.G,IM.B,POLY.GRA,CLR.TBL)  POLY2.GRA  'COLOR

  edimage  (INPUT.IMG,PSCOLOR.TBL)  (OUTPUT.IMG,PSCOLOR.TBL)


    "edimage" prints out some informative messages such as the size of the 
image being edited as the program starts up.  After the image has been 
copied and the display device initialized the program prompts for user input:

      Command: 

    The user will then type in a series of commands and use the trackball
and switches to perform the desired image editing.

Commands are of the form:

      COMMAND  KEYWORD = VALUE1,VALUE2   KEYWORD VALUE 

    Commands and keywords may be abbreviated and may be in upper or lower
case. Most any non-alphanumeric character can serve as a delimiter.  Equal 
signs and commas are optional.  Some keywords take multiple values others 
take no value.  Often the command serves as the keyword (e.g. STRETCH 50 200).

Image editing example:

 edimage (TM.RED,TM.GRN,TM.BLU) (TMNEW.RED,TMNEW.GRN,TMNEW.BLU) 'COLOR

 Commands entered:

  DISP SL 250 SS 100 NL 400 NS 400  Display a 400 square window from input
  STRETCH			    Perform trackball controlled stretch
  BRUSH SIZE 12 TYPE GAUSS	    Select gaussian brush
  COLOR AVERAGE			    Set current color to average under brush
  PAINT .5			    Airbrush a region
  Palet				    Display color palette at bottom of screen
  COLOR 6			    Select palette color 6 as current color
  DRAW BOX WIDTH=4		    Draw box in the image with current color
  EXIT				    Save modified image and exit program

    If the displayed image window does not fill the image memory planes the 
remaining empty region may be used as a scratch pad.

The following is a list of the available commands:

    DISPLAY  . . to display a region of the image
    STRETCH  . . to perform contrast stretches on the image
    HZOOM    . . to perform hardware zooming
    PAN      . . to pan around the display
    TABLE    . . to load and save display look up tables
    PALETTE  . . to control display of the color palette
    PSEUDO   . . to enter pseudo color mode
    COLOR    . . to set the current color
    BRUSH    . . to set the current brush
    PAINT    . . to paint the image with the brush
    DRAW     . . to draw lines in the image or graphics plane
    TEXT     . . to put text into the image

		 (more commands ...)

More available commands:

    POLYGON  . . to generate polygon graphics
    COPY     . . to copy polygonal image areas
    STATIST  . . to calculate image statistics in polygons
    FILL     . . to fill polygonal image areas
    TEXTURE  . . to texture polygonal image areas
    HELP     . . to get help on various commands
    COMMENT  . . to have a command line treated as a comment (i.e. ignored)
    EXIT     . . to save image planes and exit
    QUIT     . . to exit without saving image planes


    DISPLAY saves the current image memory planes in the file
and displays the new region of the image.  The default region
is as much of the upper left corner of the image as fits in the
image memory planes.  The following keywords select the region
to display:

 SL, SS  . . the starting line and sample in the image
 NL, NS  . . the number of lines and samples

    The NOSAVE keyword disables saving the current region before
displaying the new region; this is a good way of erasing mistakes.


    STRETCH performs contrast stretches on the display.  The stretch
is performed by changing the look up tables without changing the actual 
pixel values.  The stretch may be performed using various keywords:

 STRET n1 n2      performs a linear gray scale stretch between DN 
		  values n1 and n2
 STRET RED n1 n2  performs linear stretch on the red look up table.  
  		  Similarly for GREEN and BLUE.

    STRETCH by itself will perform a trackball controlled linear stretch.  
The vertical axis controls the contrast and the horizontal axis controls 
the offset.  If the program is in pseudo color mode then stretch performs 
a contrast stretch on the pseudo color table.

    HZOOM [n] performs a hardware zoom of the display.  If no value follows 
the command then the zoom factor is doubled from its previous value, otherwise 
the zoom factor is set to the new value. (Valid n range = 1 through 8)

    PAN puts the program in pan mode.  In pan mode the trackball is used to 
select the region of the image memory plane which will be displayed on the
monitor.  This is useful if the display is hardware zoomed or if the image 
memory planes are larger than the display.  Pressing switch 1 exits PAN mode.


    TABLE saves and loads display look up tables on disk.
The tables are in the same format that IDX and LOOKUP use.
Parameters:

 SAVE f    saves the current look up table in output file f
 LOAD f    loads the look up table from input file f
 NUMBER t  table number t loaded from file (default is 1)

    PALETTE controls the display of the palette.  The palette displays
the first 16 colors of the color table at the bottom of the screen.

 PALETTE       displays (or redisplays) the palette
 PALETTE OFF   erases the palette

    Zooming or panning will move the palette from the bottom of the display;
the PALETTE command will redisplay it along the bottom of the screen.

    The palette may be saved to and loaded from a file:

 PALETTE SAVE=file   saves palette colors in file
 PALETTE LOAD=file   loads palette colors from file
    The default filename is "edimage".PAL

    The palette file is an ASCII table of the 32 colors in the palette; 
the color number, red value, green value, and blue value are stored in 
each row. (Note: These files are not be entered on the VICAR command line.)

    PSEUDO changes the look up tables for pseudo color mode.
It enters pseudo color mode if in gray scale mode.

 OFF        turns off pseudo color, returning to gray scale
 TABLE [n]  selects the nth pseudo color table (same as IDX; 1-7, def=3)
 DN n1 [n2] sets the DN value [range] to change with RGB or COMP
 RGB r g b  sets the DN range to given red, green, and blue
 COMPOSE    enters interactive color composing mode

Note: PSEUDO does not change the palette colors or the current color, 
only the look up tables.
    COLOR changes the current color.  

 COLOR [n]  selects the nth palette color as the current color. If the n
is omitted the current color is changed. COLOR uses the following keywords:

 DN      sets the color to given gray scale value
 RGB     sets the color to the given red, green, and blue values
 CURSOR  sets the color to that of a selected pixel on the display
 AVERAGE sets the color to the average under the brush on the display
 COMPOSE enters the interactive color composing mode

Example:  COLOR 3  RGB 240 50 200

    Sets the current color to the particular RGB value and sets palette
color three to this color.  If no color number is specified then the
current color is changed, but the color table is not.
    BRUSH sets the size and type of the brush used for airbrushing in
PAINT mode.  Valid brush types are:

 DISK, SQUARE, DOME, GAUSSIAN.

    The SIZE parameter selects the brush diameter in pixels. (max = 32)

    The TYPE parameter selects the brush type.  

    If a parameter is not given then the old value will be used.  The brush 
size and type are displayed.

Examples:

	BRUSH SIZE 8 TYPE GAUSS
	BRUSH SIZE 3
	BRUSH TYPE DISK

    PAINT [d] puts the program in painting mode (airbrushing or dabbing). In 
paint mode the brush (marked by the cursor) is moved with the trackball. When 
switch 1 is held down the brush paints the image.  The painting involves 
a weighted average between the current color and the pixel values in the image.
The painting density (weight) may be changed by giving a new value after the 
PAINT command (d) (0< d <=1.0).  The starting paint density is .25 and if no
paint value is given the previous value is used.  Some brush types have 
variable painting densities over their surface.  A new current color may be 
selected inside paint mode by finding a pixel with the desired color and 
pressing switch 2.  Press switch 3 to leave paint mode.  See COLOR and BRUSH 
for related information.  PAINT mode requires large CPU resources:  response
will degrade significantly if adequate CPU is not available.

    DRAW draws line graphics of the current color into the image memory
planes or into the graphics plane (only with the GRAPHICS option of FILE).
The graphics lines drawn may have variable thickness (only in image plane
mode).  There are several ways of drawing the graphics into the image plane:

 default    draws the line as the cursor is moved
 LINE       draws segments between endpoints
 BOX        draws a rectangle from two corner points
 FILE [n]   draws graphics from input file n (def = first non-image input)
                  graphics from a file are in image file coordinates
 WIDTH [w]  draws lines with a width of w pixels (def = 1, max = 9)

    To draw graphics into the graphics plane:

 FILE [n] GRAPHICS [v]  draws IBIS graphics file from input file n with a 
	    value of v (def = 1; valid 0 through 7)
	0 = Black	1 = White	2 = Red		3 = Green
	4 = Blue	5 = Yellow	6 = Cyan	7 = Magenta
    TEXT sets the text parameters and draws text characters in the image 
memory planes.  The text parameters stay in effect until changed.  If a 
text string is given (with parameter STRING) then a cursor position is 
prompted for and the text is drawn on the graphics plane.  If the text
is accepted it is then burned into the image memory using the current color.
Text mode may exited with switch 3.

Parameters:

 STRING "the text string" 
 STRING    parameter with no value uses the last text string
 SIZE  h   height of the characters in pixels (def = 10)
 SCALE s   horizontal scale factor for text size (def = 1)
 ANGLE a   the angle from the horizontal axis in degrees
 FONT  f   the font number (see below)
 LEFT CENTER RIGHT  keywords for text justification


		      Text Font Descriptions

      Font     Description	      Font     Description
	0	Default Font	
	1	Simplex			8	Hollow
	2	Duplex			9	Cartographic
	3	Roman			10	Greek
	4	Standard		11	English Gothic
	5	Standard 2		12	German Gothic
	6	Standard Italics	13	Italian Gothic
	7	Script			14	Cyrillic
            There are other special fonts as well.

    POLYGON draws graphics on the graphics plane and stores the graphics 
internally for later use.  The graphics may be generated interactively or 
from an IBIS graphics file.  The graphics are in image file coordinates.

    Parameters:

 no keyword   enter interactive mode
 BOX [parm]   specify a rectangle from two corner points
               Optional parameter  SIZE SL SS NL NS
	       specifies a rectangle with standard SIZE window in image.
 READ [n]     reads graphics from input file n (def = first non-image input)
 WRITE [n]    writes graphics buffer to output file n (def = same as READ)
 CLEAR        clear graphics plane and graphics buffer

    See also FILL, COPY, and STAT.


    COPY copies the image inside of a polygon to another region of the
image memory plane.  The desired polygon is chosen by placing the cursor 
inside the polygon and pressing switch 1.  The polygon is highlighted 
and the user is asked for verification.  Another polygon may be chosen.
If the cursor is not in any polygon the command will not be performed.
The place to put the image area is chosen with another cursor selection.  
The area will be moved the distance between the first and second cursor 
selections.  Multiple copies may be made. (Note: Use reference points
to assist you in copying images; i.e. from and to points.)

    FILL fills the image area inside of a polygon.  The desired polygon
is chosen by placing the cursor inside the polygon and pressing switch 1. 
The polygon is highlighted and the user is asked for verification.  
Another polygon may be chosen.  If the cursor is not in any polygon the 
command will not be performed.

    There are three methods of filling:

 no keyword   The area is filled with the current color.
 TRANSPAR d   The area is filled with a weighted average of the original
	      image and the current color.  TRANS 1.0 is equivalent to 
	      the standard fill. (Valid range: 0< d <= 1.0)
 INTERP [r]   Interpolates the image area using the DN
              values at the polygon vertices.  r is the
              maximum radius for a vertex to be used.
 OUTSIDE      Fills outside of polygon instead of inside.


    STATISTICS calculates simple statistics for the image area inside of
a polygon.  The desired polygon is chosen by placing the cursor inside the 
polygon and pressing switch 1.  The number of pixels and the average, 
standard deviation, minimum, and maximum for each image plane within the
selected polygon is typed out.

    TEXTURE textures a polygonal image area using another area as a texture
pattern.  First, the polygon to texture is selected.  Second, the color stat-
istics polygon is selected unless the AVG or STD keywords are given.  The
color polygon is used to provide the color average and variance for the textured
area.  Finally, the texture pattern region is selected by selecting two corners
of a rectangle.  The rectangle is forced to be a power of two in size.  The
rectangle is highlighted, and the user may pick another one if desired.  The 
texture pattern rectangle is used to make a filter.  The filter is then 
convolved with gaussian noise to make the textured region.  A high pass filter
is used to cut out the low spatial frequencies and make a flat textured image.

 Keywords:
 AVG      the average DN value for each color band
 STD      the standard deviation for the color bands
 SIZE     size in pixels of the filter (default=16)
 HIPASS   cutoff size in pixels for the high pass (def=8)




    EXIT exits the program and saves the image memory planes
if they have been changed.


    QUIT exits the program without saving the current display 
screen.  Previous display screens will have already been saved, 
so the file may be changed.

OPERATION

    There are three different image coordinate systems that need to be
taken into account.  The first is the coordinates of the image file, 
i.e. the line and sample values of the pixels in the file.  The second 
coordinate system is the image memory planes.  The image memory planes 
are a window into the image file that is offset from the top left corner 
of the image file according to the SL and SS parameters in the DISPLAY 
command.  The third coordinate system is the display window.  The display 
window is a window into the image memory planes.  There may be an offset 
(from PANing) and there may be a scaling (from HZOOMimg).

RESTRICTIONS

The maximum number of samples in an image line is 32768.
The maximum number of samples in the image memory planes is 4096.
The number of colors in the palette is 32.
The maximum brush size is 32 pixels.
The maximum number of polygons is 1024.
The maximum number of polygon vertices is 16384.

Display Device Requirements:
  One image plane for gray scale mode.
  Three image planes for color mode.
  Graphics plane for polygon related commands.
  Must have hardware cursor.
  Must have cursor locating device (i.e. trackball) with three switches.

Original Programmer:   Frank Evans	May 1987

Cognizant Programmer:  Frank Evans

Revision:  New		May 1987
           Made portable for UNIX  AS  (CRI)  March 1995

PARAMETERS: