## Copyright (C) 2020 David Miguel Susano Pinto <firstname.lastname@example.org>
## This file is part of Microscope.
## Microscope is free software: you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation, either version 3 of the License, or
## (at your option) any later version.
## Microscope is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
## GNU General Public License for more details.
## You should have received a copy of the GNU General Public License
## along with Microscope. If not, see <http://www.gnu.org/licenses/>.
"""Base class for Python Microscope exceptions.
"""Raised when there is an issue controlling a device.
This exception is raised when there is an issue with controlling
the device, be it with its programming interface or with the
physical hardware. It is most common when commands to the device
fail or return something unexpected.
The subclasses `DisabledDeviceError`, `IncompatibleStateError`,
`InitialiseError`, and `UnsupportedFeatureError` provide more
fine grained exceptions.
"""Raised when an operation is incompatible with the current device
This exception is raised when the device is in a state
incompatible with an attempted operation, e.g., calling
:mod:`TriggerTargetMixin.trigger` on a device that is set for
hardware triggers. The subclass `DisabledDeviceError` provides an
exception specific to the case where the issue is the device being
This exception is for attempting to perform some action but
device is wrong state. If the issue is about a setting that is
incompatible with some other setting that this specific device
does not support, then `UnsupportedFeatureError` should be
"""Raised when an operation requires an enabled device but the device is
"""Raised when a device fails to initialise.
This exception is raised when there is a failure connecting to a
device, typically because the device is not connected, or the serial
number or port address is incorrect.
"""Raised when some operation requires a feature that is not supported.
This exception is raised when an operation requires some feature
that is not supported, either because the physical device does not
provide it, or Python Microscope has not yet implemented it. For
example, most devices do not support all trigger modes.
"""Raised when the loading and initialisation of a device library fails.
This exception is raised when a shared library or DLL fails to load,
typically because the required library is not found or is missing
some required symbol.
If there is a module that is a straight wrapper to the C library
(there should be one on the `microscope._wrappers` package) then
this exception can easily be used chained with the exception that
originated it like so::
.. code-block:: python
except Exception as e:
raise microscope.LibraryLoadError(e) from e
"""Limits of a :class:`microscope.abc.StageAxis`."""
"""A tuple containing parameters for horizontal and vertical binning. """
"""A tuple that defines a region of interest.
This rectangle format completely defines the ROI without reference
to the sensor geometry.
"""Type of a trigger for a :class:`microscope.abc.TriggerTargetMixin`.
The trigger type defines what constitutes a trigger, as opposed to
the trigger mode which defines a type of action when the trigger
when :meth:`microscope.abc.TriggerTargetMixin.trigger` is called
when level changes to high
when level changes to low
SOFTWARE = 0
RISING_EDGE = 1
HIGH = 1
FALLING_EDGE = 2
LOW = 2
PULSE = 3
"""Mode of a trigger for a :class:`microscope.abc.TriggerTargetMixin`.
The trigger mode defines what type of action when a trigger is
received, as opposed to the trigger type which defines what
constitutes a trigger. The exact type of action is highly
dependent on device type, so check their documentation.
Act once. For example, acquire a single image when a camera
Act while device is being triggered. For example, a laser
keeps emitting emit light or a camera keeps exposing while the
trigger line is high. This trigger mode is incompatible with
Act repeatably while device is being triggered. For example,
a camera keep acquiring multiple images while the trigger line
ONCE = 1
BULB = 2
STROBE = 3
START = 4