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

ephys_link/bindings/mpm_binding.py

@@ -1,315 +0,0 @@
-"""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])

ephys_link/bindings/ump_4_binding.py

@@ -1,157 +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)
-
-    @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/utils/constants.py

@@ -1,23 +0,0 @@
-"""Globally accessible constants"""
-
-from os.path import abspath, dirname, join
-
-# Ephys Link ASCII.
-ASCII = r"""
- ______       _                 _      _       _
-|  ____|     | |               | |    (_)     | |
-| |__   _ __ | |__  _   _ ___  | |     _ _ __ | | __
-|  __| | '_ \| '_ \| | | / __| | |    | | '_ \| |/ /
-| |____| |_) | | | | |_| \__ \ | |____| | | | |   <
-|______| .__/|_| |_|\__, |___/ |______|_|_| |_|_|\_\
-       | |           __/ |
-       |_|          |___/
-"""
-
-# Absolute path to the resource folder.
-PACKAGE_DIRECTORY = dirname(dirname(abspath(__file__)))
-RESOURCES_DIRECTORY = join(PACKAGE_DIRECTORY, "resources")
-BINDINGS_DIRECTORY = join(PACKAGE_DIRECTORY, "bindings")
-
-# Ephys Link Port
-PORT = 3000

ephys_link/utils/converters.py

@@ -1,86 +0,0 @@
-"""Commonly used conversion functions."""
-
-from vbl_aquarium.models.unity import Vector4
-
-
-def scalar_mm_to_um(mm: float) -> float:
-    """Convert scalar values of millimeters to micrometers.
-
-    Args:
-        mm: Scalar value in millimeters.
-
-    Returns:
-        Scalar value in micrometers.
-    """
-    return mm * 1_000
-
-
-def vector_mm_to_um(mm: Vector4) -> Vector4:
-    """Convert vector values of millimeters to micrometers.
-
-    Args:
-        mm: Vector in millimeters.
-
-    Returns:
-        Vector in micrometers.
-    """
-    return mm * 1_000
-
-
-def um_to_mm(um: Vector4) -> Vector4:
-    """Convert micrometers to millimeters.
-
-    Args:
-        um: Length in micrometers.
-
-    Returns:
-        Length in millimeters.
-    """
-    return um / 1_000
-
-
-def vector4_to_array(vector4: Vector4) -> list[float]:
-    """Convert a [Vector4][vbl_aquarium.models.unity.Vector4] to a list of floats.
-
-    Args:
-        vector4: [Vector4][vbl_aquarium.models.unity.Vector4] to convert.
-
-    Returns:
-        List of floats.
-    """
-    return [vector4.x, vector4.y, vector4.z, vector4.w]
-
-
-def list_to_vector4(float_list: list[float | int]) -> Vector4:
-    """Convert a list of floats to a [Vector4][vbl_aquarium.models.unity.Vector4].
-
-    Args:
-        float_list: List of floats.
-
-    Returns:
-        First four elements of the list as a Vector4 padded with zeros if necessary.
-    """
-
-    def get_element(this_array: list[float | int], index: int) -> float:
-        """Safely get an element from an array.
-
-        Return 0 if the index is out of bounds.
-
-        Args:
-            this_array: Array to get the element from.
-            index: Index to get.
-
-        Returns:
-            Element at the index or 0 if the index is out of bounds.
-        """
-        try:
-            return this_array[index]
-        except IndexError:
-            return 0.0
-
-    return Vector4(
-        x=get_element(float_list, 0),
-        y=get_element(float_list, 1),
-        z=get_element(float_list, 2),
-        w=get_element(float_list, 3),
-    )

ephys_link/utils/startup.py

@@ -1,65 +0,0 @@
-"""Program startup helper functions."""
-
-from importlib import import_module
-from inspect import getmembers, isclass
-from pkgutil import iter_modules
-
-from packaging.version import parse
-from requests import ConnectionError, ConnectTimeout, get
-
-from ephys_link.__about__ import __version__
-from ephys_link.utils.base_binding import BaseBinding
-from ephys_link.utils.console import Console
-from ephys_link.utils.constants import ASCII, BINDINGS_DIRECTORY
-
-
-def preamble() -> None:
-    """Print the server startup preamble."""
-    print(ASCII)  # noqa: T201
-    print(__version__)  # noqa: T201
-    print()  # noqa: T201
-    print("This is the Ephys Link server window.")  # noqa: T201
-    print("You may safely leave it running in the background.")  # noqa: T201
-    print("To stop it, close this window or press CTRL + Pause/Break.")  # noqa: T201
-    print()  # noqa: T201
-
-
-def check_for_updates(console: Console) -> None:
-    """Check for updates to the Ephys Link.
-
-    Args:
-        console: Console instance for printing messages.
-    """
-    try:
-        response = get("https://api.github.com/repos/VirtualBrainLab/ephys-link/tags", timeout=10)
-        latest_version = str(response.json()[0]["name"])  # pyright: ignore [reportAny]
-        if parse(latest_version) > parse(__version__):
-            console.critical_print(f"Update available: {latest_version} (current: {__version__})")
-            console.critical_print("Download at: https://github.com/VirtualBrainLab/ephys-link/releases/latest")
-    except (ConnectionError, ConnectTimeout):
-        console.error_print(
-            "UPDATE", "Unable to check for updates. Ignore updates or use the the -i flag to disable checks.\n"
-        )
-
-
-def get_bindings() -> list[type[BaseBinding]]:
-    """Get all binding classes from the bindings directory.
-
-    Returns:
-        List of binding classes.
-    """
-    return [
-        binding_type
-        for module in iter_modules([BINDINGS_DIRECTORY])
-        for _, binding_type in getmembers(import_module(f"ephys_link.bindings.{module.name}"), isclass)
-        if issubclass(binding_type, BaseBinding) and binding_type != BaseBinding
-    ]
-
-
-def get_binding_display_to_cli_name() -> dict[str, str]:
-    """Get mapping of display to CLI option names of the available platform bindings.
-
-    Returns:
-        Dictionary of platform binding display name to CLI option name.
-    """
-    return {binding_type.get_display_name(): binding_type.get_cli_name() for binding_type in get_bindings()}