Inheritance diagram for microscope.abc.Device:

Public Member Functions
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)

	get_setting (self, str name)

	get_all_settings (self)

None	set_setting (self, str name, value)

	describe_setting (self, str name)

	describe_settings (self)

	update_settings (self, incoming, bool init=False)

Public Attributes
bool	enabled = False

Protected Member Functions
	_do_disable (self)

	_do_enable (self)

None	_do_shutdown (self)

Protected Attributes
dict	_settings = {}

Detailed Description

A base device class. All devices should subclass this class.

Definition at line 285 of file abc.py.

Constructor & Destructor Documentation

◆ init()

None microscope.abc.Device.__init__ ( self )

Reimplemented in microscope.abc.Camera, microscope.abc.DataDevice, microscope.cameras.picam.PiCamera, microscope.cameras.ximea.XimeaCamera, microscope.filterwheels.thorlabs.ThorlabsFilterWheel, microscope.filterwheels.thorlabs.ThorlabsFW102C, microscope.filterwheels.thorlabs.ThorlabsFW212C, microscope.simulators.SimulatedCamera, microscope.simulators.stage_aware_camera.StageAwareCamera, microscope.stages.linkam._LinkamBase, and microscope.testsuite.devices.TestCamera.

Definition at line 288 of file abc.py.

    def __init__(self) -> None:
        self.enabled = False
        self._settings: typing.Dict[str, _Setting] = {}
 

◆ del()

None microscope.abc.Device.__del__ ( self )

Reimplemented in microscope.stages.linkam._LinkamBase.

Definition at line 292 of file abc.py.

    def __del__(self) -> None:
        self.shutdown()
 

Member Function Documentation

◆ _do_disable()

microscope.abc.Device._do_disable ( self )

protected

Do any device-specific work on disable.

Subclasses should override this method rather than modify
`disable`.

Reimplemented in microscope.cameras.andorsdk3.AndorSDK3, microscope.cameras.atmcd.AndorAtmcd, microscope.cameras.picam.PiCamera, microscope.cameras.pvcam.PVCamera, microscope.cameras.ximea.XimeaCamera, microscope.controllers.toptica._iChromeLaser, microscope.controllers.zaber._ZaberLED, microscope.lights.deepstar.DeepstarLaser, microscope.lights.obis.ObisLaser, microscope.simulators.SimulatedCamera, and microscope.simulators.SimulatedLightSource.

Definition at line 298 of file abc.py.

    def _do_disable(self):
        """Do any device-specific work on disable.
 
        Subclasses should override this method rather than modify
        `disable`.
 
        """
        return True
 

◆ _do_enable()

microscope.abc.Device._do_enable ( self )

protected

Do any device specific work on enable.

Subclasses should override this method, rather than modify
`enable`.

Reimplemented in microscope.cameras.andorsdk3.AndorSDK3, microscope.cameras.atmcd.AndorAtmcd, microscope.cameras.picam.PiCamera, microscope.cameras.pvcam.PVCamera, microscope.cameras.ximea.XimeaCamera, microscope.controllers.toptica._iChromeLaser, microscope.controllers.zaber._ZaberLED, microscope.controllers.zaber._ZaberStage, microscope.lights.cobolt.CoboltLaser, microscope.lights.deepstar.DeepstarLaser, microscope.lights.obis.ObisLaser, microscope.lights.sapphire.SapphireLaser, microscope.simulators.SimulatedCamera, microscope.simulators.SimulatedLightSource, and microscope.stages.ludl._LudlStage.

Definition at line 312 of file abc.py.

    def _do_enable(self):
        """Do any device specific work on enable.
 
        Subclasses should override this method, rather than modify
        `enable`.
 
        """
        return True
 

◆ _do_shutdown()

None microscope.abc.Device._do_shutdown ( self )

protected

Private method - actual shutdown of the device.

Users should be calling :meth:`shutdown` and not this method.
Concrete implementations should implement this method instead
of `shutdown`.

