ephys-link 1.3.0b2__py3-none-any.whl → 2.0.0__py3-none-any.whl

ephys_link/back_end/server.py

@@ -0,0 +1,274 @@
+"""Socket.IO Server.
+
+Responsible to managing the Socket.IO connection and events.
+Directs events to the platform handler or handles them directly.
+
+Usage:
+    Instantiate Server with the appropriate options, platform handler, and console.
+    Then call `launch()` to start the server.
+
+    ```python
+    Server(options, platform_handler, console).launch()
+    ```
+"""
+
+from asyncio import get_event_loop, run
+from collections.abc import Callable, Coroutine
+from json import JSONDecodeError, dumps, loads
+from typing import Any, TypeVar, final
+from uuid import uuid4
+
+from aiohttp.web import Application, run_app
+from pydantic import ValidationError
+from socketio import AsyncClient, AsyncServer  # pyright: ignore [reportMissingTypeStubs]
+from vbl_aquarium.models.ephys_link import (
+    EphysLinkOptions,
+    SetDepthRequest,
+    SetInsideBrainRequest,
+    SetPositionRequest,
+)
+from vbl_aquarium.models.proxy import PinpointIdResponse
+from vbl_aquarium.utils.vbl_base_model import VBLBaseModel
+
+from ephys_link.__about__ import __version__
+from ephys_link.back_end.platform_handler import PlatformHandler
+from ephys_link.utils.console import Console
+from ephys_link.utils.constants import PORT
+
+# Server message generic types.
+INPUT_TYPE = TypeVar("INPUT_TYPE", bound=VBLBaseModel)
+OUTPUT_TYPE = TypeVar("OUTPUT_TYPE", bound=VBLBaseModel)
+
+
+@final
+class Server:
+    def __init__(self, options: EphysLinkOptions, platform_handler: PlatformHandler, console: Console) -> None:
+        """Initialize server fields based on options and platform handler.
+
+        Args:
+            options: Launch options object.
+            platform_handler: Platform handler instance.
+            console: Console instance.
+        """
+
+        # Save fields.
+        self._options = options
+        self._platform_handler = platform_handler
+        self._console = console
+
+        # Initialize based on proxy usage.
+        self._sio: AsyncServer | AsyncClient = AsyncClient() if self._options.use_proxy else AsyncServer()
+        if not self._options.use_proxy:
+            # Exit if _sio is not a Server.
+            if not isinstance(self._sio, AsyncServer):
+                error = "Server not initialized."
+                self._console.critical_print(error)
+                raise TypeError(error)
+
+            self._app = Application()
+            self._sio.attach(self._app)  # pyright: ignore [reportUnknownMemberType]
+
+            # Bind connection events.
+            _ = self._sio.on("connect", self.connect)  # pyright: ignore [reportUnknownMemberType, reportUnknownVariableType]
+            _ = self._sio.on("disconnect", self.disconnect)  # pyright: ignore [reportUnknownMemberType, reportUnknownVariableType]
+
+        # Store connected client.
+        self._client_sid: str = ""
+
+        # Generate Pinpoint ID for proxy usage.
+        self._pinpoint_id = str(uuid4())[:8]
+
+        # Bind events.
+        _ = self._sio.on("*", self.platform_event_handler)  # pyright: ignore [reportUnknownMemberType, reportUnknownVariableType]
+
+    def launch(self) -> None:
+        """Launch the server.
+
+        Based on the options, either connect to a proxy or launch the server locally.
+        """
+
+        # List platform and available manipulators.
+        self._console.info_print("PLATFORM", self._platform_handler.get_display_name())
+        self._console.info_print(
+            "MANIPULATORS",
+            str(get_event_loop().run_until_complete(self._platform_handler.get_manipulators()).manipulators),
+        )
+
+        # Launch server
+        if self._options.use_proxy:
+            self._console.info_print("PINPOINT ID", self._pinpoint_id)
+
+            async def connect_proxy() -> None:
+                # Exit if _sio is not a proxy client.
+                if not isinstance(self._sio, AsyncClient):
+                    error = "Proxy client not initialized."
+                    self._console.critical_print(error)
+                    raise TypeError(error)
+
+                # noinspection HttpUrlsUsage
+                await self._sio.connect(f"http://{self._options.proxy_address}:{PORT}")  # pyright: ignore [reportUnknownMemberType]
+                await self._sio.wait()
+
+            run(connect_proxy())
+        else:
+            run_app(self._app, port=PORT)
+
+    # Helper functions.
+    def _malformed_request_response(self, request: str, data: tuple[tuple[Any], ...]) -> str:  # pyright: ignore [reportExplicitAny]
+        """Return a response for a malformed request.
+
+        Args:
+            request: Original request.
+            data: Request data.
+
+        Returns:
+            Response for a malformed request.
+        """
+        self._console.error_print("MALFORMED REQUEST", f"{request}: {data}")
+        return dumps({"error": "Malformed request."})
+
+    async def _run_if_data_available(
+        self,
+        function: Callable[[str], Coroutine[Any, Any, VBLBaseModel]],  # pyright: ignore [reportExplicitAny]
+        event: str,
+        data: tuple[tuple[Any], ...],  # pyright: ignore [reportExplicitAny]
+    ) -> str:
+        """Run a function if data is available.
+
+        Args:
+            function: Function to run.
+            event: Event name.
+            data: Event data.
+
+        Returns:
+            Response data from function.
+        """
+        request_data = data[1]
+        if request_data:
+            return str((await function(str(request_data))).to_json_string())
+        return self._malformed_request_response(event, request_data)
+
+    async def _run_if_data_parses(
+        self,
+        function: Callable[[INPUT_TYPE], Coroutine[Any, Any, OUTPUT_TYPE]],  # pyright: ignore [reportExplicitAny]
+        data_type: type[INPUT_TYPE],
+        event: str,
+        data: tuple[tuple[Any], ...],  # pyright: ignore [reportExplicitAny]
+    ) -> str:
+        """Run a function if data parses.
+
+        Args:
+            function: Function to run.
+            data_type: Data type to parse.
+            event: Event name.
+            data: Event data.
+
+        Returns:
+            Response data from function.
+        """
+        request_data = data[1]
+        if request_data:
+            try:
+                parsed_data = data_type(**loads(str(request_data)))
+            except JSONDecodeError:
+                return self._malformed_request_response(event, request_data)
+            except ValidationError as e:
+                self._console.exception_error_print(event, e)
+                return self._malformed_request_response(event, request_data)
+            else:
+                return str((await function(parsed_data)).to_json_string())
+        return self._malformed_request_response(event, request_data)
+
+    # Event Handlers.
+
+    async def connect(self, sid: str, _: str) -> bool:
+        """Handle connections to the server.
+
+        Args:
+            sid: Socket session ID.
+            _: Extra connection data (unused).
+
+        Returns:
+            False on error to refuse connection, True otherwise.
+        """
+        self._console.info_print("CONNECTION REQUEST", sid)
+
+        if self._client_sid == "":
+            self._client_sid = sid
+            self._console.info_print("CONNECTION GRANTED", sid)
+            return True
+
+        self._console.error_print(
+            "CONNECTION REFUSED", f"Cannot connect {sid} as {self._client_sid} is already connected."
+        )
+        return False
+
+    async def disconnect(self, sid: str) -> None:
+        """Handle disconnections from the server.
+
+        Args:
+            sid: Socket session ID.
+        """
+        self._console.info_print("DISCONNECTED", sid)
+
+        # Reset client SID if it matches.
+        if self._client_sid == sid:
+            self._client_sid = ""
+        else:
+            self._console.error_print("DISCONNECTION", f"Client {sid} disconnected without being connected.")
+
+    async def platform_event_handler(self, event: str, *args: tuple[Any]) -> str:  # pyright: ignore [reportExplicitAny]
+        """Handle events from the server.
+
+        Matches incoming events based on the Socket.IO API.
+
+        Args:
+            event: Event name.
+            args: Event arguments.
+
+        Returns:
+            Response data.
+        """
+
+        # Log event.
+        self._console.debug_print("EVENT", event)
+
+        # Handle event.
+        match event:
+            # Server metadata.
+            case "get_version":
+                return __version__
+            case "get_pinpoint_id":
+                return PinpointIdResponse(pinpoint_id=self._pinpoint_id, is_requester=False).to_json_string()
+            case "get_platform_info":
+                return (await self._platform_handler.get_platform_info()).to_json_string()
+
+            # Manipulator commands.
+            case "get_manipulators":
+                return str((await self._platform_handler.get_manipulators()).to_json_string())
+            case "get_position":
+                return await self._run_if_data_available(self._platform_handler.get_position, event, args)
+            case "get_angles":
+                return await self._run_if_data_available(self._platform_handler.get_angles, event, args)
+            case "get_shank_count":
+                return await self._run_if_data_available(self._platform_handler.get_shank_count, event, args)
+            case "set_position":
+                return await self._run_if_data_parses(
+                    self._platform_handler.set_position, SetPositionRequest, event, args
+                )
+            case "set_depth":
+                return await self._run_if_data_parses(self._platform_handler.set_depth, SetDepthRequest, event, args)
+            case "set_inside_brain":
+                return await self._run_if_data_parses(
+                    self._platform_handler.set_inside_brain, SetInsideBrainRequest, event, args
+                )
+            case "stop":
+                request_data = args[1]
+                if request_data:
+                    return await self._platform_handler.stop(str(request_data))
+                return self._malformed_request_response(event, request_data)
+            case "stop_all":
+                return await self._platform_handler.stop_all()
+            case _:
+                self._console.error_print("EVENT", f"Unknown event: {event}.")
+                return dumps({"error": "Unknown event."})

