ephys-link 1.3.3__py3-none-any.whl → 2.0.0__py3-none-any.whl

ephys_link/bindings/ump_4_binding.py

@@ -0,0 +1,157 @@
+"""Bindings for Sensapex uMp-4 platform.
+
+Usage: Instantiate Ump4Bindings to interact with the Sensapex uMp-4 platform.
+"""
+
+from asyncio import get_running_loop
+from typing import NoReturn, final, override
+
+from sensapex import UMP, SensapexDevice  # pyright: ignore [reportMissingTypeStubs]
+from vbl_aquarium.models.unity import Vector4
+
+from ephys_link.utils.base_binding import BaseBinding
+from ephys_link.utils.constants import RESOURCES_DIRECTORY
+from ephys_link.utils.converters import (
+    list_to_vector4,
+    scalar_mm_to_um,
+    um_to_mm,
+    vector4_to_array,
+    vector_mm_to_um,
+)
+
+
+@final
+class Ump4Binding(BaseBinding):
+    """Bindings for UMP-4 platform"""
+
+    def __init__(self) -> None:
+        """Initialize UMP-4 bindings."""
+
+        # Establish connection to Sensapex API (exit if connection fails).
+        UMP.set_library_path(RESOURCES_DIRECTORY)
+        self._ump = UMP.get_ump()  # pyright: ignore [reportUnknownMemberType]
+
+    @staticmethod
+    @override
+    def get_display_name() -> str:
+        return "Sensapex uMp-4"
+
+    @staticmethod
+    @override
+    def get_cli_name() -> str:
+        return "ump-4"
+
+    @override
+    async def get_manipulators(self) -> list[str]:
+        return list(map(str, self._ump.list_devices()))
+
+    @override
+    async def get_axes_count(self) -> int:
+        return 4
+
+    @override
+    def get_dimensions(self) -> Vector4:
+        return Vector4(x=20, y=20, z=20, w=20)
+
+    @override
+    async def get_position(self, manipulator_id: str) -> Vector4:
+        return um_to_mm(list_to_vector4(self._get_device(manipulator_id).get_pos(1)))  # pyright: ignore [reportUnknownMemberType]
+
+    @override
+    async def get_angles(self, manipulator_id: str) -> NoReturn:
+        """uMp-4 does not support getting angles so raise an error.
+
+        Raises:
+            AttributeError: uMp-4 does not support getting angles.
+        """
+        error_message = "UMP-4 does not support getting angles"
+        raise AttributeError(error_message)
+
+    @override
+    async def get_shank_count(self, manipulator_id: str) -> NoReturn:
+        """uMp-4 does not support getting shank count so raise an error.
+
+        Raises:
+            AttributeError: uMp-4 does not support getting shank count.
+        """
+        error_message = "UMP-4 does not support getting shank count"
+        raise AttributeError(error_message)
+
+    @override
+    def get_movement_tolerance(self) -> float:
+        return 0.001
+
+    @override
+    async def set_position(self, manipulator_id: str, position: Vector4, speed: float) -> Vector4:
+        # Convert position to micrometers.
+        target_position_um = vector_mm_to_um(position)
+
+        # Request movement.
+        movement = self._get_device(manipulator_id).goto_pos(  # pyright: ignore [reportUnknownMemberType]
+            vector4_to_array(target_position_um), scalar_mm_to_um(speed)
+        )
+
+        # Wait for movement to finish.
+        _ = await get_running_loop().run_in_executor(None, movement.finished_event.wait, None)
+
+        # Handle interrupted movement.
+        if movement.interrupted:
+            error_message = f"Manipulator {manipulator_id} interrupted: {movement.interrupt_reason}"  # pyright: ignore [reportUnknownMemberType]
+            raise RuntimeError(error_message)
+
+        # Handle empty end position.
+        if movement.last_pos is None or len(movement.last_pos) == 0:  # pyright: ignore [reportUnknownMemberType, reportUnknownArgumentType]
+            error_message = f"Manipulator {manipulator_id} did not reach target position"
+            raise RuntimeError(error_message)
+
+        return um_to_mm(list_to_vector4(movement.last_pos))  # pyright: ignore [reportArgumentType, reportUnknownMemberType]
+
+    @override
+    async def set_depth(self, manipulator_id: str, depth: float, speed: float) -> float:
+        # Augment current position with depth.
+        current_position = await self.get_position(manipulator_id)
+        new_platform_position = current_position.model_copy(update={"w": depth})
+
+        # Make the movement.
+        final_platform_position = await self.set_position(manipulator_id, new_platform_position, speed)
+
+        # Return the final depth.
+        return float(final_platform_position.w)
+
+    @override
+    async def stop(self, manipulator_id: str) -> None:
+        self._get_device(manipulator_id).stop()
+
+    @override
+    def platform_space_to_unified_space(self, platform_space: Vector4) -> Vector4:
+        # unified   <-  platform
+        # +x        <-  +y
+        # +y        <-  -z
+        # +z        <-  +x
+        # +d        <-  +d
+
+        return Vector4(
+            x=platform_space.y,
+            y=self.get_dimensions().z - platform_space.z,
+            z=platform_space.x,
+            w=platform_space.w,
+        )
+
+    @override
+    def unified_space_to_platform_space(self, unified_space: Vector4) -> Vector4:
+        # platform  <-  unified
+        # +x        <-  +z
+        # +y        <-  +x
+        # +z        <-  -y
+        # +d        <-  +d
+
+        return Vector4(
+            x=unified_space.z,
+            y=unified_space.x,
+            z=self.get_dimensions().z - unified_space.y,
+            w=unified_space.w,
+        )
+
+    # Helper methods.
+    def _get_device(self, manipulator_id: str) -> SensapexDevice:
+        return self._ump.get_device(int(manipulator_id))  # pyright: ignore [reportUnknownMemberType]

