Inheritance diagram for microscope.abc.Stage:

Public Member Functions
typing.Mapping[str, StageAxis]	axes (self)

bool	may_move_on_enable (self)

typing.Mapping[str, float]	position (self)

typing.Mapping[str, microscope.AxisLimits]	limits (self)

None	move_by (self, typing.Mapping[str, float] delta)

None	move_to (self, typing.Mapping[str, float] position)

Public Member Functions inherited from microscope.abc.Device
None	__init__ (self)

None	__del__ (self)

bool	get_is_enabled (self)

None	disable (self)

None	enable (self)

None	initialize (self)

None	shutdown (self)

None	add_setting (self, name, dtype, get_func, set_func, values, typing.Optional[typing.Callable[[], bool]] readonly=None)

def	get_setting (self, str name)

def	get_all_settings (self)

None	set_setting (self, str name, value)

def	describe_setting (self, str name)

def	describe_settings (self)

def	update_settings (self, incoming, bool init=False)

Additional Inherited Members
Public Attributes inherited from microscope.abc.Device
	enabled

Detailed Description

A stage device, composed of :class:`StageAxis` instances.

A stage device can have any number of axes and dimensions.  For a
single `StageDevice` instance each axis has a name that uniquely
identifies it.  The names of the individual axes are hardware
dependent and will be part of the concrete class documentation.
They are typically strings such as `"x"` or `"y"`.

.. code-block:: python

    stage = SomeStageDevice()
    stage.enable()  # may trigger a stage move

    # move operations
    stage.move_to({'x': 42.0, 'y': -5.1})
    stage.move_by({'x': -5.3, 'y': 14.6})

    # Individual StageAxis can be controlled directly.
    x_axis = stage.axes['x']
    y_axis = stage.axes['y']
    x_axis.move_to(42.0)
    y_axis.move_by(-5.3)

Not all stage devices support simultaneous move of multiple axes.
Because of this, there is no guarantee that move operations with
multiple axes are done simultaneously.  Refer to the concrete
class documentation for hardware specific details.

If a move operation involves multiple axes and there is no support
for simultaneous move, the order of the moves is undefined.  If a
specific order is required, one can either call the move functions
multiple times in the expected order, or do so via the individual
axes, like so:

.. code-block:: python

    # Move the x axis first, then mvoe the y axis:
    stage.move_by({'x': 10})
    stage.move_by({'y': 4})

    # The same thing but via the individual axes:
    stage.axes['x'].move_by(10)
    stage.axes['y'].move_by(4)

Move operations will not attempt to move a stage beyond its
limits.  If a call to the move functions would require the stage
to move beyond its limits the move operation is clipped to the
axes limits.  No exception is raised.

.. code-block:: python

    # Moves x axis to the its upper limit:
    x_axis.move_to(x_axis.limits.upper)

    # The same as above since the move operations are clipped to
    # the axes limits automatically.
    import math
    x_axis.move_to(math.inf)
    x_axis.move_by(math.inf)

Some stages need to find a reference position, home, before being
able to be moved.  If required, this happens automatically during
:func:`enable` (see also :func:`may_move_on_enable`).

Definition at line 1387 of file abc.py.

Member Function Documentation

◆ axes()

typing.Mapping[str, StageAxis] microscope.abc.Stage.axes ( self )

Map of axis names to the corresponding :class:`StageAxis`.

.. code-block:: python

    for name, axis in stage.axes.items():
        print(f'moving axis named {name}')
        axis.move_by(1)

If an axis is not available then it is not included, i.e.,
given a stage with optional axes the missing axes will *not*
appear on the returned dict with a value of `None` or some
other special `StageAxis` instance.

Reimplemented in microscope.controllers.zaber._ZaberStage, microscope.simulators.SimulatedStage, and microscope.stages.ludl._LudlStage.

Definition at line 1455 of file abc.py.

    def axes(self) -> typing.Mapping[str, StageAxis]:
        """Map of axis names to the corresponding :class:`StageAxis`.
 
        .. code-block:: python
 
            for name, axis in stage.axes.items():
                print(f'moving axis named {name}')
                axis.move_by(1)
 
        If an axis is not available then it is not included, i.e.,
        given a stage with optional axes the missing axes will *not*
        appear on the returned dict with a value of `None` or some
        other special `StageAxis` instance.
        """
        raise NotImplementedError()
 
 