ephys_link/bindings/fake_binding.py

@@ -0,0 +1,84 @@
+from typing import final, override
+
+from vbl_aquarium.models.unity import Vector3, Vector4
+
+from ephys_link.utils.base_binding import BaseBinding
+from ephys_link.utils.converters import list_to_vector4
+
+
+@final
+class FakeBinding(BaseBinding):
+    def __init__(self) -> None:
+        """Initialize fake manipulator infos."""
+
+        self._positions = [Vector4() for _ in range(8)]
+        self._angles = [
+            Vector3(x=90, y=60, z=0),
+            Vector3(x=-90, y=60, z=0),
+            Vector3(x=180, y=60, z=0),
+            Vector3(x=0, y=60, z=0),
+            Vector3(x=45, y=30, z=0),
+            Vector3(x=-45, y=30, z=0),
+            Vector3(x=135, y=30, z=0),
+            Vector3(x=-135, y=30, z=0),
+        ]
+
+    @staticmethod
+    @override
+    def get_display_name() -> str:
+        return "Fake Manipulator"
+
+    @staticmethod
+    @override
+    def get_cli_name() -> str:
+        return "fake"
+
+    @override
+    async def get_manipulators(self) -> list[str]:
+        return list(map(str, range(8)))
+
+    @override
+    async def get_axes_count(self) -> int:
+        return 4
+
+    @override
+    def get_dimensions(self) -> Vector4:
+        return list_to_vector4([20] * 4)
+
+    @override
+    async def get_position(self, manipulator_id: str) -> Vector4:
+        return self._positions[int(manipulator_id)]
+
+    @override
+    async def get_angles(self, manipulator_id: str) -> Vector3:
+        return self._angles[int(manipulator_id)]
+
+    @override
+    async def get_shank_count(self, manipulator_id: str) -> int:
+        return 1
+
+    @override
+    def get_movement_tolerance(self) -> float:
+        return 0.001
+
+    @override
+    async def set_position(self, manipulator_id: str, position: Vector4, speed: float) -> Vector4:
+        self._positions[int(manipulator_id)] = position
+        return position
+
+    @override
+    async def set_depth(self, manipulator_id: str, depth: float, speed: float) -> float:
+        self._positions[int(manipulator_id)].w = depth
+        return depth
+
+    @override
+    async def stop(self, manipulator_id: str) -> None:
+        pass
+
+    @override
+    def platform_space_to_unified_space(self, platform_space: Vector4) -> Vector4:
+        return platform_space
+
+    @override
+    def unified_space_to_platform_space(self, unified_space: Vector4) -> Vector4:
+        return unified_space