Reimplemented in microscope.abc.Controller, microscope.cameras.andorsdk3.AndorSDK3, microscope.cameras.atmcd.AndorAtmcd, microscope.cameras.picam.PiCamera, microscope.cameras.pvcam.PVCamera, microscope.cameras.ximea.XimeaCamera, microscope.controllers.coolled._CoolLEDChannel, microscope.controllers.lumencor._SpectraIIILightChannel, microscope.controllers.prior._ProScanIIIFilterWheel, microscope.controllers.toptica._iChromeLaser, microscope.controllers.zaber._ZaberFilterWheel, microscope.controllers.zaber._ZaberLED, microscope.controllers.zaber._ZaberStage, microscope.filterwheels.thorlabs.ThorlabsFilterWheel, microscope.lights.cobolt.CoboltLaser, microscope.lights.deepstar.DeepstarLaser, microscope.lights.obis.ObisLaser, microscope.lights.sapphire.SapphireLaser, microscope.lights.toptica.TopticaiBeam, microscope.mirror.alpao.AlpaoDeformableMirror, microscope.mirror.bmc.BMCDeformableMirror, microscope.mirror.mirao52e.Mirao52e, microscope.simulators.SimulatedCamera, microscope.simulators.SimulatedDeformableMirror, microscope.simulators.SimulatedFilterWheel, microscope.simulators.SimulatedLightSource, microscope.simulators.SimulatedStage, microscope.stages.linkam._LinkamBase, microscope.stages.ludl._LudlStage, microscope.testsuite.devices.DummyDSP, microscope.testsuite.devices.DummySLM, microscope.testsuite.devices.TestFloatingDevice, microscope.testsuite.test_device_server.DeviceWithPort, and microscope.testsuite.test_device_server.ExposePIDDevice.

Definition at line 329 of file abc.py.

    def _do_shutdown(self) -> None:
        """Private method - actual shutdown of the device.
 
        Users should be calling :meth:`shutdown` and not this method.
        Concrete implementations should implement this method instead
        of `shutdown`.
 
        """
        raise NotImplementedError()
 

◆ add_setting()

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

Add a setting definition.

Args:
    name: the setting's name.
    dtype: a data type from `"int"`, `"float"`, `"bool"`,
        `"enum"`, or `"str"` (see `DTYPES`).
    get_func: a function to get the current value.
    set_func: a function to set the value.
    values: a description of allowed values dependent on
        dtype, or function that returns a description.
    readonly: an optional function to indicate if the setting
        is readonly.  A setting may be readonly temporarily,
        so this function will return `True` or `False` to
        indicate its current state.  If set to no `None`
        (default), then its value will be dependent on the
        value of `set_func`.

