mskregions: Create or modify masks using regions lists

Package: proto

Usage

mskregions regions masks refimages

Parameters

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.)".
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.
refimages
The optional list of reference images. If the reference image list is defined there must be one reference image for every output mask.
dims = "512,512"
The default output mask dimensions. The value of dims is a comma delimited list of dimensions.
depth = 0
The default output mask depth in bits currently 27.
regnumber = "constant"
The region definition scheme. The options are:
constant
Assign all the mask regions the value of regval.
number
Assign each region a sequential value beginning with regval.
regval = 1
The starting mask region value.
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.
append = no
Add the region list to an existing mask ?
verbose = yes
Print task status messages ?

Description

Mskregions reads a list of region specifications from the input files regions and writes the results to the output masks masks 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 refimages if any refmasks if any or the values in the dims 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 regions are determined by the regnumber and regval parameters. By default all new regions are assigned the value of 1. The depth of the output mask in bits is defined by the depth 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.

Regions Definitions

The following region definitions are supported. 

    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

Operands Used in Region Expressions

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". 

I                x coordinate of pixel (column)
J                y coordinate of pixel (line)
K                z coordinate of pixel (band)

Operators Used in Region Expressions

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

( expr )                grouping
&&                      logical and
||                      logical or
!                       logical not

Functions Used in Region Expressions

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. 

    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"

The Expression Database

The mskexpr expression database provides a macro facility which can be used to create custom libraries of functions for specific applications. A simple example follows. 

# 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))

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.

Examples

1. Create a 0-valued 512 x 512 mask and set all the pixels inside a circular annulus to 1. 

cl> type regions.dat
cannulus 256. 256. 20. 40.
cl> mskregions regions.dat mask.pl ""

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 

cl> type region.dat
! cannulus (256., 256., 20., 40.)
cl> mskregions regions.dat mask.pl ""

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 &&. 

cl> type regions.dat
circle (220., 220., 50.) && circle (240., 220., 50.)
cl> mskexpr regions.dat mask.pl ""

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" 

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

Time requirements

Bugs

See also

imexpr, mskexpr