Repatch (from linux) of OSX IRAF

1 files changed, 454 insertions, 0 deletions

diff --git a/pkg/proto/doc/mskexpr.hlp b/pkg/proto/doc/mskexpr.hlp
new file mode 100644
index 00000000..9209b625
--- /dev/null
+++ b/pkg/proto/doc/mskexpr.hlp
@@ -0,0 +1,454 @@
+.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