Make join_segmentations return array maps from output to input labels

[aeisenbarth]

Description

This is an implementation for #6785.

It adds as optional return value two ArrayMaps which allow tracing the labels of the returned segmentation back to the labels of the two input segmentations.

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.

[aeisenbarth]

• In my original code, I used more expressive names also for s1, j etc. I can changed variable names if desired.
• I would also add type hints (although the existing code didn't have).

[jni]

@aeisenbarth very cool!

In the long term for scikit-image, we are moving away from return_something= arguments that change the return type, because they make typing very awkward. However, since we haven't quite decided yet what we'll replace it with 😅, I'm personally in favour of merging this. It's a very nice addition. I have left a couple of suggestions, but otherwise I'll approve once fixed. Thanks!!!

[aeisenbarth]

Shall I also add type hints? (I don't know whether scikit-image has any constraints on compatibility with older Python syntax).
Does scikit-image have any preferred array type hints?

Something like this should correctly describe the optional return values:

@overload
def join_segmentations(
    s1: np.ndarray, s2: np.ndarray, return_mapping: Literal[False] = False
) -> np.ndarray:
    ...


@overload
def join_segmentations(
    s1: np.ndarray, s2: np.ndarray, return_mapping: Literal[True]
) -> Tuple[np.ndarray, ArrayMap, ArrayMap]:
    ...


def join_segmentations(
    s1: np.ndarray, s2: np.ndarray, return_mapping: bool = False
) -> Union[np.ndarray, Tuple[np.ndarray, ArrayMap, ArrayMap]]:

[lagru]

Although, long-term type hints are the direction we want to go, right now they wouldn't be consistent with the rest of the library. So I'd say we don't need to add them in this PR.

Thanks for introducing me to the overload decorator! 😊 That could be quite useful down the line.

[jni]

Shall we merge this then? =)

[lagru]

Shall we merge this then? =)

Happy to. Just didn't get around to review this yet...

[jni]

@lagru you're a busy man right now so I decided to save you some trouble 😂