ephys_link/front_end/cli.py

@@ -0,0 +1,104 @@
+"""Command-line interface for the Electrophysiology Manipulator Link.
+
+Usage:
+    Instantiate CLI and call `parse_args()` to get the parsed arguments.
+
+    ```python
+    CLI().parse_args()
+    ```
+"""
+
+from argparse import ArgumentParser
+from typing import final
+
+from vbl_aquarium.models.ephys_link import EphysLinkOptions
+
+from ephys_link.__about__ import __version__ as version
+
+
+@final
+class CLI:
+    """Command-line interface for the Electrophysiology Manipulator Link.
+
+    Configures the CLI parser and options.
+    """
+
+    def __init__(self) -> None:
+        """Initialize CLI parser."""
+
+        self._parser = ArgumentParser(
+            description="Electrophysiology Manipulator Link: a Socket.IO interface for manipulators in electrophysiology experiments.",
+            prog="python -m ephys-link",
+        )
+
+        _ = self._parser.add_argument(
+            "-b", "--background", dest="background", action="store_true", help="Skip configuration window."
+        )
+        _ = self._parser.add_argument(
+            "-i",
+            "--ignore-updates",
+            dest="ignore_updates",
+            action="store_true",
+            help="Skip (ignore) checking for updates.",
+        )
+        _ = self._parser.add_argument(
+            "-t",
+            "--type",
+            type=str,
+            dest="type",
+            default="ump-4",
+            help='Manipulator type (i.e. "ump-4", "pathfinder-mpm", "fake"). Default: "ump-4".',
+        )
+        _ = self._parser.add_argument(
+            "-d",
+            "--debug",
+            dest="debug",
+            action="store_true",
+            help="Enable debug mode.",
+        )
+        _ = self._parser.add_argument(
+            "-p",
+            "--use-proxy",
+            dest="use_proxy",
+            action="store_true",
+            help="Enable proxy mode.",
+        )
+        _ = self._parser.add_argument(
+            "-a",
+            "--proxy-address",
+            type=str,
+            default="proxy2.virtualbrainlab.org",
+            dest="proxy_address",
+            help="Proxy IP address.",
+        )
+        _ = self._parser.add_argument(
+            "--mpm-port",
+            type=int,
+            default=8080,
+            dest="mpm_port",
+            help="Port New Scale Pathfinder MPM's server is on. Default: 8080.",
+        )
+        _ = self._parser.add_argument(
+            "-s",
+            "--serial",
+            type=str,
+            default="no-e-stop",
+            dest="serial",
+            nargs="?",
+            help="Emergency stop serial port (i.e. COM3). Default: disables emergency stop.",
+        )
+        _ = self._parser.add_argument(
+            "-v",
+            "--version",
+            action="version",
+            version=f"Electrophysiology Manipulator Link v{version}",
+            help="Print version and exit.",
+        )
+
+    def parse_args(self) -> EphysLinkOptions:
+        """Parse arguments and return them
+
+        Returns:
+            Parsed arguments
+        """
+        return EphysLinkOptions(**vars(self._parser.parse_args()))  # pyright: ignore [reportAny]

