.. _HybridPlanner:

HybridPlanner
=============

.. cpp:namespace:: pilot::HybridPlanner

Module
------

The `HybridPlanner` module supports a combined path planning by taking into account a Road Map as well as a Grid Map.
It automatically chooses to drive on the Road Map when possible, only to fall back to Grid Map based navigation if needed.
As such it supports different ways to specify a goal, either by station name, by providing a modified station structure
or by specifying an arbitrary pose.

Multiple goals can be specified, in which case the goals are traversed one after the other, without waiting or stopping at intermediate goals.

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(MapStation 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.MapStation`.
	Requires permission ``MOVE``.

.. cpp:function:: void set_goal_station(string name, goal_options_t options, Hash64 job)
	
	Sets a new goal using the provided station ``name``.
	Any pending goals are canceled beforehand. The station must exist in the current Road Map.
	Requires permission ``MOVE``.
	
.. cpp:function:: void set_goal_position(PathPoint2D goal, goal_options_t options, Hash64 job)
	
	Sets a new goal using the provided pose and parameters in ``goal``. Similar to ``set_goal()``.
	Any pending goals are canceled beforehand. See :ref:`pilot.PathPoint2D`.
	Requires permission ``MOVE``.
	
.. cpp:function:: void append_goal(MapStation goal, goal_options_t options, Hash64 job)
	
	Same as ``set_goal(...)`` but will not cancel active or pending goals. See :ref:`pilot.MapStation`.
	Requires permission ``MOVE``.

.. cpp:function:: void append_goal_station(string name, goal_options_t options, Hash64 job)
	
	Same as ``set_goal_station(...)`` but will not cancel active or pending goals.
	Requires permission ``MOVE``.
	
.. cpp:function:: void append_goal_position(PathPoint2D goal, goal_options_t options, Hash64 job)
	
	Same as ``set_goal_position(...)`` but will not cancel active or pending goals. 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(MapStation goal, goal_options_t options, Hash64 job)
	
	Same as ``set_goal(...)`` but will block until goal is reached or canceled. See :ref:`pilot.MapStation`.
	Requires permission ``MOVE``.

.. cpp:function:: void move_to_station(string name, goal_options_t options, Hash64 job)
	
	Same as ``set_goal_station(...)`` but will block until goal is reached or canceled.
	Requires permission ``MOVE``.
	
.. cpp:function:: void move_to_position(PathPoint2D goal, goal_options_t options, Hash64 job)
	
	Same as ``set_goal_position(...)`` but will block until goal is reached or canceled. See :ref:`pilot.PathPoint2D`.
	Requires permission ``MOVE``.
	
Asynchronous Movechain Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following functions set / append a list of new goals while returing immediately.

.. cpp:function:: void set_goals(vector<MapStation> goals, goal_options_t options, Hash64 job)
	
	Sets a list of new goals, similar to ``set_goal(...)``. See :ref:`pilot.MapStation`.
	Requires permission ``MOVE``.

.. cpp:function:: void set_goal_stations(vector<string> names, goal_options_t options, Hash64 job)
	
	Sets a list of new goals, similar to ``set_goal_station(...)``. The stations must exist in the current Road Map.
	Requires permission ``MOVE``.
	
.. cpp:function:: void set_goal_positions(vector<PathPoint2D> goals, goal_options_t options, Hash64 job)
	
	Sets a list of new goals, similar to ``set_goal_position(...)``. See :ref:`pilot.PathPoint2D`.
	Requires permission ``MOVE``.
	
.. cpp:function:: void append_goals(vector<MapStation> goals, goal_options_t options, Hash64 job)
	
	Appends a list of new goals, similar to ``append_goal(...)``. See :ref:`pilot.MapStation`.
	Requires permission ``MOVE``.

.. cpp:function:: void append_goal_stations(vector<string> names, goal_options_t options, Hash64 job)
	
	Appends a list of new goals, similar to ``append_goal_station(...)``.
	Requires permission ``MOVE``.
	
.. cpp:function:: void append_goal_positions(vector<PathPoint2D> goals, goal_options_t options, Hash64 job)
	
	Appends a list of new goals, similar to ``append_goal_position(...)``. See :ref:`pilot.PathPoint2D`.
	Requires permission ``MOVE``.
	
Synchronous Movechain Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following functions return when the last goal specified has been physically reached, or the goals were canceled.

.. cpp:function:: void move_tos(vector<MapStation> goals, goal_options_t options, Hash64 job)
	
	Same as ``set_goals(...)`` but will block until last goal is reached or canceled. See :ref:`pilot.MapStation`.
	Requires permission ``MOVE``.

.. cpp:function:: void move_to_stations(vector<string> names, goal_options_t options, Hash64 job)
	
	Same as ``set_goal_stations(...)`` but will block until last goal is reached or canceled.
	Requires permission ``MOVE``.
	
.. cpp:function:: void move_to_positions(vector<PathPoint2D> goals, goal_options_t options, Hash64 job)
	
	Same as ``set_goal_positions(...)`` but will block until last goal is reached or canceled. See :ref:`pilot.PathPoint2D`.
	Requires permission ``MOVE``.