The IDLanROI::ComputeMask function method prepares a two-dimensional mask for the region.

Syntax

Result = Obj->[IDLanROI::]ComputeMask( [, INITIALIZE={ –1 | 0 | 1 }] [, DIMENSIONS=[xdim, ydim]] | [, MASK_IN=array] [, LOCATION=[x, y [, z]]] [, MASK_RULE={ 0 | 1 | 2 }] [, PIXEL_CENTER=[x, y]] [, PLANE_NORMAL=[x, y, z]] [, PLANE_XAXIS=[x,y,z]] [, /RUN_LENGTH] )

Return Value

Result

The return value is a two-dimensional array of bytes whose values range from 0 to 255. The mask is computed by applying the following formula to the current mask for each mask point contained within the ROI:

Mout = MAX(MIN(255, (Mroi*Ext) + Min), 0)

where Mroi is 255 and Ext is 1 for points within an exterior region and –1 for points within an interior region.

If the TYPE of the region is 0 (points), a single mask pixel is set for each region vertex that falls within the bounds of the mask.

If the TYPE of the region is 1 (path), one-pixel-wide line segments are set within the mask.

If the TYPE of the region is 2 (closed polygon), a mask pixel is set if that pixel is on the plane of a region, and the pixel falls within the region (according to the MASK_RULE).

Arguments

None.

Keywords

DIMENSIONS

Set this keyword to a two-element vector, [xdim, ydim], specifying the requested dimensions of the returned mask. If MASK_IN is provided, the value of this keyword is ignored and the dimensions of that mask are used. Otherwise, the default dimensions are [100, 100].

INITIALIZE

Set this keyword to indicate how the mask should be initialized. Valid values include:

  • –1 = The mask is not initialized. This option is useful when updating an already existing mask. This is the default if the MASK_IN keyword is set.
  • 0 = The mask is initialized so that each pixel is set to 0. This is the default if the MASK_IN keyword is not set.
  • 1 = The mask is initialized so that each pixel is set to 255.

LOCATION

Set this keyword to a vector of the form [X, Y[, Z]] specifying the location of the origin of the mask. The default is [0, 0, 0]. IDL converts and maintains this value in double-precision floating-point.

MASK_IN

Set this keyword to a two-dimensional array representing a mask that is already allocated and to be updated for this region. If the variable specified by this keyword is of type BYTE and is also specified as the function result, then this method updates the mask data in-place without copying. If this keyword is not provided, a mask is allocated by default to match the dimensions specified via the DIMENSIONS keyword.

MASK_RULE

Set this keyword to an integer specifying the rule used to determine whether a given pixel should be set within the mask. Valid values include:

  • 0 = Boundary only. All pixels falling on a region’s boundary are set.
  • 1 = Interior only. All pixels falling within the region’s boundary, but not on the boundary, are set.
  • 2 = Boundary + Interior. All pixels falling on or within a region’s boundary are set. This is the default.

PIXEL_CENTER

Set this keyword to a 2-element vector, [x, y], to indicate where the lower-left mask pixel is centered relative to a Cartesian grid. The default value is [0.0, 0.0], indicating that the lower-left pixel is centered at [0.0, 0.0].

PLANE_NORMAL

Set this keyword to a three-element vector, [x, y, z], specifying the normal vector for the plane on which the mask is to be computed. The default is [0, 0, 1].

PLANE_XAXIS

Set this keyword to a three-element vector, [x, y, z], specifying the direction vector along which each row of mask pixels is to be computed (starting at LOCATION). The default is [1, 0, 0].

RUN_LENGTH

Set this keyword to a non-zero value to return a run-length encoded representation of the mask, stored in a one-dimensional unsigned long array. When run-length encoded, each element with an even subscript contains the length of the run, and the following element contains the starting index of the run.

Examples

See "Creating and Displaying an ROI Mask" (Chapter 6, Image Processing in IDL in the help/pdf directory of your IDL installation).

Version History

5.3

Introduced

5.6

Added RUN_LENGTH keyword