Inheritance diagram for microscope.abc.DataDevice:

Public Member Functions
None	__init__ (self, int buffer_length=0, **kwargs)

	__del__ (self)

None	abort (self)

None	enable (self)

None	disable (self)

None	set_client (self, new_client)

None	update_settings (self, settings, bool init=False)

None	receiveClient (self, str client_uri)

	grab_next_data (self, bool soft_trigger=True)

None	receiveData (self, data, timestamp)

Public Member Functions inherited from microscope.abc.Device
bool	get_is_enabled (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)

Public Attributes
bool	enabled = False

bool	_fetch_thread = True

bool	_dispatch_thread = True

None	_fetch_thread_run = self._fetch_data()

Public Attributes inherited from microscope.abc.Device
bool	enabled = False

Static Public Attributes
	set_setting = keep_acquiring(Device.set_setting)

Protected Member Functions
None	_fetch_data (self)

	_process_data (self, data)

	_send_data (self, client, data, timestamp)

None	_dispatch_loop (self)

None	_fetch_loop (self)

	_client (self)

	_client (self, val)

None	_put (self, data, timestamp)

Protected Member Functions inherited from microscope.abc.Device
	_do_disable (self)

	_do_enable (self)

None	_do_shutdown (self)

Protected Attributes
	_fetch_thread = None

bool	_fetch_thread_run = False

bool	_using_callback = False

list	_clientStack = []

	_liveClients = set()

	_dispatch_thread = None

	_dispatch_buffer = queue.Queue(maxsize=buffer_length)

bool	_acquiring = False

	_new_data_condition = threading.Condition()

	_client = None

tuple	_new_data = (data, timestamp)

Protected Attributes inherited from microscope.abc.Device
dict	_settings = {}

Detailed Description

A data capture device.

This class handles a thread to fetch data from a device and dispatch
it to a client.  The client is set using set_client(uri) or (legacy)
receiveClient(uri).

Derived classed should implement::

* :meth:`abort` (required)
* :meth:`_fetch_data` (required)
* :meth:`_process_data` (optional)

Derived classes may override `__init__`, `enable` and `disable`,
but must ensure to call this class's implementations as indicated
in the docstrings.

Definition at line 539 of file abc.py.

Constructor & Destructor Documentation

◆ init()

None microscope.abc.DataDevice.__init__	(		self,
		int	buffer_length = 0,
		**	kwargs )

Derived.__init__ must call this at some point.

Reimplemented from microscope.abc.Device.

Reimplemented in microscope.abc.Camera, microscope.cameras.picam.PiCamera, microscope.cameras.ximea.XimeaCamera, microscope.simulators.SimulatedCamera, microscope.simulators.stage_aware_camera.StageAwareCamera, and microscope.testsuite.devices.TestCamera.

Definition at line 558 of file abc.py.

    def __init__(self, buffer_length: int = 0, **kwargs) -> None:
        """Derived.__init__ must call this at some point."""
        super().__init__(**kwargs)
        # A thread to fetch and dispatch data.
        self._fetch_thread = None
        # A flag to control the _fetch_thread.
        self._fetch_thread_run = False
        # A flag to indicate that this class uses a fetch callback.
        self._using_callback = False
        # Clients to which we send data.
        self._clientStack = []
        # A set of live clients to avoid repeated dispatch to disconnected client.
        self._liveClients = set()
        # A thread to dispatch data.
        self._dispatch_thread = None
        # A buffer for data dispatch.
        self._dispatch_buffer = queue.Queue(maxsize=buffer_length)
        # A flag to indicate if device is ready to acquire.
        self._acquiring = False
        # A condition to signal arrival of a new data and unblock grab_next_data
        self._new_data_condition = threading.Condition()
 

◆ del()

microscope.abc.DataDevice.__del__ ( self )

Reimplemented from microscope.abc.Device.

Definition at line 580 of file abc.py.

    def __del__(self):
        self.disable()
        super().__del__()
 

Member Function Documentation

◆ _client() [1/2]

microscope.abc.DataDevice._client ( self )

protected

A getter for the current client.

Definition at line 732 of file abc.py.

    def _client(self):
        """A getter for the current client."""
        return (self._clientStack or [None])[-1]
 

◆ _client() [2/2]

microscope.abc.DataDevice._client	(		self,
			val )

protected

Push or pop a client from the _clientStack.

Definition at line 737 of file abc.py.

    def _client(self, val):
        """Push or pop a client from the _clientStack."""
        if val is None:
            self._clientStack.pop()
        else:
            self._clientStack.append(val)
        self._liveClients = set(self._clientStack)
 

◆ _dispatch_loop()

