imswitchclient 0.1.7__tar.gz → 0.2.0__tar.gz

{imswitchclient-0.1.7 → imswitchclient-0.2.0}/MANIFEST.in

@@ -1,6 +1,4 @@
 include AUTHORS.rst
-include CONTRIBUTING.rst
-include HISTORY.rst
 include LICENSE
 include README.rst
 

{imswitchclient-0.1.7 → imswitchclient-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imswitchclient
-Version: 0.1.7
+Version: 0.2.0
 Summary: This is a package that connects ImSwitch's REST API to the rest of the world (e.g. jupyter lab)
 Home-page: https://github.com/openuc2/imswitchclient
 Author: Benedict Diederich
@@ -23,7 +23,7 @@ Requires-Dist: Pillow
 Requires-Dist: numpy
 Requires-Dist: matplotlib
 Requires-Dist: opencv-python
-Requires-Dist: python-socketio==5.12.1
+Requires-Dist: python-socketio
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -81,10 +81,23 @@ pip install imswitchclient
 ```python
 import imswitchclient.ImSwitchClient as imc
 
-# Initialize the client
-client = imc.ImSwitchClient(host="0.0.0.0", isHttps=True, port=8001)
+# A full URL is the least ambiguous way to say where ImSwitch is:
+client = imc.ImSwitchClient("http://localhost:8001/imswitch/api")   # local instance
+client = imc.ImSwitchClient("http://192.168.178.76/imswitch/api")   # Raspberry Pi / Docker behind Caddy (port 80)
+client = imc.ImSwitchClient("https://imswitch.openuc2.com")         # https -> port 443
+
+# Without arguments it uses $IMSWITCH_API_URL - which ImSwitch sets for the
+# notebooks it serves itself - and otherwise http://localhost:8001/imswitch/api.
+client = imc.ImSwitchClient()
+
+# The classic form still works; a bare host name keeps the old defaults (port 8001, http).
+client = imc.ImSwitchClient(host="192.168.178.76", port=80, isHttps=False)
+
+print(client.base_uri)   # http://192.168.178.76:80/imswitch/api
 ```
 
+Pass `socket_port=` when Socket.IO is not served on the API port.
+
 ### Example: Moving a Stage and Acquiring an Image
 
 ```python
@@ -162,18 +175,30 @@ The ImSwitch API provides access to various components:
 - `getAllDeviceNames()` - Get all available positioners.
 - `getPositionerPositions()` - Get current position.
 - `movePositioner(name, axis, value, is_absolute, is_blocking)` - Move the stage.
+- `moveRelativeXY(dx, dy, positioner_name, is_blocking, speed)` - Relative X/Y move in µm.
+- `stop(name, axis)` / `stopAllAxes(name)` - Stop one axis / every axis.
 - `homeAxis(name, axis, is_blocking)` - Home the positioner.
 
 ### Lasers Manager
 - `getLaserNames()` - Get available lasers.
 - `setLaserActive(name, status)` - Turn laser on/off.
 - `setLaserValue(name, value)` - Set laser intensity.
+- `getLaserValueRanges(name)` / `getLaserValue(name)` / `getLaserActive(name)` - Read back.
+- `setLaserOn(name, value)` / `setLaserOff(name)` - Value and on/off in one call.
+- `runLaserFor(name, value, duration, on_tick, stop_event)` - Run a PWM channel (pump, valve)
+  for a fixed time; always switched off afterwards, also on errors or interruption.
 
 ### Recording Manager
 - `snapNumpyToFastAPI(resizeFactor)` - Capture an image as numpy array.
 - `startRecording(save_format)` - Begin recording with optional save format (SaveFormat enum).
 - `stopRecording()` - Stop recording.
-- `snapImageToPath(file_name)` - Snap image and save to specified path.
+- `snapImageToPath(file_name, save_format, return_preview)` - Snap image and save to specified path.
+- `snapAndWait(file_name, save_format, poll, timeout, on_progress, stop_event)` - Snap in the
+  background on the server and wait for it. Use for long exposures (minutes to hours); an
+  interrupt, `stop_event` or timeout cancels the exposure on the server.
+- `startSnap(...)` / `getSnapStatus(job_id)` / `cancelSnap(job_id)` - The same, step by step.
+- `previewToNumpy(result)` - 8-bit preview of a snap result as numpy array.
+- `downloadImage(relative_file_path)` / `downloadFile(...)` - Fetch the saved file (full bit depth).
 - `startVideoStream()` - Start MJPEG video stream.
 - `stopVideoStream()` - Stop MJPEG video stream.
 - `getVideoFrame()` - Get current frame from video stream.
@@ -186,6 +211,7 @@ The recording manager supports multiple save formats:
 - `SaveFormat.MP4` - MP4 video format
 - `SaveFormat.PNG` - PNG format
 - `SaveFormat.JPG` - JPEG format
+- `SaveFormat.OME_TIFF`, `SaveFormat.OME_ZARR`, `SaveFormat.STITCHED_TIFF`
 
 ### Settings Manager
 - `getDetectorNames()` - Get available detector names.
@@ -194,6 +220,25 @@ The recording manager supports multiple save formats:
 - `setDetectorGain(detector_name, gain)` - Set detector gain.
 - `setDetectorParameter(detector_name, parameter_name, value)` - Set generic detector parameter.
 - `setDetectorROI(detector_name, x, y, w, h)` - Set detector Region of Interest.
+- `getDetectorParameter(parameter_name, detector_name)` - Read one parameter from the camera.
+- `setDetectorMode(detector_name, is_auto)` / `setDetectorExposureOnce(detector_name)` - Auto exposure.
+- `getCameraTemperature(detector_name)` / `setCameraTargetTemperature(temperature_c)` - Cooled cameras.
+- `getDetectorParameterTree(detector_name)` / `setDetectorParameterValue(name, value)` - Typed access
+  to every camera parameter.
+
+### Live View Manager
+- `startLiveView(detector_name, protocol, params, force)` / `stopLiveView(detector_name)`
+- `getLiveViewActive()`, `getActiveStreams()`, `getLongExposureInfo(detector_name)`
+
+### UC2 Config Manager
+- `getBusStatus()` - CAN-bus power and emergency-stop state.
+- `setBusPower(enable)` / `setBusPowerAndWait(enable, settle)` - Switch the power of all CAN
+  slave boards (motors, LED/laser boards). Raises if the board refuses.
+- `isBoardConnected()`, `getBoardTemperature()`
+
+### Autofocus Manager
+- `autoFocusAndWait(rangez, resolutionz, ...)` - Server-side Z scan around the current focus,
+  waits for the result. `autoFocus`, `getAutofocusStatus`, `stopAutofocus` for manual control.
 
 ### View Manager
 - `setLiveViewActive(active)` - Enable/disable live view.
@@ -208,6 +253,30 @@ The recording manager supports multiple save formats:
 - `setLED(led_id, state)` - Set specific LED with ID and state.
 - `setSpecial(pattern, intensity, get_return)` - Set special LED pattern.
 
+### Smart microscopy helpers (`imswitchclient.smart`)
+Building blocks for closed-loop experiments; they work on numpy frames and plain callables and are
+tested without a microscope (`tests/test_smart.py`).
+
+```python
+from imswitchclient import smart
+snap = smart.make_snap(client)                    # -> float32 frame
+move = smart.make_relative_mover(client)          # move(dx_um, dy_um), blocking
+
+cal = smart.StageCameraCalibration.measure(snap, move, step_um=50)
+obj = smart.find_objects(snap())[0]               # largest blob
+move(*cal.move_to_center(*obj["offset"]))         # centre it - rotation and flips included
+```
+
+- `StageCameraCalibration` - pixel offsets <-> stage moves, measured on the live images.
+- `phase_correlate(a, b)` - sub-pixel image shift.
+- `find_objects(frame)` / `foreground_mask(frame)` - blob detection.
+- `EmptyFieldReference(empty_frame).coverage(frame)` - how much of a field is sample (0..1).
+- `SafetyBox` - limits closed-loop moves to a square around the start.
+- `Mosaic(frames, positions, cal)` - quick overview of frames placed by stage position.
+
+The ImSwitch notebooks `ImSwitch_Smart_ObjectTracking`, `ImSwitch_Smart_PathFollowing` and
+`ImSwitch_Smart_AdaptiveImaging` show them in use.
+
 ### Communication Manager
 - `acquireImage()` - Acquire an image through communication channel.
 - `getImage()` - Get an image from communication channel.
@@ -246,7 +315,7 @@ import numpy as np
 import matplotlib.pyplot as plt
 
 # Initialize client
-client = imc.ImSwitchClient(host="192.168.1.100", port=8001)
+client = imc.ImSwitchClient("http://192.168.1.100:8001/imswitch/api")
 
 # XY scanning parameters
 start_x, start_y = 0, 0  # Starting position in µm
@@ -309,7 +378,7 @@ import imswitchclient.ImSwitchClient as imc
 import numpy as np
 
 # Initialize client
-client = imc.ImSwitchClient(host="192.168.1.100", port=8001)
+client = imc.ImSwitchClient("http://192.168.1.100:8001/imswitch/api")
 
 def calculate_focus_score(image):
     """Calculate focus score using Laplacian variance"""
@@ -362,7 +431,7 @@ from imswitchclient.recordingManager import SaveFormat
 import time
 
 # Initialize client
-client = imc.ImSwitchClient(host="192.168.1.100", port=8001)
+client = imc.ImSwitchClient("http://192.168.1.100:8001/imswitch/api")
 
 # Setup LED illumination
 client.ledMatrixManager.setAllLEDOff()
@@ -407,7 +476,7 @@ import imswitchclient.ImSwitchClient as imc
 from imswitchclient.recordingManager import SaveFormat
 
 # Initialize client
-client = imc.ImSwitchClient(host="192.168.1.100", port=8001)
+client = imc.ImSwitchClient("http://192.168.1.100:8001/imswitch/api")
 
 # Define multiple positions of interest
 positions = [

{imswitchclient-0.1.7 → imswitchclient-0.2.0}/README.md

@@ -42,10 +42,23 @@ pip install imswitchclient
 ```python
 import imswitchclient.ImSwitchClient as imc
 
-# Initialize the client
-client = imc.ImSwitchClient(host="0.0.0.0", isHttps=True, port=8001)
+# A full URL is the least ambiguous way to say where ImSwitch is:
+client = imc.ImSwitchClient("http://localhost:8001/imswitch/api")   # local instance
+client = imc.ImSwitchClient("http://192.168.178.76/imswitch/api")   # Raspberry Pi / Docker behind Caddy (port 80)
+client = imc.ImSwitchClient("https://imswitch.openuc2.com")         # https -> port 443
+
+# Without arguments it uses $IMSWITCH_API_URL - which ImSwitch sets for the
+# notebooks it serves itself - and otherwise http://localhost:8001/imswitch/api.
+client = imc.ImSwitchClient()
+
+# The classic form still works; a bare host name keeps the old defaults (port 8001, http).
+client = imc.ImSwitchClient(host="192.168.178.76", port=80, isHttps=False)
+
+print(client.base_uri)   # http://192.168.178.76:80/imswitch/api
 ```
 
+Pass `socket_port=` when Socket.IO is not served on the API port.
+
 ### Example: Moving a Stage and Acquiring an Image
 
 ```python
@@ -123,18 +136,30 @@ The ImSwitch API provides access to various components:
 - `getAllDeviceNames()` - Get all available positioners.
 - `getPositionerPositions()` - Get current position.
 - `movePositioner(name, axis, value, is_absolute, is_blocking)` - Move the stage.
+- `moveRelativeXY(dx, dy, positioner_name, is_blocking, speed)` - Relative X/Y move in µm.
+- `stop(name, axis)` / `stopAllAxes(name)` - Stop one axis / every axis.
 - `homeAxis(name, axis, is_blocking)` - Home the positioner.
 
 ### Lasers Manager
 - `getLaserNames()` - Get available lasers.
 - `setLaserActive(name, status)` - Turn laser on/off.
 - `setLaserValue(name, value)` - Set laser intensity.
+- `getLaserValueRanges(name)` / `getLaserValue(name)` / `getLaserActive(name)` - Read back.
+- `setLaserOn(name, value)` / `setLaserOff(name)` - Value and on/off in one call.
+- `runLaserFor(name, value, duration, on_tick, stop_event)` - Run a PWM channel (pump, valve)
+  for a fixed time; always switched off afterwards, also on errors or interruption.
 
 ### Recording Manager
 - `snapNumpyToFastAPI(resizeFactor)` - Capture an image as numpy array.
 - `startRecording(save_format)` - Begin recording with optional save format (SaveFormat enum).
 - `stopRecording()` - Stop recording.
-- `snapImageToPath(file_name)` - Snap image and save to specified path.
+- `snapImageToPath(file_name, save_format, return_preview)` - Snap image and save to specified path.
+- `snapAndWait(file_name, save_format, poll, timeout, on_progress, stop_event)` - Snap in the
+  background on the server and wait for it. Use for long exposures (minutes to hours); an
+  interrupt, `stop_event` or timeout cancels the exposure on the server.
+- `startSnap(...)` / `getSnapStatus(job_id)` / `cancelSnap(job_id)` - The same, step by step.
+- `previewToNumpy(result)` - 8-bit preview of a snap result as numpy array.
+- `downloadImage(relative_file_path)` / `downloadFile(...)` - Fetch the saved file (full bit depth).
 - `startVideoStream()` - Start MJPEG video stream.
 - `stopVideoStream()` - Stop MJPEG video stream.
 - `getVideoFrame()` - Get current frame from video stream.
@@ -147,6 +172,7 @@ The recording manager supports multiple save formats:
 - `SaveFormat.MP4` - MP4 video format
 - `SaveFormat.PNG` - PNG format
 - `SaveFormat.JPG` - JPEG format
+- `SaveFormat.OME_TIFF`, `SaveFormat.OME_ZARR`, `SaveFormat.STITCHED_TIFF`
 
 ### Settings Manager
 - `getDetectorNames()` - Get available detector names.
@@ -155,6 +181,25 @@ The recording manager supports multiple save formats:
 - `setDetectorGain(detector_name, gain)` - Set detector gain.
 - `setDetectorParameter(detector_name, parameter_name, value)` - Set generic detector parameter.
 - `setDetectorROI(detector_name, x, y, w, h)` - Set detector Region of Interest.
+- `getDetectorParameter(parameter_name, detector_name)` - Read one parameter from the camera.
+- `setDetectorMode(detector_name, is_auto)` / `setDetectorExposureOnce(detector_name)` - Auto exposure.
+- `getCameraTemperature(detector_name)` / `setCameraTargetTemperature(temperature_c)` - Cooled cameras.
+- `getDetectorParameterTree(detector_name)` / `setDetectorParameterValue(name, value)` - Typed access
+  to every camera parameter.
+
+### Live View Manager
+- `startLiveView(detector_name, protocol, params, force)` / `stopLiveView(detector_name)`
+- `getLiveViewActive()`, `getActiveStreams()`, `getLongExposureInfo(detector_name)`
+
+### UC2 Config Manager
+- `getBusStatus()` - CAN-bus power and emergency-stop state.
+- `setBusPower(enable)` / `setBusPowerAndWait(enable, settle)` - Switch the power of all CAN
+  slave boards (motors, LED/laser boards). Raises if the board refuses.
+- `isBoardConnected()`, `getBoardTemperature()`
+
+### Autofocus Manager
+- `autoFocusAndWait(rangez, resolutionz, ...)` - Server-side Z scan around the current focus,
+  waits for the result. `autoFocus`, `getAutofocusStatus`, `stopAutofocus` for manual control.
 
 ### View Manager
 - `setLiveViewActive(active)` - Enable/disable live view.
@@ -169,6 +214,30 @@ The recording manager supports multiple save formats:
 - `setLED(led_id, state)` - Set specific LED with ID and state.
 - `setSpecial(pattern, intensity, get_return)` - Set special LED pattern.
 
+### Smart microscopy helpers (`imswitchclient.smart`)
+Building blocks for closed-loop experiments; they work on numpy frames and plain callables and are
+tested without a microscope (`tests/test_smart.py`).
+
+```python
+from imswitchclient import smart
+snap = smart.make_snap(client)                    # -> float32 frame
+move = smart.make_relative_mover(client)          # move(dx_um, dy_um), blocking
+
+cal = smart.StageCameraCalibration.measure(snap, move, step_um=50)
+obj = smart.find_objects(snap())[0]               # largest blob
+move(*cal.move_to_center(*obj["offset"]))         # centre it - rotation and flips included
+```
+
+- `StageCameraCalibration` - pixel offsets <-> stage moves, measured on the live images.
+- `phase_correlate(a, b)` - sub-pixel image shift.
+- `find_objects(frame)` / `foreground_mask(frame)` - blob detection.
+- `EmptyFieldReference(empty_frame).coverage(frame)` - how much of a field is sample (0..1).
+- `SafetyBox` - limits closed-loop moves to a square around the start.
+- `Mosaic(frames, positions, cal)` - quick overview of frames placed by stage position.
+
+The ImSwitch notebooks `ImSwitch_Smart_ObjectTracking`, `ImSwitch_Smart_PathFollowing` and
+`ImSwitch_Smart_AdaptiveImaging` show them in use.
+
 ### Communication Manager
 - `acquireImage()` - Acquire an image through communication channel.
 - `getImage()` - Get an image from communication channel.
@@ -207,7 +276,7 @@ import numpy as np
 import matplotlib.pyplot as plt
 
 # Initialize client
-client = imc.ImSwitchClient(host="192.168.1.100", port=8001)
+client = imc.ImSwitchClient("http://192.168.1.100:8001/imswitch/api")
 
 # XY scanning parameters
 start_x, start_y = 0, 0  # Starting position in µm
@@ -270,7 +339,7 @@ import imswitchclient.ImSwitchClient as imc
 import numpy as np
 
 # Initialize client
-client = imc.ImSwitchClient(host="192.168.1.100", port=8001)
+client = imc.ImSwitchClient("http://192.168.1.100:8001/imswitch/api")
 
 def calculate_focus_score(image):
     """Calculate focus score using Laplacian variance"""
@@ -323,7 +392,7 @@ from imswitchclient.recordingManager import SaveFormat
 import time
 
 # Initialize client
-client = imc.ImSwitchClient(host="192.168.1.100", port=8001)
+client = imc.ImSwitchClient("http://192.168.1.100:8001/imswitch/api")
 
 # Setup LED illumination
 client.ledMatrixManager.setAllLEDOff()
@@ -368,7 +437,7 @@ import imswitchclient.ImSwitchClient as imc
 from imswitchclient.recordingManager import SaveFormat
 
 # Initialize client
-client = imc.ImSwitchClient(host="192.168.1.100", port=8001)
+client = imc.ImSwitchClient("http://192.168.1.100:8001/imswitch/api")
 
 # Define multiple positions of interest
 positions = [

imswitchclient-0.2.0/imswitchclient/ImSwitchClient.py

@@ -0,0 +1,142 @@
+import os
+import requests
+import logging
+from urllib.parse import urlsplit
+from .positionersManager import positionersManager
+from .recordingManager import recordingManager
+from .lasersManager import lasersManager
+from .histoscanManager import histoscanManager
+from .experimentController import ExperimentController
+from .mdaController import mdaController
+from .objectiveController import objectiveController
+from .ledMatrixManager import ledMatrixManager
+from .settingsManager import settingsManager
+from .readnoiseManager import readnoiseManager
+from .viewManager import viewManager
+from .communicationManager import communicationManager
+from .uc2ConfigManager import uc2ConfigManager
+from .liveViewManager import liveViewManager
+from .autofocusManager import autofocusManager
+from .socketClient import socketClient
+
+DEFAULT_ROUTE = "/imswitch/api"
+DEFAULT_PORT = 8001
+
+
+def parseBaseUrl(url, defaultRoute=DEFAULT_ROUTE):
+    """Split a base URL into (host, port, isHttps, route).
+
+    Takes whatever you can copy out of the browser's address bar::
+
+        http://192.168.178.76/imswitch/api/docs -> ('192.168.178.76', 80, False, '/imswitch/api')
+        http://100.100.43.118:8001             -> ('100.100.43.118', 8001, False, '/imswitch/api')
+        https://imswitch.openuc2.com           -> ('imswitch.openuc2.com', 443, True, '/imswitch/api')
+    """
+    parts = urlsplit(url if "://" in url else f"http://{url}")
+    isHttps = parts.scheme == "https"
+    route = parts.path.rstrip("/")
+    for suffix in ("/docs", "/redoc", "/openapi.json"):
+        if route.endswith(suffix):
+            route = route[: -len(suffix)]
+    port = parts.port or (443 if isHttps else 80)
+    return parts.hostname, port, isHttps, route or defaultRoute
+
+
+class ImSwitchClient(object):
+    def __init__(self, host=None, isHttps=None, port=None, route=None, socket_port=None):
+        """Connect to an ImSwitch server.
+
+        `host` may be a full URL, which is the least error-prone way to reach a
+        server that is not on the default port::
+
+            ImSwitchClient("http://192.168.178.76/imswitch/api")  # Docker/Caddy on port 80
+            ImSwitchClient("http://100.100.43.118:8001")          # local instance
+            ImSwitchClient("imswitch.openuc2.com")                # host only -> port 8001
+            ImSwitchClient()                                      # $IMSWITCH_API_URL, else localhost:8001
+
+        A plain host name keeps the historical defaults (port 8001, http). A URL
+        without a port uses the scheme's port (80/443). Explicit `isHttps`,
+        `port` and `route` arguments always win over what the URL says.
+        `socket_port` defaults to the API port - set it when Socket.IO is not
+        proxied on the same port.
+        """
+        url = host if (host and "://" in host) else None
+        if url is None and host is None:
+            url = os.environ.get("IMSWITCH_API_URL") or None
+        if url:
+            urlHost, urlPort, urlHttps, urlRoute = parseBaseUrl(url)
+        else:
+            urlHost, urlPort, urlHttps, urlRoute = host, None, None, None
+
+        self.host = urlHost or "localhost"
+        self.isHttps = isHttps if isHttps is not None else bool(urlHttps)
+        self.port = port if port is not None else (urlPort or (443 if self.isHttps else DEFAULT_PORT))
+        self.route = (route or urlRoute or DEFAULT_ROUTE).rstrip("/")
+        self.get_json(self.base_swagger_uri)
+
+        logging.info(f"Connecting to microscope at {self.base_uri}")
+        
+        # register managers
+        self.positionersManager = positionersManager(self)
+        self.recordingManager = recordingManager(self)
+        self.lasersManager = lasersManager(self)
+        self.histoscanManager = histoscanManager(self)
+        self.experimentController = ExperimentController(self)
+        self.mdaController = mdaController(self)
+        self.objectiveController = objectiveController(self)
+        self.ledMatrixManager = ledMatrixManager(self)
+        self.settingsManager = settingsManager(self)
+        self.readnoiseManager = readnoiseManager(self)
+        self.viewManager = viewManager(self)
+        self.communicationManager = communicationManager(self)
+        self.uc2ConfigManager = uc2ConfigManager(self)
+        self.liveViewManager = liveViewManager(self)
+        self.autofocusManager = autofocusManager(self)
+
+        # initialize Socket.IO client
+        try:
+            self.socketClient = socketClient(host=self.host,
+                                             port=socket_port or self.port,
+                                             isHttps=self.isHttps)
+        except Exception as e:
+            logging.error(f"Failed to connect Socket.IO client: {e}")
+            self.socketClient = None
+        
+    @property
+    def base_uri(self):
+        scheme = "https" if self.isHttps else "http"
+        return f"{scheme}://{self.host}:{self.port}{self.route}"
+
+    @property
+    def base_root_uri(self):
+        """Server root without the API suffix - serves /data, /jupyter, /openapi.json"""
+        base = self.base_uri
+        return base[:-4] if base.endswith("/api") else base
+
+    @property
+    def base_swagger_uri(self):
+        return self.base_root_uri + "/openapi.json"
+        
+    def get_json(self, path, payload={}, headers={}, timeout=30):
+        """Perform an HTTP GET request and return the JSON response"""
+        if not path.startswith("http"):
+            path = self.base_uri + path
+        r = requests.get(path, params=payload, headers=headers, verify=False, timeout=timeout)
+        r.raise_for_status()
+        return r.json()
+
+    def post_json(self, path, payload={}, headers={}, wait_on_task="auto", params=None, timeout=30):
+        """Make an HTTP POST request and return the JSON response.
+
+        `params` goes into the query string: FastAPI puts scalar arguments of a
+        POST endpoint there, only pydantic-model arguments come from the body.
+        """
+        if not path.startswith("http"):
+            path = self.base_uri + path
+        r = requests.post(path, json=payload, params=params, headers=headers,
+                          verify=False, timeout=timeout)
+        r.raise_for_status()
+        r = r.json()
+        return r
+
+

{imswitchclient-0.1.7 → imswitchclient-0.2.0}/imswitchclient/__init__.py

@@ -3,4 +3,4 @@ from imswitchclient import *
 
 __author__ = """Benedict Diederich"""
 __email__ = 'benedictdied@gmail.com'
-__version__ = "v0.1.7"#'0.1.7'
+__version__ = "v0.2.0"#'0.1.7'

imswitchclient-0.2.0/imswitchclient/autofocusManager.py

@@ -0,0 +1,51 @@
+import time
+
+
+class autofocusManager(object):
+    """Server-side autofocus (AutofocusController): a Z step scan around the
+    current position with a Gaussian fit of the focus metric. Runs on the
+    server; `autoFocusAndWait` polls it to completion."""
+
+    def __init__(self, parent):
+        self.parent = parent
+
+    def _url(self, func):
+        return f"{self.parent.base_uri}/AutofocusController/{func}"
+
+    def autoFocus(self, rangez=100, resolutionz=10, tSettle=0.1, focusAlgorithm="LAPE",
+                  nCropsize=2048, nGauss=0, twoStage=False):
+        """Start a scan of ±`rangez` µm in `resolutionz` µm steps; returns at once"""
+        payload = {'rangez': rangez, 'resolutionz': resolutionz, 'tSettle': tSettle,
+                   'focusAlgorithm': focusAlgorithm, 'nCropsize': nCropsize, 'nGauss': nGauss,
+                   'twoStage': twoStage}
+        return self.parent.get_json(self._url("autoFocus"), payload=payload)
+
+    def getAutofocusStatus(self):
+        """{'state': idle|starting|scanning|fitting|moving_to_focus|finished|aborted|error, ...}"""
+        return self.parent.get_json(self._url("getAutofocusStatus"))
+
+    def stopAutofocus(self):
+        return self.parent.get_json(self._url("stopAutofocus"))
+
+    def autoFocusAndWait(self, rangez=100, resolutionz=10, poll=0.5, timeout=300, **kwargs):
+        """`autoFocus` and wait for it; returns the final status dict.
+
+        Raises if the server refuses to start, the scan ends in error/aborted,
+        or `timeout` s pass (the scan is stopped then).
+        """
+        started = self.autoFocus(rangez=rangez, resolutionz=resolutionz, **kwargs)
+        if isinstance(started, dict) and started.get("status") == "error":
+            raise RuntimeError(f"autofocus refused: {started.get('message')}")
+        t0 = time.time()
+        time.sleep(poll)
+        while True:
+            status = self.getAutofocusStatus()
+            state = status.get("state")
+            if state in ("finished", "idle") and not status.get("isRunning"):
+                return status
+            if state in ("error", "aborted"):
+                raise RuntimeError(f"autofocus ended with state '{state}'")
+            if time.time() - t0 > timeout:
+                self.stopAutofocus()
+                raise TimeoutError(f"autofocus exceeded {timeout} s")
+            time.sleep(poll)

imswitchclient-0.2.0/imswitchclient/client.py

@@ -0,0 +1,6 @@
+"""Backwards-compatible alias.
+
+The client used to exist twice, and this copy pointed at `/imswitch/api/v2`,
+a route the server does not serve. Everything lives in `ImSwitchClient.py` now.
+"""
+from .ImSwitchClient import ImSwitchClient, parseBaseUrl  # noqa: F401

imswitchclient-0.2.0/imswitchclient/lasersManager.py

@@ -0,0 +1,76 @@
+import time
+
+
+class lasersManager(object):
+
+    def __init__(self, parent):
+        self.parent = parent
+
+    def getLaserNames(self):
+        url = f"{self.parent.base_uri}/LaserController/getLaserNames"
+        headers = {'accept': 'application/json'}
+
+        response = self.parent.get_json(url, headers=headers)
+        return response
+
+    def getLaserValueRanges(self, laser_name):
+        """(min, max) of the value `setLaserValue` accepts, e.g. (0, 1023) for a PWM channel"""
+        url = f"{self.parent.base_uri}/LaserController/getLaserValueRanges"
+        return self.parent.get_json(url, payload={'laserName': laser_name})
+
+    def getLaserValue(self, laser_name):
+        url = f"{self.parent.base_uri}/LaserController/getLaserValue"
+        return self.parent.get_json(url, payload={'laserName': laser_name})
+
+    def getLaserActive(self, laser_name):
+        url = f"{self.parent.base_uri}/LaserController/getLaserActive"
+        return self.parent.get_json(url, payload={'laserName': laser_name})
+
+    def setLaserValue(self, laser_name, value=0):
+        url = f"{self.parent.base_uri}/LaserController/setLaserValue"
+        payload = {
+            'laserName': laser_name,
+            'value': value
+        }
+        response = self.parent.get_json(url, payload=payload)
+        return response
+
+    def setLaserActive(self, laser_name, active=True):
+        url = f"{self.parent.base_uri}/LaserController/setLaserActive"
+        payload = {
+            "laserName": laser_name,
+            "active": active
+        }
+        response = self.parent.get_json(url, payload=payload)
+        return response
+
+    def setLaserOn(self, laser_name, value):
+        """Set the value and switch the channel on"""
+        self.setLaserValue(laser_name, value)
+        return self.setLaserActive(laser_name, True)
+
+    def setLaserOff(self, laser_name):
+        """Set the value to 0 and switch the channel off"""
+        self.setLaserValue(laser_name, 0)
+        return self.setLaserActive(laser_name, False)
+
+    def runLaserFor(self, laser_name, value, duration, on_tick=None, tick=1.0, stop_event=None):
+        """Drive a channel at `value` for `duration` seconds, then switch it off.
+
+        Meant for actuators wired to a laser/PWM output (pumps, valves). The
+        channel is switched off in a `finally`, so an interrupted notebook
+        cell (KeyboardInterrupt) or a failed request does not leave a pump
+        running. `on_tick(elapsed_s)` is called about every `tick` seconds.
+        Setting the `threading.Event` `stop_event` ends the run early.
+        """
+        self.setLaserOn(laser_name, value)
+        try:
+            t0 = time.time()
+            while (elapsed := time.time() - t0) < duration:
+                if stop_event is not None and stop_event.is_set():
+                    break
+                if on_tick:
+                    on_tick(elapsed)
+                time.sleep(min(tick, duration - elapsed))
+        finally:
+            self.setLaserOff(laser_name)

imswitchclient-0.2.0/imswitchclient/liveViewManager.py

@@ -0,0 +1,38 @@
+class liveViewManager(object):
+    """Server-side live stream (LiveViewController).
+
+    Long exposures stop the stream on the server; snaps arm the camera on
+    demand, so the stream only needs to run for things that converge on
+    streamed frames, such as auto exposure.
+    """
+
+    def __init__(self, parent):
+        self.parent = parent
+
+    def _url(self, func):
+        return f"{self.parent.base_uri}/LiveViewController/{func}"
+
+    def startLiveView(self, detector_name=None, protocol="jpeg", params=None, force=False):
+        """Start the stream. Refused with status 'long_exposure' above the
+        server's long-exposure threshold unless `force` is set."""
+        query = {'protocol': protocol, 'force': force}
+        if detector_name is not None:
+            query['detectorName'] = detector_name
+        return self.parent.post_json(self._url("startLiveView"), payload=params, params=query)
+
+    def stopLiveView(self, detector_name=None, stop_camera=True):
+        payload = {'stopCamera': stop_camera}
+        if detector_name is not None:
+            payload['detectorName'] = detector_name
+        return self.parent.get_json(self._url("stopLiveView"), payload=payload)
+
+    def getLiveViewActive(self):
+        return self.parent.get_json(self._url("getLiveViewActive"))
+
+    def getActiveStreams(self):
+        return self.parent.get_json(self._url("getActiveStreams"))
+
+    def getLongExposureInfo(self, detector_name=None):
+        """{'exposureMs', 'thresholdMs', 'isLongExposure'}"""
+        payload = {} if detector_name is None else {'detectorName': detector_name}
+        return self.parent.get_json(self._url("getLongExposureInfo"), payload=payload)