ephys_link/bindings/mpm_binding.py

@@ -0,0 +1,315 @@
+"""Bindings for New Scale Pathfinder MPM HTTP server platform.
+
+Usage: Instantiate MPMBindings to interact with the New Scale Pathfinder MPM HTTP server platform.
+"""
+
+from asyncio import get_running_loop, sleep
+from json import dumps
+from typing import Any, final, override
+
+from requests import JSONDecodeError, get, put
+from vbl_aquarium.models.unity import Vector3, Vector4
+
+from ephys_link.utils.base_binding import BaseBinding
+from ephys_link.utils.converters import scalar_mm_to_um, vector4_to_array
+
+
+@final
+class MPMBinding(BaseBinding):
+    """Bindings for New Scale Pathfinder MPM HTTP server platform."""
+
+    # Valid New Scale manipulator IDs
+    VALID_MANIPULATOR_IDS = (
+        "A",
+        "B",
+        "C",
+        "D",
+        "E",
+        "F",
+        "G",
+        "H",
+        "I",
+        "J",
+        "K",
+        "L",
+        "M",
+        "N",
+        "O",
+        "P",
+        "Q",
+        "R",
+        "S",
+        "T",
+        "U",
+        "V",
+        "W",
+        "X",
+        "Y",
+        "Z",
+        "AA",
+        "AB",
+        "AC",
+        "AD",
+        "AE",
+        "AF",
+        "AG",
+        "AH",
+        "AI",
+        "AJ",
+        "AK",
+        "AL",
+        "AM",
+        "AN",
+    )
+
+    # Server cache lifetime (60 FPS).
+    CACHE_LIFETIME = 1 / 60
+
+    # Movement polling preferences.
+    UNCHANGED_COUNTER_LIMIT = 10
+    POLL_INTERVAL = 0.1
+
+    # Speed preferences (mm/s to use coarse mode).
+    COARSE_SPEED_THRESHOLD = 0.1
+    INSERTION_SPEED_LIMIT = 9_000
+
+    def __init__(self, port: int = 8080) -> None:
+        """Initialize connection to MPM HTTP server.
+
+        Args:
+            port: Port number for MPM HTTP server.
+        """
+        self._url = f"http://localhost:{port}"
+        self._movement_stopped = False
+
+        # Data cache.
+        self.cache: dict[str, Any] = {}  # pyright: ignore [reportExplicitAny]
+        self.cache_time = 0
+
+    @staticmethod
+    @override
+    def get_display_name() -> str:
+        return "Pathfinder MPM Control v2.8.8+"
+
+    @staticmethod
+    @override
+    def get_cli_name() -> str:
+        return "pathfinder-mpm"
+
+    @override
+    async def get_manipulators(self) -> list[str]:
+        return [manipulator["Id"] for manipulator in (await self._query_data())["ProbeArray"]]  # pyright: ignore [reportAny]
+
+    @override
+    async def get_axes_count(self) -> int:
+        return 3
+
+    @override
+    def get_dimensions(self) -> Vector4:
+        return Vector4(x=15, y=15, z=15, w=15)
+
+    @override
+    async def get_position(self, manipulator_id: str) -> Vector4:
+        manipulator_data: dict[str, float] = await self._manipulator_data(manipulator_id)
+        stage_z: float = manipulator_data["Stage_Z"]
+
+        await sleep(self.POLL_INTERVAL)  # Wait for the stage to stabilize.
+
+        return Vector4(
+            x=manipulator_data["Stage_X"],
+            y=manipulator_data["Stage_Y"],
+            z=stage_z,
+            w=stage_z,
+        )
+
+    @override
+    async def get_angles(self, manipulator_id: str) -> Vector3:
+        manipulator_data: dict[str, float] = await self._manipulator_data(manipulator_id)
+
+        # Apply PosteriorAngle to Polar to get the correct angle.
+        adjusted_polar: int = manipulator_data["Polar"] - (await self._query_data())["PosteriorAngle"]
+
+        return Vector3(
+            x=adjusted_polar if adjusted_polar > 0 else 360 + adjusted_polar,
+            y=manipulator_data["Pitch"],
+            z=manipulator_data["ShankOrientation"],
+        )
+
+    @override
+    async def get_shank_count(self, manipulator_id: str) -> int:
+        return int((await self._manipulator_data(manipulator_id))["ShankCount"])  # pyright: ignore [reportAny]
+
+    @override
+    def get_movement_tolerance(self) -> float:
+        return 0.01
+
+    @override
+    async def set_position(self, manipulator_id: str, position: Vector4, speed: float) -> Vector4:
+        # Keep track of the previous position to check if the manipulator stopped advancing.
+        current_position = await self.get_position(manipulator_id)
+        previous_position = current_position
+        unchanged_counter = 0
+
+        # Set step mode based on speed.
+        await self._put_request(
+            {
+                "PutId": "ProbeStepMode",
+                "Probe": self.VALID_MANIPULATOR_IDS.index(manipulator_id),
+                "StepMode": 0 if speed > self.COARSE_SPEED_THRESHOLD else 1,
+            }
+        )
+
+        # Send move request.
+        await self._put_request(
+            {
+                "PutId": "ProbeMotion",
+                "Probe": self.VALID_MANIPULATOR_IDS.index(manipulator_id),
+                "Absolute": 1,
+                "Stereotactic": 0,
+                "AxisMask": 7,
+                "X": position.x,
+                "Y": position.y,
+                "Z": position.z,
+            }
+        )
+
+        # Wait for the manipulator to reach the target position or be stopped or stuck.
+        while (
+            not self._movement_stopped
+            and not self._is_vector_close(current_position, position)
+            and unchanged_counter < self.UNCHANGED_COUNTER_LIMIT
+        ):
+            # Wait for a short time before checking again.
+            await sleep(self.POLL_INTERVAL)
+
+            # Update current position.
+            current_position = await self.get_position(manipulator_id)
+
+            # Check if manipulator is not moving.
+            if self._is_vector_close(previous_position, current_position):
+                # Position did not change.
+                unchanged_counter += 1
+            else:
+                # Position changed.
+                unchanged_counter = 0
+                previous_position = current_position
+
+        # Reset movement stopped flag.
+        self._movement_stopped = False
+
+        # Return the final position.
+        return await self.get_position(manipulator_id)
+
+    @override
+    async def set_depth(self, manipulator_id: str, depth: float, speed: float) -> float:
+        # Keep track of the previous depth to check if the manipulator stopped advancing unexpectedly.
+        current_depth = (await self.get_position(manipulator_id)).w
+        previous_depth = current_depth
+        unchanged_counter = 0
+
+        # Send move request.
+        # Convert mm/s to um/min and cap speed at the limit.
+        await self._put_request(
+            {
+                "PutId": "ProbeInsertion",
+                "Probe": self.VALID_MANIPULATOR_IDS.index(manipulator_id),
+                "Distance": scalar_mm_to_um(current_depth - depth),
+                "Rate": min(scalar_mm_to_um(speed) * 60, self.INSERTION_SPEED_LIMIT),
+            }
+        )
+
+        # Wait for the manipulator to reach the target depth or be stopped or get stuck.
+        while not self._movement_stopped and not abs(current_depth - depth) <= self.get_movement_tolerance():
+            # Wait for a short time before checking again.
+            await sleep(self.POLL_INTERVAL)
+
+            # Get the current depth.
+            current_depth = (await self.get_position(manipulator_id)).w
+
+            # Check if manipulator is not moving.
+            if abs(previous_depth - current_depth) <= self.get_movement_tolerance():
+                # Depth did not change.
+                unchanged_counter += 1
+            else:
+                # Depth changed.
+                unchanged_counter = 0
+                previous_depth = current_depth
+
+        # Reset movement stopped flag.
+        self._movement_stopped = False
+
+        # Return the final depth.
+        return float((await self.get_position(manipulator_id)).w)
+
+    @override
+    async def stop(self, manipulator_id: str) -> None:
+        request: dict[str, str | int | float] = {
+            "PutId": "ProbeStop",
+            "Probe": self.VALID_MANIPULATOR_IDS.index(manipulator_id),
+        }
+        await self._put_request(request)
+        self._movement_stopped = True
+
+    @override
+    def platform_space_to_unified_space(self, platform_space: Vector4) -> Vector4:
+        # unified   <-  platform
+        # +x        <-  -x
+        # +y        <-  +z
+        # +z        <-  +y
+        # +w        <-  -w
+
+        return Vector4(
+            x=self.get_dimensions().x - platform_space.x,
+            y=platform_space.z,
+            z=platform_space.y,
+            w=self.get_dimensions().w - platform_space.w,
+        )
+
+    @override
+    def unified_space_to_platform_space(self, unified_space: Vector4) -> Vector4:
+        # platform  <-  unified
+        # +x        <-  -x
+        # +y        <-  +z
+        # +z        <-  +y
+        # +w        <-  -w
+
+        return Vector4(
+            x=self.get_dimensions().x - unified_space.x,
+            y=unified_space.z,
+            z=unified_space.y,
+            w=self.get_dimensions().w - unified_space.w,
+        )
+
+    # Helper functions.
+    async def _query_data(self) -> dict[str, Any]:  # pyright: ignore [reportExplicitAny]
+        try:
+            # Update cache if it's expired.
+            if get_running_loop().time() - self.cache_time > self.CACHE_LIFETIME:
+                # noinspection PyTypeChecker
+                self.cache = (await get_running_loop().run_in_executor(None, get, self._url)).json()
+                self.cache_time = get_running_loop().time()
+        except ConnectionError as connectionError:
+            error_message = f"Unable to connect to MPM HTTP server: {connectionError}"
+            raise RuntimeError(error_message) from connectionError
+        except JSONDecodeError as jsonDecodeError:
+            error_message = f"Unable to decode JSON response from MPM HTTP server: {jsonDecodeError}"
+            raise ValueError(error_message) from jsonDecodeError
+        else:
+            # Return cached data.
+            return self.cache
+
+    async def _manipulator_data(self, manipulator_id: str) -> dict[str, Any]:  # pyright: ignore [reportExplicitAny]
+        probe_data: list[dict[str, Any]] = (await self._query_data())["ProbeArray"]  # pyright: ignore [reportExplicitAny]
+        for probe in probe_data:
+            if probe["Id"] == manipulator_id:
+                return probe
+
+        # If we get here, that means the manipulator doesn't exist.
+        error_message = f"Manipulator {manipulator_id} not found."
+        raise ValueError(error_message)
+
+    async def _put_request(self, request: dict[str, Any]) -> None:  # pyright: ignore [reportExplicitAny]
+        _ = await get_running_loop().run_in_executor(None, put, self._url, dumps(request))
+
+    def _is_vector_close(self, target: Vector4, current: Vector4) -> bool:
+        return all(abs(axis) <= self.get_movement_tolerance() for axis in vector4_to_array(target - current)[:3])