Description

This PR affects skimage/morphology/gray.py:

• Fixes the opening and closing to be correct (Morphological closing and opening are incorrect #6676).
• Makes the dilation mirror the footprint.
• Deprecates the shift_x and shift_y parameters, in favour of the new mirror parameter (see below).
• Makes erosion, dilation, opening and closing, with default parameters and a binary input image, identical to the equivalent binary_... functions.
• Simplifies the code for white_tophat, and complicates the code for black_tophat so that it matches white_tophat. Both now special-case for out is image.
• Adds mode and cval parameters, with the special option None that sets the pixels outside the image to the max value for the image's dtype in the erosion, and to the min in the dilation. This causes the pixels outside the image to be ignored in these operations. The default boundary condition is 'reflect', as it was before (because that is the default in ndimage), but that condition causes surprising results if the footprint is not simple. Adding mode=None is recommended in these cases. (Dilation and erosion image boundary extension #6665).
• Adds a border_value parameter to binary_erosion and binary_dilation, they might come in handy (in binary.py).
• Adds a mirror parameter to erosion, dilation, binary_erosion and binary_dilation, setting it to True will mirror the footprint. For binary_dilation it is True by default, to match previous behavior. This is necessary to build the opening and closing correctly (in gray.py and binary.py). For skimage 2.0 I would suggest setting the default mirror to the same value for the gray-value and binary versions of the same operator.
• Adds functions skimage.morphology.pad_footprint and skimage.morphology.mirror_footprint (in footprints.py). pad_footprint is used so that mirror_footprint works correctly for even-sized footprints, and to be able to keep things consistent with previous behavior. Note that the binary dilation and erosion pad on the left, and the gray-value ones on the right. This is the reason that we can't make these operators equivalent without breaking changes. For skimage 2.0 I would suggest making this padding consistent between the two versions.

This PR closes #6665 and addresses #6676 -- it was a lot easier fixing both at the same time.

This PR causes changes to the output for the opening, closing, and tophat if the footprint is not mirror symmetric (e.g. if it's even in size). This is because the output was incorrect for these cases previously, see #6676.

@stefanv and @lagru: Thank you for your help with this.

Test failure

The CI test failed on GitHub. It ran OK on my machine only if I changed the line

expected = dict(np.load(fetch('data/gray_morph_output.npz')))

to not use fetch, and to have the absolute path to the file (which has changed). I think this fetch function is broken, it reads the file from elsewhere, not from the cloned repository. Note that I needed to change this file because the opening, closing, and tophat functions have been fixed.

Checklist

• Docstrings for all functions
• Gallery example in ./doc/examples (new features only)
• Benchmark in ./benchmarks, if your changes aren't covered by an
  existing benchmark
• Unit tests
• Clean style in the spirit of PEP8
• Descriptive commit messages (see below)

For reviewers

• Check that the PR title is short, concise, and will make sense 1 year
  later.
• Check that new functions are imported in corresponding __init__.py.
• Check that new features, API changes, and deprecations are mentioned in
  doc/release/release_dev.rst.
• There is a bot to help automate backporting a PR to an older branch. For
  example, to backport to v0.19.x after merging, add the following in a PR
  comment: @meeseeksdev backport to v0.19.x
• To run benchmarks on a PR, add the run-benchmark label. To rerun, the label
  can be removed and then added again. The benchmark output can be checked in
  the "Actions" tab.

Release note

Summarize the introduced changes in the code block below in one or a few sentences. The
summary will be included in the next release notes automatically:

{label="New Feature, Highlight"} Add parameters `mode` and `cval` to `erosion`, `dilation`,
`opening`, `closing`, `white_tophat`, and `black_tophat` in
`skimage.morphology`. These new parameters determine how array borders are
handled.

{label="New Feature, Highlight"} Add parameter `mode` to `binary_erosion`, `binary_dilation`,
`binary_opening` and `binary_closing` in `skimage.morphology`. These new
parameters determine how array borders are handled.

{label="New Feature"} Add functions `mirror_footprint` and `pad_footprint` to
`skimage.morphology`.

{label="Bug fix, Highlight"} Ensure `skimage.morphology.closing` and `skimage.morphology.opening`
are extensive and anti-extensive, respectively, if the footprint is not mirror
symmetric.

{label="API"} Parameters `shift_x` and `shift_y` in `skimage.morphology.erosion`
and `skimage.morphology.dilation` are deprecated.
Use `pad_footprint` or modify the footprint manually instead.