None microscope.abc.DataDevice._dispatch_loop ( self )

protected

Process data and send results to any client.

Definition at line 684 of file abc.py.

    def _dispatch_loop(self) -> None:
        """Process data and send results to any client."""
        while True:
            client, data, timestamp = self._dispatch_buffer.get(block=True)
            if client not in self._liveClients:
                continue
            err = None
            if isinstance(data, Exception):
                standard_exception = Exception(str(data).encode("ascii"))
                try:
                    self._send_data(client, standard_exception, timestamp)
                except Exception as e:
                    err = e
            else:
                try:
                    self._send_data(
                        client, self._process_data(data), timestamp
                    )
                except Exception as e:
                    err = e
            if err:
                # Raising an exception will kill the dispatch loop. We need
                # another way to notify the client that there was a problem.
                _logger.error("in _dispatch_loop:", exc_info=err)
            self._dispatch_buffer.task_done()
 

◆ _fetch_data()

None microscope.abc.DataDevice._fetch_data ( self )

protected

Poll for data and return it, with minimal processing.

If the device uses buffering in software, this function should
copy the data from the buffer, release or recycle the buffer,
then return a reference to the copy.  Otherwise, if the SDK
returns a data object that will not be written to again, this
function can just return a reference to the object.  If no
data is available, return `None`.

Reimplemented in microscope.cameras.andorsdk3.AndorSDK3, microscope.cameras.atmcd.AndorAtmcd, microscope.cameras.picam.PiCamera, microscope.cameras.pvcam.PVCamera, microscope.cameras.ximea.XimeaCamera, microscope.simulators.SimulatedCamera, and microscope.simulators.stage_aware_camera.StageAwareCamera.

Definition at line 643 of file abc.py.

    def _fetch_data(self) -> None:
        """Poll for data and return it, with minimal processing.
 
        If the device uses buffering in software, this function should
        copy the data from the buffer, release or recycle the buffer,
        then return a reference to the copy.  Otherwise, if the SDK
        returns a data object that will not be written to again, this
        function can just return a reference to the object.  If no
        data is available, return `None`.
 
        """
        return None
 

◆ _fetch_loop()

None microscope.abc.DataDevice._fetch_loop ( self )

protected

Poll source for data and put it into dispatch buffer.

Definition at line 710 of file abc.py.

    def _fetch_loop(self) -> None:
        """Poll source for data and put it into dispatch buffer."""
        self._fetch_thread_run = True
 
        while self._fetch_thread_run:
            try:
                data = self._fetch_data()
            except Exception as e:
                _logger.error("in _fetch_loop:", exc_info=e)
                # Raising an exception will kill the fetch loop. We need
                # another way to notify the client that there was a problem.
                timestamp = time.time()
                self._put(e, timestamp)
                data = None
            if data is not None:
                # TODO Add support for timestamp from hardware.
                timestamp = time.time()
                self._put(data, timestamp)
            else:
                time.sleep(0.001)
 

◆ _process_data()

microscope.abc.DataDevice._process_data	(		self,
			data )

protected

Do any data processing and return data.

Reimplemented in microscope.abc.Camera.

Definition at line 656 of file abc.py.

    def _process_data(self, data):
        """Do any data processing and return data."""
        return data
 

◆ _put()

None microscope.abc.DataDevice._put	(	self,
		data,
		timestamp )

protected

Put data and timestamp into dispatch buffer with target dispatch client.

Definition at line 745 of file abc.py.

    def _put(self, data, timestamp) -> None:
        """Put data and timestamp into dispatch buffer with target dispatch client."""
        self._dispatch_buffer.put((self._client, data, timestamp))
 

◆ _send_data()

microscope.abc.DataDevice._send_data	(	self,
		client,
		data,
		timestamp )

protected

Dispatch data to the client.

Definition at line 660 of file abc.py.

    def _send_data(self, client, data, timestamp):
        """Dispatch data to the client."""
        try:
            # Cockpit will send a client with receiveData and expects
            # two arguments (data and timestamp).  But we really want
            # to use Python's Queue and instead of just the timestamp
            # we should be sending some proper metadata object.  We
            # don't have that proper metadata class yet so just send
            # the image data as a numpy ndarray for now.
            if hasattr(client, "put"):
                client.put(data)
            else:
                client.receiveData(data, timestamp)
        except (
            Pyro4.errors.ConnectionClosedError,
            Pyro4.errors.CommunicationError,
        ):
            # Client not listening
            _logger.info(
                "Removing %s from client stack: disconnected.", client._pyroUri
            )
            self._clientStack = list(filter(client.__ne__, self._clientStack))
            self._liveClients = self._liveClients.difference([client])
 

