path: root/pkg/proto/doc/mskregions.hlp

.help mskregions Dec01 proto
.ih
NAME
mskregions -- Create mask from a list of region specifications
.ih
USAGE
mskregions regions masks refimages
.ih
PARAMETERS
.ls regions
The list of input regions files. The number of regions files must be one or
equal to the number of output mask images. Regions files contain a list of
region specifications one region per line. The region specifications may be
a simple region description, e.g. "circle 100. 100. 50.", or a region
expression, e.g.  "circle (100., 100., 50.) && circle (125., 100., 50.)".
.le
.ls masks
The output masks. The size of the output masks defaults to the size of
the reference image or the value of the dims parameter in that order of
precedence.
.le
.ls refimages
The optional list of reference images. If the reference image list is defined
there must be one reference image for every output mask.
.le
.ls dims = "512,512"
The default output mask dimensions. The value of dims is a comma delimited
list of dimensions.
.le
.ls depth = 0
The default output mask depth in bits currently 27.
.le
.ls regnumber = "constant"
The region definition scheme. The options are:
.ls constant
Assign all the mask regions the value of \fIregval\fR.
.le
.ls number
Assign each region a sequential value beginning with \fIregval\fR.
.le
.le
.ls regval = 1
The starting mask region value.
.le
.ls exprdb = "none"
The file name of an optional expression database. An expression database
may be used to define symbolic constants or a library of custom function
macros.
.le
.ls append = no
Add the region list to an existing mask ?
.le
.ls verbose = yes
Print task status messages ?
.le

.ih
DESCRIPTION

Mskregions reads a list of region specifications from the input files
\fIregions\fR and writes the results to the output masks \fImasks\fR image.
The number of regions files must be on or equal to the number of output
masks. The size of the output mask is determined by the reference image
\fIrefimages\fR if any \fIrefmasks\fR if any or the values in the
\fIdims\fR parameter in that order of precedence.

The output mask is an integer image. Therefore all mask values must be
integer. The mask values assigned to the regions in \fIregions\fR are
determined  by the \fIregnumber\fR and \fIregval\fR parameters. By
default all new regions are assigned the value of 1. The depth of the output
mask in bits is defined by the \fIdepth\fR parameter. The default value is
27 bits.

The input region specifications may be region descriptions or region
expressions. Region descriptions are simple definitions of common geometric
shapes. Evaluation of the regions expressions is carried out one line at a time.

\fBRegions Definitions\fR

The following region definitions are supported.

.nf
      point x1 y1
     circle xc yc r
    ellipse xc yc r ratio theta
        box x1 y1 x2 y2)
  rectangle xc yc r ratio theta
     vector x1 y1 x2 y2 width
        pie xc yc theta1 theta2
    polygon x1 y1 ..., xn yn
       cols ranges
      lines ranges
   cannulus xc yc r1 r2
   eannulus xc yc r1 r2 ratio theta
   rannulus xc yc r1 r2 ratio theta
   pannulus width x1 y1 ... xn yn
.fi

\fBOperands Used in Region Expressions\fR

Input operands are represented symbolically in the input expression. Use of
symbolic operands allows the same expression to be used with different data
sets, simplifies the expression syntax, and allows a single input image
to be used several places in the same expression.

There is a special builtin type of operand used to represent the
mask pixel coordinates in a mask expression.  These operands have the
special reserved names "I", "J", "K", etc., up to the dimensions of the
output image.  The names must be upper case to avoid confusion to with the
input operands "i" and "m".

.nf
        I                x coordinate of pixel (column)
        J                y coordinate of pixel (line)
        K                z coordinate of pixel (band)
.fi

\fBOperators Used in Region Expressions\fR

The expression syntax implemented by mskexpr provides the following
set of operators:

.nf
        ( expr )                grouping
        &&                      logical and
        ||                      logical or
        !                       logical not
.fi


\fBFunctions Used in Region Expressions\fR

Mskexpr supports a group of boolean region functions which can be used to set
values inside or outside of certain geometric shapes. The routines may be
called in two ways. The first way assumes that the output masks are two-
dimensional. The second way assumes that they are multi-dimensional and
specifies which dimensions the geometric operator applies to.

