irsim.lib.handler.kinematics_handler ==================================== .. py:module:: irsim.lib.handler.kinematics_handler Classes ------- .. autoapisummary:: irsim.lib.handler.kinematics_handler.KinematicsHandler irsim.lib.handler.kinematics_handler.OmniKinematics irsim.lib.handler.kinematics_handler.OmniAngularKinematics irsim.lib.handler.kinematics_handler.DifferentialKinematics irsim.lib.handler.kinematics_handler.AckermannKinematics irsim.lib.handler.kinematics_handler.KinematicsFactory Functions --------- .. autoapisummary:: irsim.lib.handler.kinematics_handler.register_kinematics Module Contents --------------- .. py:function:: register_kinematics(name: str) Decorator to register a KinematicsHandler subclass. :param name: Name used in YAML configs (e.g. ``"diff"``, ``"omni"``). :type name: str :returns: Class decorator that registers and returns the class unchanged. :rtype: Callable .. py:class:: KinematicsHandler(name, noise: bool = False, alpha: list | None = None) Bases: :py:obj:`abc.ABC` Abstract base class for handling robot kinematics. Subclasses should set the class-attribute metadata described below and implement :meth:`step`, :meth:`velocity_to_xy`, :meth:`compute_max_speed`, and :meth:`compute_heading`. Initialize the KinematicsHandler class. :param name: Kinematics model name. :type name: str :param noise: Boolean indicating whether to add noise to the velocity (default False). :type noise: bool :param alpha: List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]). :type alpha: list .. py:attribute:: action_dim :type: int :value: 2 .. py:attribute:: min_state_dim :type: int :value: 3 .. py:attribute:: state_dim :type: int :value: 3 .. py:attribute:: vel_max :type: ClassVar[list[float]] :value: [1, 1] .. py:attribute:: vel_min :type: ClassVar[list[float]] .. py:attribute:: acce :type: ClassVar[list[float]] .. py:attribute:: color :type: str :value: 'g' .. py:attribute:: obstacle_color :type: str :value: 'k' .. py:attribute:: description :type: str | None :value: None .. py:attribute:: show_arrow :type: bool :value: True .. py:attribute:: name .. py:attribute:: noise :value: False .. py:attribute:: alpha :value: [0.03, 0, 0, 0.03] .. py:method:: step(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float) -> numpy.ndarray :abstractmethod: Calculate the next state using the kinematics model. :param state: Current state. :type state: np.ndarray :param velocity: Velocity vector. :type velocity: np.ndarray :param step_time: Time step for simulation. :type step_time: float :returns: Next state. :rtype: np.ndarray .. py:method:: 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. :param state: Current state vector. :type state: np.ndarray :param velocity: Velocity vector in kinematics frame. :type velocity: np.ndarray :returns: (2, 1) array of [vx, vy]. :rtype: np.ndarray .. py:method:: 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. :param vel_max: Maximum velocity vector. :type vel_max: np.ndarray :returns: Scalar maximum speed. :rtype: float .. py:method:: 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. :param state: Current state vector. :type state: np.ndarray :param velocity: Current velocity vector. :type velocity: np.ndarray :returns: Heading in radians. :rtype: float .. py:class:: OmniKinematics(name, noise, alpha) Bases: :py:obj:`KinematicsHandler` Abstract base class for handling robot kinematics. Subclasses should set the class-attribute metadata described below and implement :meth:`step`, :meth:`velocity_to_xy`, :meth:`compute_max_speed`, and :meth:`compute_heading`. Initialize the KinematicsHandler class. :param name: Kinematics model name. :type name: str :param noise: Boolean indicating whether to add noise to the velocity (default False). :type noise: bool :param alpha: List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]). :type alpha: list .. py:attribute:: action_dim :value: 2 .. py:attribute:: min_state_dim :value: 3 .. py:attribute:: state_dim :value: 3 .. py:attribute:: vel_max :type: ClassVar[list[float]] :value: [1, 1] .. py:attribute:: vel_min :type: ClassVar[list[float]] .. py:attribute:: acce :type: ClassVar[list[float]] .. py:attribute:: color :value: 'g' .. py:attribute:: obstacle_color :value: 'k' .. py:attribute:: description :value: None .. py:attribute:: show_arrow :value: False .. py:method:: step(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float) -> numpy.ndarray Advance omnidirectional state one step. :param state: Current state [x, y, theta]. :type state: np.ndarray :param velocity: Velocity [forward, lateral] in body frame. :type velocity: np.ndarray :param step_time: Time step. :type step_time: float :returns: New state [x, y, theta] (theta preserved). :rtype: np.ndarray .. py:method:: 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. :param state: Current state vector. :type state: np.ndarray :param velocity: Velocity vector in kinematics frame. :type velocity: np.ndarray :returns: (2, 1) array of [vx, vy]. :rtype: np.ndarray .. py:method:: 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. :param vel_max: Maximum velocity vector. :type vel_max: np.ndarray :returns: Scalar maximum speed. :rtype: float .. py:method:: 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. :param state: Current state vector. :type state: np.ndarray :param velocity: Current velocity vector. :type velocity: np.ndarray :returns: Heading in radians. :rtype: float .. py:class:: OmniAngularKinematics(name, noise, alpha) Bases: :py:obj:`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 :class:`OmniKinematics` which derives heading from velocity direction. Initialize the KinematicsHandler class. :param name: Kinematics model name. :type name: str :param noise: Boolean indicating whether to add noise to the velocity (default False). :type noise: bool :param alpha: List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]). :type alpha: list .. py:attribute:: action_dim :value: 3 .. py:attribute:: min_state_dim :value: 3 .. py:attribute:: state_dim :value: 3 .. py:attribute:: vel_max :type: ClassVar[list[float]] :value: [1, 1, 1] .. py:attribute:: vel_min :type: ClassVar[list[float]] .. py:attribute:: acce :type: ClassVar[list[float]] .. py:attribute:: color :value: 'g' .. py:attribute:: obstacle_color :value: 'k' .. py:attribute:: description :value: None .. py:attribute:: show_arrow :value: True .. py:method:: step(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float) -> numpy.ndarray Advance omnidirectional-angular state one step. :param state: Current state [x, y, theta]. :type state: np.ndarray :param velocity: Velocity [forward, lateral, yaw_rate] in body frame. :type velocity: np.ndarray :param step_time: Time step. :type step_time: float :returns: New state [x, y, theta]. :rtype: np.ndarray .. py:method:: 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. :param state: Current state vector. :type state: np.ndarray :param velocity: Velocity vector in kinematics frame. :type velocity: np.ndarray :returns: (2, 1) array of [vx, vy]. :rtype: np.ndarray .. py:method:: 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. :param vel_max: Maximum velocity vector. :type vel_max: np.ndarray :returns: Scalar maximum speed. :rtype: float .. py:class:: DifferentialKinematics(name, noise, alpha) Bases: :py:obj:`KinematicsHandler` Abstract base class for handling robot kinematics. Subclasses should set the class-attribute metadata described below and implement :meth:`step`, :meth:`velocity_to_xy`, :meth:`compute_max_speed`, and :meth:`compute_heading`. Initialize the KinematicsHandler class. :param name: Kinematics model name. :type name: str :param noise: Boolean indicating whether to add noise to the velocity (default False). :type noise: bool :param alpha: List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]). :type alpha: list .. py:attribute:: action_dim :value: 2 .. py:attribute:: min_state_dim :value: 3 .. py:attribute:: state_dim :value: 3 .. py:attribute:: vel_max :type: ClassVar[list[float]] :value: [1, 1] .. py:attribute:: vel_min :type: ClassVar[list[float]] .. py:attribute:: acce :type: ClassVar[list[float]] .. py:attribute:: color :value: 'g' .. py:attribute:: obstacle_color :value: 'k' .. py:attribute:: description :value: None .. py:attribute:: show_arrow :value: True .. py:method:: step(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float) -> numpy.ndarray Advance differential-drive state one step. :param state: Current state [x, y, theta]. :type state: np.ndarray :param velocity: [linear, angular]. :type velocity: np.ndarray :param step_time: Time step. :type step_time: float :returns: Next state. :rtype: np.ndarray .. py:class:: AckermannKinematics(name, noise: bool = False, alpha: list | None = None, mode: str = 'steer', wheelbase: float = 1.0) Bases: :py:obj:`KinematicsHandler` Abstract base class for handling robot kinematics. Subclasses should set the class-attribute metadata described below and implement :meth:`step`, :meth:`velocity_to_xy`, :meth:`compute_max_speed`, and :meth:`compute_heading`. Initialize the KinematicsHandler class. :param name: Kinematics model name. :type name: str :param noise: Boolean indicating whether to add noise to the velocity (default False). :type noise: bool :param alpha: List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]). :type alpha: list .. py:attribute:: action_dim :value: 2 .. py:attribute:: min_state_dim :value: 4 .. py:attribute:: state_dim :value: 4 .. py:attribute:: vel_max :type: ClassVar[list[float]] :value: [1, 1] .. py:attribute:: vel_min :type: ClassVar[list[float]] .. py:attribute:: acce :type: ClassVar[list[float]] .. py:attribute:: color :value: 'y' .. py:attribute:: obstacle_color :value: 'k' .. py:attribute:: description :value: 'car_green.png' .. py:attribute:: show_arrow :value: True .. py:attribute:: mode :value: 'steer' .. py:attribute:: wheelbase :value: 1.0 .. py:method:: step(state: numpy.ndarray, velocity: numpy.ndarray, step_time: float) -> numpy.ndarray Advance Ackermann-steered state one step. :param state: Current state [x, y, theta, steer]. :type state: np.ndarray :param velocity: Depending on mode: [linear, steer] or [linear, angular]. :type velocity: np.ndarray :param step_time: Time step. :type step_time: float :returns: Next state. :rtype: np.ndarray .. py:class:: KinematicsFactory Factory class to create kinematics handlers. .. py:method:: create_kinematics(name: str | None = None, noise: bool = False, alpha: list | None = None, mode: str = 'steer', wheelbase: float | None = None, role: str = 'robot') -> KinematicsHandler :staticmethod: .. py:method:: get_handler_class(name: str) -> type[KinematicsHandler] | None :staticmethod: Look up a registered handler class by name without instantiation. :param name: Kinematics name (e.g. ``"diff"``, ``"omni"``). :type name: str :returns: The class, or ``None`` if not found. :rtype: type[KinematicsHandler] | None