15.5.8 area

area, bitmap [, seed=seed, numbers=numbers, diagonal=diagonal]

area, bitmap identifies all disjoint areas in long array bitmap (of arbitrary dimensions) which have elements with value one. Elements with values equal to zero or greater than one 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.

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 area is called with bitmap a two-dimensional long array and with no other arguments, then a special-purpose version of the routine is called which is optimized for this case for speed. Otherwise, a more versatile but somewhat slower version is used.

On an SGI R5000 (200 MHz) running Irix, for 2D data, the special-purpose version takes about 0.14 microseconds (27 CPU cycles) per data element, and the general version about 0.15 microseconds (30 CPU cycles) per data element. If the special-purpose version cannot be speeded up more, then it may be discarded.

See also: area2, segment, areaconnect, Topology