openflexure_microscope_server.things.stage.BaseStage

class documentation

class BaseStage(lt.Thing): (source)

Known subclasses: openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Constructor: BaseStage(thing_server_interface)

View In Hierarchy

A base stage class for OpenFlexure translation stages.

This can't be used directly but should reduce boilerplate code when implementing new stages.

Note that the coordinate system used for the microscope may need to have different axis direction as those used by the underlying stage controller.

A minimal working stage must implement _hardware_move_relative and _hardware_move_absolute actions, which update the _hardware_position attribute on completion, and also should implement set_zero_position.

Method	`__init__`	Initialise the stage.
Method	`get_xyz_position`	Return a tuple containing (x, y, z) position.
Method	`invert_axis_direction`	Invert the direction setting of the given axis.
Method	`jog`	Make a relative move that may be interrupted by a future `jog`.
Method	`move_absolute`	Make an absolute move. Keyword arguments should be axis names.
Method	`move_relative`	Make a relative move. Keyword arguments should be axis names.
Method	`move_to_xyz_position`	Move to the location specified by an (x, y, z) tuple.
Method	`set_zero_position`	Make the current position zero in all axes.
Method	`update_position`	Update the position property from the stage.
Class Variable	`backlash_steps`	The number of steps to elimate backlash. The sign sets the direction.
Class Variable	`moving`	Whether the stage is in motion.
Instance Variable	`axis_inverted`	Used to convert coordinates between the program frame and the hardware frame.
Property	`axis_names`	The names of the stage's axes, in order.
Property	`position`	Current position of the stage.
Property	`thing_state`	Summary metadata describing the current state of the stage.
Method	`_apply_axis_direction`	Undocumented
Method	`_estimate_move_duration`	Calculate the expected duration of a move with the given displacement.
Method	`_get_from_jog_queue`	Get the next JogCommand from the jog queue.
Method	`_hardware_move_absolute`	Make a absolute move in the coordinate system used by the physical hardware.
Method	`_hardware_move_relative`	Make a relative move in the coordinate system used by the physical hardware.
Method	`_hardware_start_move_relative`	Start a relative move.
Method	`_hardware_stop`	Undocumented
Method	`_hardware_update_position`	Read position from the stage and set internal attribute _hardware_position.
Method	`_jog_loop`	Execute jog commands in a background thread.
Method	`_move_with_backlash_correction`	Make a movement with backlash correction.
Method	`_poll_moving`	Determine if the stage is still moving.
Method	`_send_jog_command`	Send a jog command to the background jog thread.
Class Variable	`_axis_names`	Undocumented
Instance Variable	`_backlash_state`	Undocumented
Instance Variable	`_hardware_lock`	Undocumented
Instance Variable	`_hardware_position`	Undocumented
Instance Variable	`_jog_lock`	Undocumented
Instance Variable	`_jog_queue`	Undocumented
Instance Variable	`_jog_thread`	Undocumented

def __init__(self, thing_server_interface: lt.ThingServerInterface): (source) ¶

overridden in openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Initialise the stage.

Raises
`RedefinedBaseMovementError`	if `move_relative` and/or `move_absolute` are overridden. It is recommended to override `_hardware_move_relative` and/or `_hardware_move_absolute` instead so that all code in the child class uses the hardware reference frame.

@lt.action

def get_xyz_position(self) -> tuple[int, int, int]: (source) ¶

Return a tuple containing (x, y, z) position.

This method provides the interface expected by the camera_stage_mapping.

Raises
`KeyError`	if this stage does not have axes named "x", "y", and "z".

@lt.action

def invert_axis_direction(self, axis: Literal['x', 'y', 'z']): (source) ¶

Invert the direction setting of the given axis.

Parameters
axis:`Literal['x', 'y', 'z']`	The axis name (x, y or z) to invert.

@lt.action

def jog(self, stop: bool = False, **kwargs: int): (source) ¶

Make a relative move that may be interrupted by a future jog.

This action makes a relative move. If another jog action is called while a jog is already in progress, the first will be stopped and the second will start immediately. This allows for responsive manual control of the stage, for example with a joystick.

Parameters
stop:`bool`	if this is set to `True` the jog will be terminated.
**kwargs:`int`	Keyword arguments should be axis names.

@lt.action

def move_absolute(self, block_cancellation: bool = False, backlash_compensation: BacklashCompensation | None = None, **kwargs: int): (source) ¶

Make an absolute move. Keyword arguments should be axis names.

@lt.action

def move_relative(self, block_cancellation: bool = False, backlash_compensation: BacklashCompensation | None = None, **kwargs: int): (source) ¶

Make a relative move. Keyword arguments should be axis names.

@lt.action

