diff options
Diffstat (limited to 'pkg/proto/doc/mskregions.hlp')
| -rw-r--r-- | pkg/proto/doc/mskregions.hlp | 279 |
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 |