Mappings from physical components (phase,retardance,orientation) to HSV /JCh

[edyoshikun]

This PR has czyx functions that take a stack and output an RGB image mapping the label-free measurements to HSV.

This includes PRO-> HSV, RO->HSV and RO->JCh.

[edyoshikun]

@talonchandler tagging you here as reviewer, so we can move these functions to whatever repo makes sense later.

[ieivanov]

@talonchandler

[talonchandler]

Thanks @edyoshikun, I just took a closer look and I think there're some really nice functions in analysis/visualization.py.

I think the key function signatures are:

def HSV_PRO(czyx, channel_order, max_val_V: float = 1.0, max_val_S: float = 1.0):
def HSV_RO(czyx, channel_order: list[int], max_val_V: int = 1):
def JCh_mapping(czyx, channel_order: list[int], max_val_ret: int = None, noise_level: int = 1):

Compare those with the signature of recOrder's overlay function

def ret_ori_overlay(retardance, orientation, ret_max: Union[float, Literal["auto"]] = 10, cmap: Literal["JCh", "HSV"] = "JCh")

I think it's worthwhile cleaning these up and merging them.

Notes on overlap:

• ret_ori_overlay and HSV_RO share similar functionality. ret_ori_overlay provides more colormap options and IMO has a clearer name.
• HSV_PRO provides new and useful functionality, a mapping from (retardance, orientation, phase) to (hue, saturation, value)
• JCh_mapping provides a different mapping from (retardance, orientation, phase) to (hue, saturation, value).

I will suggest:

• HSV_RO be removed (I don't think it adds anything new)
• HSV_PRO and JCh_mapping be merged into a ret_ori_phase_overlay function with a cmap option.
• The new function signature be: def ret_ori_phase_overlay(retardance, orientation, phase, phase_max, ret_max, cmap). I prefer direct slots instead of the channel_order pattern, but please comment @edyoshikun if you have a different perspective.
• That these functions live in recOrder for now, with a potential move to iphub or similar in the future.

[talonchandler]

@edyoshikun and I met and discussed our plan for handling this. I will work through and request @edyoshikun's reviews

• confirm oindex behavior

>>> z = zarr.array(np.arange(15).reshape(3, 5))
>>> z.oindex[:, [3, 1]]
array([[ 3,  1],
       [ 8,  6],
       [13, 11]])
>>> z.oindex[:, [1, 3]]
array([[ 1,  3],
       [ 6,  8],
       [11, 13]])

• refactor shrimpy visualization call into this function definition def ret_ori_phase_overlay(czyx, max_val_V: float = 1.0, max_val_S: float = 1.0, cmap: Literal["JCh", "HSV"] = "JCh"): -> (3, z, y, x) and move it to recOrder
• refactor recOrder's call to match def ret_ori_overlay(czyx, ret_max: Union[float, Literal["auto"]] = 10, cmap: Literal["JCh", "HSV"] = "JCh"): -> (3, z, y, x)
• test with recOrder test datasets, and merge into recOrder
• close this draft PR without merging

[talonchandler]

Paired with mehta-lab/recOrder#473. After approving and merging that PR, this PR can close.