A client needs some way of knowing a setting name and data
type, retrieving the current value and, if settable, a way to
retrieve allowable values, and set the value.  We store this
info in a dictionary.  I considered having a `Setting1 class
with getter, setter, etc., and adding `Setting` instances as
device attributes, but Pyro does not support dot notation to
access the functions we need (e.g. `Device.some_setting.set`),
so I'd have to write access functions, anyway.

Definition at line 399 of file abc.py.

    ) -> None:
        """Add a setting definition.
 
        Args:
            name: the setting's name.
            dtype: a data type from `"int"`, `"float"`, `"bool"`,
                `"enum"`, or `"str"` (see `DTYPES`).
            get_func: a function to get the current value.
            set_func: a function to set the value.
            values: a description of allowed values dependent on
                dtype, or function that returns a description.
            readonly: an optional function to indicate if the setting
                is readonly.  A setting may be readonly temporarily,
                so this function will return `True` or `False` to
                indicate its current state.  If set to no `None`
                (default), then its value will be dependent on the
                value of `set_func`.
 
        A client needs some way of knowing a setting name and data
        type, retrieving the current value and, if settable, a way to
        retrieve allowable values, and set the value.  We store this
        info in a dictionary.  I considered having a `Setting1 class
        with getter, setter, etc., and adding `Setting` instances as
        device attributes, but Pyro does not support dot notation to
        access the functions we need (e.g. `Device.some_setting.set`),
        so I'd have to write access functions, anyway.
 
        """
        if dtype not in DTYPES:
            raise ValueError("Unsupported dtype.")
        elif not (isinstance(values, DTYPES[dtype]) or callable(values)):
            raise TypeError(
                "Invalid values type for %s '%s': expected function or %s"
                % (dtype, name, DTYPES[dtype])
            )
        else:
            self._settings[name] = _Setting(
                name, dtype, get_func, set_func, values, readonly
            )
 

◆ describe_setting()

microscope.abc.Device.describe_setting	(		self,
		str	name )

Return ordered setting descriptions as a list of dicts.

Definition at line 476 of file abc.py.

    def describe_setting(self, name: str):
        """Return ordered setting descriptions as a list of dicts."""
        return self._settings[name].describe()
 

◆ describe_settings()

microscope.abc.Device.describe_settings ( self )

Return ordered setting descriptions as a list of dicts.

Definition at line 480 of file abc.py.

    def describe_settings(self):
        """Return ordered setting descriptions as a list of dicts."""
        return [(k, v.describe()) for (k, v) in self._settings.items()]
 

◆ disable()

None microscope.abc.Device.disable ( self )

Disable the device for a short period for inactivity.

Reimplemented in microscope.abc.DataDevice, microscope.controllers.coolled._CoolLEDChannel, microscope.controllers.lumencor._SpectraIIILightChannel, microscope.lights.cobolt.CoboltLaser, microscope.lights.sapphire.SapphireLaser, and microscope.lights.toptica.TopticaiBeam.

Definition at line 307 of file abc.py.

    def disable(self) -> None:
        """Disable the device for a short period for inactivity."""
        self._do_disable()
        self.enabled = False
 

◆ enable()

None microscope.abc.Device.enable ( self )

Enable the device.

Reimplemented in microscope.abc.DataDevice, microscope.controllers.coolled._CoolLEDChannel, microscope.controllers.lumencor._SpectraIIILightChannel, and microscope.lights.toptica.TopticaiBeam.

Definition at line 321 of file abc.py.

    def enable(self) -> None:
        """Enable the device."""
        try:
            self.enabled = self._do_enable()
        except Exception as err:
            _logger.debug("Error in _do_enable:", exc_info=err)
 

◆ get_all_settings()

microscope.abc.Device.get_all_settings ( self )

Return ordered settings as a list of dicts.

Definition at line 455 of file abc.py.

    def get_all_settings(self):
        """Return ordered settings as a list of dicts."""
        # Fetching some settings may fail depending on device state.
        # Report these values as 'None' and continue fetching other settings.
        def catch(f):
            try:
                return f()
            except Exception as err:
                _logger.error("getting %s: %s", f.__self__.name, err)
                return None
 
        return {k: catch(v.get) for k, v in self._settings.items()}
 

◆ get_is_enabled()

bool microscope.abc.Device.get_is_enabled ( self )

Definition at line 295 of file abc.py.

    def get_is_enabled(self) -> bool:
        return self.enabled
 

◆ get_setting()

microscope.abc.Device.get_setting	(		self,
		str	name )

Return the current value of a setting.

Definition at line 447 of file abc.py.

    def get_setting(self, name: str):
        """Return the current value of a setting."""
        try:
            return self._settings[name].get()
        except Exception as err:
            _logger.error("in get_setting(%s):", name, exc_info=err)
            raise
 

◆ initialize()

None microscope.abc.Device.initialize ( self )

Initialize the device.

If devices have this method (not required, and many don't),
then they should call it as part of the initialisation, i.e.,
they should call it on their `__init__` method.

Reimplemented in microscope.cameras.andorsdk3.AndorSDK3, microscope.cameras.atmcd.AndorAtmcd, microscope.cameras.picam.PiCamera, microscope.cameras.pvcam.PVCamera, microscope.cameras.ximea.XimeaCamera, microscope.lights.cobolt.CoboltLaser, microscope.lights.obis.ObisLaser, microscope.lights.sapphire.SapphireLaser, and microscope.testsuite.devices.TestFloatingDevice.

Definition at line 339 of file abc.py.

    def initialize(self) -> None:
        """Initialize the device.
 
        If devices have this method (not required, and many don't),
        then they should call it as part of the initialisation, i.e.,
        they should call it on their `__init__` method.
 
        """
        pass
 

◆ set_setting()

None microscope.abc.Device.set_setting	(		self,
		str	name,
			value )

Set a setting.

Definition at line 468 of file abc.py.

    def set_setting(self, name: str, value) -> None:
        """Set a setting."""
        try:
            self._settings[name].set(value)
        except Exception as err:
            _logger.error("in set_setting(%s):", name, exc_info=err)
            raise
 

◆ shutdown()

None microscope.abc.Device.shutdown ( self )

Shutdown the device.

Disable and disconnect the device.  This method should be
called before destructing the device object, to ensure that
the device is actually shutdown.

After `shutdown`, the device object is no longer usable and
calling any other method is undefined behaviour.  The only
exception `shutdown` itself which can be called consecutively,
and after the first time will have no effect.

A device object that has been shutdown can't be reinitialised.
Instead of reusing the object, a new one should be created
instead.  This means that `shutdown` will leave the device in
a state that it can be reconnected.

.. code-block:: python

    device = SomeDevice()
    device.shutdown()

    # Multiple calls to shutdown are OK
    device.shutdown()
    device.shutdown()

    # After shutdown, everything else is undefined behaviour.
    device.enable()  # undefined behaviour
    device.get_setting("speed")  # undefined behaviour

    # To reinitialise the device, construct a new instance.
    device = SomeDevice()


.. note::

    While `__del__` calls `shutdown`, one should not rely on
    it.  Python does not guarante that `__del__` will be
    called when the interpreter exits so if `shutdown` is not
    called explicitely, the devices might not be shutdown.

Definition at line 349 of file abc.py.

    def shutdown(self) -> None:
        """Shutdown the device.
 
        Disable and disconnect the device.  This method should be
        called before destructing the device object, to ensure that
        the device is actually shutdown.
 
        After `shutdown`, the device object is no longer usable and
        calling any other method is undefined behaviour.  The only
        exception `shutdown` itself which can be called consecutively,
        and after the first time will have no effect.
 
        A device object that has been shutdown can't be reinitialised.
        Instead of reusing the object, a new one should be created
        instead.  This means that `shutdown` will leave the device in
        a state that it can be reconnected.
 
        .. code-block:: python
 
            device = SomeDevice()
            device.shutdown()
 
            # Multiple calls to shutdown are OK
            device.shutdown()
            device.shutdown()
 
            # After shutdown, everything else is undefined behaviour.
            device.enable()  # undefined behaviour
            device.get_setting("speed")  # undefined behaviour
 
            # To reinitialise the device, construct a new instance.
            device = SomeDevice()
 
 
        .. note::
 
            While `__del__` calls `shutdown`, one should not rely on
            it.  Python does not guarante that `__del__` will be
            called when the interpreter exits so if `shutdown` is not
            called explicitely, the devices might not be shutdown.
 
        """
        try:
            self.disable()
        except Exception as e:
            _logger.warning("Exception in disable() during shutdown: %s", e)
        _logger.info("Shutting down ... ... ...")
        self._do_shutdown()
        _logger.info("... ... ... ... shut down completed.")
 

◆ update_settings()

microscope.abc.Device.update_settings	(		self,
			incoming,
		bool	init = False )

Update settings based on dict of settings and values.

Reimplemented in microscope.abc.DataDevice.

Definition at line 484 of file abc.py.

    def update_settings(self, incoming, init: bool = False):
        """Update settings based on dict of settings and values."""
        if init:
            # Assume nothing about state: set everything.
            my_keys = set(self._settings.keys())
            their_keys = set(incoming.keys())
            update_keys = my_keys & their_keys
            if update_keys != my_keys:
                missing = ", ".join([k for k in my_keys - their_keys])
                msg = (
                    "update_settings init=True but missing keys: %s." % missing
                )
                _logger.debug(msg)
                raise Exception(msg)
        else:
            # Only update changed values.
            my_keys = set(self._settings.keys())
            their_keys = set(incoming.keys())
            update_keys = set(
                key
                for key in my_keys & their_keys
                if self.get_setting(key) != incoming[key]
            )
        results = {}
        # Update values.
        for key in update_keys:
            if key not in my_keys or not self._settings[key].set:
                # Setting not recognised or no set function implemented
                results[key] = NotImplemented
                update_keys.remove(key)
                continue
            if self._settings[key].readonly():
                continue
            self._settings[key].set(incoming[key])
        # Read back values in second loop.
        for key in update_keys:
            results[key] = self._settings[key].get()
        return results
 
 

Member Data Documentation

◆ _settings

dict microscope.abc.Device._settings = {}

protected

Definition at line 290 of file abc.py.

◆ enabled

microscope.abc.Device.enabled = False

Definition at line 289 of file abc.py.

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

BioImager/PythonMicroscope/microscope/abc.py

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

◆ __del__()

Member Function Documentation

◆ _do_disable()

◆ _do_enable()

◆ _do_shutdown()

◆ add_setting()

◆ describe_setting()

◆ describe_settings()

◆ disable()

◆ enable()

◆ get_all_settings()

◆ get_is_enabled()

◆ get_setting()

◆ initialize()

◆ set_setting()

◆ shutdown()

◆ update_settings()

Member Data Documentation

◆ _settings

◆ enabled

◆ init()

◆ del()