instamatic-dev
diff --git a/‎THANKS.md
+1-1 b/‎THANKS.md
+1-1
diff --git a/‎src/instamatic/camera/camera_serval.py
+97-51 b/‎src/instamatic/camera/camera_serval.py
+97-51
diff --git a/‎src/instamatic/camera/videostream.py
+72-45 b/‎src/instamatic/camera/videostream.py
+72-45
@@ -1,7 +1,7 @@
 Code contributors
 -----------------
 
-See [Github contributors list](https://github.com/nipy/nipype/graphs/contributors)
+See [Github contributors list](https://github.com/instamatic-dev/instamatic/graphs/contributors)
 
 Special thanks
 --------------
 
@@ -2,13 +2,13 @@
 
 import atexit
 import logging
-from pathlib import Path
-from typing import Tuple
+import math
+from itertools import batched
+from typing import List, Optional, Sequence, Tuple, Union
 
 import numpy as np
 from serval_toolkit.camera import Camera as ServalCamera
 
-from instamatic import config
 from instamatic.camera.camera_base import CameraBase
 
 logger = logging.getLogger(__name__)
@@ -18,40 +18,100 @@
 # 2. `java -jar .\server\serv-2.1.3.jar`
 # 3. launch `instamatic`
 
+Ignore = object()  # sentinel object: informs `_get_images` to get a single image
+
 
 class CameraServal(CameraBase):
     """Interfaces with Serval from ASI."""
 
     streamable = True
+    MIN_EXPOSURE = 0.000001
+    MAX_EXPOSURE = 10.0
+    BAD_EXPOSURE_MSG = 'Requested exposure exceeds native Serval support (>0-10s)'
 
     def __init__(self, name='serval'):
         """Initialize camera module."""
         super().__init__(name)
-
         self.establish_connection()
-
-        msg = f'Camera {self.get_name()} initialized'
-        logger.info(msg)
-
+        self.dead_time = (
+            self.detector_config['TriggerPeriod'] - self.detector_config['ExposureTime']
+        )
+        logger.info(f'Camera {self.get_name()} initialized')
         atexit.register(self.release_connection)
 
-    def get_image(self, exposure=None, binsize=None, **kwargs) -> np.ndarray:
-        """Image acquisition routine. If the exposure and binsize are not
-        given, the default values are read from the config file.
+    def get_image(self, exposure: Optional[float] = None, **kwargs) -> np.ndarray:
+        """Image acquisition interface. If the exposure is not given, the
+        default value is read from the config file. Binning is ignored.
 
-        exposure:
+        exposure: `float` or `None`
             Exposure time in seconds.
-        binsize:
-            Which binning to use.
         """
-        if exposure is None:
-            exposure = self.default_exposure
-        if not binsize:
-            binsize = self.default_binsize
+        return self._get_images(n_frames=Ignore, exposure=exposure, **kwargs)
+
+    def get_movie(
+        self, n_frames: int, exposure: Optional[float] = None, **kwargs
+    ) -> List[np.ndarray]:
+        """Movie acquisition interface. If the exposure is not given, the
+        default value is read from the config file. Binning is ignored.
 
+        n_frames: `int`
+            Number of frames to collect
+        exposure: `float` or `None`
+            Exposure time in seconds.
+        """
+        return self._get_images(n_frames=n_frames, exposure=exposure, **kwargs)
+
+    def _get_images(
+        self,
+        n_frames: Union[int, Ignore],
+        exposure: Optional[float] = None,
+        **kwargs,
+    ) -> Union[np.ndarray, List[np.ndarray]]:
+        """General media acquisition dispatcher for other protected methods."""
+        n: int = 1 if n_frames is Ignore else n_frames
+        e: float = self.default_exposure if exposure is None else exposure
+
+        if n_frames == 0:  # single image is communicated via n_frames = Ignore
+            return []
+
+        elif e < self.MIN_EXPOSURE:
+            logger.warning('%s: %d', self.BAD_EXPOSURE_MSG, e)
+            if n_frames is Ignore:
+                return self._get_image_null(exposure=e, **kwargs)
+            return [self._get_image_null(exposure=e, **kwargs) for _ in range(n)]
+
+        elif e > self.MAX_EXPOSURE:
+            logger.warning('%s: %d', self.BAD_EXPOSURE_MSG, e)
+            n1 = math.ceil(e / self.MAX_EXPOSURE)
+            e = (e + self.dead_time) / n1 - self.dead_time
+            images = self._get_image_stack(n_frames=n * n1, exposure=e, **kwargs)
+            if n_frames is Ignore:
+                return self._spliced_sum(images, exposure=e)
+            return [self._spliced_sum(i, exposure=e) for i in batched(images, n1)]
+
+        else:  # if exposure is within limits
+            if n_frames is Ignore:
+                return self._get_image_single(exposure=e, **kwargs)
+            return self._get_image_stack(n_frames=n, exposure=e, **kwargs)
+
+    def _spliced_sum(self, arrays: Sequence[np.ndarray], exposure: float) -> np.ndarray:
+        """Sum a series of arrays while applying a dead time correction."""
+        array_sum = sum(arrays, np.zeros_like(arrays[0]))
+        total_exposure = len(arrays) * exposure + (len(arrays) - 1) * self.dead_time
+        live_fraction = len(arrays) * exposure / total_exposure
+        return (array_sum / live_fraction).astype(arrays[0].dtype)
+
+    def _get_image_null(self, **_) -> np.ndarray:
+        logger.debug('Creating a synthetic image with zero counts')
+        return np.zeros(shape=self.get_image_dimensions(), dtype=np.int32)
+
+    def _get_image_single(self, exposure: float, **_) -> np.ndarray:
+        """Request a single frame in the mode in a trigger collection mode."""
+        logger.debug(f'Collecting a single image with exposure {exposure} s')
         # Upload exposure settings (Note: will do nothing if no change in settings)
         self.conn.set_detector_config(
-            ExposureTime=exposure, TriggerPeriod=exposure + 0.00050001
+            ExposureTime=exposure,
+            TriggerPeriod=exposure + self.dead_time,
         )
 
         # Check if measurement is running. If not: start
@@ -67,31 +127,23 @@ def get_image(self, exposure=None, binsize=None, **kwargs) -> np.ndarray:
         arr = np.array(img)
         return arr
 
-    def get_movie(self, n_frames, exposure=None, binsize=None, **kwargs):
-        """Movie acquisition routine. If the exposure and binsize are not
-        given, the default values are read from the config file.
-
-        n_frames:
-            Number of frames to collect
-        exposure:
-            Exposure time in seconds.
-        binsize:
-            Which binning to use.
-        """
-        if exposure is None:
-            exposure = self.default_exposure
-        if not binsize:
-            binsize = self.default_binsize
-
-        self.conn.set_detector_config(TriggerMode='CONTINUOUS')
-
-        arr = self.conn.get_images(
-            nTriggers=n_frames,
+    def _get_image_stack(self, n_frames: int, exposure: float, **_) -> list[np.ndarray]:
+        """Get a series of images in a mode with minimal dead time."""
+        logger.debug(f'Collecting {n_frames} images with exposure {exposure} s')
+        mode = 'AUTOTRIGSTART_TIMERSTOP' if self.dead_time else 'CONTINUOUS'
+        self.conn.measurement_stop()
+        previous_config = self.conn.detector_config
+        self.conn.set_detector_config(
+            TriggerMode=mode,
             ExposureTime=exposure,
-            TriggerPeriod=exposure,
+            TriggerPeriod=exposure + self.dead_time,
+            nTriggers=n_frames,
         )
-
-        return arr
+        self.conn.measurement_start()
+        images = self.conn.get_image_stream(nTriggers=n_frames, disable_tqdm=True)
+        self.conn.measurement_stop()
+        self.conn.set_detector_config(**previous_config)
+        return [np.array(image) for image in images]
 
     def get_image_dimensions(self) -> Tuple[int, int]:
         """Get the binned dimensions reported by the camera."""
@@ -111,23 +163,17 @@ def establish_connection(self) -> None:
             bpc_file_path=self.bpc_file_path, dacs_file_path=self.dacs_file_path
         )
         self.conn.set_detector_config(**self.detector_config)
-        # Check pixel depth. If 24 bit mode is used, the pgm format does not work
-        # (has support up to 16 bits) so use tiff in that case. In other cases (1, 6, 12 bits)
-        # use pgm since it is more efficient
-        self.pixel_depth = self.conn.detector_config['PixelDepth']
-        if self.pixel_depth == 24:
-            file_format = 'tiff'
-        else:
-            file_format = 'pgm'
+
         self.conn.destination = {
             'Image': [
                 {
                     # Where to place the preview files (HTTP end-point: GET localhost:8080/measurement/image)
                     'Base': 'http://localhost',
                     # What (image) format to provide the files in.
-                    'Format': file_format,
+                    'Format': 'tiff',
                     # What data to build a frame from
                     'Mode': 'count',
+                    # 'QueueSize': 2,
                 }
             ],
         }
 
@@ -2,21 +2,40 @@
 
 import atexit
 import threading
+from dataclasses import dataclass
+from typing import List, Optional, Union
+
+import numpy as np
 
 from instamatic.camera.camera_base import CameraBase
 
 from .camera import Camera
 
 
-class ImageGrabber:
+@dataclass(frozen=True)
+class MediaRequest:
+    n_frames: Optional[int] = None
+    exposure: Optional[float] = None
+    binsize: Optional[int] = None
+
+
+class ImageRequest(MediaRequest):
+    """To be used when requesting a single image via `get_image`"""
+
+
+class MovieRequest(MediaRequest):
+    """To be used when requesting an image series via `get_movie`"""
+
+
+class MediaGrabber:
     """Continuously read out the camera for continuous acquisition.
 
     When the continousCollectionEvent is set, the camera will set the
     exposure to `frametime`, otherwise, the default camera exposure is
     used.
 
-    The callback function is used to send the frame back to the parent
-    routine.
+    The callback function is used to send the media, either image or movie,
+    back to the parent routine.
     """
 
     def __init__(self, cam: CameraBase, callback, frametime: float = 0.05):
@@ -37,9 +56,8 @@ def __init__(self, cam: CameraBase, callback, frametime: float = 0.05):
         self.stash = None
 
         self.frametime = frametime
-        self.exposure = self.frametime
-        self.binsize = self.cam.default_binsize
-
+        self.request: Optional[MediaRequest] = None
+        self.requested_media = None
         self.lock = threading.Lock()
 
         self.stopEvent = threading.Event()
@@ -50,14 +68,22 @@ def __init__(self, cam: CameraBase, callback, frametime: float = 0.05):
     def run(self):
         while not self.stopEvent.is_set():
             if self.acquireInitiateEvent.is_set():
+                r = self.request
                 self.acquireInitiateEvent.clear()
-
-                frame = self.cam.get_image(exposure=self.exposure, binsize=self.binsize)
-                self.callback(frame, acquire=True)
+                e = r.exposure if r.exposure else self.default_exposure
+                b = r.binsize if r.binsize else self.default_binsize
+                if isinstance(r, ImageRequest):
+                    media = self.cam.get_image(exposure=e, binsize=b)
+                else:  # isinstance(r, MovieRequest):
+                    n = r.n_frames if r.n_frames else 1
+                    media = self.cam.get_movie(n_frames=n, exposure=e, binsize=b)
+                self.callback(media, request=r)
 
             elif not self.continuousCollectionEvent.is_set():
-                frame = self.cam.get_image(exposure=self.frametime, binsize=self.binsize)
-                self.callback(frame)
+                frame = self.cam.get_image(
+                    exposure=self.frametime, binsize=self.default_binsize
+                )
+                self.callback(frame, request=None)
 
     def start_loop(self):
         self.thread = threading.Thread(target=self.run, args=(), daemon=True)
@@ -71,14 +97,10 @@ def stop(self):
 class VideoStream(threading.Thread):
     """Handle the continuous stream of incoming data from the ImageGrabber."""
 
-    def __init__(self, cam='simulate'):
+    def __init__(self, cam: Union[CameraBase, str] = 'simulate'):
         threading.Thread.__init__(self)
 
-        if isinstance(cam, str):
-            self.cam = Camera(name=cam)
-        else:
-            self.cam = cam
-
+        self.cam: CameraBase = Camera(name=cam) if isinstance(cam, str) else cam
         self.lock = threading.Lock()
 
         self.default_exposure = self.cam.default_exposure
@@ -109,43 +131,48 @@ def __getattr__(self, attrname):
     def start(self):
         self.grabber.start_loop()
 
-    def send_frame(self, frame, acquire=False):
-        if acquire:
-            self.grabber.lock.acquire(True)
-            self.acquired_frame = self.frame = frame
-            self.grabber.lock.release()
-            self.grabber.acquireCompleteEvent.set()
-        else:
-            self.grabber.lock.acquire(True)
-            self.frame = frame
-            self.grabber.lock.release()
-
-    def setup_grabber(self) -> ImageGrabber:
-        grabber = ImageGrabber(self.cam, callback=self.send_frame, frametime=self.frametime)
+    def send_media(
+        self,
+        media: Union[np.ndarray, List[np.ndarray]],
+        request: Optional[MediaRequest] = None,
+    ) -> None:
+        """Callback function of `self.grabber` that handles grabbed media."""
+        with self.grabber.lock:
+            if request is None:
+                self.frame = media
+            elif isinstance(request, ImageRequest):
+                self.requested_media = self.frame = media
+                self.grabber.acquireCompleteEvent.set()
+            else:  # isinstance(request, MovieRequest):
+                self.requested_media = media
+                self.frame = media[-1]
+                self.grabber.acquireCompleteEvent.set()
+
+    def setup_grabber(self) -> MediaGrabber:
+        grabber = MediaGrabber(self.cam, callback=self.send_media, frametime=self.frametime)
         atexit.register(grabber.stop)
         return grabber
 
     def get_image(self, exposure=None, binsize=None):
-        current_frametime = self.grabber.frametime
+        request = ImageRequest(exposure=exposure, binsize=binsize)
+        return self._get_media(request)
 
-        # set to 0 to prevent it lagging data acquisition
-        self.grabber.frametime = 0
-        if exposure:
-            self.grabber.exposure = exposure
-        if binsize:
-            self.grabber.binsize = binsize
+    def get_movie(self, n_frames: int, exposure=None, binsize=None):
+        request = MovieRequest(n_frames=n_frames, exposure=exposure, binsize=binsize)
+        return self._get_media(request)
 
+    def _get_media(self, request: MediaRequest) -> Union[np.ndarray, List[np.ndarray]]:
+        self.block()  # Stop the passive collection during request acquisition
+        self.grabber.request = request
         self.grabber.acquireInitiateEvent.set()
-
         self.grabber.acquireCompleteEvent.wait()
-
-        self.grabber.lock.acquire(True)
-        frame = self.acquired_frame
-        self.grabber.lock.release()
-
+        with self.grabber.lock:
+            media = self.requested_media
+            self.requested_media = None
+        self.grabber.request = None
         self.grabber.acquireCompleteEvent.clear()
-        self.grabber.frametime = current_frametime
-        return frame
+        self.unblock()  # Resume the passive collection
+        return media
 
     def update_frametime(self, frametime):
         self.frametime = frametime