◆ abort()

None microscope.abc.DataDevice.abort ( self )

Stop acquisition as soon as possible.

Reimplemented in microscope.cameras.andorsdk3.AndorSDK3, microscope.cameras.atmcd.AndorAtmcd, microscope.cameras.picam.PiCamera, microscope.cameras.pvcam.PVCamera, microscope.cameras.ximea.XimeaCamera, and microscope.simulators.SimulatedCamera.

Definition at line 588 of file abc.py.

    def abort(self) -> None:
        """Stop acquisition as soon as possible."""
        self._acquiring = False
 

◆ disable()

None microscope.abc.DataDevice.disable ( self )

Disable the data capture device.

Implement device-specific code in `_do_disable`.

Reimplemented from microscope.abc.Device.

Definition at line 629 of file abc.py.

    def disable(self) -> None:
        """Disable the data capture device.
 
        Implement device-specific code in `_do_disable`.
 
        """
        self.enabled = False
        if self._fetch_thread:
            if self._fetch_thread.is_alive():
                self._fetch_thread_run = False
                self._fetch_thread.join()
        super().disable()
 

◆ enable()

None microscope.abc.DataDevice.enable ( self )

Enable the data capture device.

Ensures that a data handling threads are running.  Implement
device specific code in `_do_enable`.

Reimplemented from microscope.abc.Device.

Definition at line 592 of file abc.py.

    def enable(self) -> None:
        """Enable the data capture device.
 
        Ensures that a data handling threads are running.  Implement
        device specific code in `_do_enable`.
 
        """
        _logger.debug("Enabling ...")
        # Call device-specific code.
        try:
            result = self._do_enable()
        except Exception as err:
            _logger.debug("Error in _do_enable:", exc_info=err)
            self.enabled = False
            raise err
        if not result:
            self.enabled = False
        else:
            self.enabled = True
            # Set up data fetching
            if self._using_callback:
                if self._fetch_thread:
                    self._fetch_thread_run = False
            else:
                if not self._fetch_thread or not self._fetch_thread.is_alive():
                    self._fetch_thread = Thread(target=self._fetch_loop)
                    self._fetch_thread.daemon = True
                    self._fetch_thread.start()
            if (
                not self._dispatch_thread
                or not self._dispatch_thread.is_alive()
            ):
                self._dispatch_thread = Thread(target=self._dispatch_loop)
                self._dispatch_thread.daemon = True
                self._dispatch_thread.start()
            _logger.debug("... enabled.")
 

◆ grab_next_data()

microscope.abc.DataDevice.grab_next_data	(		self,
		bool	soft_trigger = True )

Returns results from next trigger via a direct call.

Args:
    soft_trigger: calls :meth:`trigger` if `True`, waits for
        hardware trigger if `False`.

Definition at line 789 of file abc.py.

    def grab_next_data(self, soft_trigger: bool = True):
        """Returns results from next trigger via a direct call.
 
        Args:
            soft_trigger: calls :meth:`trigger` if `True`, waits for
                hardware trigger if `False`.
 
        """
        if not self.enabled:
            raise microscope.DisabledDeviceError("Camera not enabled.")
        self._new_data_condition.acquire()
        # Push self onto client stack.
        self.set_client(self)
        # Wait for data from next trigger.
        if soft_trigger:
            self.trigger()
        self._new_data_condition.wait()
        # Pop self from client stack
        self.set_client(None)
        # Return the data.
        return self._new_data
 

◆ receiveClient()

None microscope.abc.DataDevice.receiveClient	(		self,
		str	client_uri )

A passthrough for compatibility.

Definition at line 785 of file abc.py.

    def receiveClient(self, client_uri: str) -> None:
        """A passthrough for compatibility."""
        self.set_client(client_uri)
 

◆ receiveData()

None microscope.abc.DataDevice.receiveData	(	self,
		data,
		timestamp )

Unblocks grab_next_frame so it can return.

Definition at line 812 of file abc.py.

    def receiveData(self, data, timestamp) -> None:
        """Unblocks grab_next_frame so it can return."""
        with self._new_data_condition:
            self._new_data = (data, timestamp)
            self._new_data_condition.notify()
 
 

◆ set_client()

None microscope.abc.DataDevice.set_client	(		self,
			new_client )

Set up a connection to our client.

Clients now sit in a stack so that a single device may send
different data to multiple clients in a single experiment.
The usage is currently::

    device.set_client(client) # Add client to top of stack
    # do stuff, send triggers, receive data
    device.set_client(None)   # Pop top client off stack.

There is a risk that some other client calls ``None`` before
the current client is finished.  Avoiding this will require
rework here to identify the caller and remove only that caller
from the client stack.

