irsim.lib.handler.kinematics_handler#

Classes#

`KinematicsHandler`	Abstract base class for handling robot kinematics.
`OmniKinematics`	Omnidirectional model with body-frame translational velocity.
`OmniAngularKinematics`	Omnidirectional kinematics with angular velocity control.
`DifferentialKinematics`	Differential-drive model with `[linear, angular]` velocity.
`AckermannKinematics`	Ackermann car-like model with steering or angular-rate control.
`KinematicsFactory`	Factory class to create kinematics handlers.

Functions#

register_kinematics(name)

Decorator to register a KinematicsHandler subclass.

Module Contents#

irsim.lib.handler.kinematics_handler.register_kinematics(name: str)[源代码]#

Decorator to register a KinematicsHandler subclass.

Any extra key under kinematics: in YAML is passed to the subclass's __init__ (after name, noise, alpha), so a registered model can take its own parameters, e.g. kinematics: {name: lag, tau: 0.5}.

参数:: name (str) -- Name used in YAML configs (e.g. "diff", "omni").
返回:: Class decorator that registers and returns the class unchanged.
返回类型:: Callable

class irsim.lib.handler.kinematics_handler.KinematicsHandler(name, noise: bool = False, alpha: list | None = None)[源代码]#

Bases: abc.ABC

Abstract base class for handling robot kinematics.

Subclasses should set the class-attribute metadata described below and implement step(), velocity_to_xy(), compute_max_speed(), and compute_heading(). A subclass may add keyword parameters to __init__; any extra key under kinematics: in YAML is passed to it.

Initialize the KinematicsHandler class.

参数:

name (str) -- Kinematics model name.
noise (bool) -- Boolean indicating whether to add noise to the velocity (default False).
alpha (list) -- List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]).

action_dim: int = 2#

min_state_dim: int = 3#

state_dim: int = 3#

vel_max: ClassVar[list[float]] = [1, 1]#

vel_min: ClassVar[list[float]]#

acce: ClassVar[list[float]]#

color: str = 'g'#

obstacle_color: str = 'k'#

description: str | None = None#

show_arrow: bool = True#

name#

noise = False#

alpha = [0.03, 0, 0, 0.03]#

abstractmethod step(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float) → numpy.ndarray[源代码]#

Calculate the next state using the kinematics model.

参数:

state (np.ndarray) -- Current state.
velocity (np.ndarray) -- Velocity vector.
step_time (float) -- Time step for simulation.

返回:

Next state.

返回类型:

np.ndarray

velocity_to_xy(state: numpy.ndarray, velocity: numpy.ndarray) → numpy.ndarray[源代码]#

Convert velocity to [vx, vy] in world frame.

The default implementation follows differential-drive conventions: velocity[0] is the linear speed projected through the heading angle state[2], which is what vel_diff2world() does. Subclasses with different velocity semantics (e.g. omnidirectional) should override this.

参数:

state (np.ndarray) -- Current state vector.
velocity (np.ndarray) -- Velocity vector in kinematics frame.

返回:

(2, 1) array of [vx, vy].

返回类型:

np.ndarray

compute_max_speed(vel_max: numpy.ndarray) → float[源代码]#

Compute the scalar maximum speed from the vel_max vector.

The default implementation follows differential-drive conventions: the first component vel_max[0, 0] is the translational speed limit. Subclasses where max speed is derived differently (e.g. omnidirectional using the L2 norm) should override this.

参数:: vel_max (np.ndarray) -- Maximum velocity vector.
返回:: Scalar maximum speed.
返回类型:: float

compute_heading(state: numpy.ndarray, velocity: numpy.ndarray) → float[源代码]#

Compute the heading angle.

The default implementation follows differential-drive conventions: heading is state[2] (the orientation component). Returns 0.0 if the state has fewer than 3 rows.

参数:

state (np.ndarray) -- Current state vector.
velocity (np.ndarray) -- Current velocity vector.

返回:

Heading in radians.

返回类型:

float

class irsim.lib.handler.kinematics_handler.OmniKinematics(name, noise, alpha)[源代码]#

Bases: KinematicsHandler

