Skip to content

Skeleton API

skelarm.skeleton

Defines the Link and Skeleton classes for the skelarm robot arm simulator.

Represents a single link of the robot arm.

Source code in src/skelarm/skeleton.py 
 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
class Link:
    """Represents a single link of the robot arm."""

    def __init__(self, properties: LinkProp | dict[str, Any]) -> None:
        """
        Initialize a Link object from LinkProp or a dictionary.

        :param properties: Either a LinkProp object or a dictionary containing
                           link properties ('length', 'm', 'i', 'rgx', 'rgy', 'qmin', 'qmax').
        """
        if isinstance(properties, LinkProp):
            self.prop = properties
        elif isinstance(properties, dict):
            # Ensure 'l' is handled if passed in dict, convert to 'length'
            if "l" in properties:
                properties["length"] = properties.pop("l")
            self.prop = LinkProp(**properties)
        else:
            error_msg = "Properties must be a LinkProp object or a dictionary."
            raise TypeError(error_msg)

        # State variables, initialized to zeros or defaults
        self.q: float = 0.0  # Joint angle
        self.dq: float = 0.0  # Joint angular velocity
        self.ddq: float = 0.0  # Joint angular acceleration
        self.q_absolute: float = 0.0  # Absolute angle of the link (used in RNE)

        # End-effector position and velocity (local to link)
        self.x: float = 0.0
        self.y: float = 0.0
        self.vx: float = 0.0
        self.vy: float = 0.0
        self.ax: float = 0.0
        self.ay: float = 0.0

        # Center of mass position and velocity (global)
        self.xg: float = 0.0
        self.yg: float = 0.0
        self.agx: float = 0.0
        self.agy: float = 0.0

        # Joint forces/torques
        self.jx: float = 0.0  # Force at joint x
        self.jy: float = 0.0  # Force at joint y
        self.hx: float = 0.0  # Moment at joint x
        self.hy: float = 0.0  # Moment at joint y
        self.fx: float = 0.0  # Force applied to link x
        self.fy: float = 0.0  # Force applied to link y
        self.tau: float = 0.0  # Torque at joint

        # External forces/torques
        self.fex: float = 0.0  # External force x
        self.fey: float = 0.0  # External force y
        self.rex: float = 0.0  # External force x application point
        self.rey: float = 0.0  # External force y application point

        # End-effector position (global)
        self.xe: float = 0.0
        self.ye: float = 0.0

        # --- Attributes for Inverse Dynamics (RNE) ---
        self.w: float = 0.0  # Angular velocity of link frame
        self.dw: float = 0.0  # Angular acceleration of link frame

        # Linear velocity/acceleration of link origin (joint)
        self.v: NDArray[np.float64] = cast("NDArray[np.float64]", np.zeros(2))
        self.dv: NDArray[np.float64] = cast("NDArray[np.float64]", np.zeros(2))

        # Linear velocity/acceleration of center of mass
        self.vc: NDArray[np.float64] = cast("NDArray[np.float64]", np.zeros(2))
        self.dvc: NDArray[np.float64] = cast("NDArray[np.float64]", np.zeros(2))

        # Forces and moments
        self.f: NDArray[np.float64] = cast("NDArray[np.float64]", np.zeros(2))  # Force from parent link
        self.n: float = 0.0  # Moment exerted by parent link on current link

__init__(properties)

Initialize a Link object from LinkProp or a dictionary.

:param properties: Either a LinkProp object or a dictionary containing link properties ('length', 'm', 'i', 'rgx', 'rgy', 'qmin', 'qmax').

Source code in src/skelarm/skeleton.py 
 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
def __init__(self, properties: LinkProp | dict[str, Any]) -> None:
    """
    Initialize a Link object from LinkProp or a dictionary.

    :param properties: Either a LinkProp object or a dictionary containing
                       link properties ('length', 'm', 'i', 'rgx', 'rgy', 'qmin', 'qmax').
    """
    if isinstance(properties, LinkProp):
        self.prop = properties
    elif isinstance(properties, dict):
        # Ensure 'l' is handled if passed in dict, convert to 'length'
        if "l" in properties:
            properties["length"] = properties.pop("l")
        self.prop = LinkProp(**properties)
    else:
        error_msg = "Properties must be a LinkProp object or a dictionary."
        raise TypeError(error_msg)

    # State variables, initialized to zeros or defaults
    self.q: float = 0.0  # Joint angle
    self.dq: float = 0.0  # Joint angular velocity
    self.ddq: float = 0.0  # Joint angular acceleration
    self.q_absolute: float = 0.0  # Absolute angle of the link (used in RNE)

    # End-effector position and velocity (local to link)
    self.x: float = 0.0
    self.y: float = 0.0
    self.vx: float = 0.0
    self.vy: float = 0.0
    self.ax: float = 0.0
    self.ay: float = 0.0

    # Center of mass position and velocity (global)
    self.xg: float = 0.0
    self.yg: float = 0.0
    self.agx: float = 0.0
    self.agy: float = 0.0

    # Joint forces/torques
    self.jx: float = 0.0  # Force at joint x
    self.jy: float = 0.0  # Force at joint y
    self.hx: float = 0.0  # Moment at joint x
    self.hy: float = 0.0  # Moment at joint y
    self.fx: float = 0.0  # Force applied to link x
    self.fy: float = 0.0  # Force applied to link y
    self.tau: float = 0.0  # Torque at joint

    # External forces/torques
    self.fex: float = 0.0  # External force x
    self.fey: float = 0.0  # External force y
    self.rex: float = 0.0  # External force x application point
    self.rey: float = 0.0  # External force y application point

    # End-effector position (global)
    self.xe: float = 0.0
    self.ye: float = 0.0

    # --- Attributes for Inverse Dynamics (RNE) ---
    self.w: float = 0.0  # Angular velocity of link frame
    self.dw: float = 0.0  # Angular acceleration of link frame

    # Linear velocity/acceleration of link origin (joint)
    self.v: NDArray[np.float64] = cast("NDArray[np.float64]", np.zeros(2))
    self.dv: NDArray[np.float64] = cast("NDArray[np.float64]", np.zeros(2))

    # Linear velocity/acceleration of center of mass
    self.vc: NDArray[np.float64] = cast("NDArray[np.float64]", np.zeros(2))
    self.dvc: NDArray[np.float64] = cast("NDArray[np.float64]", np.zeros(2))

    # Forces and moments
    self.f: NDArray[np.float64] = cast("NDArray[np.float64]", np.zeros(2))  # Force from parent link
    self.n: float = 0.0  # Moment exerted by parent link on current link

LinkProp dataclass

Properties of a single robot arm link.

Source code in src/skelarm/skeleton.py 
17
18
19
20
21
22
23
24
25
26
27
@dataclass
class LinkProp:
    """Properties of a single robot arm link."""

    length: float
    m: float
    i: float
    rgx: float
    rgy: float
    qmin: float  # Radians
    qmax: float  # Radians

Skeleton

Represents the entire robot arm (skeleton).

