Add setting to allow labels to be dropped from input maps

[tkkuehn]

Proposed changes

Overlay exceptions' behaviour was kind of ambiguous, so this clarifies it and adds the option to drop labels from either input map. Now overlay exceptions are overwritten by base labels, base exceptions overwrite everything else, and base/overlay drops are just removed entirely.

Types of changes

What types of changes does your code introduce? Put an x in the boxes that apply

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionalitiy)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Other (if none of the other choices apply)

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you are unsure about any of the choices, don't hesitate to ask!

• Changes have been tested to ensure that fix is effective or that a feature works.
• Changes pass the unit tests
• Code has been run through the poe quality task
• I have included necessary documentation or comments (as necessary)
• Any dependent changes have been merged and published

Notes

All PRs will undergo the unit testing before being reviewed. You may be requested to explain or make additional changes before the PR is accepted.

[kaitj]

I have some minor concerns with how merge_labels works now if I understand it correctly, stemming from some original discussions about dropping vs overwriting labels, but I think those can be fixed down the line and not necessarily needed for this PR.

[kaitj]

Could you just walk me through this? From what I gather, we are adding (in order):

overlay exceptions -> base inclusions -> overlay inclusions -> base exceptions?

I am guessing this results in some overwriting of the existing labels?

[tkkuehn]

Sure:
split_labels considers each unique label found in a label map. If that label is in the list of drops, it is ignored. If that label is in the list of exclusions, it's split into a dataset that contains all the exclusion masks. Otherwise, it's split into a dataset that contains all the "regular" masks. (If there are no exceptions, only the dataset of "regular" masks is returned)

So, after applying split_labels to the base and overlay input label maps, we have a base dataset, an overlay dataset, and maybe a base exclusions dataset and/or overlay exclusion dataset.

We then pass a list of those datasets in the priority order you identified (overlay exceptions (if applicable) -> base regular -> overlay regular -> base exceptions (if applicable)) to merge_labels, which reindexes all the label names that show up in the datasets, and writes the masks to an output 3D array with the new indices in order, so that later datasets overwrite labels written by earlier datasets.

[kaitj]

Sounds good - I think there is still a potential fundamental concern about mixed labels for voxels within a region that don't overlap, but that was present prior to this. In any case, this PR looks good to merge to me.