Help for PAINT

PURPOSE:

Program "paint" takes an image that is divided into regions and
'paints' each region of the image a different color.  The regions
of the input image are defined in terms of border (or boundary)
pixels.  A border pixel is a pixel whose data number is greater
than or equal to the value specified for the BORDER parameter.
(See under BORDER parameter.)  A region is defined as a connected
set of non-border pixels that is bounded by border pixels.  In
the 'painted' image produced by "paint", the regions are numbered
consecutively beginning with 1, and all pixels in a given region
are assigned (as their data numbers) the number of that region.
 EXECUTION:

Commonly, the input image will be made up of sinuous lines of 
(border) pixels against a background of pixels with zero data numbers.
The lines divide the image into polygon-shaped regions.  The program,
however, does not impose requirements upon the arrangements and the
precise values of border and non-border pixels.  Non-border pixels
may have any value less than the BORDER parameter.  Although
border pixels usually form continuous curves, isolated border
pixels are allowed. Regions may have irregular shapes.  Depending on
the ZEDGE parameter, connected sets of non-border pixels that are
bounded in part by the edges of the image may or may not be considered
to be regions.  The input image may either be byte or halfword data.
In the output image the regions are numbered sequentially in the order
that the program encounters them as it reads (in order) the lines
of the file, scanning them from left to right. The maximum number of 
regions the program can handle is limited by the number of different 
data number values that can be represented in the data format of the input
image ie. 254 regions for byte data and 65534 regions for halfword data.)  
Byte-data images with more than 254 regions should be run with the parameter 
'HALF specified to produce a halfword output image.  Images in halfword 
format with more than 32767 regions will have their regions numbered 
sequentially from 1 to 32767 and then sequentially increasing from -32768. 
(This is sequentially in terms of unsigned 16-bit format.)

When the PBORDER option is used, border points are assigned the
data number of a neighboring region provided one exists. (See
under PBORDER.)  If the PBORDER option is not used, border points
will be assigned a data number of 255 for byte images, 32767 for
halfword images with less than 32767 regions, and 65535 (= -1 in
signed format) for halfword images with at least 32767 regions.

"paint" uses a halfword-format work file in its algorithm for identifying
and numbering the regions. In the work file the regions are numbered in a
preliminary way.  In certain cases portions of a region may be assigned
different numbers. (The program may find that two 'preliminary'
regions are actually connected several lines beneath where the regions
are first encountered by the program.)  Since the number of
preliminary regions is also limited to 65534, this can in effect
reduce the number of regions the program can handle for halfword
images.

TAE COMMAND LINE FORMAT
      The following command line formats show the major allowable forms:
      paint INP=a OUT=(b,w) SIZE=(sl,ss,nl,ns) optional parameters
      paint INP=a OUT=(b,w) SL=sl SS=ss NL=nl NS=ns optional parameters
      paint a (b,w) (sl,ss,nl,ns) optional parameters
      paint a (b,w) optional parameters

       Here 'a' represents the input image file name,
       'b' represents the output image file name, and 
       'w' represents the work file name.
EXAMPLES

 1.   paint INP=P1 OUT=(P2,WRK) SIZE=(1,1,100,100) BORDER=128

      In this example a byte-data image is painted.  Since WRK
      is halfword, it has twice the number of samples.


 2.   paint A (B,WK) 'HALF BORDER=200 'ZEDGE 'PBORDER

      In this example, file A is the input, file B is the output, and
      file WK is the work file.  The output and workfiles are halfword.  
      The border consists of pixels with a value greater than or equal
      to 200. Boundary polygons are zeroed by the keyword ZEDGE, and
      the keyword PBORDER assigns boundary pixels to the nearest 
      non-border polygon.

RESTRICTIONS
1. The input and output images must be byte data.
2. Maximum number of pixels is 64000 per line.  The TAE/VICAR executive
   may impose further size limitations.
3. Maximum number of regions is 254 for byte output data and 65534 for
   halfword data.
4. Maximum number of preliminary regions is 65534.
 OPERATION:

"paint" is an important step in the process of image polygon overlay.  The 
"paint" program assigns region numbers sequentially to non-border pixels,
line by line, using the connectivity algorithm to the pixel above and to
the left.  This algorithm has two possible cases which will cause pixels
to be temporarily mis-assigned.  Case 1 occurs when the first
point in a line for a particular region has a border point immediately
above it and the point is part of a previously encountered region.
In this case the algorithm at first assigns a new region number to the
pixel.  Case 2 occurs when a the intersection of a region with a line is 
a set of two or more strings of pixels.  In this case the algorithm at first
might assign different region numbers to each string. 

In the first case mis-assigned regions are corrected as soon as a non-border
pixel is encountered above the pixel being processed.  In this case the program
moves backwards correcting each pixel up to the border.  In the second case
strings are connected using the table JOIN to link sections of the region
together.  This is done in a second step which picks the final value for each
region while maintaining the reference to the original value through the
table so that the values of the differrent strings in the same region are
the same.
The following diagrams illustrate the two cases in which the program must
correct for mis-assignments. (Border points are denoted by the letter X.)


  XXXXXXX                              XXXXXXXXXXXX
  XXX2222                              X222XXXX333X
  X333333                              X2222222222X
 
   corrected to                 Table JOIN prior to correction:
                                             JOIN(1) = 1
  XXXXXXX                                    JOIN(2) = 3
  XXX2222                                    JOIN(3) = 2
  X222222                                    JOIN(4) = 4

 Example of Case 1                     Example of Case 2


In the final step of "paint", final values are assigned for both non-border
and border pixels.  If PBORDER is specified, border pixels are assigned
the value of the closest non-border pixel.  The search is made in a spiral
from the original pixel.  The direction of the spiral is randomly determined.

 ORIGINAL PROGRAMMER:   A. Zobrist		1975

 COGNIZANT PROGRAMMER:   Barbara McGuffie       4/1986

 DOCUMENTATION WRITTEN BY:             Steve Pohorsky               
 REVISION:               1      
 REVISION:               2      AMS (CRI) Mar. 6 1995   Made portable for UNIX

PARAMETERS: