Repatch (from linux) of OSX IRAF

1 files changed, 279 insertions, 0 deletions

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