python-microscopy 26.7.9__cp313-cp313-macosx_26_0_arm64.whl

PYME/Acquire/ActionManager.py

@@ -0,0 +1,450 @@
+# -*- coding: utf-8 -*-
+"""
+Created on Sat May 28 23:12:24 2016
+
+@author: david
+"""
+try:
+    #python 2.x
+    # noinspection PyCompatibility
+    import Queue
+except ImportError:
+    #python 3.x
+    import queue as Queue
+    
+import time
+from PYME.contrib import dispatch
+import weakref
+import threading
+from PYME.util import webframework
+import numpy as np
+import logging
+logger = logging.getLogger(__name__)
+
+from .actions import *
+
+class MutablePriorityQueue(Queue.PriorityQueue):
+    def __init__(self, *args, **kwargs):
+        Queue.PriorityQueue.__init__(self, *args,**kwargs)
+
+    def remove(self, item):
+        with self.mutex:
+            if item in self.queue:
+                self.queue.remove(item)
+                #self.queue.sort()
+                self.not_full.notify()
+
+class ActionManager(object):
+    """This implements a queue for actions which should be called sequentially.
+    
+    The main purpose of the ActionManager is to facilitate automated imaging by 
+    allowing multiple operations to be queued. Rather than being strictly FIFO,
+    different tasks can be asigned different priorities, with higher priority 
+    tasks bubbling up and and being executed before lower priority tasks. This 
+    allows high priority "imaging" tasks to be inserted into a stream of lower
+    priority "monitoring" tasks if something interesting is detected during 
+    monitoring.
+    
+    An individual action is a function which can be found within the scope of
+    our microscope object (for more details see the QueueAction method).
+    
+    To function correctly the Tick() method should be called regularly - e.g.
+    from a GUI timer.
+    """
+    def __init__(self, scope):
+        """Initialise our action manager
+        
+        Parameters
+        ----------
+        
+        scope : PYME.Acquire.microscope.Microscope object
+            The microscope. The function object to call for an action should be 
+            accessible within the scope namespace, and will be resolved by
+            calling eval('scope.functionName')
+        
+        """
+        self.actionQueue = MutablePriorityQueue() # queue for immediate execution
+        self.scheduledQueue = MutablePriorityQueue() # queue for scheduled execution
+        self.scope = weakref.ref(scope)
+        
+        #this will be assigned to a callback to indicate if the last task has completed        
+        self.isLastTaskDone = None
+        self.paused = False
+        
+        self.currentTask = None
+        
+        self.onQueueChange = dispatch.Signal()
+        
+        self._timestamp = 0
+
+        self._monitoring = True
+        self._monitor = threading.Thread(target=self._monitor_defunct)
+        self._monitor.daemon = True
+        self._monitor.start()
+        
+        self._lock = threading.Lock()
+        
+    def QueueAction(self, functionName, args, nice=10, timeout=1e6, 
+                    max_duration=np.finfo(float).max, execute_after=0):
+        """Add an action to the queue. Legacy version for string based actions. Most applications should use queue_actions() below instead
+        
+        Parameters
+        ----------
+        
+        functionName : string
+            The name of a function relative to the microscope object.
+            e.g. to `call scope.spoolController.start_spooling()`, you would use
+            a functionName of 'spoolController.start_spooling'.
+            
+            The function should either return `None` if the operation has already
+            completed, or function which evaluates to True once the operation
+            has completed. See `scope.spoolController.start_spooling()` for an
+            example.
+            
+        args : dict
+            a dictionary of arguments to pass the function    
+        nice : int (or float)
+            The priority with which to execute the function. Functions with a
+            lower nice value execute first. Nice should have a value between 0 and 20. nice=20 is reserved by convention
+            for tidy-up tasks which should run
+            after all other tasks and put the microscope in a 'safe' state.
+        timeout : float
+            A timeout in seconds from the current time at which the action
+            becomes irrelevant and should be ignored.
+        max_duration : float
+            A generous estimate, in seconds, of how long the task might take, 
+            after which the lasers will be automatically turned off and the 
+            action queue paused. This will not interrupt the current task, 
+            though it has presumably already failed at that point. Intended as a
+            safety feature for automated acquisitions, the check is every 3 s 
+            rather than fine-grained.
+        execute_after: float
+            A timestamp in system time before which the action should not be executed.
+            If this is before the current time, the action will be queued for immediate
+            execution, otherwise it will be placed in a queue of scheduled acquisitions
+            which is polled by the Tick() method and added to the execution queue when
+            the time is right. The default of 0 means that the action will be queued for
+            immediate execution.
+            
+        """
+        # make sure nice is in supported range.
+        assert ((nice >= 0) and (nice <= 20))
+        
+        curTime = time.time()
+        expiry = curTime + timeout
+        
+        #make sure our timestamps strictly increment
+        self._timestamp = max(curTime, self._timestamp + 1e-3)
+        
+        #ensure FIFO behaviour for events with the same priority
+        nice_ = nice + self._timestamp*1e-10
+        
+        if execute_after < curTime:
+            logger.debug('Queuing action %s for immediate execution (%s, %s)' % (functionName, curTime, execute_after))
+            self.actionQueue.put_nowait((nice_, FunctionAction(functionName, args), expiry, max_duration))
+        else:
+            logger.debug('Queuing action %s for delayed execution (%s, %s)' % (functionName, curTime, execute_after))
+            self.scheduledQueue.put_nowait((execute_after, (nice_, FunctionAction(functionName, args), expiry, max_duration)))
+        
+        self.onQueueChange.send(self)
+        
+    def queue_actions(self, actions, nice=10, timeout=1e6, max_duration=np.finfo(float).max, execute_after=0):
+        '''
+        Queue a number of actions for subsequent execution
+        
+        Parameters
+        ----------
+        actions : list
+            A list of Action instances
+        nice : int (or float)
+            The priority with which to execute the function. Functions with a
+            lower nice value execute first. Nice should have a value between 0 and 20.
+        timeout : float
+            A timeout in seconds from the current time at which the action
+            becomes irrelevant and should be ignored.
+        max_duration : float
+            A generous estimate, in seconds, of how long the task might take,
+            after which the lasers will be automatically turned off and the
+            action queue paused. This will not interrupt the current task,
+            though it has presumably already failed at that point. Intended as a
+            safety feature for automated acquisitions, the check is every 3 s
+            rather than fine-grained.
+        execute_after: float
+            A timestamp in system time before which the action should not be executed.
+            If this is before the current time, the action will be queued for immediate
+            execution, otherwise it will be placed in a queue of scheduled acquisitions
+            which is polled by the Tick() method and added to the execution queue when
+            the time is right. The default of 0 means that the action will be queued for
+            immediate execution.
+
+        Returns
+        -------
+        
+        
+        Examples
+        --------
+        
+        >>> my_actions = [UpdateState(state={'Camera.ROI' : [50, 50, 200, 200]}),
+        >>>      SpoolSeries(maxFrames=500, stack=False),
+        >>>      UpdateState(state={'Camera.ROI' : [100, 100, 250, 250]}).then(SpoolSeries(maxFrames=500, stack=False)),
+        >>>      ]
+        >>>
+        >>>ActionManager.queue_actions(my_actions)
+        
+        Note that the first two tasks are independant -
+
+        '''
+        # make sure nice is in supported range.
+        assert((nice >= 0) and (nice <= 20))
+        
+        with self._lock:
+            # lock to prevent 'nice' collisions when queueing from separate threads.
+            
+            for j, action in enumerate(actions):
+                curTime = time.time()
+                expiry = curTime + timeout
+            
+                #make sure our timestamps strictly increment
+                self._timestamp = max(curTime, self._timestamp + 1e-3)
+            
+                #ensure FIFO behaviour for events with the same priority
+                nice_ = nice + self._timestamp * 1e-10
+
+                if np.isscalar(execute_after):
+                    after = execute_after
+                else:
+                    after = execute_after[j]
+
+                if after < curTime:
+                    #logger.debug('Queuing action %s for immediate execution (%s, %s)' % (functionName, curTime, execute_after))
+                    self.actionQueue.put_nowait((nice_, action, expiry, max_duration))
+                else:
+                    #logger.debug('Queuing action %s for delayed execution (%s, %s)' % (functionName, curTime, execute_after))
+                    self.scheduledQueue.put_nowait((after, (nice_, action, expiry, max_duration)))
+            
+        self.onQueueChange.send(self)
+
+    def remove_actions(self, actions):
+        """Remove a specific action from the queue
+        
+        Parameters
+        ----------
+        action : Action
+            The action to remove
+        """
+        
+        #TODO - do we need to lock here?
+        
+        for action in actions:
+            # try and remove from both queues
+            try:
+                self.actionQueue.remove(action)
+            except ValueError:
+                pass
+            try:
+                self.scheduledQueue.remove(action)
+            except ValueError:
+                pass
+
+        self.onQueueChange.send(self)
+        
+        
+    def Tick(self, **kwargs):
+        """Polling function to check if the current action is finished and, if so, start the next
+        action if available.
+        
+        Should be called regularly for a timer or event loop.
+        """
+        if self.paused:
+            return
+            
+        # queue scheduled actions which are now due
+        _n_queued = 0
+        while (self.scheduledQueue.qsize() > 0) and ((self.scheduledQueue.queue[0][0]) < time.time()):
+            execute_after, action = self.scheduledQueue.get_nowait()
+            print(time.time(), execute_after, action)
+            self.actionQueue.put_nowait(action)
+            _n_queued += 1
+
+        if _n_queued > 0:
+            self.onQueueChange.send(self) # TODO - avoid sending this signal here and below??
+        
+        if (self.isLastTaskDone is None) or self.isLastTaskDone():
+            try:
+                self.currentTask.finalise(self.scope())
+                self.currentTask = None
+                self.isLastTaskDone = None # prevent us from continuing to poll the last task if it's done
+            except AttributeError:
+                pass
+
+            try:
+                self.currentTask = self.actionQueue.get_nowait()
+                nice, action, expiry, max_duration = self.currentTask
+                self._cur_task_kill_time = time.time() + max_duration
+                self.onQueueChange.send(self)
+            except Queue.Empty:
+                self.currentTask = None
+                return
+            
+            if expiry > time.time():
+                logger.debug('Executing action: %s, %s' % (self.currentTask, action))
+                #fcn = eval('.'.join(['self.scope()', functionName]))
+                self.isLastTaskDone = action(self.scope())
+            else:
+                past_expire = time.time() - expiry
+                logger.debug('Action expired %f s ago, ignoring %s' % (past_expire,
+                                                                     self.currentTask))
+    
+    def _monitor_defunct(self):
+        """
+        polling thread method to check that if a task is being executed through
+        the action manager it isn't taking longer than its `max_duration`.
+        """
+        while self._monitoring:
+            if self.currentTask is not None:
+                #logger.debug('here, %f s until kill' % (self._cur_task_kill_time - time.time()))
+                if time.time() > self._cur_task_kill_time:
+                    self.scope().turnAllLasersOff()
+                    # pause and reset so we can start up again later
+                    self.paused = True
+                    self.isLastTaskDone = None
+                    self.currentTask = None
+                    self.onQueueChange.send(self)
+                    logger.error('task exceeded specified max duration')
+        
+            time.sleep(3)
+    
+    def __del__(self):
+        self._monitoring = False
+
+
+class ActionManagerWebWrapper(object):
+    def __init__(self, action_manager):
+        """ Wraps an action manager instance with server endpoints
+
+        Parameters
+        ----------
+        action_manager : ActionManager
+            action manager instance to wrap
+        """
+        self.action_manager = action_manager
+
+    @webframework.register_endpoint('/queue_actions', output_is_json=False)
+    def queue_actions(self, body, nice=10, timeout=1e6, max_duration=np.finfo(float).max, execute_after=0):
+        """
+        Add a list of actions to the queue
+        
+        Parameters
+        ----------
+        body - json formatted list of serialised actions (see example below)
+        nice
+        timeout
+        max_duration
+
+        Returns
+        -------
+        
+        
+        Examples
+        --------
+        
+        Body json
+        ^^^^^^^^^
+        
+        .. code-block:: json
+
+            [{'UpdateState':{'foo':'bar', 'then': {'SpoolSeries' : {...}}}]
+
+        """
+        import json
+        actions = [action_from_dict(a) for a in json.loads(body)]
+
+        self.action_manager.queue_actions(actions, nice=int(nice), 
+                                          timeout=float(timeout), 
+                                          max_duration=float(max_duration),
+                                          execute_after=execute_after)
+        
+    
+    @webframework.register_endpoint('/queue_action', output_is_json=False)
+    def queue_action(self, body):
+        """
+        adds an action to the queue
+
+        Parameters
+        ----------
+        body: str
+            json.dumps(dict) with the following keys:
+                function_name : str
+                    The name of a function relative to the microscope object.
+                    e.g. to `call scope.spoolController.start_spooling()`, you 
+                    would use a functionName of 'spoolController.start_spooling'.
+                    
+                    The function should either return `None` if the operation 
+                    has already completed, or function which evaluates to True 
+                    once the operation has completed. See 
+                    `scope.spoolController.start_spooling()` for an example.
+                args : dict, optional
+                    a dictionary of arguments to pass to `function_name`
+                nice : int, optional
+                    priority with which to execute the function, by default 10. 
+                    Functions with a lower nice value execute first.
+                timeout : float, optional
+                    A timeout in seconds from the current time at which the 
+                    action becomes irrelevant and should be ignored. By default
+                    1e6.
+                max_duration : float
+                    A generous estimate, in seconds, of how long the task might
+                    take, after which the lasers will be automatically turned 
+                    off and the action queue paused.
+        """
+        import json
+        params = json.loads(body)
+        function_name = params['function_name']
+        args = params.get('args', {})
+        nice = params.get('nice', 10.)
+        timeout = params.get('timeout', 1e6)
+        max_duration = params.get('max_duration', np.finfo(float).max)
+        execute_after = params.get('execute_after', 0)
+
+        self.action_manager.QueueAction(function_name, args, nice, timeout,
+                                        max_duration, execute_after)
+
+
+class ActionManagerServer(webframework.APIHTTPServer, ActionManagerWebWrapper):
+    def __init__(self, action_manager, port, bind_address=''):
+        """
+        Server process to expose queue_action functionality to everything on the
+        cluster network.
+
+        NOTE - this will likely not be around long, as it would be preferable to
+        add the ActionManagerWebWrapper to
+        `PYME.acquire_server.AcquireHTTPServer` and run a single server process
+        on the microscope computer.
+
+        Parameters
+        ----------
+        action_manager : ActionManager
+            already initialized
+        port : int
+            port to listen on
+        bind_address : str, optional
+            specifies ip address to listen on, by default '' will bind to local 
+            host.
+        """
+        webframework.APIHTTPServer.__init__(self, (bind_address, port))
+        ActionManagerWebWrapper.__init__(self, action_manager)
+        
+        self.daemon_threads = True
+        self._server_thread = threading.Thread(target=self._serve)
+        self._server_thread.daemon_threads = True
+        self._server_thread.start()
+
+    def _serve(self):
+        try:
+            logger.info('Starting ActionManager server on %s:%s' % (self.server_address[0], self.server_address[1]))
+            self.serve_forever()
+        finally:
+            logger.info('Shutting down ActionManager server ...')
+            self.shutdown()
+            self.server_close()
+

