ephys-link 2.0.2__py3-none-any.whl → 2.1.0b0__py3-none-any.whl

ephys_link/__about__.py

@@ -1 +1 @@
-__version__ = "2.0.2"
+__version__ = "2.1.0b0"

ephys_link/back_end/platform_handler.py

@@ -70,10 +70,22 @@ class PlatformHandler:
         Returns:
             Bindings for the specified platform type.
         """
+
+        # What the user supplied.
+        selected_type = options.type
+
         for binding_type in get_bindings():
             binding_cli_name = binding_type.get_cli_name()
 
-            if binding_cli_name == options.type:
+            # Notify deprecation of "ump-4" and "ump-3" CLI options and fix.
+            if selected_type in ("ump-4", "ump-3"):
+                self._console.error_print(
+                    "DEPRECATION",
+                    f"CLI option '{selected_type}' is deprecated and will be removed in v3.0.0. Use 'ump' instead.",
+                )
+                selected_type = "ump"
+
+            if binding_cli_name == selected_type:
                 # Pass in HTTP port for Pathfinder MPM.
                 if binding_cli_name == "pathfinder-mpm":
                     return MPMBinding(options.mpm_port)

ephys_link/bindings/ump_binding.py

@@ -0,0 +1,239 @@
+"""Bindings for Sensapex uMp platform.
+
+Usage: Instantiate UmpBindings to interact with Sensapex uMp-4 and uMp-3 manipulators.
+"""
+
+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 UmpBinding(BaseBinding):
+    """Bindings for uMp platform"""
+
+    # Number of axes for uMp-3.
+    UMP_3_NUM_AXES = 3
+
+    def __init__(self) -> None:
+        """Initialize uMp bindings."""
+
+        # Establish connection to Sensapex API (exit if connection fails).
+        UMP.set_library_path(RESOURCES_DIRECTORY)
+        self._ump: UMP = UMP.get_ump()  # pyright: ignore [reportUnknownMemberType]
+
+        # Exit if no manipulators are connected.
+        device_ids: list[str] = list(map(str, self._ump.list_devices()))
+        if len(device_ids) == 0:
+            msg = "No manipulators connected."
+            raise RuntimeError(msg)
+
+        # Currently only supports using uMp-4 XOR uMp-3. Exit if both are connected.
+
+        # Use the first device as the reference for the number of axes.
+        self.num_axes: int = self._get_device(device_ids[0]).n_axes()
+
+        if any(self._get_device(device_id).n_axes() != self.num_axes for device_id in device_ids):  # pyright: ignore [reportUnknownArgumentType, reportUnknownMemberType]
+            msg = "uMp-4 and uMp-3 cannot be used at the same time."
+            raise RuntimeError(msg)
+
+    @staticmethod
+    @override
+    def get_display_name() -> str:
+        return "Sensapex uMp"
+
+    @staticmethod
+    @override
+    def get_cli_name() -> str:
+        return "ump"
+
+    @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 self.num_axes
+
+    @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:
+        # Get the position list from the device.
+        position = self._get_device(manipulator_id).get_pos(1)  # pyright: ignore [reportUnknownMemberType]
+
+        # Copy x-coordinate into depth for uMp-3.
+        return um_to_mm(list_to_vector4([*position, position[0]] if self._is_ump_3() else position))
+
+    @override
+    async def get_angles(self, manipulator_id: str) -> NoReturn:
+        """uMp does not support getting angles so raise an error.
+
+        Raises:
+            AttributeError: uMp does not support getting angles.
+        """
+        error_message = "uMp does not support getting angles"
+        raise AttributeError(error_message)
+
+    @override
+    async def get_shank_count(self, manipulator_id: str) -> NoReturn:
+        """uMp does not support getting shank count so raise an error.
+
+        Raises:
+            AttributeError: uMp does not support getting shank count.
+        """
+        error_message = "uMp does not support getting shank count"
+        raise AttributeError(error_message)
+
+    @staticmethod
+    @override
+    def get_movement_tolerance() -> float:
+        return 0.001
+
+    @override
+    async def set_position(self, manipulator_id: str, position: Vector4, speed: float) -> Vector4:
+        # Convert position to micrometers array.
+        target_position_um = vector4_to_array(vector_mm_to_um(position))
+
+        # Request movement (clip 4th axis for uMp-3).
+        movement = self._get_device(
+            manipulator_id
+        ).goto_pos(  # pyright: ignore [reportUnknownMemberType]
+            target_position_um[: self.UMP_3_NUM_AXES] if self._is_ump_3() else 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, movement.last_pos[0]] if self._is_ump_3() else list(movement.last_pos))  # pyright: ignore [reportUnknownArgumentType, 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={"x" if self._is_ump_3() else "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:
+        """
+        For uMp-3:
+        unified   <-  platform
+        +x        <-  +y
+        +y        <-  -x
+        +z        <-  -z
+        +d        <-  +d
+
+        For uMp-4:
+        unified   <-  platform
+        +x        <-  +y
+        +y        <-  -z
+        +z        <-  +x
+        +d        <-  +d
+        """
+
+        return (
+            Vector4(
+                x=platform_space.y,
+                y=self.get_dimensions().x - platform_space.x,
+                z=self.get_dimensions().z - platform_space.z,
+                w=platform_space.w,
+            )
+            if self._is_ump_3()
+            else 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:
+        """
+        For uMp-3:
+        platform  <-  unified
+        +x        <-  -y
+        +y        <-  +x
+        +z        <-  -z
+        +d        <-  +d
+
+        For uMp-4:
+        platform  <-  unified
+        +x        <-  +z
+        +y        <-  +x
+        +z        <-  -y
+        +d        <-  +d
+        """
+
+        return (
+            Vector4(
+                x=self.get_dimensions().y - unified_space.y,
+                y=unified_space.x,
+                z=self.get_dimensions().z - unified_space.z,
+                w=unified_space.w,
+            )
+            if self._is_ump_3()
+            else Vector4(
+                x=unified_space.z,
+                y=unified_space.x,
+                z=self.get_dimensions().y - unified_space.y,
+                w=unified_space.w,
+            )
+        )
+
+    # Helper methods.
+    def _get_device(self, manipulator_id: str) -> SensapexDevice:
+        """Returns the Sensapex device object for the given manipulator ID.
+
+        Args:
+            manipulator_id: Manipulator ID.
+        Returns:
+            Sensapex device object.
+        """
+
+        return self._ump.get_device(int(manipulator_id))  # pyright: ignore [reportUnknownMemberType]
+
+    def _is_ump_3(self) -> bool:
+        """Check if the current device is uMp-3.
+
+        Returns:
+            True if the device is uMp-3, False otherwise.
+        """
+        return self.num_axes == self.UMP_3_NUM_AXES

{ephys_link-2.0.2.dist-info → ephys_link-2.1.0b0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ephys-link
-Version: 2.0.2
+Version: 2.1.0b0
 Summary: A Python Socket.IO server that allows any Socket.IO-compliant application to communicate with manipulators used in electrophysiology experiments.
 Project-URL: Documentation, https://virtualbrainlab.org/ephys_link/installation_and_use.html
 Project-URL: Issues, https://github.com/VirtualBrainLab/ephys-link/issues
@@ -28,7 +28,7 @@ Requires-Dist: keyboard==0.13.5
 Requires-Dist: packaging==24.2
 Requires-Dist: platformdirs==4.3.7
 Requires-Dist: pyserial==3.5
-Requires-Dist: python-socketio[asyncio-client]==5.12.1
+Requires-Dist: python-socketio[asyncio-client]==5.13.0
 Requires-Dist: requests==2.32.3
 Requires-Dist: rich==14.0.0
 Requires-Dist: sensapex==1.400.3

{ephys_link-2.0.2.dist-info → ephys_link-2.1.0b0.dist-info}/RECORD

@@ -1,13 +1,13 @@
-ephys_link/__about__.py,sha256=tATvJM5shAzfspHYjdVwpV2w3-gDA119NlEYi5X2lFY,22
+ephys_link/__about__.py,sha256=72sTjjXH8lKUBOrH9ADJVFplt-JL7YxNRjHxZ7aL25E,24
 ephys_link/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ephys_link/__main__.py,sha256=sbFdC6KJjTfXDgRraU_fmGRPcF4I1Ur9PRDiD86dkRI,1449
 ephys_link/back_end/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ephys_link/back_end/platform_handler.py,sha256=PSlBa2_jM073uaF3MvCd-_a7XXEeTfn5KXJ7aPEwMVk,12149
+ephys_link/back_end/platform_handler.py,sha256=gdiO6d0L-DWWLEJOL6eP6685tOC6otffmhfIBtPjhq0,12604
 ephys_link/back_end/server.py,sha256=mb3K3pXSO-gHaSj1CGJ0v3CSOW5YCi-p0EOKoySRzKQ,10322
 ephys_link/bindings/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ephys_link/bindings/fake_binding.py,sha256=PI7zYv-SjWsGFEs_FVu5Z5l9gykIqG3C7pQISdbwdoY,2357
 ephys_link/bindings/mpm_binding.py,sha256=vn7IKqdiZ6_MX91zomqDXX08ONHwVVgWncRuJTxJpOM,10872
-ephys_link/bindings/ump_4_binding.py,sha256=NTewhryjJYDDGYXHMiFRICfGBPJqrdStKOMB87dftiY,5421
+ephys_link/bindings/ump_binding.py,sha256=-RwzUggGYsznhV6yiXb96y6WD-e3E7-tcDk6NfesiWU,8080
 ephys_link/front_end/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ephys_link/front_end/cli.py,sha256=isIJs_sZbz7VbNvLgi-HyDlE-TyKD12auDhMTxAkWQU,3099
 ephys_link/front_end/gui.py,sha256=MDcrTS_Xz9bopAgamh4HknqRC10W8E6eOS3Kss_2ZKQ,6864
@@ -18,8 +18,8 @@ ephys_link/utils/console.py,sha256=52SYvXv_7Fx8QDL3RMFQoggQ1n5W93Yu5aU7uuJQgfg,3
 ephys_link/utils/constants.py,sha256=1aML7zBNTM5onVSf6NDrYIR33VJy-dIHd1lFORVBGbM,725
 ephys_link/utils/converters.py,sha256=ZdVmIX-LHCwM__F0SpjN_mfNGGetr1U97xvHd0hf8T0,2038
 ephys_link/utils/startup.py,sha256=jZVed78tuWjUuZqWVgii_zumDr87T-ikEtOFa6KTE_E,2500
-ephys_link-2.0.2.dist-info/METADATA,sha256=goBbmRyz6sCH8A6KRRuIz9Jo2AHT4vkkoRLNcgUvbnA,4607
-ephys_link-2.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-ephys_link-2.0.2.dist-info/entry_points.txt,sha256=o8wV3AdnJ9o47vg9ymKxPNVq9pMdPq8UZHE_iyAJx-k,124
-ephys_link-2.0.2.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-ephys_link-2.0.2.dist-info/RECORD,,
+ephys_link-2.1.0b0.dist-info/METADATA,sha256=i3-gX7xuUweGrkbvtoQQ01nNf2jsrd-hYtvLL_zF4tE,4609
+ephys_link-2.1.0b0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ephys_link-2.1.0b0.dist-info/entry_points.txt,sha256=o8wV3AdnJ9o47vg9ymKxPNVq9pMdPq8UZHE_iyAJx-k,124
+ephys_link-2.1.0b0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+ephys_link-2.1.0b0.dist-info/RECORD,,

ephys_link/bindings/ump_4_binding.py

@@ -1,158 +0,0 @@
-"""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)
-
-    @staticmethod
-    @override
-    def get_movement_tolerance() -> 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]