Definition at line 749 of file abc.py.

    def set_client(self, new_client) -> None:
        """Set up a connection to our client.
 
        Clients now sit in a stack so that a single device may send
        different data to multiple clients in a single experiment.
        The usage is currently::
 
            device.set_client(client) # Add client to top of stack
            # do stuff, send triggers, receive data
            device.set_client(None)   # Pop top client off stack.
 
        There is a risk that some other client calls ``None`` before
        the current client is finished.  Avoiding this will require
        rework here to identify the caller and remove only that caller
        from the client stack.
 
        """
        if new_client is not None:
            if isinstance(new_client, (str, Pyro4.core.URI)):
                self._client = Pyro4.Proxy(new_client)
            else:
                self._client = new_client
        else:
            self._client = None
        # _client uses a setter. Log the result of assignment.
        if self._client is None:
            _logger.info("Current client is None.")
        else:
            _logger.info("Current client is %s.", str(self._client))
 

◆ update_settings()

None microscope.abc.DataDevice.update_settings	(		self,
			settings,
		bool	init = False )

Update settings, toggling acquisition if necessary.

Reimplemented from microscope.abc.Device.

Definition at line 780 of file abc.py.

    def update_settings(self, settings, init: bool = False) -> None:
        """Update settings, toggling acquisition if necessary."""
        super().update_settings(settings, init)
 

Member Data Documentation

◆ _acquiring

bool microscope.abc.DataDevice._acquiring = False

protected

Reimplemented in microscope.cameras.atmcd.AndorAtmcd.

Definition at line 576 of file abc.py.

◆ _client

microscope.abc.DataDevice._client = None

protected

Definition at line 747 of file abc.py.

◆ _clientStack

list microscope.abc.DataDevice._clientStack = []

protected

Definition at line 568 of file abc.py.

◆ _dispatch_buffer

microscope.abc.DataDevice._dispatch_buffer = queue.Queue(maxsize=buffer_length)

protected

Definition at line 574 of file abc.py.

◆ _dispatch_thread [1/2]

microscope.abc.DataDevice._dispatch_thread = None

protected

Definition at line 572 of file abc.py.

◆ _dispatch_thread [2/2]

bool microscope.abc.DataDevice._dispatch_thread = True

Definition at line 624 of file abc.py.

◆ _fetch_thread [1/2]

microscope.abc.DataDevice._fetch_thread = None

protected

Definition at line 562 of file abc.py.

◆ _fetch_thread [2/2]

bool microscope.abc.DataDevice._fetch_thread = True

Definition at line 617 of file abc.py.

◆ _fetch_thread_run [1/2]

bool microscope.abc.DataDevice._fetch_thread_run = False

protected

Definition at line 564 of file abc.py.

◆ _fetch_thread_run [2/2]

None microscope.abc.DataDevice._fetch_thread_run = self._fetch_data()

Definition at line 714 of file abc.py.

◆ _liveClients

microscope.abc.DataDevice._liveClients = set()

protected

Definition at line 570 of file abc.py.

◆ _new_data

tuple microscope.abc.DataDevice._new_data = (data, timestamp)

protected

Definition at line 815 of file abc.py.

◆ _new_data_condition

microscope.abc.DataDevice._new_data_condition = threading.Condition()

protected

Definition at line 578 of file abc.py.

◆ _using_callback

bool microscope.abc.DataDevice._using_callback = False

protected

Definition at line 566 of file abc.py.

◆ enabled

bool microscope.abc.DataDevice.enabled = False

Definition at line 605 of file abc.py.

◆ set_setting

microscope.abc.DataDevice.set_setting = keep_acquiring(Device.set_setting)

static

Definition at line 585 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

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

◆ __del__()

Member Function Documentation

◆ _client() [1/2]

◆ _client() [2/2]

◆ _dispatch_loop()

◆ _fetch_data()

◆ _fetch_loop()

◆ _process_data()

◆ _put()

◆ _send_data()

◆ abort()

◆ disable()

◆ enable()

◆ grab_next_data()

◆ receiveClient()

◆ receiveData()

◆ set_client()

◆ update_settings()

Member Data Documentation

◆ _acquiring

◆ _client

◆ _clientStack

◆ _dispatch_buffer

◆ _dispatch_thread [1/2]

◆ _dispatch_thread [2/2]

◆ _fetch_thread [1/2]

◆ _fetch_thread [2/2]

◆ _fetch_thread_run [1/2]

◆ _fetch_thread_run [2/2]

◆ _liveClients

◆ _new_data

◆ _new_data_condition

◆ _using_callback

◆ enabled

◆ set_setting

◆ init()

◆ del()