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

.help mskexpr Dec01 proto
.ih
NAME
mskexpr -- General mask expression evaluator
.ih
USAGE
mskexpr expr masks refimages
.ih
PARAMETERS
.ls expr
The expression to be evaluated.  This may be the actual expression, or the
string "@file" in which case the expression is taken from the named file.
.le
.ls masks
The output masks. The size of the output masks defaults to the size of
the reference image if any, the size of the reference mask if any, or the
value of the dims parameter, in that order.
.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. The reference image
operand name is "i" and the associated reference image keywords are
referred to as "i.<keyword>".
.le
.ls refmasks
The optional list of reference masks. If the reference mask list is defined
there must be one reference mask for every output mask. The reference mask
operand name is "m" and the associated reference image keywords are
referred to as "m.<keyword>".

If both a reference image and reference mask are defined the reference mask will
be matched to reference image as described by the help topic \fBpmmatch\fR.
The application default is a match in "logical" coordinates which is
effectively a trim or pad operation to match the size of the reference image.
However, by use of the "pmmatch" environment variable one may match in
"physcial" or "world" coordinates.  Note that the simple expression
"m" may be used to create an output mask file from the internal matching.
.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 output mask depth in bits. The maximum depth and current default is
27.
.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 verbose = yes
Print task status messages ?
.le

.ih
DESCRIPTION

Mskexpr evaluates a mask expression \fIexpr\fR and writes the results to an
output mask \fImasks\fR image. If expr is preceded by an "@" sign then
the expression is read from the named file.  The size of the output mask is
determined by the reference image \fIrefimages\fR if any, the reference masks
\fIrefmasks\fR if any, or the values of the \fIdims\fR parameter, in that
order of precedence.

The output mask is an integer image. Therefore any mask expression must
evaluate to an integer value. The depth of the output mask in bits is defined
by the \fIdepth\fR parameter. The default value is 27 bits.

Evaluation of the mask expression is carried out one line at a time. This
is efficient and permits operations on masks with large reference images
to be carried out efficiently without using excessive memory. The entire
expression is evaluated once per line of the output mask.

\fBReference Images and Masks\fR

In most cases one wants to make output masks to associate with images.
The reference image list provides a reference image which is used to
define the size and some of the header for the output mask.  Note that
a reference mask may be used for this purpose if no reference image
is specified.

Sometimes one may want to merge previous mask information into the output
mask.  The reference mask can be used for this purpose using the operand
"m" in the expressions.

When both a reference image and a reference mask are specified another
useful feature is provided.  This consists of matching the reference
mask to the reference image even when the two are of different sizes or
are related not "pixel-by-pixel" but through various transformations.
The matching feature is described in the help topic \fBpmmatch\fR.
(Note that the default for matching in world coordinates results in
boolean mask values so if the actual mask values are needed the pmmatch
setting must be set appropriately.)  The application default is a match
in "logical" coordinates which is effectively a trim or pad operation to
match the size of the reference image.  However, by use of the "pmmatch"
environment variable one may match in "physcial" or "world" coordinates.

This task is one way to create a matched mask for tasks that do not
do the matching.  The simple expression "m" when both a reference image
and reference mask are specified will output a mask from for the reference
image that is match in logical pixel space.

\fBOperands\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.

The following operands are recognized:

.nf
	i		reference image 
	i.itime		reference image keyword
	m		reference mask 
	m.itime		reference mask keyword
	1.2345		numeric constant
.fi

Finally, 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\fR

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

.nf
        ( expr )                grouping
        + - * /                 arithmetic
        **                      exponentiation
        //                      concatenate
        expr ? expr1 : expr2    conditional expression
        @ "name"                get operand

        &&                      logical and
        ||                      logical or
        !                       logical not
        <                       less than
        <=                      less than or equal
        >                       greater than
        >=                      greater than or equal
        ==                      equals
        !=                      not equals
        ?=                      substring equals

        &                       bitwise and
        |                       bitwise or
        ^                       bitwise exclusive or
        ~                       bitwise not
.fi

The conditional expression has the value \fIexpr1\fR if \fIexpr\fR is true,
and \fIexpr2\fR otherwise.  Since the expression is evaluated at every pixel
this permits pixel-dependent operations such as checking for special pixel
values, or selection of elements from either of two vectors.  For example,
the command

        (i > -10 && i < 32000) ? 0 : 1

has the constant value 0 if the reference image is greater than -10 and less
than 32000, and 1 otherwise. Conditional expressions are general expressions
and may be nested or used anywhere an expression is permitted.

The concatenation operator applies to all types of data, not just strings.
Concatenating two vectors results in a vector the combined length of the
two input vectors.

The substring equals operator "?=", used for string comparisons,  is like
"==" but checks for the presence of a substring, rather than exact equality
of the two strings.

\fBRegion Functions\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, 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)

      point (I, J, x1, y1)
     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

\fBOther Functions\fR