Source code in src/skelarm/skeleton.py 
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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
class Skeleton:
    """Represents the entire robot arm (skeleton)."""

    def __init__(self, link_props: Sequence[LinkProp | dict[str, Any]]) -> None:
        """
        Initialize the Skeleton with a list of link properties.

        :param link_props: A list of LinkProp objects or dictionaries, one for each link.
        """
        self.links: list[Link] = [Link(prop) for prop in link_props]
        self.num_links: int = len(self.links)

    @classmethod
    def from_toml(cls, file_path: str | Path) -> Skeleton:
        """
        Create a Skeleton from a TOML configuration file.

        :param file_path: Path to the TOML file.
        :return: A new Skeleton instance.
        """
        path = Path(file_path)
        with path.open("rb") as f:
            data = tomllib.load(f)

        link_props = []
        for link_data in data.get("link", []):
            # Extract properties from TOML data
            length = link_data["length"]
            mass = link_data["mass"]
            inertia = link_data["inertia"]

            # Allow 'com' as [x, y] or 'rgx'/'rgy' keys
            if "com" in link_data:
                rgx, rgy = link_data["com"]
            else:
                rgx = link_data.get("rgx", 0.0)
                rgy = link_data.get("rgy", 0.0)

            # Allow 'limits' as [min, max] or 'qmin'/'qmax' keys
            if "limits" in link_data:
                qmin_deg, qmax_deg = link_data["limits"]
            else:
                qmin_deg = link_data.get("qmin", -180.0)
                qmax_deg = link_data.get("qmax", 180.0)

            # Convert limits from degrees (config) to radians (internal)
            qmin = np.deg2rad(qmin_deg)
            qmax = np.deg2rad(qmax_deg)

            link_props.append(
                LinkProp(
                    length=length,
                    m=mass,
                    i=inertia,
                    rgx=rgx,
                    rgy=rgy,
                    qmin=qmin,
                    qmax=qmax,
                )
            )

        return cls(link_props)

    @property
    def q(self) -> NDArray[np.float64]:
        """Return current joint angles."""
        import numpy as np  # Import at runtime for actual usage

        return np.array([link.q for link in self.links], dtype=np.float64)

    @q.setter
    def q(self, q_values: NDArray[np.float64]) -> None:
        """Set joint angles."""
        if len(q_values) != self.num_links:
            error_msg = f"Expected {self.num_links} joint angles, but got {len(q_values)}"
            raise ValueError(error_msg)
        for i, link in enumerate(self.links):
            link.q = q_values[i]

    @property
    def dq(self) -> NDArray[np.float64]:
        """Return current joint angular velocities."""
        import numpy as np  # Import at runtime for actual usage

        return np.array([link.dq for link in self.links], dtype=np.float64)

    @dq.setter
    def dq(self, dq_values: NDArray[np.float64]) -> None:
        """Set joint angular velocities."""
        if len(dq_values) != self.num_links:
            error_msg = f"Expected {self.num_links} joint angular velocities, but got {len(dq_values)}"
            raise ValueError(error_msg)
        for i, link in enumerate(self.links):
            link.dq = dq_values[i]

    @property
    def ddq(self) -> NDArray[np.float64]:
        """Return current joint angular accelerations."""
        import numpy as np  # Import at runtime for actual usage

        return np.array([link.ddq for link in self.links], dtype=np.float64)

    @ddq.setter
    def ddq(self, ddq_values: NDArray[np.float64]) -> None:
        """Set joint angular accelerations."""
        if len(ddq_values) != self.num_links:
            error_msg = f"Expected {self.num_links} joint angular accelerations, but got {len(ddq_values)}"
            raise ValueError(error_msg)
        for i, link in enumerate(self.links):
            link.ddq = ddq_values[i]

    @property
    def tau(self) -> NDArray[np.float64]:
        """Return current joint torques."""
        import numpy as np

        return np.array([link.tau for link in self.links], dtype=np.float64)

    @tau.setter
    def tau(self, tau_values: NDArray[np.float64]) -> None:
        """Set joint torques."""
        if len(tau_values) != self.num_links:
            error_msg = f"Expected {self.num_links} joint torques, but got {len(tau_values)}"
            raise ValueError(error_msg)
        for i, link in enumerate(self.links):
            link.tau = tau_values[i]

ddq property writable

Return current joint angular accelerations.

dq property writable

Return current joint angular velocities.

q property writable

Return current joint angles.

tau property writable

Return current joint torques.

__init__(link_props)

Initialize the Skeleton with a list of link properties.

:param link_props: A list of LinkProp objects or dictionaries, one for each link.

Source code in src/skelarm/skeleton.py 
110
111
112
113
114
115
116
117
def __init__(self, link_props: Sequence[LinkProp | dict[str, Any]]) -> None:
    """
    Initialize the Skeleton with a list of link properties.

    :param link_props: A list of LinkProp objects or dictionaries, one for each link.
    """
    self.links: list[Link] = [Link(prop) for prop in link_props]
    self.num_links: int = len(self.links)

from_toml(file_path) classmethod

Create a Skeleton from a TOML configuration file.

:param file_path: Path to the TOML file. :return: A new Skeleton instance.

Source code in src/skelarm/skeleton.py 
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
@classmethod
def from_toml(cls, file_path: str | Path) -> Skeleton:
    """
    Create a Skeleton from a TOML configuration file.

    :param file_path: Path to the TOML file.
    :return: A new Skeleton instance.
    """
    path = Path(file_path)
    with path.open("rb") as f:
        data = tomllib.load(f)

    link_props = []
    for link_data in data.get("link", []):
        # Extract properties from TOML data
        length = link_data["length"]
        mass = link_data["mass"]
        inertia = link_data["inertia"]

        # Allow 'com' as [x, y] or 'rgx'/'rgy' keys
        if "com" in link_data:
            rgx, rgy = link_data["com"]
        else:
            rgx = link_data.get("rgx", 0.0)
            rgy = link_data.get("rgy", 0.0)

        # Allow 'limits' as [min, max] or 'qmin'/'qmax' keys
        if "limits" in link_data:
            qmin_deg, qmax_deg = link_data["limits"]
        else:
            qmin_deg = link_data.get("qmin", -180.0)
            qmax_deg = link_data.get("qmax", 180.0)

        # Convert limits from degrees (config) to radians (internal)
        qmin = np.deg2rad(qmin_deg)
        qmax = np.deg2rad(qmax_deg)

        link_props.append(
            LinkProp(
                length=length,
                m=mass,
                i=inertia,
                rgx=rgx,
                rgy=rgy,
                qmin=qmin,
                qmax=qmax,
            )
        )

    return cls(link_props)