Omnidirectional model with body-frame translational velocity.

Velocity is [forward, lateral] in the robot body frame. The state is [x, y, theta] and theta is preserved by step().

Initialize the KinematicsHandler class.

参数:

name (str) -- Kinematics model name.
noise (bool) -- Boolean indicating whether to add noise to the velocity (default False).
alpha (list) -- List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]).

action_dim = 2#

min_state_dim = 3#

state_dim = 3#

vel_max: ClassVar[list[float]] = [1, 1]#

vel_min: ClassVar[list[float]]#

acce: ClassVar[list[float]]#

color = 'g'#

obstacle_color = 'k'#

description = None#

show_arrow = False#

step(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float) → numpy.ndarray[源代码]#

Advance omnidirectional state one step.

参数:

state (np.ndarray) -- Current state [x, y, theta].
velocity (np.ndarray) -- Velocity [forward, lateral] in body frame.
step_time (float) -- Time step.

返回:

New state [x, y, theta] (theta preserved).

返回类型:

np.ndarray

velocity_to_xy(state: numpy.ndarray, velocity: numpy.ndarray) → numpy.ndarray[源代码]#

Convert body-frame translation to world-frame [vx, vy].

参数:

state (np.ndarray) -- Current state [x, y, theta].
velocity (np.ndarray) -- Body-frame [forward, lateral] velocity.

返回:

(2, 1) world-frame velocity.

返回类型:

np.ndarray

compute_max_speed(vel_max: numpy.ndarray) → float[源代码]#

Compute translational speed limit from forward/lateral limits.

参数:: vel_max (np.ndarray) -- Maximum [forward, lateral] velocity.
返回:: Euclidean norm of the translational velocity bound.
返回类型:: float

compute_heading(state: numpy.ndarray, velocity: numpy.ndarray) → float[源代码]#

Compute travel-direction heading for omnidirectional motion.

参数:

state (np.ndarray) -- Current state [x, y, theta].
velocity (np.ndarray) -- Body-frame [forward, lateral] velocity.

返回:

World-frame velocity direction in radians.

返回类型:

float

class irsim.lib.handler.kinematics_handler.OmniAngularKinematics(name, noise, alpha)[源代码]#

Bases: KinematicsHandler

Omnidirectional kinematics with angular velocity control.

Velocity is [forward, lateral, yaw_rate] in body frame. The kinematics function converts to world-frame internally.

Note: compute_heading is intentionally inherited from the base class (returns state[2]), because this robot has independent yaw control and its heading IS the orientation angle, unlike OmniKinematics which derives heading from velocity direction.

Initialize the KinematicsHandler class.

参数:

name (str) -- Kinematics model name.
noise (bool) -- Boolean indicating whether to add noise to the velocity (default False).
alpha (list) -- List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]).

action_dim = 3#

min_state_dim = 3#

state_dim = 3#

vel_max: ClassVar[list[float]] = [1, 1, 1]#

vel_min: ClassVar[list[float]]#

acce: ClassVar[list[float]]#

color = 'g'#

obstacle_color = 'k'#

description = None#

show_arrow = True#

step(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float) → numpy.ndarray[源代码]#

Advance omnidirectional-angular state one step.

参数:

state (np.ndarray) -- Current state [x, y, theta].
velocity (np.ndarray) -- Velocity [forward, lateral, yaw_rate] in body frame.
step_time (float) -- Time step.

返回:

New state [x, y, theta].

返回类型:

np.ndarray

velocity_to_xy(state: numpy.ndarray, velocity: numpy.ndarray) → numpy.ndarray[源代码]#

Convert body-frame translation to world-frame [vx, vy].

The yaw-rate component is ignored for this projection.

参数:

state (np.ndarray) -- Current state [x, y, theta].
velocity (np.ndarray) -- Body-frame [forward, lateral, yaw_rate].

返回:

(2, 1) world-frame velocity.

返回类型:

np.ndarray

compute_max_speed(vel_max: numpy.ndarray) → float[源代码]#

Compute translational speed limit from the first two components.

参数:: vel_max (np.ndarray) -- Maximum [forward, lateral, yaw_rate] velocity.
返回:: Euclidean norm of forward/lateral velocity bounds.
返回类型:: float

