Add SLM mask to MDAEvent

[tlambert03]

It's long been on my list of things to do to add some concept of an SLM or other image mask to the MDAEvent. micro-manager supports it, and the only thing stopping us from adding support in the pymmcore-plus engine is a recognized field for it.

@hinderling has mentioned it would be useful to him as well. It's easy to add. (any suggestions on field name and type?)

[hinderling]

Would be fantastic to have! This is my current workaround:

class MDAEngine_DMD(MDAEngine):
    """An MDA engine that expects acquisition events to have a stim_mask property 
    in the metadata, that can be sent to the DMD. E.g. np.ones((800,600))
    to get the whole FOV illuminated."""

    _mmc = None

    def __init__(self, dmd: DMD):
        self.dmd = dmd
        super().__init__(dmd.mmc)

    def exec_event(self, event: useq.MDAEvent) -> object:
        if 'stim_mask' in event.metadata:
            stim_mask = event.metadata['stim_mask']
            self.dmd.display_mask(stim_mask)
        else:
            #no mask in metadata, turn on all pixels
            self.dmd.all_on()

As data type np.array would be easiest? Some difficulties are that different DMDs require different dimensions/data types.

Looking back at our last discussion here and here about SLMs, for pymmcore compatibility we would need:

• 2D[h,w] np.uint8
• 3D[h,w,(rgb)] np.uint8
• char * with either w*h bytes or w*h*4 bytes (for imgRGB32)

I think it would be nice to be able to pass 2D [h,w] np.bool, but this is currently not supported in pymmcore, as different SLMs use different ON-values, and there is no way to extract this information. This currently breaks scripts when using different DMDs, e.g. (Mosaic3 uses 1 for ON-pixels pixelon='\x01' but Polygon1000 requires pixelon='\x7f', unicode for 127).

For naming maybe slm_image to follow the micro-manager convention?