15.5.9 area2

area2, bitmap, data [, seed=seeds, numbers=numbers, diagonal=diagonal, sign=sign]

area2, bitmap, data identifies all disjoint areas in long array bitmap (of arbitrary dimensions) which have elements with value one, guided by the data values in numerical array data, which must have one element for each element of bitmap. Elements with values equal to zero or greater than one in bitmap are disregarded. Negative values are used internally to indicate intermediate processing states, so these must not be present in bitmap! The identified areas in bitmap are filled with a number which uniquely label them.

Those elements of bitmap with values equal to 1 are assigned to the same area that (1) share a vertex or face, according to diagonal (see below), and (2) are linked to the same local appropriate extreme through steepest-gradient paths. If sign is specified and negative, then links to local minima are sought, otherwise to local maxima. The second criterion ensures that any given area contains at most one local extreme of the desired kind.

If seed is specified, then it is assumed to contain indices to bitmap at which areas are to be sought. In that case, only the areas found at those positions are identified.

If number is specified, then it is assumed to contain area numbers to assign to the areas found at the corresponding positions from seed. number must have either one element or the same number as seed. In the former case, area numbers are incremented by one, starting at the value of number. If no number is specified, then assigned area numbers start at 2.

If diagonal is specified, then it must have one element per data dimension and is taken as instructions on which nearest-neighbor connections to recognize. A 2 means that nearest neighbors with their bitmap values equal to 1 are assigned to the same area if they share any face or vertex in the corresponding dimension. A 1 means that such neighbors are assigned to the same area only if they share a face in the corresponding dimension. A 0 means that connections in the corresponding dimension are ignored. If diagonal is not specified, then code 2 is assumed for all dimensions.

For example, if diagonal is equal to [2, 2, 0], then no connections in the third dimension are recognized, and the data is treated as a set of unconnected two-dimensional images (but no area in any of these images shares its area number with any area in any of the other images). Within each of the images, connections in all four directions (N-S, E-W, NE-SW, NW-SE) are recognized in this case. If diagonal is equal to [1, 1, 0], then only directions in the orthogonal directions (N-S, E-W) are recognized. Likewise for [2, 1, 0], because even though the first dimension allowes vertices, the second one only accepts faces.

If bitmap is a 2D array, and no seed, numbers, or diagonal is specified, then a special-purpose version optimized for speed is used. Otherwise, a more general-purpose version is used. On an sgi r5000 (200 MHz) running Irix, for 2D data, the special-purpose version takes about 0.11 microseconds (23 cpu cycles) per data element, and the general-purpose version about 0.12 microseconds (24 cpu cycles).

See also: area, segment, areaconnect, Topology