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)[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

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.

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 body-frame translation to world-frame [vx, vy].

Parameters:

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

Returns:

(2, 1) world-frame velocity.

Return type:

np.ndarray

compute_max_speed(vel_max: numpy.ndarray) → float[source]#

Compute translational speed limit from forward/lateral limits.

Parameters:: vel_max (np.ndarray) – Maximum [forward, lateral] velocity.
Returns:: Euclidean norm of the translational velocity bound.
Return type:: float

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

Compute travel-direction heading for omnidirectional motion.

Parameters:

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

Returns:

World-frame velocity direction 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 body-frame translation to world-frame [vx, vy].

The yaw-rate component is ignored for this projection.

Parameters:

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

Returns:

(2, 1) world-frame velocity.

Return type:

np.ndarray

compute_max_speed(vel_max: numpy.ndarray) → float[source]#

Compute translational speed limit from the first two components.

Parameters:: vel_max (np.ndarray) – Maximum [forward, lateral, yaw_rate] velocity.
Returns:: Euclidean norm of forward/lateral velocity bounds.
Return type:: float

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

Bases: KinematicsHandler

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

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

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.

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

Create a kinematics handler from a YAML kinematics.name value.

Parameters:

name – Registered kinematics name, such as diff, omni, omni_angular, or acker. None uses the fallback.
noise – Whether to apply motion noise.
alpha – Noise parameters passed to the handler.
mode – Ackermann mode, used only by acker.
wheelbase – Ackermann wheelbase; defaults to 1.0 for acker.
role – Object role used for warnings.

Returns:

Registered handler instance, or a differential handler fallback when the name is missing or unknown.

Return type:

KinematicsHandler

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