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

ephys_link/bindings/fake_bindings.py

@@ -0,0 +1,54 @@
+from vbl_aquarium.models.unity import Vector3, Vector4
+
+from ephys_link.util.base_bindings import BaseBindings
+
+
+class FakeBindings(BaseBindings):
+    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),
+        ]
+
+    async def get_manipulators(self) -> list[str]:
+        return list(map(str, range(8)))
+
+    async def get_num_axes(self) -> int:
+        return 4
+
+    def get_dimensions(self) -> Vector4:
+        return Vector4(x=20, y=20, z=20, w=20)
+
+    async def get_position(self, manipulator_id: str) -> Vector4:
+        return self._positions[int(manipulator_id)]
+
+    async def get_angles(self, manipulator_id: str) -> Vector3:
+        return self._angles[int(manipulator_id)]
+
+    async def get_shank_count(self, _: str) -> int:
+        return 1
+
+    async def get_movement_tolerance(self) -> float:
+        return 0.001
+
+    async def set_position(self, manipulator_id: str, position: Vector4, _: float) -> Vector4:
+        self._positions[int(manipulator_id)] = position
+        return position
+
+    async def stop(self, _: str) -> None:
+        pass
+
+    def platform_space_to_unified_space(self, platform_space: Vector4) -> Vector4:
+        pass
+
+    def unified_space_to_platform_space(self, unified_space: Vector4) -> Vector4:
+        pass

ephys_link/bindings/ump_4_bindings.py

@@ -0,0 +1,127 @@
+"""Bindings for Sensapex uMp-4 platform.
+
+Usage: Instantiate Ump4Bindings to interact with the Sensapex uMp-4 platform.
+"""
+
+from asyncio import get_running_loop
+
+from sensapex import UMP, SensapexDevice
+from vbl_aquarium.models.unity import Vector3, Vector4
+
+from ephys_link.util.base_bindings import BaseBindings
+from ephys_link.util.common import RESOURCES_PATH, array_to_vector4, mm_to_um, mmps_to_umps, um_to_mm, vector4_to_array
+from ephys_link.util.console import Console
+
+
+class Ump4Bindings(BaseBindings):
+    """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_PATH)
+        self._ump = UMP.get_ump()
+        if self._ump is None:
+            error_message = "Unable to connect to uMp"
+            Console.error_print(error_message)
+            raise ValueError(error_message)
+
+    async def get_manipulators(self) -> list[str]:
+        return list(map(str, self._ump.list_devices()))
+
+    async def get_num_axes(self) -> int:
+        return 4
+
+    def get_dimensions(self) -> Vector4:
+        return Vector4(x=20, y=20, z=20, w=20)
+
+    async def get_position(self, manipulator_id: str) -> Vector4:
+        return um_to_mm(array_to_vector4(self._get_device(manipulator_id).get_pos(1)))
+
+    # noinspection PyTypeChecker
+    async def get_angles(self, _: str) -> Vector3:
+        """uMp-4 does not support getting angles so raise an error.
+
+        :raises: AttributeError
+        """
+        error_message = "UMP-4 does not support getting angles"
+        raise AttributeError(error_message)
+
+    # noinspection PyTypeChecker
+    async def get_shank_count(self, _: str) -> int:
+        """uMp-4 does not support getting shank count so raise an error.
+
+        :raises: AttributeError
+        """
+        error_message = "UMP-4 does not support getting shank count"
+        raise AttributeError(error_message)
+
+    async def get_movement_tolerance(self) -> float:
+        return 0.001
+
+    async def set_position(self, manipulator_id: str, position: Vector4, speed: float) -> Vector4:
+        """Set the position of the manipulator.
+
+        Waits using Asyncio until the movement is finished. This assumes the application is running in an event loop.
+
+        :param manipulator_id: Manipulator ID.
+        :type manipulator_id: str
+        :param position: Platform space position to set the manipulator to (mm).
+        :type position: Vector4
+        :param speed: Speed to move the manipulator to the position (mm/s).
+        :type speed: float
+        :returns: Final position of the manipulator in platform space (mm).
+        :rtype: Vector4
+        :raises RuntimeError: If the movement is interrupted.
+        """
+        # Convert position to micrometers.
+        target_position_um = mm_to_um(position)
+
+        # Request movement.
+        movement = self._get_device(manipulator_id).goto_pos(vector4_to_array(target_position_um), mmps_to_umps(speed))
+
+        # Wait for movement to finish.
+        await get_running_loop().run_in_executor(None, movement.finished_event.wait)
+
+        # Handle interrupted movement.
+        if movement.interrupted:
+            error_message = f"Manipulator {manipulator_id} interrupted: {movement.interrupt_reason}"
+            raise RuntimeError(error_message)
+
+        return um_to_mm(array_to_vector4(movement.last_pos))
+
+    async def stop(self, manipulator_id: str) -> None:
+        self._get_device(manipulator_id).stop()
+
+    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,
+        )
+
+    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))

ephys_link/front_end/cli.py

@@ -0,0 +1,98 @@
+"""Command-line interface for the Electrophysiology Manipulator Link.
+
+Usage: instantiate CLI and call parse_args() to get the parsed arguments.
+"""
+
+from argparse import ArgumentParser
+
+from vbl_aquarium.models.ephys_link import EphysLinkOptions
+
+from ephys_link.__about__ import __version__ as version
+
+
+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", "ump-3", "pathfinder-mpm", "new-scale", "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
+        :rtype: EphysLinkOptions
+        """
+        return EphysLinkOptions(**vars(self._parser.parse_args()))

