BUGS · SEE_ALSO
mskexpr -- General mask expression evaluator
mskexpr expr masks refimages
- 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.
- 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.
- 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>".
- 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>".
- dims = "512,512"
- The default output mask dimensions. The value of dims is a comma delimited list of dimensions.
- depth = 0
- The output mask depth in bits. The maximum depth and current default is 27.
- 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.
- verbose = yes
- Print task status messages ?
Mskexpr evaluates a mask expression expr and writes the results to an output mask masks 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 refimages if any, the reference masks refmasks if any, or the values of the dims 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 depth 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.
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:
i reference image i.itime reference image keyword m reference mask m.itime reference mask keyword 1.2345 numeric constant
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".
I x coordinate of pixel (column) J y coordinate of pixel (line) K z coordinate of pixel (band)
The expression syntax implemented by mskexpr provides the following set of operators:
( 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
The conditional expression has the value expr1 if expr is true, and expr2 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.
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, 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"
Where it makes sense all intrinsic functions support all datatypes, with some restrictions on bool and char . 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 lines 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
abs (arg) absolute value max (arg, 0.0, ...) maximum value min (arg1, arg2, ...) minimum value mod (arg1, arg2) modulus sqrt (arg) square root
Mathematical or trigonometric functions
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
The trigonometric functions operate in units of radians. The deg and rad intrinsic functions (see below) can be used to convert to and from degrees if desired.
Type conversion functions
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
The numeric type conversion functions will convert a string to a number if called with a character argument. The str function will convert any number to a string.
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
The projection functions take a vector as input and return a scalar value as output. The functions mean and stddev , 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.
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
The median function shown here computes the vector median of several input vectors, unlike the projection median which computes the median value of a vector sample. sort sorts a vector, returning the sorted vector as output (this can be useful for studying the statistics of a sample). shift 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 repl (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.
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.
1. Create a 0-valued 512 x 512 mask and set all the pixels inside a circular annulus to 1.
cl> type expr.dat cannulus (256., 256., 20., 40.) ? 1 : 0 cl> mskexpr @expr.dat mask.pl ""
2. Repeat the previous example but set all the pixels outside the circular annulus to 1.
cl> type expr.dat ! cannulus (256., 256., 20., 40.) ? 1 : 0 cl> mskexpr @expr.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.
cl> type expr.dat circle (220., 220., 50.) && circle (240., 220., 50.) ? 1 : 0 cl> mskexpr @expr.dat mask.pl ""
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.
cl> type expr.dat i < 0 || i > 10000 || circle (256., 256., 50.) ? 1 : 0 cl> mskexpr @expr.dat mask.pl dev$pix
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"
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