ephys_link/front_end/gui.py

@@ -0,0 +1,204 @@
+"""Graphical User Interface for Ephys Link.
+
+Usage:
+    Create a GUI instance and call `get_options()` to get the options.
+
+    ```python
+    GUI().get_options()
+    ```
+"""
+
+from json import load
+from os import makedirs
+from os.path import exists, join
+from socket import gethostbyname, gethostname
+from sys import exit
+from tkinter import CENTER, RIGHT, BooleanVar, E, IntVar, StringVar, Tk, ttk
+from typing import final
+
+from platformdirs import user_config_dir
+from vbl_aquarium.models.ephys_link import EphysLinkOptions
+
+from ephys_link.__about__ import __version__ as version
+from ephys_link.utils.startup import get_binding_display_to_cli_name
+
+# Define options path.
+OPTIONS_DIR = join(user_config_dir(), "VBL", "Ephys Link")
+OPTIONS_FILENAME = "options.json"
+OPTIONS_PATH = join(OPTIONS_DIR, OPTIONS_FILENAME)
+
+
+@final
+class GUI:
+    """Graphical User Interface for Ephys Link.
+
+    Gathers options from the user and saves them to a file.
+    """
+
+    def __init__(self) -> None:
+        """Setup GUI properties."""
+
+        self._root = Tk()
+
+        # Create default options.
+        options = EphysLinkOptions()
+
+        # Read options.
+        if exists(OPTIONS_PATH):
+            with open(OPTIONS_PATH) as options_file:
+                options = EphysLinkOptions(**load(options_file))  # pyright: ignore [reportAny]
+
+        # Load options into GUI variables.
+        self._ignore_updates = BooleanVar(value=options.ignore_updates)
+        self._type = StringVar(value=options.type)
+        self._debug = BooleanVar(value=options.debug)
+        self._use_proxy = BooleanVar(value=options.use_proxy)
+        self._proxy_address = StringVar(value=options.proxy_address)
+        self._mpm_port = IntVar(value=options.mpm_port)
+        self._serial = StringVar(value=options.serial)
+
+        # Submit flag.
+        self._submit = False
+
+    def get_options(self) -> EphysLinkOptions:
+        """Get options from GUI.
+
+        Returns:
+            Options gathered from the GUI.
+        """
+
+        # Launch GUI.
+        self._build_gui()
+        self._root.mainloop()
+
+        # Exit if the user did not submit options.
+        if not self._submit:
+            exit(1)
+
+        # Extract options from GUI.
+        options = EphysLinkOptions(
+            ignore_updates=self._ignore_updates.get(),
+            type=self._type.get(),
+            debug=self._debug.get(),
+            use_proxy=self._use_proxy.get(),
+            proxy_address=self._proxy_address.get(),
+            mpm_port=self._mpm_port.get(),
+            serial=self._serial.get(),
+        )
+
+        # Save options.
+        makedirs(OPTIONS_DIR, exist_ok=True)
+        with open(OPTIONS_PATH, "w+") as options_file:
+            _ = options_file.write(options.model_dump_json())
+
+        # Return options
+        return options
+
+    def _build_gui(self) -> None:
+        """Build GUI."""
+
+        self._root.title(f"Ephys Link v{version}")
+
+        mainframe = ttk.Frame(self._root, padding=3)
+        mainframe.grid(column=0, row=0, sticky="news")
+        _ = self._root.columnconfigure(0, weight=1)
+        _ = self._root.rowconfigure(0, weight=1)
+        _ = mainframe.columnconfigure(0, weight=1)
+        _ = mainframe.rowconfigure(0, weight=1)
+
+        # Server serving settings.
+
+        server_serving_settings = ttk.LabelFrame(mainframe, text="Serving Settings", padding=3)
+        server_serving_settings.grid(column=0, row=0, sticky="news")
+
+        # Local IP.
+        ttk.Label(server_serving_settings, text="Local IP:", anchor=E, justify=RIGHT).grid(column=0, row=0, sticky="we")
+        ttk.Label(server_serving_settings, text=gethostbyname(gethostname())).grid(column=1, row=0, sticky="we")
+
+        # Proxy.
+        ttk.Label(server_serving_settings, text="Use Proxy:", anchor=E, justify=RIGHT).grid(
+            column=0, row=1, sticky="we"
+        )
+        ttk.Checkbutton(
+            server_serving_settings,
+            variable=self._use_proxy,
+        ).grid(column=1, row=1, sticky="we")
+
+        # Proxy address.
+        ttk.Label(server_serving_settings, text="Proxy Address:", anchor=E, justify=RIGHT).grid(
+            column=0, row=2, sticky="we"
+        )
+        ttk.Entry(server_serving_settings, textvariable=self._proxy_address, justify=CENTER).grid(
+            column=1, row=2, sticky="we"
+        )
+
+        # Ignore updates.
+        ttk.Label(server_serving_settings, text="Ignore Updates:", anchor=E, justify=RIGHT).grid(
+            column=0, row=4, sticky="we"
+        )
+        ttk.Checkbutton(
+            server_serving_settings,
+            variable=self._ignore_updates,
+        ).grid(column=1, row=4, sticky="we")
+
+        # Debug mode.
+        ttk.Label(server_serving_settings, text="Debug mode:", anchor=E, justify=RIGHT).grid(
+            column=0, row=5, sticky="we"
+        )
+        ttk.Checkbutton(
+            server_serving_settings,
+            variable=self._debug,
+        ).grid(column=1, row=5, sticky="we")
+
+        # ---
+
+        # Platform type.
+        platform_type_settings = ttk.LabelFrame(mainframe, text="Platform Type", padding=3)
+        platform_type_settings.grid(column=0, row=1, sticky="news")
+
+        for index, (display_name, cli_name) in enumerate(get_binding_display_to_cli_name().items()):
+            ttk.Radiobutton(
+                platform_type_settings,
+                text=display_name,
+                variable=self._type,
+                value=cli_name,
+            ).grid(column=0, row=index, sticky="we")
+
+        # ---
+
+        # New Scale Settings.
+        new_scale_settings = ttk.LabelFrame(mainframe, text="Pathfinder MPM Settings", padding=3)
+        new_scale_settings.grid(column=0, row=2, sticky="news")
+
+        # Port
+        ttk.Label(new_scale_settings, text="HTTP Server Port:", anchor=E, justify=RIGHT).grid(
+            column=0, row=1, sticky="we"
+        )
+        ttk.Entry(new_scale_settings, textvariable=self._mpm_port, width=5, justify=CENTER).grid(
+            column=1, row=1, sticky="we"
+        )
+
+        # ---
+
+        # Emergency Stop serial port.
+        e_stop_settings = ttk.LabelFrame(mainframe, text="Emergency Stop Settings", padding=3)
+        e_stop_settings.grid(column=0, row=3, sticky="news")
+
+        # Serial Port
+        ttk.Label(e_stop_settings, text="Serial Port:", anchor=E, justify=RIGHT).grid(column=0, row=1, sticky="we")
+        ttk.Entry(e_stop_settings, textvariable=self._serial, justify=CENTER).grid(column=1, row=1, sticky="we")
+
+        # Server launch button.
+        ttk.Button(
+            mainframe,
+            text="Launch Server",
+            command=self._launch_server,
+        ).grid(column=0, row=4, columnspan=2, sticky="we")
+
+    def _launch_server(self) -> None:
+        """Close GUI and return to the server.
+
+        Options are saved in fields.
+        """
+        self._submit = True
+        self._root.destroy()