ephys_link/{gui.py → front_end/gui.py}

@@ -1,64 +1,89 @@
-from asyncio import run
-from json import dumps, load
+"""Graphical User Interface for Ephys Link.
+
+Usage: create a GUI instance and call get_options() to get the options.
+"""
+
+from json import load
 from os import makedirs
-from os.path import exists
+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 platformdirs import user_config_dir
+from vbl_aquarium.models.ephys_link import EphysLinkOptions
 
-import ephys_link.common as com
 from ephys_link.__about__ import __version__ as version
-from ephys_link.emergency_stop import EmergencyStop
-from ephys_link.server import Server
 
-SETTINGS_DIR = f"{user_config_dir()}\\VBL\\Ephys Link"
-SETTINGS_FILENAME = "settings.json"
+# Define options path.
+OPTIONS_DIR = join(user_config_dir(), "VBL", "Ephys Link")
+OPTIONS_FILENAME = "options.json"
+OPTIONS_PATH = join(OPTIONS_DIR, OPTIONS_FILENAME)
 
 
 class GUI:
-    """GUI definition for Ephys Link"""
+    """Graphical User Interface for Ephys Link.
+
+    Gathers options from the user and saves them to a file.
+    """
 
     def __init__(self) -> None:
-        """Setup and construction of the Tk GUI"""
+        """Setup GUI properties."""
 
         self._root = Tk()
 
-        # Create default settings dictionary
-        settings = {
-            "ignore_updates": False,
-            "type": "sensapex",
-            "debug": False,
-            "proxy": False,
-            "proxy_address": "proxy2.virtualbrainlab.org",
-            "port": 8081,
-            "pathfinder_port": 8080,
-            "serial": "no-e-stop",
-        }
-
-        # Read settings.
-        if exists(f"{SETTINGS_DIR}\\{SETTINGS_FILENAME}"):
-            with open(f"{SETTINGS_DIR}\\{SETTINGS_FILENAME}") as settings_file:
-                settings = load(settings_file)
-
-        self._ignore_updates = BooleanVar(value=settings["ignore_updates"])
-        self._type = StringVar(value=settings["type"])
-        self._debug = BooleanVar(value=settings["debug"])
-        self._proxy = BooleanVar(value=settings["proxy"])
-        self._proxy_address = StringVar(value=settings["proxy_address"])
-        self._port = IntVar(value=settings["port"])
-        self._pathfinder_port = IntVar(value=settings["pathfinder_port"])
-        self._serial = StringVar(value=settings["serial"])
-
-    def launch(self) -> None:
-        """Build and launch GUI"""
-
-        # Build and run GUI.
+        # Create default options.
+        options = EphysLinkOptions()
+
+        # Read options.
+        if exists(OPTIONS_PATH):
+            with open(OPTIONS_PATH) as options_file:
+                options = EphysLinkOptions(**load(options_file))
+
+        # 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."""
+
+        # Launch GUI.
         self._build_gui()
         self._root.mainloop()
 
