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

ephys_link/{utils/base_binding.py → util/base_bindings.py}

@@ -1,176 +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 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.
-        """
+"""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
+        """

ephys_link/util/common.py

@@ -0,0 +1,121 @@
+# ruff: noqa: T201
+"""Commonly used utility functions and constants."""
+
+from os.path import join
+from pathlib import Path
+
+from packaging.version import parse
+from requests import get
+from vbl_aquarium.models.unity import Vector4
+
+from ephys_link.__about__ import __version__
+from ephys_link.util.console import Console
+
+# Ephys Link ASCII.
+ASCII = r"""
+ ______       _                 _      _       _
+|  ____|     | |               | |    (_)     | |
+| |__   _ __ | |__  _   _ ___  | |     _ _ __ | | __
+|  __| | '_ \| '_ \| | | / __| | |    | | '_ \| |/ /
+| |____| |_) | | | | |_| \__ \ | |____| | | | |   <
+|______| .__/|_| |_|\__, |___/ |______|_|_| |_|_|\_\
+       | |           __/ |
+       |_|          |___/
+"""
+
+# Absolute path to the resource folder.
+RESOURCES_PATH = join(str(Path(__file__).parent.parent.absolute()), "resources")
+
+# Ephys Link Port
+PORT = 3000
+
+
+# Server startup.
+def server_preamble() -> None:
+    """Print the server startup preamble."""
+    print(ASCII)
+    print(__version__)
+    print()
+    print("This is the Ephys Link server window.")
+    print("You may safely leave it running in the background.")
+    print("To stop it, close this window or press CTRL + Pause/Break.")
+    print()
+
+
+def check_for_updates() -> None:
+    """Check for updates to the Ephys Link."""
+    response = get("https://api.github.com/repos/VirtualBrainLab/ephys-link/tags", timeout=10)
+    latest_version = response.json()[0]["name"]
+    if parse(latest_version) > parse(__version__):
+        Console.info_print("Update available", latest_version)
+        Console.info_print("", "Download at: https://github.com/VirtualBrainLab/ephys-link/releases/latest")
+
+
+# Unit conversions
+
+
+def mmps_to_umps(mmps: float) -> float:
+    """Convert millimeters per second to micrometers per second.
+
+    :param mmps: Speed in millimeters per second.
+    :type mmps: float
+    :returns: Speed in micrometers per second.
+    :rtype: float
+    """
+    return mmps * 1_000
+
+
+def mm_to_um(mm: Vector4) -> Vector4:
+    """Convert millimeters to micrometers.
+
+    :param mm: Length in millimeters.
+    :type mm: Vector4
+    :returns: Length in micrometers.
+    :rtype: Vector4
+    """
+    return mm * 1_000
+
+
+def um_to_mm(um: Vector4) -> Vector4:
+    """Convert micrometers to millimeters.
+
+    :param um: Length in micrometers.
+    :type um: Vector4
+    :returns: Length in millimeters.
+    :rtype: Vector4
+    """
+    return um / 1_000
+
+
+def vector4_to_array(vector4: Vector4) -> list[float]:
+    """Convert a Vector4 to a list of floats.
+
+    :param vector4: Vector4 to convert.
+    :type vector4: :class:`vbl_aquarium.models.unity.Vector4`
+    :return: List of floats.
+    :rtype: list[float]
+    """
+    return [vector4.x, vector4.y, vector4.z, vector4.w]
+
+
+def array_to_vector4(array: list[float]) -> Vector4:
+    """Convert a list of floats to a Vector4.
+
+    :param array: List of floats.
+    :type array: list[float]
+    :return: First four elements of the list as a Vector4 padded with zeros if necessary.
+    :rtype: :class:`vbl_aquarium.models.unity.Vector4`
+    """
+
+    def get_element(this_array: list[float], index: int) -> float:
+        try:
+            return this_array[index]
+        except IndexError:
+            return 0.0
+
+    return Vector4(
+        x=get_element(array, 0),
+        y=get_element(array, 1),
+        z=get_element(array, 2),
+        w=get_element(array, 3),
+    )

ephys_link/util/console.py

@@ -0,0 +1,112 @@
+# ruff: noqa: T201
+"""Console class for printing messages to the console.
+
+Configure the console to print error and debug messages.
+
+Usage: Create a Console object and call the appropriate method to print messages.
+"""
+
+from traceback import print_exc
+
+from colorama import Back, Fore, Style, init
+
+# Constants.
+TAB_BLOCK = "\t\t"
+
+
+class Console:
+    def __init__(self, *, enable_debug: bool) -> None:
+        """Initialize console properties.
+
+        :param enable_debug: Enable debug mode.
+        :type enable_debug: bool
+        """
+        self._enable_debug = enable_debug
+
+        # Repeat message fields.
+        self._last_message = ""
+        self._repeat_counter = 1
+
+        # Initialize colorama.
+        init(autoreset=True)
+
+    @staticmethod
+    def error_print(msg: str) -> None:
+        """Print an error message to the console.
+
+        :param msg: Error message to print.
+        :type msg: str
+        """
+        print(f"\n{Back.RED}{Style.BRIGHT} ERROR {Style.RESET_ALL}{TAB_BLOCK}{Fore.RED}{msg}")
+
+    @staticmethod
+    def labeled_error_print(label: str, msg: str) -> None:
+        """Print an error message with a label to the console.
+
+        :param label: Label for the error message.
+        :type label: str
+        :param msg: Error message to print.
+        :type msg: str
+        """
+        print(f"\n{Back.RED}{Style.BRIGHT} ERROR {label} {Style.RESET_ALL}{TAB_BLOCK}{Fore.RED}{msg}")
+
+    @staticmethod
+    def pretty_exception(exception: Exception) -> str:
+        """Pretty print an exception.
+
+        :param exception: Exception to pretty print.
+        :type exception: Exception
+        :return: Pretty printed exception.
+        :rtype: str
+        """
+        return f"{type(exception).__name__}: {exception}"
+
+    @staticmethod
+    def exception_error_print(label: str, exception: Exception) -> None:
+        """Print an error message with exception details to the console.
+
+        :param label: Label for the error message.
+        :type label: str
+        :param exception: Exception to print.
+        :type exception: Exception
+        """
+        Console.labeled_error_print(label, Console.pretty_exception(exception))
+        print_exc()
+
+    def debug_print(self, label: str, msg: str) -> None:
+        """Print a debug message to the console.
+
+        :param label: Label for the debug message.
+        :type label: str
+        :param msg: Debug message to print.
+        :type msg: str
+        """
+        if self._enable_debug:
+            self._repeat_print(f"{Back.BLUE}{Style.BRIGHT} DEBUG {label} {Style.RESET_ALL}{TAB_BLOCK}{Fore.BLUE}{msg}")
+
+    @staticmethod
+    def info_print(label: str, msg: str) -> None:
+        """Print info to console.
+
+        :param label: Label for the message.
+        :type label: str
+        :param msg: Message to print.
+        :type msg: str
+        """
+        print(f"\n{Back.GREEN}{Style.BRIGHT} {label} {Style.RESET_ALL}{TAB_BLOCK}{Fore.GREEN}{msg}")
+
+    # Helper methods.
+    def _repeat_print(self, msg: str) -> None:
+        """Print a message to the console with repeat counter.
+
+        :param msg: Message to print.
+        :type msg: str
+        """
+        if msg == self._last_message:
+            self._repeat_counter += 1
+        else:
+            self._repeat_counter = 1
+            self._last_message = msg
+            print()
+
+        print(f"\r{msg}{f" (x{self._repeat_counter})" if self._repeat_counter > 1 else ""}", end="")