PYME/Acquire/ExecTools.py

@@ -0,0 +1,235 @@
+#!/usr/bin/python
+
+##################
+# ExecTools.py
+#
+# Copyright David Baddeley, 2009
+# d.baddeley@auckland.ac.nz
+#
+# This program 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.
+#
+# This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+##################
+
+#!/usr/bin/python
+"""Defines a few neat things to allow scripts to be executed in background during
+initialisation & to allow a user script directory"""
+import threading
+#import pythoncom
+
+import os
+import sys
+
+import logging
+logger = logging.getLogger(__name__)
+
+homedir = os.path.expanduser('~') #unix & possibly others ...
+execPath = []
+
+if 'USERPROFILE' in os.environ.keys(): #windows
+    homedir = os.environ['USERPROFILE']
+
+localScriptPath = os.path.join(homedir, 'PYMEScripts')
+if os.path.exists(localScriptPath):
+    sys.path.append(localScriptPath)
+    execPath.append(localScriptPath)
+
+#append global script directory _after_ user script directory so we use local init.py
+execPath.append(os.path.join(os.path.dirname(__file__), 'Scripts'))
+sys.path.append(os.path.join(os.path.dirname(__file__), 'Scripts'))
+
+global defGlobals
+global defLocals
+defGlobals = {}
+defLocals = {}
+
+#bgInitThreads = []
+bg_init_tasks = []
+#bgInitStatus = {}
+
+class HWNotPresent(Exception):
+    """An exception which, if thrown during initialisation, will result in a more
+    informative error message than just failure"""
+    pass
+
+
+def setDefaultNamespace(locals, globals):
+    """Populate the namespace in which the initialisation script will run.
+    
+    Parameters
+    ----------
+    locals : dict
+    globals : dict    
+    """
+    global defGlobals
+    global defLocals
+
+    defLocals = locals
+    defGlobals = globals
+
+from PYME.util.execfile import _exec, _execfile
+
+def execBG(codeObj, localVars = defLocals, globalVars = defGlobals):
+    """Executes a code object in a background thread, using the given namespace.
+    
+    Returns
+    -------
+    t : thread
+        The thread in which the code is executing (can be used with threading.join later)
+    """
+    t = threading.Thread(target=_exec, args = (codeObj, localVars, globalVars))
+    t.start()
+    return t
+
+def execFile(filename, localVars = defLocals, globalVars = defGlobals, then=None):
+    #fid = open(checkFilename(filename))
+    #code = fid.read()
+    #fid.close()
+
+    _execfile(filename, localVars, globalVars)
+    if then is not None:
+        then()
+
+def execFileBG(filename, localVars = defLocals, globalVars = defGlobals, then=None):
+    t = threading.Thread(target=execFile, args = (filename, localVars, globalVars, then))
+    t.start()
+    #return the thread so we can join it ...
+    return t
+
+def _bginit(name, codeObj):
+    global defGlobals
+    global defLocals
+    _exec("splash.SetMessage('%s', 'Initialising %s ...')" % (name,name), defGlobals, defLocals)
+    try:
+        _exec(codeObj, defGlobals, defLocals)
+        _exec("splash.SetMessage('%s', 'Initialising %s ... DONE')" % (name,name), defGlobals, defLocals)
+    except HWNotPresent:
+        _exec("splash.SetMessage('%s', 'Initialising %s ... NOT PRESENT')" % (name,name), defGlobals, defLocals)
+    except Exception as e:
+        _exec("splash.SetMessage('%s', 'Initialising %s ... FAIL')" % (name,name), defGlobals, defLocals)
+        raise e
+
+class BGInitTask(object):
+    TASK_RUNNING, TASK_DONE, TASK_FAILED, NOT_PRESENT = range(4)
+    _status_codes = ['', 'DONE', 'FAIL', 'NOT PRESENT']
+    
+    def __init__(self, name, codeObj):
+        self.name = name
+        self.status = self.TASK_RUNNING
+        self.codeObj = codeObj
+        
+        self.thread = threading.Thread(target=self._bginit)
+        self.thread.start()
+
+    def _bginit(self):
+        global defGlobals
+        global defLocals
+        self.status = self.TASK_RUNNING
+        try:
+            if callable(self.codeObj):
+                self.codeObj(defLocals['scope'])
+            else:
+                _exec(self.codeObj, defGlobals, defLocals)
+            self.status = self.TASK_DONE
+        except HWNotPresent:
+            self.status = self.NOT_PRESENT
+        except Exception as e:
+            self.status = self.TASK_FAILED
+            logger.exception('Error running background init task %s' % self.name)
+            raise e
+        
+    def get_status_msg(self):
+        return 'Initialising %s ... %s' % (self.name, self._status_codes[self.status])
+    
+    def join(self, timeout=None):
+        self.thread.join(timeout)
+        
+
+def InitBG(name, codeObj):
+    """Runs a portion of the initialisation code in a background thread
+    
+    Parameters
+    ----------
+    name : string
+        A descriptive name for the code block - e.g. 'Camera'
+    codeObj : string, compiled code object
+        The code that will be executed - something that `exec` understands
+    
+    Returns
+    -------
+    t : thread
+        The thread in which the code is executing (can be used with threading.join later)    
+    """
+    t = BGInitTask(name,codeObj)
+    bg_init_tasks.append(t)
+    return t
+    
+
+def joinBGInit():
+    """
+    Wait for all the initialisation tasks that bave been launched as background 
+    threads to complete.
+    """
+    for t in bg_init_tasks:
+        #print(t)
+        t.join()
+
+class GUIInitTask(object):
+    def __init__(self, name, codeObj):
+        self.name = name
+        self.codeObj = codeObj
+
+    def run(self, parent, scope):
+        """
+
+        Parameters
+        ----------
+        parent : PYME.Acquire.acquiremainframe.PYMEMainFrame, wx.Frame
+        scope : PYME.Acquire.microscope.Microscope
+        
+        """
+        global defGlobals
+        global defLocals
+        #try:
+        if callable(self.codeObj):
+            self.codeObj(parent, scope)
+        else:
+            _exec(self.codeObj, defGlobals, defLocals)
+
+        #except Exception as e:
+        #    raise e
+
+def InitGUI(code='', name=''):
+    """Add a piece of code to a list of items to be executed once the GUI is
+    up and running. Used to defer the initialisation of GUI components ascociated
+    with hardware items until they can be displayed.
+    
+    Parameters
+    ----------
+    codeObj : string, compiled code object
+        The code that will be executed - something that `exec` understands  
+    """
+    defLocals['postInit'].append(GUIInitTask(name, code))
+
+#define decorators
+def init_gui(name):
+    def _init_gui(fcn):
+        return InitGUI(fcn, name)
+        
+    return _init_gui
+        
+def init_hardware(name):
+    def _init_hw(fcn):
+        return InitBG(name, fcn)
+    
+    return _init_hw