ephys_link/utils/base_binding.py

@@ -0,0 +1,176 @@
+"""Binding methods for Ephys Link manipulator platforms.
+
+Definition of the methods a platform binding class must implement to be used by Ephys Link.
+
+Usage:
+    Implement the BaseBindings class when defining a platform binding to ensure it supports the necessary methods.
+"""
+
+from abc import ABC, abstractmethod
+
+from vbl_aquarium.models.unity import Vector3, Vector4
+
+
+class BaseBinding(ABC):
+    """Base class to enforce bindings manipulator platforms will support.
+
+    No need to catch exceptions as the [Platform Handler][ephys_link.back_end.platform_handler] will catch them.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def get_display_name() -> str:
+        """Get the full display name of the platform.
+
+        Returns:
+            Full display name of the platform.
+        """
+
+    @staticmethod
+    @abstractmethod
+    def get_cli_name() -> str:
+        """Get the name of the platform for CLI usage.
+
+        This is the value used to identify the platform when using the `-t` flag in the CLI.
+
+        Returns:
+            Name of the platform to use on the CLI.
+        """
+
+    @abstractmethod
+    async def get_axes_count(self) -> int:
+        """Get the number of axes for the current platform.
+
+        Returns:
+            Number of axes.
+        """
+
+    @abstractmethod
+    def get_dimensions(self) -> Vector4:
+        """Get the dimensions of the manipulators on the current platform (mm).
+
+        For 3-axis manipulators, copy the dimension of the axis parallel to the probe into w.
+
+        Returns:
+            Dimensions of the manipulators.
+        """
+
+    @abstractmethod
+    async def get_manipulators(self) -> list[str]:
+        """Get a list of available manipulators on the current platform.
+
+        Returns:
+            List of manipulator IDs.
+        """
+
+    @abstractmethod
+    async def get_position(self, manipulator_id: str) -> Vector4:
+        """Get the current position of a manipulator.
+
+        These will be the translation values of the manipulator (mm), so they may need to be rotated to unified space.
+        For 3-axis manipulators, copy the position of the axis parallel to the probe into w.
+
+        Args:
+            manipulator_id: Manipulator ID.
+
+        Returns:
+            Current position of the manipulator in platform space (mm).
+        """
+
+    @abstractmethod
+    async def get_angles(self, manipulator_id: str) -> Vector3:
+        """Get the current rotation angles of a manipulator in Yaw, Pitch, Roll (degrees).
+
+        Args:
+            manipulator_id: Manipulator ID.
+
+        Returns:
+            Current angles of the manipulator.
+        """
+
+    @abstractmethod
+    async def get_shank_count(self, manipulator_id: str) -> int:
+        """Get the number of shanks on a manipulator.
+
+        Args:
+            manipulator_id: Manipulator ID.
+
+        Returns:
+            Number of shanks on the manipulator.
+        """
+
+    @abstractmethod
+    def get_movement_tolerance(self) -> float:
+        """Get the tolerance for how close the final position must be to the target position in a movement (mm).
+
+        Returns:
+            Movement tolerance (mm).
+        """
+
+    @abstractmethod
+    async def set_position(self, manipulator_id: str, position: Vector4, speed: float) -> Vector4:
+        """Set the position of a manipulator.
+
+        This will directly set the position in the original platform space.
+        For 3-axis manipulators, the first 3 values of the position will be used.
+
+        Args:
+            manipulator_id: Manipulator ID.
+            position: Platform space position to set the manipulator to (mm).
+            speed: Speed to move the manipulator to the position (mm/s).
+
+        Returns:
+            Final position of the manipulator in platform space (mm).
+        """
+
+    @abstractmethod
+    async def set_depth(self, manipulator_id: str, depth: float, speed: float) -> float:
+        """Set the depth of a manipulator.
+
+        This will directly set the depth stage in the original platform space.
+
+        Args:
+            manipulator_id: Manipulator ID.
+            depth: Depth to set the manipulator to (mm).
+            speed: Speed to move the manipulator to the depth (mm/s).
+
+        Returns:
+            Final depth of the manipulator in platform space (mm).
+        """
+
+    @abstractmethod
+    async def stop(self, manipulator_id: str) -> None:
+        """Stop a manipulator.
+
+        Args:
+            manipulator_id: Manipulator ID.
+        """
+
+    @abstractmethod
+    def platform_space_to_unified_space(self, platform_space: Vector4) -> Vector4:
+        """Convert platform space coordinates to unified space coordinates.
+
+        This is an axes-swapping transformation.
+
+        Unified coordinate space is the standard left-handed cartesian coordinate system
+        with an additional depth axis pointing from the base of the probe to the tip.
+
+        Args:
+            platform_space: Platform space coordinates.
+
+        Returns:
+            Unified space coordinates.
+        """
+
+    @abstractmethod
+    def unified_space_to_platform_space(self, unified_space: Vector4) -> Vector4:
+        """Convert unified space coordinates to platform space coordinates.
+
+        This is an axes-swapping transformation.
+
+        Args:
+            unified_space: Unified space coordinates.
+
+        Returns:
+            Platform space coordinates.
+        """