The IDLanROIGroup::ComputeMask function method prepares a two-dimensional mask for this group of regions.

Syntax

Result = Obj->[IDLanROIGroup::]ComputeMask( [, INITIALIZE={ ‑1 | 0 | 1 }] [, DIMENSIONS=[xdim, ydim]] | [, MASK_IN=array] [, LOCATION=[x, y [, z]]] [, MASK_RULE={ 0 | 1 | 2 }] [, 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(0, (Mroi*Ext) + Min), 255)

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 contained regions 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 contained regions is 1 (path), each pixel along the paths of the regions is set if it falls 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 contained region, and the pixel falls within that 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; the default if the MASK_IN keyword is set. This option is useful when updating an already existing mask.
  • 0 = The mask is initialized with each pixel set to 0; the default if the MASK_IN keyword is not set.
  • 1 = The mask is initialized with each pixel 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].

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.

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.

Version History

5.3

Introduced

5.6

Added RUN_LENGTH keyword