-    def _build_gui(self):
-        """Build GUI"""
+        # 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}")
 
@@ -84,7 +109,7 @@ class GUI:
         )
         ttk.Checkbutton(
             server_serving_settings,
-            variable=self._proxy,
+            variable=self._use_proxy,
         ).grid(column=1, row=1, sticky="we")
 
         # Proxy address.
@@ -95,12 +120,6 @@ class GUI:
             column=1, row=2, sticky="we"
         )
 
-        # Port.
-        ttk.Label(server_serving_settings, text="Port:", anchor=E, justify=RIGHT).grid(column=0, row=3, sticky="we")
-        ttk.Entry(server_serving_settings, textvariable=self._port, width=5, justify=CENTER).grid(
-            column=1, row=3, sticky="we"
-        )
-
         # Ignore updates.
         ttk.Label(server_serving_settings, text="Ignore Updates:", anchor=E, justify=RIGHT).grid(
             column=0, row=4, sticky="we"
@@ -110,6 +129,15 @@ class GUI:
             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.
@@ -120,38 +148,44 @@ class GUI:
             platform_type_settings,
             text="Sensapex uMp-4",
             variable=self._type,
-            value="sensapex",
+            value="ump-4",
         ).grid(column=0, row=0, sticky="we")
         ttk.Radiobutton(
             platform_type_settings,
             text="Sensapex uMp-3",
             variable=self._type,
-            value="ump3",
+            value="ump-3",
         ).grid(column=0, row=1, sticky="we")
         ttk.Radiobutton(
             platform_type_settings,
             text="Pathfinder MPM Control v2.8.8+",
             variable=self._type,
-            value="new_scale_pathfinder",
+            value="pathfinder-mpm",
         ).grid(column=0, row=2, sticky="we")
         ttk.Radiobutton(
             platform_type_settings,
             text="New Scale M3-USB-3:1-EP",
             variable=self._type,
-            value="new_scale",
+            value="new-scale",
         ).grid(column=0, row=3, sticky="we")
+        ttk.Radiobutton(
+            platform_type_settings,
+            text="Fake Platform",
+            variable=self._type,
+            value="fake",
+        ).grid(column=0, row=4, sticky="we")
 
         # ---
 
         # New Scale Settings.
-        new_scale_settings = ttk.LabelFrame(mainframe, text="Pathfinder Settings", padding=3)
+        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._pathfinder_port, width=5, justify=CENTER).grid(
+        ttk.Entry(new_scale_settings, textvariable=self._mpm_port, width=5, justify=CENTER).grid(
             column=1, row=1, sticky="we"
         )
 
@@ -173,45 +207,9 @@ class GUI:
         ).grid(column=0, row=4, columnspan=2, sticky="we")
 
     def _launch_server(self) -> None:
-        """Launch server based on GUI settings"""
+        """Close GUI and return to the server.
 
-        # Close GUI.
+        Options are saved in fields.
+        """
+        self._submit = True
         self._root.destroy()
