Skip to content

base_binding

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.

BaseBinding

Bases: ABC

Base class to enforce bindings manipulator platforms will support.

No need to catch exceptions as the Platform Handler will catch them.

Source code in src/ephys_link/utils/base_binding.py 
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
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.
        """

get_angles(manipulator_id) abstractmethod async

Get the current rotation angles of a manipulator in Yaw, Pitch, Roll (degrees).

Parameters:

Name Type Description Default
manipulator_id str

Manipulator ID.

 required

Returns:

Type Description
Vector3

Current angles of the manipulator.
Source code in src/ephys_link/utils/base_binding.py 
80
81
82
83
84
85
86
87
88
89
@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.
    """

get_axes_count() abstractmethod async

Get the number of axes for the current platform.

Returns:

Type Description
int

Number of axes.
Source code in src/ephys_link/utils/base_binding.py 
40
41
42
43
44
45
46
@abstractmethod
async def get_axes_count(self) -> int:
    """Get the number of axes for the current platform.

    Returns:
        Number of axes.
    """

get_cli_name() abstractmethod staticmethod

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:

Type Description
str

Name of the platform to use on the CLI.
Source code in src/ephys_link/utils/base_binding.py 
29
30
31
32
33
34
35
36
37
38
@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.
    """

get_dimensions() abstractmethod

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:

Type Description
Vector4

Dimensions of the manipulators.
Source code in src/ephys_link/utils/base_binding.py 
48
49
50
51
52
53
54
55
56
@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.
    """

get_display_name() abstractmethod staticmethod

Get the full display name of the platform.

Returns:

Type Description
str

Full display name of the platform.
Source code in src/ephys_link/utils/base_binding.py 
20
21
22
23
24
25
26
27
@staticmethod
@abstractmethod
def get_display_name() -> str:
    """Get the full display name of the platform.

    Returns:
        Full display name of the platform.
    """

get_manipulators() abstractmethod async

Get a list of available manipulators on the current platform.

Returns:

Type Description
list[str]

List of manipulator IDs.
Source code in src/ephys_link/utils/base_binding.py 
58
59
60
61
62
63
64
@abstractmethod
async def get_manipulators(self) -> list[str]:
    """Get a list of available manipulators on the current platform.

    Returns:
        List of manipulator IDs.
    """

get_movement_tolerance() abstractmethod

Get the tolerance for how close the final position must be to the target position in a movement (mm).

Returns:

Type Description
float

Movement tolerance (mm).
Source code in src/ephys_link/utils/base_binding.py 
102
103
104
105
106
107
108
@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).
    """

get_position(manipulator_id) abstractmethod async

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.

Parameters:

Name Type Description Default
manipulator_id str

Manipulator ID.

 required

Returns:

Type Description
Vector4

Current position of the manipulator in platform space (mm).
Source code in src/ephys_link/utils/base_binding.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
@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).
    """

get_shank_count(manipulator_id) abstractmethod async

Get the number of shanks on a manipulator.

Parameters:

Name Type Description Default
manipulator_id str

Manipulator ID.

 required

Returns:

Type Description
int

Number of shanks on the manipulator.
Source code in src/ephys_link/utils/base_binding.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
@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.
    """

platform_space_to_unified_space(platform_space) abstractmethod

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.

Parameters:

Name Type Description Default
platform_space Vector4

Platform space coordinates.

 required

Returns:

Type Description
Vector4

Unified space coordinates.
Source code in src/ephys_link/utils/base_binding.py 
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
@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.
    """

set_depth(manipulator_id, depth, speed) abstractmethod async

Set the depth of a manipulator.

This will directly set the depth stage in the original platform space.

Parameters:

Name Type Description Default
manipulator_id str

Manipulator ID.

 required
depth float

Depth to set the manipulator to (mm).

 required
speed float

Speed to move the manipulator to the depth (mm/s).

 required

Returns:

Type Description
float

Final depth of the manipulator in platform space (mm).
Source code in src/ephys_link/utils/base_binding.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
@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).
    """

set_position(manipulator_id, position, speed) abstractmethod async

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.

Parameters:

Name Type Description Default
manipulator_id str

Manipulator ID.

 required
position Vector4

Platform space position to set the manipulator to (mm).

 required
speed float

Speed to move the manipulator to the position (mm/s).

 required

Returns:

Type Description
Vector4

Final position of the manipulator in platform space (mm).
Source code in src/ephys_link/utils/base_binding.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
@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).
    """

stop(manipulator_id) abstractmethod async

Stop a manipulator.

Parameters:

Name Type Description Default
manipulator_id str

Manipulator ID.

 required
Source code in src/ephys_link/utils/base_binding.py 
141
142
143
144
145
146
147
@abstractmethod
async def stop(self, manipulator_id: str) -> None:
    """Stop a manipulator.

    Args:
        manipulator_id: Manipulator ID.
    """

unified_space_to_platform_space(unified_space) abstractmethod

Convert unified space coordinates to platform space coordinates.

This is an axes-swapping transformation.

Parameters:

Name Type Description Default
unified_space Vector4

Unified space coordinates.

 required

Returns:

Type Description
Vector4

Platform space coordinates.
Source code in src/ephys_link/utils/base_binding.py 
165
166
167
168
169
170
171
172
173
174
175
176
@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.
    """