.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: ['(' 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