Referenced by microscope.abc.Stage.limits(), microscope.simulators.SimulatedStage.move_by(), microscope.simulators.SimulatedStage.move_to(), and microscope.abc.Stage.position().

◆ limits()

typing.Mapping[str, microscope.AxisLimits] microscope.abc.Stage.limits ( self )

Map of axis name to its upper and lower limits.

.. code-block:: python

    for name, limits in stage.limits.items():
        print(f'{name} axis lower limit is {limits.lower}')
        print(f'{name} axis upper limit is {limits.upper}')

These are the limits currently imposed by the device or
underlying software and may change over the time of the
`StageDevice` object.

The units of the limits is the same as the ones being
currently used for the move operations.

Definition at line 1515 of file abc.py.

    def limits(self) -> typing.Mapping[str, microscope.AxisLimits]:
        """Map of axis name to its upper and lower limits.
 
        .. code-block:: python
 
            for name, limits in stage.limits.items():
                print(f'{name} axis lower limit is {limits.lower}')
                print(f'{name} axis upper limit is {limits.upper}')
 
        These are the limits currently imposed by the device or
        underlying software and may change over the time of the
        `StageDevice` object.
 
        The units of the limits is the same as the ones being
        currently used for the move operations.
 
        """
        return {name: axis.limits for name, axis in self.axes.items()}
 

References microscope.abc.Stage.axes(), microscope.controllers.zaber._ZaberStage.axes(), microscope.simulators.SimulatedStage.axes(), and microscope.stages.ludl._LudlStage.axes().

Referenced by microscope.stages.ludl._LudlStageAxis.limits().

◆ may_move_on_enable()

bool microscope.abc.Stage.may_move_on_enable ( self )

Whether calling :func:`enable` is likely to make the stage move.

Most stages need to be driven to their limits at startup to
find a repeatable zero position and sometimes to find their
limits as well.  This is typically called "homing".

Stages that need to "home" differ on how often they need it
but they only do it during :func:`enable`.  They may need to
move each time `enable` is called, the first time after the
`Stage` object has been created, or even only the first time
since the device was powered up.

Note the "*may*" on "may_move_on_enable".  This is because it
can be difficult to know for certain if `enable` will cause
the stage to home.  Still, knowing that the stage *may* move
is essential for safety.  An unexpected movement of the stage,
particularly large movements such as moving to the stage
limits, can destroy a sample on the stage --- or even worse,
it can damage an objective or the stage itself.  When in
doubt, implementations should return `True`.

Reimplemented in microscope.controllers.zaber._ZaberStage, microscope.simulators.SimulatedStage, and microscope.stages.ludl._LudlStage.

Definition at line 1473 of file abc.py.

    def may_move_on_enable(self) -> bool:
        """Whether calling :func:`enable` is likely to make the stage move.
 
        Most stages need to be driven to their limits at startup to
        find a repeatable zero position and sometimes to find their
        limits as well.  This is typically called "homing".
 
        Stages that need to "home" differ on how often they need it
        but they only do it during :func:`enable`.  They may need to
        move each time `enable` is called, the first time after the
        `Stage` object has been created, or even only the first time
        since the device was powered up.
 
        Note the "*may*" on "may_move_on_enable".  This is because it
        can be difficult to know for certain if `enable` will cause
        the stage to home.  Still, knowing that the stage *may* move
        is essential for safety.  An unexpected movement of the stage,
        particularly large movements such as moving to the stage
        limits, can destroy a sample on the stage --- or even worse,
        it can damage an objective or the stage itself.  When in
        doubt, implementations should return `True`.
 
        """
        raise NotImplementedError()
 
 

◆ move_by()

None microscope.abc.Stage.move_by	(		self,
		typing.Mapping[str, float]	delta
	)

Move axes by the corresponding amounts.

Args:
    delta: map of axis name to the amount to be moved.

.. code-block:: python

    # Move 'x' axis by 10.2 units and the y axis by -5 units:
    stage.move_by({'x': 10.2, 'y': -5})

    # The above is equivalent, but possibly faster than:
    stage.axes['x'].move_by(10.2)
    stage.axes['y'].move_by(-5)

