Expose stage travel limits through CMMCore

[hinderling]

Seems the stage device API has a travel-limits concept (MM::Stage::GetLimits, MM::XYStage::GetLimitsUm), but these are not exposed by MMCore. XY stage position is not a device property, so the usual hasPropertyLimits / getPropertyLowerLimit / getPropertyUpperLimit don't apply. MMCore already wraps the device methods internally (XYStageInstance::GetLimitsUm, StageInstance::GetLimits in mmcore::internal), they are just not reachable from CMMCore.

Proposal would be something like:
getXYStageLimits(* xyStageLabel, & xMin, & xMax, & yMin, & yMax)
getStageLimits(* stageLabel, & lower, & upper)

(similar to getGalvoXRange, getGalvoXMinimum, ...)

Ran into this working on a widget that shows the live stage position, where I wanted to draw the max stage range as an outline. I think it could also be a useful safety layer for programmatic control, e.g. validating acquisition events before starting an experiment.

A quick search shows several adapters return DEVICE_UNSUPPORTED_COMMAND (ASIStage, Ludl) or DEVICE_OK (OpenFlexure) for GetLimitsUm (case for GetLimits is similar), so clients would need an unambiguous way to deal with stages that don't implement limits. Maybe would require a hasXYStageLimits(label)?

Let me know if I'm missing something, and there is a way to do this already! Also happy to work towards a PR if this is something of interest.

[marktsuchida]

You're absolutely right about these lacking API methods. But I'm not so sure about the possibility of using these to validate acquisition events, because the way limits are handled (or even known) varies widely between stages.

Hard limits like these are most useful for piezo flexure stages that have a fixed range (say, 0–100 µm). For those stages, there is nothing complicated (other than needing to be able to query the device/driver for the range — in theory that might not be known to an analog driver).

For motorized stages, the hard limits are rarely known, as far as I know. Most motorized stages have limit switches that can detect when the stage reaches the end of travel, but do not have a way to know ahead of time what the limits are. Perhaps the approximate travel is known from the specs. For many stages, it is also unknown where within the travel the origin lies, not to mention that the origin can change. So it's a bit of a can of worms. Not to mention that the full stage travel is rarely the safe travel limits for an XY stage. I think this is why we never bothered to implement these limit parameters.

So I guess I'd be interested in hearing more about exactly how you'd use this, and whether the stage hardware/drivers can in fact support those use cases with reliable information before we go ahead and expose these.

[hinderling]

As always, things are more complex than I imagined!

These are all great points. The use-case I have in mind is to access safe travel limits to validate acquisition events before executing them. Indeed on our microscopes, the max range of the stage is larger than the safe travel limits, and I agree that the drivers are the wrong place to store this information. When proposing this I was thinking of then overwriting these within a custom acquisition engine, but what might work better is to have an API for user-defined soft limits that are owned by the core rather than the devices (similar to the device timeouts PR #914)?

I think there might still be some value in exposing also the device stage limits, for the devices that do have them:

// read-only, owned by device
bool hasXYStageLimits(const char* label);
void getXYStageLimits(const char* label, double& xMin, double& xMax, double& yMin, double& yMax);

// user-defined, owned by core
void setXYStageSoftLimits(const char* label, double xMin, double xMax, double yMin, double yMax);
void unsetXYStageSoftLimits(const char* label);
bool hasXYStageSoftLimits(const char* label);
void getXYStageSoftLimits(const char* label, double& xMin, double& xMax, double& yMin, double& yMax);
void setStageSoftLimits(... ) // same for Stage

This would raise an additional questions on:

• wether soft limits are enforced by the core
• persistence, if/where to store these values. Seems there is some precedent for both not storing (device timeouts) and storing (set focus direction), where device defaults can be complemented/overwritten via API and stored in the .cfg (setFocusDirection -> saveSystemConfiguration -> updates .cfg)
• what happens on setOriginXY / setAdapterOriginXY (shift soft limits by the offset, drop with warning?) Dealing with seems like a good argument for core-owned limits.