irsim.lib.handler.kinematics_handler

Classes

KinematicsHandler	Abstract base class for handling robot kinematics.
OmniKinematics	Abstract base class for handling robot kinematics.
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.

Parameters:

name (str) – Name used in YAML configs (e.g. "diff", "omni").

Returns:

Class decorator that registers and returns the class unchanged.

Return type:

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.

Parameters:

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

Parameters:

• state (np.ndarray) – Current state.

• velocity (np.ndarray) – Velocity vector.

• step_time (float) – Time step for simulation.

Returns:

Next state.

Return type:

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.

Parameters:

• state (np.ndarray) – Current state vector.

• velocity (np.ndarray) – Velocity vector in kinematics frame.

Returns:

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

Return type:

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.

Parameters:

vel_max (np.ndarray) – Maximum velocity vector.

Returns:

Scalar maximum speed.

Return type:

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.

Parameters:

• state (np.ndarray) – Current state vector.

• velocity (np.ndarray) – Current velocity vector.

Returns:

Heading in radians.

Return type:

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.

Parameters:

• 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 = 2

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.

Parameters:

• state (np.ndarray) – Current state [x, y, theta, …].

• velocity (np.ndarray) – Velocity [vx, vy].

• step_time (float) – Time step.

Returns:

New state (x, y updated; rest preserved).

Return type:

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.

Parameters:

• state (np.ndarray) – Current state vector.

• velocity (np.ndarray) – Velocity vector in kinematics frame.

Returns:

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

Return type:

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.

Parameters:

vel_max (np.ndarray) – Maximum velocity vector.

Returns:

Scalar maximum speed.

Return type:

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.

Parameters:

• state (np.ndarray) – Current state vector.

• velocity (np.ndarray) – Current velocity vector.

Returns:

Heading in radians.

Return type:

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.

Parameters:

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

Parameters:

• state (np.ndarray) – Current state [x, y, theta].

• velocity (np.ndarray) – [linear, angular].

• step_time (float) – Time step.

Returns:

Next state.

Return type:

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.

Parameters:

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

Parameters:

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

Returns:

Next state.

Return type:

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.

Parameters:

name (str) – Kinematics name (e.g. "diff", "omni").

Returns:

The class, or None if not found.

Return type:

type[KinematicsHandler] | None