The axes will not move beyond :func:`limits`.  If `delta`
would move an axis beyond it limit, no exception is raised.
Instead, the stage will move until the axis limit.

Reimplemented in microscope.controllers.zaber._ZaberStage, microscope.simulators.SimulatedStage, and microscope.stages.ludl._LudlStage.

Definition at line 1535 of file abc.py.

    def move_by(self, delta: typing.Mapping[str, float]) -> None:
        """Move axes by the corresponding amounts.
 
        Args:
            delta: map of axis name to the amount to be moved.
 
        .. code-block:: python
 
            # Move 'x' axis by 10.2 units and the y axis by -5 units:
            stage.move_by({'x': 10.2, 'y': -5})
 
            # The above is equivalent, but possibly faster than:
            stage.axes['x'].move_by(10.2)
            stage.axes['y'].move_by(-5)
 
        The axes will not move beyond :func:`limits`.  If `delta`
        would move an axis beyond it limit, no exception is raised.
        Instead, the stage will move until the axis limit.
 
        """
        # TODO: implement a software fallback that moves the
        # individual axis, for stages that don't have provide
        # simultaneous move of multiple axes.
        raise NotImplementedError()
 

References microscope.abc.Stage.move_by().

Referenced by microscope.abc.Stage.move_by().

◆ move_to()

None microscope.abc.Stage.move_to	(		self,
		typing.Mapping[str, float]	position
	)

Move axes to the corresponding positions.

Args:
    position: map of axis name to the positions to move to.

.. code-block:: python

    # Move 'x' axis to position 8 and the y axis to position -5.3
    stage.move_to({'x': 8, 'y': -5.3})

    # The above is equivalent to
    stage.axes['x'].move_to(8)
    stage.axes['y'].move_to(-5.3)

The axes will not move beyond :func:`limits`.  If `positions`
is beyond the limits, no exception is raised.  Instead, the
stage will move until the axes limit.

Reimplemented in microscope.controllers.zaber._ZaberStage, microscope.simulators.SimulatedStage, and microscope.stages.ludl._LudlStage.

Definition at line 1561 of file abc.py.

    def move_to(self, position: typing.Mapping[str, float]) -> None:
        """Move axes to the corresponding positions.
 
        Args:
            position: map of axis name to the positions to move to.
 
        .. code-block:: python
 
            # Move 'x' axis to position 8 and the y axis to position -5.3
            stage.move_to({'x': 8, 'y': -5.3})
 
            # The above is equivalent to
            stage.axes['x'].move_to(8)
            stage.axes['y'].move_to(-5.3)
 
        The axes will not move beyond :func:`limits`.  If `positions`
        is beyond the limits, no exception is raised.  Instead, the
        stage will move until the axes limit.
 
        """
        raise NotImplementedError()

References microscope.abc.Stage.move_to().

Referenced by microscope.stages.ludl._LudlStageAxis.limits(), microscope.simulators.SimulatedStageAxis.move_by(), and microscope.abc.Stage.move_to().

◆ position()

typing.Mapping[str, float] microscope.abc.Stage.position ( self )

Map of axis name to their current position.

.. code-block:: python

    for name, position in stage.position.items():
        print(f'{name} axis is at position {position}')

The units of the position is the same as the ones being
currently used for the absolute move (:func:`move_to`)
operations.

Definition at line 1500 of file abc.py.

    def position(self) -> typing.Mapping[str, float]:
        """Map of axis name to their current position.
 
        .. code-block:: python
 
            for name, position in stage.position.items():
                print(f'{name} axis is at position {position}')
 
        The units of the position is the same as the ones being
        currently used for the absolute move (:func:`move_to`)
        operations.
        """
        return {name: axis.position for name, axis in self.axes.items()}
 

References microscope.abc.Stage.axes(), microscope.controllers.zaber._ZaberStage.axes(), microscope.simulators.SimulatedStage.axes(), and microscope.stages.ludl._LudlStage.axes().

Referenced by microscope.abc.FilterWheel.get_num_positions(), and microscope.stages.ludl._LudlStageAxis.limits().

The documentation for this class was generated from the following file:

F:/repos/BioImager/BioImager/PythonMicroscope/microscope/abc.py

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ axes()

◆ limits()

◆ may_move_on_enable()

◆ move_by()

◆ move_to()

◆ position()