No instructions for saving image segmentation mask

[jAllyn-ACTA]

Problem

Link: https://mpl-interactions.readthedocs.io/en/latest/examples/image-segmentation.html#
There is no example showing the best way to save an image segmentation mask. Based on the example for loading, I assumed using numpy.save() was the best way but clarity on this would be helpful for those who are less experienced.

Suggested Improvement

Add a code snippet for saving a segmentation mask to a file.

[ianhi]

Hi @jAllyn-ACTA great point!

In fact it looks like I never fully define what is acceptable as a mask. Looking at the code I think that the correct statement for what masks can be is:

A numpy array (or array-like that supports multidimensional indexing) of any dtype with the same first two dimesions as the image being segmented.

It also looks like this isn't in the docstrings:

https://github.com/ianhi/mpl-interactions/blob/519c2922c9391cb78ba7d7657be865a0c81bd2c9/mpl_interactions/generic.py#L391-L392

and more concerningly that if you pass in a pre-made mask it just uses it directly rather than first casting to a numpy array:
https://github.com/ianhi/mpl-interactions/blob/519c2922c9391cb78ba7d7657be865a0c81bd2c9/mpl_interactions/generic.py#L432-L436

---

also https://mpl-interactions.readthedocs.io/en/latest/api/mpl_interactions.generic.html#mpl_interactions.generic.image_segmenter doesn't seem to capture most of the docstrings as it lives in the init function.

---

Finally @jAllyn-ACTA this segmenter is useful for quick segmentations in the notebook, but for any serious interactive segmentation I now recommend using https://napari.org/ which is extremely fast and smooth to use - it's what I use for all my research work now.

[ianhi]

@jAllyn-ACTA do you have any interest in opening a PR improving the documentation/code as described below (or however you think would be most helpful)? If you do I'm happy to talk you through it so you get credit for pointing out and fixing this! If not then no worries and I'll try to get to this in the (hopefully near) future.

TODOs:

Docs

• Update the docstring of the init function
  • (in https://github.com/ianhi/mpl-interactions/blob/master/mpl_interactions/generic.py)
• Add a sentence defining what is acceptable as a mask to the docs page
• Add explanation on saving the mask (e.g. "the mask is a normal numpy array so to save it you should call np.save(...)
• Add a statement encouraging people to use napari to the docs

Code

More care needs to be taken with what types the mask can be. Currently this is completely ungaurded so you could pass in a list of lists which would break on the indexing in the update. As a first pass there should at least be a np.asanyarray on https://github.com/ianhi/mpl-interactions/blob/519c2922c9391cb78ba7d7657be865a0c81bd2c9/mpl_interactions/generic.py#L436

More serious changes could be to make mask a property and cast to numpy in the setter.

@property
def mask(self):
   return self._mask

@mask.setter
def mask(self, value):
    # do some checks about the shape of the new mask.
    self._mask = np.asanyarray(value)
# maybe add some try excepts here to catch execptions and give helpful messges explain