#!/usr/bin/env python3
## Copyright (C) 2020 David Miguel Susano Pinto <carandraug@gmail.com>
##
## 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/>.
import enum
import typing
[docs]class MicroscopeError(Exception):
"""Base class for Python Microscope exceptions."""
pass
[docs]class DeviceError(MicroscopeError):
"""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.
.. note::
The subclasses `DisabledDeviceError`, `IncompatibleStateError`,
`InitialiseError`, and `UnsupportedFeatureError` provide more
fine grained exceptions.
"""
pass
[docs]class IncompatibleStateError(DeviceError):
"""Raised when an operation is incompatible with the current device
state.
This exception is raised when the device is in a state
incompatible with an attempted operation, e.g., calling
:mod:`trigger <microscope.abc.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 disabled.
.. note::
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.
"""
pass
[docs]class DisabledDeviceError(IncompatibleStateError):
"""Raised when an operation requires an enabled device but the device is
disabled.
"""
pass
[docs]class InitialiseError(DeviceError):
"""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.
"""
pass
[docs]class UnsupportedFeatureError(DeviceError):
"""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.
"""
pass
[docs]class LibraryLoadError(MicroscopeError):
"""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
try:
import microscope._wrappers.libname
except Exception as e:
raise microscope.LibraryLoadError(e) from e
"""
pass
[docs]class AxisLimits(typing.NamedTuple):
"""Limits of a :class:`microscope.abc.StageAxis`."""
lower: float
upper: float
[docs]class Binning(typing.NamedTuple):
"""A tuple containing parameters for horizontal and vertical binning."""
h: int
v: int
[docs]class ROI(typing.NamedTuple):
"""A tuple that defines a region of interest.
This rectangle format completely defines the ROI without reference
to the sensor geometry.
"""
left: int
top: int
width: int
height: int
[docs]class TriggerType(enum.Enum):
"""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
is received.
:const:`TriggerType.SOFTWARE`
when :meth:`microscope.abc.TriggerTargetMixin.trigger` is called
:const:`TriggerType.RISING_EDGE`
when level changes to high
:const:`TriggerType.FALLING_EDGE`
when level changes to low
"""
SOFTWARE = 0
RISING_EDGE = 1
HIGH = 1
FALLING_EDGE = 2
LOW = 2
PULSE = 3
[docs]class TriggerMode(enum.Enum):
"""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.
:const:`TriggerMode.ONCE`
Act once. For example, acquire a single image when a camera
is triggered.
:const:`TriggerMode.BULB`
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
:attr:`TriggerType.SOFTWARE`.
:const:`TriggerMode.STROBE`
Act repeatably while device is being triggered. For example,
a camera keep acquiring multiple images while the trigger line
is high.
"""
ONCE = 1
BULB = 2
STROBE = 3
START = 4