.. _GlobalPlanner:

GlobalPlanner
=============

.. cpp:namespace:: pilot::GlobalPlanner

Module
------

The `GlobalPlanner` module supports path planning based on a global cost map, which is generated from a Grid Map.
The module uses an `A*` style path finding algorithm.

Most functions require permission ``pilot.permission_e.MOVE``, see :ref:`pilot.permission_e`.


Functions
---------

Common Parameters
^^^^^^^^^^^^^^^^^

``goal_options_t options``
	Optional goal options, see :ref:`pilot.goal_options_t`. If not specified will use default values.
	
``Hash64 job``
	Optional job id, to identify the new goal. If not specified (or set to zero) will generate a new random id. See :ref:`vnx.Hash64`.


Asynchronous Move Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following functions set / append a new goal while returing immediately.

.. cpp:function:: void set_goal(PathPoint2D goal, goal_options_t options, Hash64 job)
	
	Sets a new goal using the provided pose and parameters in ``goal``.
	Any pending goals are canceled beforehand. See :ref:`pilot.PathPoint2D`.
	Requires permission ``MOVE``.

Synchronous Move Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following functions return when the new goal is physically reached, or the goal was canceled.

.. cpp:function:: void move_to(PathPoint2D goal, goal_options_t options, Hash64 job)
	
	Same as ``set_goal(...)`` but will block until goal is reached or canceled. See :ref:`pilot.PathPoint2D`.
	Requires permission ``MOVE``.