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)[source]#

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)[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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)[source]#

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 = False#

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

Advance omnidirectional state one step.

Parameters:

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

Returns:

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

Return type:

np.ndarray

velocity_to_xy(state: numpy.ndarray, velocity: numpy.ndarray) → numpy.ndarray[source]#

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[source]#

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[source]#

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.OmniAngularKinematics(name, noise, alpha)[source]#

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.

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 = 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[source]#

Advance omnidirectional-angular state one step.

Parameters:

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

Returns:

New state [x, y, theta].

Return type:

np.ndarray

velocity_to_xy(state: numpy.ndarray, velocity: numpy.ndarray) → numpy.ndarray[source]#

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[source]#

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

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

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[source]#

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)[source]#

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[source]#

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[source]#

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[source]#

static get_handler_class(name: str) → type[KinematicsHandler] | None[source]#

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