class irsim.lib.handler.kinematics_handler.DifferentialKinematics(name, noise, alpha)[源代码]#

Bases: KinematicsHandler

Differential-drive model with [linear, angular] velocity.

Initialize the KinematicsHandler class.

参数:

name (str) -- Kinematics model name.
noise (bool) -- Boolean indicating whether to add noise to the velocity (default False).
alpha (list) -- List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]).

action_dim = 2#

min_state_dim = 3#

state_dim = 3#

vel_max: ClassVar[list[float]] = [1, 1]#

vel_min: ClassVar[list[float]]#

acce: ClassVar[list[float]]#

color = 'g'#

obstacle_color = 'k'#

description = None#

show_arrow = True#

step(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float) → numpy.ndarray[源代码]#

Advance differential-drive state one step.

参数:

state (np.ndarray) -- Current state [x, y, theta].
velocity (np.ndarray) -- [linear, angular].
step_time (float) -- Time step.

返回:

Next state.

返回类型:

np.ndarray

class irsim.lib.handler.kinematics_handler.AckermannKinematics(name, noise: bool = False, alpha: list | None = None, mode: str = 'steer', wheelbase: float = 1.0)[源代码]#

Bases: KinematicsHandler

Ackermann car-like model with steering or angular-rate control.

The state is [x, y, theta, steer]. In mode="steer", velocity is interpreted as [linear, steer]; other modes are handled by irsim.lib.algorithm.kinematics.ackermann_kinematics().

Initialize the KinematicsHandler class.

参数:

name (str) -- Kinematics model name.
noise (bool) -- Boolean indicating whether to add noise to the velocity (default False).
alpha (list) -- List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]).

action_dim = 2#

min_state_dim = 4#

state_dim = 4#

vel_max: ClassVar[list[float]] = [1, 1]#

vel_min: ClassVar[list[float]]#

acce: ClassVar[list[float]]#

color = 'y'#

obstacle_color = 'k'#

description = 'car_green.png'#

show_arrow = True#

mode = 'steer'#

wheelbase = 1.0#

step(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float) → numpy.ndarray[源代码]#

Advance Ackermann-steered state one step.

参数:

state (np.ndarray) -- Current state [x, y, theta, steer].
velocity (np.ndarray) -- Depending on mode: [linear, steer] or [linear, angular].
step_time (float) -- Time step.

返回:

Next state.

返回类型:

np.ndarray

class irsim.lib.handler.kinematics_handler.KinematicsFactory[源代码]#

Factory class to create kinematics handlers.

static create_kinematics(name: str | None = None, noise: bool = False, alpha: list | None = None, mode: str | None = None, wheelbase: float | None = None, role: str = 'robot', *, shape_wheelbase: float | None = None, **kwargs: Any) → KinematicsHandler[源代码]#

Create a kinematics handler from a YAML kinematics block.

参数:

name -- Registered kinematics name: diff, omni, omni_angular, acker, or a custom name registered with register_kinematics(). None defaults to diff; static is retained as the static-object sentinel.
noise -- Whether to apply motion noise.
alpha -- Noise parameters passed to the handler.
mode -- Steering mode of acker handlers; forwarded when given.
wheelbase -- Wheelbase set under kinematics; forwarded when given and takes precedence over shape_wheelbase.
role -- Object role, retained for API compatibility.
shape_wheelbase -- Wheelbase taken from a car-like shape; the fallback for acker handlers (default 1.0) when wheelbase is not given.
**kwargs -- Any other kinematics key, forwarded to the handler's __init__ (a custom handler's own parameters).

返回:

Handler instance for name.

返回类型:

KinematicsHandler

抛出:

NotImplementedError -- If name is not registered.
TypeError -- If the handler does not accept a forwarded parameter.

static get_handler_class(name: str) → type[KinematicsHandler] | None[源代码]#

Look up a registered handler class by name without instantiation.

参数:: name (str) -- Kinematics name (e.g. "diff", "omni").
返回:: The class, or None if not found.
返回类型:: type[KinematicsHandler] | None