-
-        # Save settings.
-        settings = {
-            "ignore_updates": self._ignore_updates.get(),
-            "type": self._type.get(),
-            "debug": self._debug.get(),
-            "proxy": self._proxy.get(),
-            "proxy_address": self._proxy_address.get(),
-            "port": self._port.get(),
-            "pathfinder_port": self._pathfinder_port.get(),
-            "serial": self._serial.get(),
-        }
-        makedirs(SETTINGS_DIR, exist_ok=True)
-        with open(f"{SETTINGS_DIR}\\{SETTINGS_FILENAME}", "w+") as f:
-            f.write(dumps(settings))
-
-        # Launch server.
-        server = Server()
-
-        com.DEBUG = self._debug.get()
-
-        if self._serial.get() != "no-e-stop":
-            e_stop = EmergencyStop(server, self._serial.get())
-            e_stop.watch()
-
-        # Launch with parsed arguments on main thread.
-        if self._proxy.get():
-            run(
-                server.launch_for_proxy(
-                    self._proxy_address.get(),
-                    self._port.get(),
-                    self._type.get(),
-                    self._pathfinder_port.get(),
-                    self._ignore_updates.get(),
-                )
-            )
-        else:
-            server.launch(self._type.get(), self._port.get(), self._pathfinder_port.get(), self._ignore_updates.get())

ephys_link/util/base_bindings.py

@@ -0,0 +1,133 @@
+"""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 BaseBindings(ABC):
+    """Base class to enforce bindings manipulator platforms will support.
+
+    No need to catch exceptions as the Platform Handler will catch them.
+    """
+
+    @abstractmethod
+    async def get_manipulators(self) -> list[str]:
+        """Get a list of available manipulators on the current platform.
+
+        :returns: List of manipulator IDs.
+        :rtype: list[str]
+        """
+
+    @abstractmethod
+    async def get_num_axes(self) -> int:
+        """Get the number of axes for the current platform.
+
+        :returns: Number of axes.
+        :rtype: int
+        """
+
+    @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.
+        :rtype: Vector4
+        """
+
+    @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.
+
+        :param manipulator_id: Manipulator ID.
+        :type manipulator_id: str
+        :returns: Current position of the manipulator in platform space (mm).
+        :rtype: Vector4
+        """
+
+    @abstractmethod
+    async def get_angles(self, manipulator_id: str) -> Vector3:
+        """Get the current rotation angles of a manipulator in Yaw, Pitch, Roll (degrees).
+
+        :param manipulator_id: Manipulator ID.
+        :type manipulator_id: str
+        :returns: Current angles of the manipulator.
+        :rtype: Vector3
+        """
+
+    @abstractmethod
+    async def get_shank_count(self, manipulator_id: str) -> int:
+        """Get the number of shanks on a manipulator.
+
+        :param manipulator_id: Manipulator ID.
+        :type manipulator_id: str
+        :returns: Number of shanks on the manipulator.
+        :rtype: int
+        """
+
+    @abstractmethod
+    async 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).
+        :rtype: float
+        """
+
+    @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.
+        Unified space coordinates will need to be converted to platform space.
+        For 3-axis manipulators, the first 3 values of the position will be used.
+
+        :param manipulator_id: Manipulator ID.
+        :type manipulator_id: str
+        :param position: Platform space position to set the manipulator to (mm).
+        :type position: Vector4
+        :param speed: Speed to move the manipulator to the position (mm/s).
+        :type speed: float
+        :returns: Final position of the manipulator in platform space (mm).
+        :rtype: Vector4
+        """
+
+    @abstractmethod
+    async def stop(self, manipulator_id: str) -> None:
+        """Stop a manipulator."""
+
+    @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.
+
+        :param platform_space: Platform space coordinates.
+        :type platform_space: Vector4
+        :returns: Unified space coordinates.
+        :rtype: Vector4
+        """
+
+    @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.
+
+        :param unified_space: Unified space coordinates.
+        :type unified_space: Vector4
+        :returns: Platform space coordinates.
+        :rtype: Vector4
+        """