image.calcmask - Function

Image mask calculator

Synopsis
calcmask(mask, name, default)

Arguments

mask	in	Boolean LEL expression
		Allowed:	Boolean LEL expression or mask region
name	in	Mask name
		Allowed:	String
		Default:	Auto new name
default	in	Make specified mask the default mask ?
		Allowed:	Bool
		Default:	T

Returns
T or fail

Description

This function is used to create a new pixel mask via a Boolean LEL expression. This gives you much more scope than the simple set and putregion functions.

See note 223 which describes the the syntax and functionality of LEL in detail.

If the expression is not a scalar, the shapes and coordinates of the image and expression must conform. If the expression is a scalar then the entire pixel mask will be set to that value.

By default (argument name) the name of a new pixel mask is made up for you. However, you specify a pixel mask name (use function summary or maskhandler to see the mask names) then it is used. If the pixel mask already exists, it is overwritten.

You can specify whether the new pixel mask should be the default mask or not. By default, it is made the default pixel mask !

Example

 
- im.calcmask(T)                  # Automatically converted to a string
- im.calcmask('zz>0')             # Mask of zz ignored
- im.calcmask('mask(zz) && zz>0') # Mask of zz included
- im.calcmask('$im>min($im)')     # Use tool names
- im.calcmask('zz>min(zz:nomask)')  # Mask of zz not used in scalar function

The first example is the equivalent of im.set(pixelmask=T). It sets the entire mask to True.

The second example creates a new pixel mask which is True when the pixel values in image zz are greater than 0.

Now for some subtlety. Read carefully ! Any LEL expression can be thought of as having a value and a mask. Usually the value is Float and the mask Boolean. In this case, because the expression is Boolean itself, the value is also Boolean. The expression mask would just be the mask of zz. Now what calcmask does is create a mask from the expression value (which is Boolean) and discards the expression mask. Therefore, the resulting mask is independent of any mask that zz might have.

If you wish the mask of the expression be honoured as well, then you can do as in the third example. It says the output pixel mask will be True if the current pixel mask of zz is True and the expression value is True.

The fourth example is like the second, except that we use the pixel values associated with the im Image tool itself rather than using its disk name (the Image tool might be virtual so there might not be a disk file). Note one further subtlety here. When the scalar function min evaluates a value from $im, the default mask of $im will be used. All the scalar functions look at the mask. If you didn't want the mask to be used you can use the special :nomask syntax shown in the final example.

Next: image.close - Function Up: image - Tool Previous: image.calc - Function Contents Index

	Package	general
	Module	images
	Tool	image