irsim.lib.path_planners.jps
===========================

.. py:module:: irsim.lib.path_planners.jps

.. autoapi-nested-parse::

   Jump Point Search (JPS) grid planning.

   An optimization of A* for uniform-cost grids that prunes symmetric paths
   and expands "jump points" only, preserving optimality while reducing nodes expanded.

   Collision precedence:
     1. Grid lookup when ``env_map.grid`` is not ``None``; if occupied, collision.
     2. When the grid reports free or is unavailable, Shapely vs. obstacle_list.
     (Grid and obstacle_list are combined when both are present.)

   .. rubric:: References

   - D. Harabor and A. Grastien. Online Graph Pruning for Pathfinding on Grid Maps.
     In AAAI, 2011. https://en.wikipedia.org/wiki/Jump_point_search
   - 2D implementation reference: KumarRobotics/jps3d (C++ JPS on 2D/3D maps).
     https://github.com/KumarRobotics/jps3d



Attributes
----------

.. autoapisummary::

   irsim.lib.path_planners.jps.JpsSuccessor


Classes
-------

.. autoapisummary::

   irsim.lib.path_planners.jps.JPSPlanner


Module Contents
---------------

.. py:data:: JpsSuccessor

.. py:class:: JPSPlanner(env_map: irsim.world.map.EnvGridMap)

   Jump Point Search planner for uniform-cost 8-connected grids.

   When the environment map carries an occupancy grid (``env_map.grid``),
   collision checks use a fast O(1) grid lookup.  Otherwise, the planner
   falls back to Shapely geometry intersection (same as :class:`AStarPlanner`).

   Initialize JPS planner.

   :param env_map: Environment map (any :class:`~irsim.world.map.EnvGridMap`
                   compatible object).  Resolution and bounds are taken from the
                   map (same as :class:`AStarPlanner`).


   .. py:attribute:: origin_x


   .. py:attribute:: origin_y


   .. py:attribute:: max_x


   .. py:attribute:: max_y


   .. py:attribute:: obstacle_list


   .. py:method:: planning(start_pose: numpy.ndarray, goal_pose: numpy.ndarray, show_animation: bool = True) -> numpy.ndarray | None

      JPS path search.

      :param start_pose: start pose [x, y]
      :type start_pose: np.ndarray
      :param goal_pose: goal pose [x, y]
      :type goal_pose: np.ndarray
      :param show_animation: If true, shows the animation of planning process
      :type show_animation: bool

      :returns: shape (2, N) array [rx, ry] of the final path, or None
                if the start or goal cell is not walkable, or if no path exists (open set
                exhausted).
      :rtype: np.ndarray | None



   .. py:method:: calc_grid_position(index: int, min_position: float) -> float


   .. py:method:: calc_xy_index(position: float, min_pos: float) -> int


   .. py:method:: calc_grid_index_from_xy(x: int, y: int) -> int


   .. py:method:: is_collision(x: float, y: float) -> bool

      True if world position ``(x, y)`` is in collision.