20.5 Binary morphology

(`generate_binary_structure``rank, connectivity`)-
The
`generate_binary_structure`functions generates a binary structuring element for use in binary morphology operations. The`rank`of the structure must be provided. The size of the structure that is returned is equal to three in each direction. The value of each element is equal to one if the square of the Euclidean distance from the element to the center is less or equal to`connectivity`. For instance, two dimensional 4-connected and 8-connected structures are generated as follows:>>> print generate_binary_structure(2, 1) [[0 1 0] [1 1 1] [0 1 0]] >>> print generate_binary_structure(2, 2) [[1 1 1] [1 1 1] [1 1 1]]

Most binary morphology functions can be expressed in terms of the basic operations erosion and dilation:

(`binary_erosion``input, structure=None, iterations=1, mask=None, output=None, border_value=0, origin=0`)- The
`binary_erosion`function implements binary erosion of arrays of arbitrary rank with the given structuring element. The origin parameter controls the placement of the structuring element as described in section 20.2. If no structuring element is provided, an element with connectivity equal to one is generated using`generate_binary_structure`. The`border_value`parameter gives the value of the array outside boundaries. The erosion is repeated`iterations`times. If`iterations`is less than one, the erosion is repeated until the result does not change anymore. If a`mask`array is given, only those elements with a true value at the corresponding mask element are modified at each iteration.

(`binary_dilation``input, structure=None, iterations=1, mask=None, output=None, border_value=0, origin=0`)- The
`binary_dilation`function implements binary dilation of arrays of arbitrary rank with the given structuring element. The origin parameter controls the placement of the structuring element as described in section 20.2. If no structuring element is provided, an element with connectivity equal to one is generated using`generate_binary_structure`. The`border_value`parameter gives the value of the array outside boundaries. The dilation is repeated`iterations`times. If`iterations`is less than one, the dilation is repeated until the result does not change anymore. If a`mask`array is given, only those elements with a true value at the corresponding mask element are modified at each iteration.Here is an example of using

`binary_dilation`to find all elements that touch the border, by repeatedly dilating an empty array from the border using the data array as the mask:>>> struct = array([[0, 1, 0], [1, 1, 1], [0, 1, 0]]) >>> a = array([[1,0,0,0,0], [1,1,0,1,0], [0,0,1,1,0], [0,0,0,0,0]]) >>> print a [[1 0 0 0 0] [1 1 0 1 0] [0 0 1 1 0] [0 0 0 0 0]] >>> print binary_dilation(zeros(a.shape), struct, -1, a, border_value=1) [[1 0 0 0 0] [1 1 0 0 0] [0 0 0 0 0] [0 0 0 0 0]]

The `binary_erosion` and `binary_dilation` functions both
have an `iterations` parameter which allows the erosion or dilation to
be repeated a number of times. Repeating an erosion of a dilation with a
given structure `n` times is equivalent to an erosion or a
dilation with a structure that is `n-1` times dilated with itself.
For a low number of iterations this is more efficient, and for this reason
a function is provided that allows the calculation of a structure that is
dilated a number of times with itself:

(`iterate_structure``structure, iterations, origin=None`)-
The
`iterate_structure`function returns a structure by dilation of the input structure`iteration`- 1 times with itself. For instance:If the origin of the original structure is equal to 0, then it is also equal to 0 for the iterated structure. If not, the origin must also be adapted if the equivalent of the>>> struct = generate_binary_structure(2, 1) >>> print struct [[0 1 0] [1 1 1] [0 1 0]] >>> print iterate_structure(struct, 2) [[0 0 1 0 0] [0 1 1 1 0] [1 1 1 1 1] [0 1 1 1 0] [0 0 1 0 0]]

`iterations`erosions or dilations must be achieved with the iterated structure. The adapted origin is simply obtained by multiplying with the number of iterations. For convenience the`iterate_structure`also returns the adapted origin if the`origin`parameter is not`None`:>>> print iterate_structure(struct, 2, -1) (array([[0, 0, 1, 0, 0], [0, 1, 1, 1, 0], [1, 1, 1, 1, 1], [0, 1, 1, 1, 0], [0, 0, 1, 0, 0]], type=Bool), [-2, -2])

Other morphology operations can be defined in terms of erosion and d dilation. Following functions provide a few of these operations for convenience:

(`binary_opening``input, structure=None, iterations=1, output=None, origin=0`)- The
`binary_opening`function implements binary opening of arrays of arbitrary rank with the given structuring element. Binary opening is equivalent to a binary erosion followed by a binary dilation with the same structuring element. The origin parameter controls the placement of the structuring element as described in section 20.2. If no structuring element is provided, an element with connectivity equal to one is generated using`generate_binary_structure`. The`iterations`parameter gives the number of erosions that is performed followed by the same number of dilations.

(`binary_closing``input, structure=None, iterations=1, output=None, origin=0`)- The
`binary_closing`function implements binary closing of arrays of arbitrary rank with the given structuring element. Binary closing is equivalent to a binary dilation followed by a binary erosion with the same structuring element. The origin parameter controls the placement of the structuring element as described in section 20.2. If no structuring element is provided, an element with connectivity equal to one is generated using`generate_binary_structure`. The`iterations`parameter gives the number of dilations that is performed followed by the same number of erosions.

(`binary_hit_or_miss``input, structure1=None, structure2=None, output=None, origin1=0, origin2=None`)- The
`binary_hit_or_miss`function implements a binary hit-or-miss transform of arrays of arbitrary rank with the given structuring elements. The hit-or-miss transform is calculated by erosion of the input with the first structure, erosion of the logical*not*of the input with the second structure, followed by the logical*and*of these two erosions. The origin parameters control the placement of the structuring elements as described in section 20.2. If`origin2`equals`None`it is set equal to the`origin1`parameter. If the first structuring element is not provided, a structuring element with connectivity equal to one is generated using`generate_binary_structure`, if`structure2`is not provided, it is set equal to the logical*not*of`structure1`.

Send comments to the NumArray community.