def move_to_xyz_position(self, xyz_pos: tuple[int, int, int]): (source) ¶

Move to the location specified by an (x, y, z) tuple.

This method provides the interface expected by the camera_stage_mapping.

Parameters
xyz_pos:`tuple[int, int, int]`	The (x, y, z) position to move to.

Raises
`KeyError`	if this stage does not have axes named "x", "y", and "z".

@lt.action

def set_zero_position(self): (source) ¶

overridden in openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Make the current position zero in all axes.

This action does not move the stage, but resets the position to zero. It is intended for use after manually or automatically recentring the stage.

def update_position(self): (source) ¶

Update the position property from the stage.

backlash_steps: dict[str, int] = (source) ¶

The number of steps to elimate backlash. The sign sets the direction.

A positive number sets the direction of the second move in a backlash correction. For example, consider z=200. If the previous move was more than +200 in z, no correction is needed. If the last movement was negative then a move of -200, followed by +200 will wipe out backlash.

moving: bool = (source) ¶

overridden in openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Whether the stage is in motion.

axis_inverted: dict[str, bool] = (source) ¶

overridden in openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Used to convert coordinates between the program frame and the hardware frame.

@lt.property

axis_names: Sequence[str] = (source) ¶

The names of the stage's axes, in order.

@lt.property

position: Mapping[str, int] = (source) ¶

Current position of the stage.

@property

thing_state: Mapping[str, Any] = (source) ¶

Summary metadata describing the current state of the stage.

@overload

def _apply_axis_direction(self, position: list[int] | tuple[int]) -> list[int]:

@overload

def _apply_axis_direction(self, position: Mapping[str, int]) -> Mapping[str, int]:

(source) ¶

Undocumented

def _estimate_move_duration(self, displacement: Sequence[int]) -> float: (source) ¶

overridden in openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Calculate the expected duration of a move with the given displacement.

def _get_from_jog_queue(self, timeout: float) -> JogCommand | None: (source) ¶

Get the next JogCommand from the jog queue.

Parameters
timeout:`float`	The estimtated time the move will take for the queue timeout.

Returns
`JogCommand \| None`	The jog command or None if the stage stops before a command is received.

def _hardware_move_absolute(self, block_cancellation: bool = False, **kwargs: int): (source) ¶

overridden in openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Make a absolute move in the coordinate system used by the physical hardware.

Make sure to use and update self._hardware_position not self.position.

def _hardware_move_relative(self, block_cancellation: bool = False, **kwargs: int): (source) ¶

overridden in openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Make a relative move in the coordinate system used by the physical hardware.

Make sure to use and update self._hardware_position not self.position.

def _hardware_start_move_relative(self, displacement: Sequence[int]): (source) ¶

overridden in openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Start a relative move.

def _hardware_stop(self): (source) ¶

overridden in openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Undocumented

def _hardware_update_position(self): (source) ¶

overridden in openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Read position from the stage and set internal attribute _hardware_position.

_hardware_position should only be set in this function.

def _jog_loop(self, first_command: JogCommand): (source) ¶

Execute jog commands in a background thread.

This function is intended to be run in a background thread. It will look at self._jog_command when the self._jog_send event is set.

def _move_with_backlash_correction(self, block_cancellation: bool, relative: bool, backlash_compensation: BacklashCompensation, **kwargs: int): (source) ¶

Make a movement with backlash correction.

Parameters
block_cancellation:`bool`	True to prevent the move being cancelled.
relative:`bool`	True if the kwargs are relative moves. False if they are absolute.
backlash_compensation:`BacklashCompensation`	A BacklashCompensation which sets which axes to apply backalsh compensation to.
**kwargs:`int`	A mapping of axis name to integer for the movement.

def _poll_moving(self) -> bool: (source) ¶

overridden in openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Determine if the stage is still moving.

def _send_jog_command(self, command: JogCommand): (source) ¶

Send a jog command to the background jog thread.

This function will start the background thread if it is not running. This function acquires _jog_lock and uses the _jog_send event to signal the thread to read the next command. As commands interrupt each other, this function should never block for a long time.

Parameters
command:`JogCommand`	the jog command to send.

_axis_names: tuple[str, ...] = (source) ¶

Undocumented

_backlash_state: dict[str, float] = (source) ¶

Undocumented

_hardware_lock = (source) ¶

Undocumented

_hardware_position: Mapping[str, int] = (source) ¶

overridden in openflexure_microscope_server.things.stage.dummy.DummyStage, openflexure_microscope_server.things.stage.sangaboard.SangaboardThing

Undocumented

_jog_lock = (source) ¶

Undocumented

_jog_queue = (source) ¶

Undocumented

_jog_thread: threading.Thread | None = (source) ¶

Undocumented