irsim.lib.handler.kinematics_handler

Classes

KinematicsHandler	Abstract base class for handling robot kinematics.
OmniKinematics	Abstract base class for handling robot kinematics.
OmniAngularKinematics	Omnidirectional kinematics with angular velocity control.
DifferentialKinematics	Abstract base class for handling robot kinematics.
AckermannKinematics	Abstract base class for handling robot kinematics.
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.

参数:

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().

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]. 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

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().

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 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]. 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.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 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]. 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

class irsim.lib.handler.kinematics_handler.DifferentialKinematics(name, noise, alpha)

Bases: KinematicsHandler

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().

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

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().

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 = 'steer', wheelbase: float | None = None, role: str = 'robot') → KinematicsHandler

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