Where it makes sense all intrinsic functions support all datatypes, with
some restrictions on \fIbool\fR and \fIchar\fR.  Arguments may be scalars or
vectors. Scalar and vector arguments may be mixed in the same function
call.  Arguments are automatically type converted upon input as necessary.
Some functions support a variable number of arguments and the details of
the the operation to be performed may depend upon how many arguments are
given.

Functions which operate upon vectors are applied to the \fIlines\fR of an
image.  When applied to an image of dimension two or greater, these
functions are evaluated separately for every line of the multidimensional
image.

Standard Intrinsic Functions

.nf
        abs (arg)                       absolute value
        max (arg, 0.0, ...)             maximum value
        min (arg1, arg2, ...)           minimum value
        mod (arg1, arg2)                modulus
       sqrt (arg)                       square root
.fi

Mathematical or trigonometric functions

.nf
       acos (arg)                         arc cosine
       asin (arg)                         arc sine
       atan (arg [,arg2])                 arc tangent
      atan2 (arg [,arg2])                 arc tangent
        cos (arg)                         cosine
       cosh (arg)                         hyperbolic cosine
        exp (arg)                         exponential
        log (arg)                         natural logarithm
      log10 (arg)                         logarithm base 10
        sin (arg)                         sine
       sinh (arg)                         hyperbolic sine
        tan (arg)                         tangent
       tanh (arg)                         hyperbolic tangent
.fi

The trigonometric functions operate in units of radians.  The \fIdeg\fR and
\fIrad\fR intrinsic functions (see below) can be used to convert to and from
degrees if desired.

Type conversion functions

.nf
       bool (arg)                         coerce to boolean
      short (arg)                         coerce to short
        int (arg)                         truncate to integer
       nint (arg)                         nearest integer
       long (arg)                         coerce to long (same as int)
       real (arg)                         coerce to real
     double (arg)                         coerce to double
        str (arg)                         coerce to string
.fi

The numeric type conversion functions will convert a string to a number if
called with a character argument.  The \fIstr\fR function will convert any
number to a string.

Projection functions

.nf
        len (arg)                         length of a vector
        hiv (arg)                         high value of a vector
        lov (arg)                         low value of a vector
       mean (arg [,ksigma])               mean of a vector
     median (arg)                         median of a vector
     stddev (arg [, ksigma])              standard deviation
        sum (arg)                         sum of a vector
.fi

The projection functions take a vector as input and return a scalar value as
output.  The functions \fImean\fR and \fIstddev\fR, used to compute the mean
and standard deviation of a vector, allow an optional second argument which
if given causes a K-sigma rejection to be performed.

Miscellaneous functions

.nf
        deg (arg)                         radians to degrees
        rad (arg)                         degrees to radians
     median (arg1, arg2, arg3, ...)       vector median of 3-5 vectors
       repl (arg, n)                      replicate
       sort (arg)                         sort a vector
      shift (arg, npix)                   shift a vector
.fi

The \fImedian\fR function shown here computes the vector median of several
input vectors, unlike the projection median which computes the median value
of a vector sample.  \fIsort\fR sorts a vector, returning the sorted vector
as output (this can be useful for studying the statistics of a sample).
\fIshift\fR applies an integral pixel shift to a vector, wrapping around at
the endpoints.  A positive shift shifts data features to the right (higher
indices).

The \fIrepl\fR (replicate) function replicates a data element, returning a
vector of length (n * len(a)) as output.  For example, this can be used to
create a dummy data array or image by replicating a constant value.

\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 expr.dat
cannulus (256., 256., 20., 40.) ? 1 : 0 
cl> mskexpr @expr.dat mask.pl ""
.fi

2. Repeat the previous example but set all the pixels outside the circular
annulus to 1.

.nf
cl> type expr.dat
! cannulus (256., 256., 20., 40.) ? 1 : 0 
cl> mskexpr @expr.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.

.nf
cl> type expr.dat
circle (220., 220., 50.) && circle (240., 220., 50.) ? 1 : 0 
cl> mskexpr @expr.dat mask.pl ""
.fi

4. Create a 0 valued mask and set all the pixels outside the good
data range 0 <= pixval <= 10000 in the reference image and outside
a circle to 1. Note that the i character defines the reference image
operand.

.nf
cl> type expr.dat
i < 0 || i > 10000 || circle (256., 256., 50.) ? 1 : 0 
cl> mskexpr @expr.dat mask.pl dev$pix
.fi

5. 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 expr.dat
cmpie (256., 256., 50., 0., 30.) ? 1 : 0

cl> mskexpr @expr.dat mask.pl "" exprdb=myexpr.db
.fi

6.  A set of dithered images have been transformed to a common world
coordinate system, stacked, and a mask created for the sources.  To
create a boolean mask for one of the images from the deep source mask:

.nf
cl> set pmmatch="world"
cl> mskexpr "m" mask1.pl exp1 refmask=stackmask
.fi


.ih
TIME REQUIREMENTS

.ih
BUGS

.ih
SEE ALSO
imexpr, mskregions, pmmatch
.endhelp