.nf
      point (x1, x2)
     circle (xc, yc, r)
    ellipse (xc, yc, r, ratio, theta)
        box (x1, y1, x2, y2) 
  rectangle (xc, yc, r, ratio, theta)
     vector (x1, y1, x2, y2, width)
        pie (xc, yc, theta1, theta2)
    polygon (x1, y1, ..., xn, yn)
       cols (ranges)
      lines (ranges)
   cannulus (xc, yc, r1, r2)
   eannulus (xc, yc, r1, r2, ratio, theta)
   rannulus (xc, yc, r1, r2, ratio, theta)
   pannulus (width, x1, y1, ..., xn, yn)

      point (I, J, x1, x2)
     circle (I, J, xc, yc, r)
    ellipse (I, J, xc, yc, r, ratio, theta)
        box (I, J, x1, y1, x2, y2) 
  rectangle (I, J, xc, yc, r, ratio, theta)
     vector (I, J, x1, y1, x2, y2, width)
        pie (I, J, xc, yc, theta1, theta2)
    polygon (I, J, x1, y1, .., xn, yn)
       cols (I, ranges)
      lines (J, ranges)
   cannulus (I, J, xc, yc, r1, r2)
   eannulus (I, J, xc, yc, r1, r2, ratio, theta)
   rannulus (I, J, xc, yc, r1, r2, ratio, theta)
   pannulus (I, J, width, x1, y1, ..., xn, yn)

      xc,yc - center coordinates in pixels
      r1,r2 - semi-major axis lengths in pixels
      ratio - ratio of semi-minor / semi-major axes
   theta[n] - position angle in degrees
      x1,y1 - starting coordinates in pixels
      x2,y2 - ending coordinates in pixels
  x[n],y[n] - vertices of a polygon
     ranges - string defining a range, e.g. "100-200,300,400-500"
.fi

\fBThe Expression Database\fR

The \fImskexpr\fR expression database provides a macro facility which can be
used to create custom libraries of functions for specific applications. A
simple example follows.

.nf
        # Sample MSKEXPR expression database file.

        # Constants.
        SQRTOF2=        1.4142135623730950488
        PI=             3.1415926535897932385

        # Simple bad data functions.
	bdata1		(i < -100 || i > 25000)
	bdata2		(i < -100 || i > 32000)

	# New regions functions.
	cmpie(xc,yc,r,t1,t2) 	circle (xc, yc, r) && (! pie (xc, yc, t1, t2))
.fi

The complete syntax of a macro entry is as follows:

        <symbol>['(' arg-list ')'][':'|'=']     replacement-text

The replacement text may appear on the same line as the macro name or may
start on the next line, and may extend over multiple input lines if necessary.
If so, continuation lines must be indented.  The first line with no whitespace
at the beginning of the line terminates the macro. Macro functions may be
nested.  Macro functions are indistinguishable from intrinsic functions in
expressions.


.ih
EXAMPLES

1. Create a 0-valued 512 x 512 mask and set all the pixels inside a circular
annulus to 1.

.nf
cl> type regions.dat
cannulus 256. 256. 20. 40.
cl> mskregions regions.dat mask.pl ""
.fi

2. Repeat the previous example but set all the pixels outside the circular
annulus to 1. Note that in this case the user must use regions expression
syntax not region definition syntax

.nf
cl> type region.dat
! cannulus (256., 256., 20., 40.) 
cl> mskregions regions.dat mask.pl ""
.fi

3. Create a 0-valued 512 x 512 mask and set all the pixels inside the
intersection of 2 circles to 1. The & operator produces the same result
as &&.

.nf
cl> type regions.dat
circle (220., 220., 50.) && circle (240., 220., 50.) 
cl> mskexpr regions.dat mask.pl ""
.fi

4. Create a 0 valued 512 x 512 mask and set all the pixels inside a circle
excluding a wedge shaped region to 1. The expression cmpie is used defined
and stored in the expression database "myexpr.db" 

.nf
cl> type myexpr.db
# Sample MSKEXPR expression database file.

# Constants.
SQRTOF2=        1.4142135623730950488
PI=             3.1415926535897932385

# Simple bad data functions.
bdata1          (i < -100 || i > 25000)
bdata2          (i < -100 || i > 32000)

# New regions functions.
cmpie(xc,yc,r,t1,t2)    circle (xc, yc, r) && (! pie (xc, yc, t1, t2))

cl> type regions.dat
cmpie (256., 256., 50., 0., 30.) ? 1 : 0

cl> mskregions regions.dat mask.pl "" exprdb=myexpr.db
.fi

.ih
TIME REQUIREMENTS

.ih
BUGS

.ih
SEE ALSO
imexpr, mskexpr
.endhelp