.. _package-rst-navigation:
========================
Package rst.navigation
========================
A Navigation is a field of study that focuses on the process of
monitoring and controlling the movement of a craft or vehicle from
one place to another.
This package contains data type definitions related to (robot)
navigation.
.. seealso::
Wikipedia article containing the definition above
http://en.wikipedia.org/wiki/navigation
Messages
========
.. container:: mess4ge-multi
.. container:: mess4ge-graph
.. digraph:: message_graph
fontname="Arial";
fontsize=11;
stylesheet="../_static/graphs.css";
node [fontsize=11,fontname="Arial"]
edge [fontsize=11,fontname="Arial"]
"12" [label=<
| OccupancyGrid2DInt |
|
FLOAT32 | resolution |
UINT32 | width |
UINT32 | height |
Pose | origin |
OCTET-VECTOR | map |
>,shape=box,style=filled,fillcolor="white"];
"11" [label=< | PlatformCapabilities |
|
FLOAT32 | max_velocity |
FLOAT32 | max_acceleration |
BOOL | has_fine_localization |
>,shape=box,style=filled,fillcolor="white"];
"10" [label=< | Path |
|
Pose | poses |
>,shape=box,style=filled,fillcolor="white"];
"6" [label=< | CoordinateCommand |
|
Pose | goal |
MotionParameters | motion_parameters |
ExecutionParameters | execution_parameters |
>,shape=box,style=filled,fillcolor="white"];
"7" [label=< | Pose |
|
Translation | translation |
Rotation | rotation |
>,shape=box,style=filled,fillcolor="white"];
"9" [label=< | Rotation |
|
FLOAT64 | qw |
FLOAT64 | qx |
FLOAT64 | qy |
FLOAT64 | qz |
ASCII-STRING | frame_id |
>,shape=box,style=filled,fillcolor="white"];
"8" [label=< | Translation |
|
FLOAT64 | x |
FLOAT64 | y |
FLOAT64 | z |
ASCII-STRING | frame_id |
>,shape=box,style=filled,fillcolor="white"];
"4" [label=< | CommandResult |
|
Result | type |
UINT32 | code |
ASCII-STRING | description |
>,shape=box,style=filled,fillcolor="white"];
"5" [label=< | Result |
|
SUCCESS | 0 |
SUPERSEDED | 1 |
CANCELLED | 2 |
EMERGENCY_STOPPED | 3 |
PATH_BLOCKED | 4 |
TIMEOUT | 5 |
CUSTOM_ERROR | 100 |
UNKNOWN_ERROR | 101 |
>,shape=box,style=filled,fillcolor="white"];
"1" [label=< | LabelCommand |
|
ASCII-STRING | goal |
MotionParameters | motion_parameters |
ExecutionParameters | execution_parameters |
>,shape=box,style=filled,fillcolor="white"];
"3" [label=< | ExecutionParameters |
|
FLOAT32 | timeout |
UINT32 | max_replan_cycles |
BOOL | use_fine_localization |
>,shape=box,style=filled,fillcolor="white"];
"2" [label=< | MotionParameters |
|
FLOAT32 | max_velocity |
FLOAT32 | max_acceleration |
FLOAT32 | translation_accuracy |
FLOAT32 | orientation_accuracy |
BOOL | prefer_forward_orientation |
>,shape=box,style=filled,fillcolor="white"];
"12":origin -> "7" [];
"10":poses -> "7" [];
"6":execution_parameters -> "3" [];
"6":motion_parameters -> "2" [];
"6":goal -> "7" [];
"7":rotation -> "9" [];
"7":translation -> "8" [];
"4" -> "5" [];
"4":type -> "5" [];
"1":execution_parameters -> "3" [];
"1":motion_parameters -> "2" [];
.. container:: mess4ge-list
.. container:: messages
* :ref:`LabelCommand `
* :ref:`CommandResult `
* :ref:`CoordinateCommand `
* :ref:`MotionParameters `
* :ref:`Path `
* :ref:`PlatformCapabilities `
* :ref:`OccupancyGrid2DInt `
* :ref:`ExecutionParameters `
.. container:: clearer
clearer: should be made invisible via css
.. _message-rst-navigation-labelcommand:
Message LabelCommand
--------------------
.. container:: message-rst-navigation-labelcommand-multi
.. container:: message-rst-navigation-labelcommand-documentation
.. py:class:: rst.navigation.LabelCommand
A navigation command for a robot with a goal that is designated by
pre-learned name.
.. codeauthor:: Johannes Wienke
.. codeauthor:: Leon Ziegler
.. py:attribute:: goal
:type: :py:class:`ASCII-STRING`
The name of the goal to reach by the navigation.
.. py:attribute:: motion_parameters
:type: :py:class:`rst.navigation.MotionParameters`
Parameters for the motions used to reach the specified goal.
.. py:attribute:: execution_parameters
:type: :py:class:`rst.navigation.ExecutionParameters`
Parameters used to specify the execution semantics while
moving towards the goal.
.. container:: message-rst-navigation-labelcommand-source
:download:`Download this file /home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/LabelCommand.proto>`
.. literalinclude:: //home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/LabelCommand.proto
:lines: 15-33
:language: protobuf
:emphasize-lines: 6-6,11-11,17-17
.. _message-rst-navigation-commandresult:
Message CommandResult
---------------------
.. container:: message-rst-navigation-commandresult-multi
.. container:: message-rst-navigation-commandresult-documentation
.. py:class:: rst.navigation.CommandResult
Describes the result of a navigation command including possible error
conditions and reasons for these errors.
.. codeauthor:: Johannes Wienke
.. codeauthor:: Leon Ziegler
.. py:attribute:: type
:type: :py:class:`rst.navigation.CommandResult.Result`
Indicates the general result of the command.
.. py:attribute:: code
:type: :py:class:`UINT32`
An optional code describing the command result for automatic processing.
Mainly used to distinguish platform-specific errors that are not
modelled otherwise.
.. py:attribute:: description
:type: :py:class:`ASCII-STRING`
A human-readable description for the achieved result. Mainly used for
unknown or custom error description messages.
.. container:: message-rst-navigation-commandresult-source
:download:`Download this file /home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/CommandResult.proto>`
.. literalinclude:: //home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/CommandResult.proto
:lines: 12-82
:language: protobuf
:emphasize-lines: 56-56,63-63,69-69
.. _message-rst-navigation-commandresult-result:
Message Result
--------------
.. container:: message-rst-navigation-commandresult-result-multi
.. container:: message-rst-navigation-commandresult-result-documentation
.. py:class:: rst.navigation.CommandResult.Result
*Not documented*
.. py:attribute:: SUCCESS
= 0
The commanded target could be reached successfully.
.. py:attribute:: SUPERSEDED
= 1
Before reaching the commanded target, a new command was issued.
.. py:attribute:: CANCELLED
= 2
The target was not reached due to an explicit stop command.
.. py:attribute:: EMERGENCY_STOPPED
= 3
The commanded target was not reached because an emergency stop
occurred.
.. py:attribute:: PATH_BLOCKED
= 4
At some point in time during the command execution the motion
stopped because the path planning could not find a valid path to the
commanded target.
.. py:attribute:: TIMEOUT
= 5
The target could not be reached inside the specified time.
.. py:attribute:: CUSTOM_ERROR
= 100
Target could not be reached. An error that is specific to a certain
robot platform. Further details can be found in the error code and
the error message.
.. py:attribute:: UNKNOWN_ERROR
= 101
Target could not be reached due to an unknown error. Further details
can be found in the error code and the error message.
.. container:: message-rst-navigation-commandresult-result-source
:download:`Download this file /home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/CommandResult.proto>`
.. literalinclude:: //home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/CommandResult.proto
:lines: 14-62
:language: protobuf
:emphasize-lines: 6-6,11-11,16-16,22-22,29-29,34-34,41-41,47-47
.. _message-rst-navigation-coordinatecommand:
Message CoordinateCommand
-------------------------
.. container:: message-rst-navigation-coordinatecommand-multi
.. container:: message-rst-navigation-coordinatecommand-documentation
.. py:class:: rst.navigation.CoordinateCommand
A navigation command for a robot with a goal that is specified as
an arbitrary coordinate in the coordinate frame used for the
navigation.
.. codeauthor:: Johannes Wienke
.. codeauthor:: Leon Ziegler
.. py:attribute:: goal
:type: :py:class:`rst.geometry.Pose`
The goal to reach by the navigation.
.. py:attribute:: motion_parameters
:type: :py:class:`rst.navigation.MotionParameters`
Parameters for the motions used to reach the specified goal.
.. py:attribute:: execution_parameters
:type: :py:class:`rst.navigation.ExecutionParameters`
Parameters used to specify the execution semantics while
moving towards the goal.
.. container:: message-rst-navigation-coordinatecommand-source
:download:`Download this file /home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/CoordinateCommand.proto>`
.. literalinclude:: //home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/CoordinateCommand.proto
:lines: 17-35
:language: protobuf
:emphasize-lines: 6-6,11-11,17-17
.. _message-rst-navigation-motionparameters:
Message MotionParameters
------------------------
.. container:: message-rst-navigation-motionparameters-multi
.. container:: message-rst-navigation-motionparameters-documentation
.. py:class:: rst.navigation.MotionParameters
Defines parameters that specify the aspects of the motions used to
reach a navigation goal. This means properties like the velocity
or orientation of the robot but not execution properties like a
timeout.
If one of the values is not specified, the robot driver may decide
on this one arbitrarily. Velocity and acceleration restrict the
magnitude in the direction of the movement and not per axis.
Accuracies need to be reached for every axis individually.
.. codeauthor:: Johannes Wienke
.. codeauthor:: Leon Ziegler
.. py:attribute:: max_velocity
:type: :py:class:`FLOAT32`
**Constraint**: ``value >= 0``
The maximum velocity to be used when reaching the goal.
@unit(meter / second)
.. py:attribute:: max_acceleration
:type: :py:class:`FLOAT32`
**Constraint**: ``value >= 0``
The maximum acceleration to be used when reaching the goal.
@unit(meter / second^2)
.. py:attribute:: translation_accuracy
:type: :py:class:`FLOAT32`
**Unit**: meter
**Constraint**: ``value >= 0``
The desired translational accuracy to reach for a successful
motion command.
.. py:attribute:: orientation_accuracy
:type: :py:class:`FLOAT32`
**Unit**: rad
**Constraint**: ``value >= 0``
The desired orientation accuracy to reach for a successful
motion command.
.. py:attribute:: prefer_forward_orientation
:type: :py:class:`BOOL`
If true, try to prefer moving in the forward orientation of
the platform.
.. container:: message-rst-navigation-motionparameters-source
:download:`Download this file /home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/MotionParameters.proto>`
.. literalinclude:: //home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/MotionParameters.proto
:lines: 19-57
:language: protobuf
:emphasize-lines: 8-8,15-15,23-23,31-31,37-37
.. _message-rst-navigation-path:
Message Path
------------
.. container:: message-rst-navigation-path-multi
.. container:: message-rst-navigation-path-documentation
.. py:class:: rst.navigation.Path
A path that consists of tracked poses.
.. codeauthor:: Phillip Luecking
.. py:attribute:: poses
:type: array of :py:class:`rst.geometry.Pose`
The path represents a collection of poses.
Order of poses is significant.
.. container:: message-rst-navigation-path-source
:download:`Download this file /home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/Path.proto>`
.. literalinclude:: //home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/Path.proto
:lines: 12-21
:language: protobuf
:emphasize-lines: 8-8
.. _message-rst-navigation-platformcapabilities:
Message PlatformCapabilities
----------------------------
.. container:: message-rst-navigation-platformcapabilities-multi
.. container:: message-rst-navigation-platformcapabilities-documentation
.. py:class:: rst.navigation.PlatformCapabilities
Describes the navigation capabilities of a mobile platform.
Boolean parameters that are not specified imply a false value. Numeric
parameters are unspecified.
.. codeauthor:: jwienke
.. py:attribute:: max_velocity
:type: :py:class:`FLOAT32`
**Constraint**: ``value >= 0``
The maximum velocity of the platform.
@unit(meter / second)
.. py:attribute:: max_acceleration
:type: :py:class:`FLOAT32`
**Constraint**: ``value >= 0``
The maximum acceleration of the platform.
@unit(meter / second^2)
.. py:attribute:: has_fine_localization
:type: :py:class:`BOOL`
Indicates whether the platform has a fine localization skill that can be
used when navigating towards goals.
.. container:: message-rst-navigation-platformcapabilities-source
:download:`Download this file /home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/PlatformCapabilities.proto>`
.. literalinclude:: //home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/PlatformCapabilities.proto
:lines: 13-35
:language: protobuf
:emphasize-lines: 8-8,15-15,21-21
.. _message-rst-navigation-occupancygrid2dint:
Message OccupancyGrid2DInt
--------------------------
.. container:: message-rst-navigation-occupancygrid2dint-multi
.. container:: message-rst-navigation-occupancygrid2dint-documentation
.. py:class:: rst.navigation.OccupancyGrid2DInt
**Constraint**: ``len(.map) = (.width * .height)``
This represents a 2D grid map, in which each cell represents the
probability of occupancy.
This kind of representation is often used in SLAM implementations.
.. codeauthor:: Leon Ziegler
.. py:attribute:: resolution
:type: :py:class:`FLOAT32`
**Unit**: meter
The map resolution as edge length of a cell.
.. py:attribute:: width
:type: :py:class:`UINT32`
Number of cells in x direction.
.. py:attribute:: height
:type: :py:class:`UINT32`
Number of cells in y direction.
.. py:attribute:: origin
:type: :py:class:`rst.geometry.Pose`
The origin of the map.
This is the real-world pose of the cell (0,0) in the map. The
grid is defined in the x-y plane given by this pose, therefore
the rotation defines the orientation of the 2D grid in the real
three-dimensional world. If the floor is defined as the x-y
plane in world coordinates, the pose should only contain a
rotation around the z-axis.
.. py:attribute:: map
:type: :py:class:`OCTET-VECTOR`
The map data, in row-major order.
Occupancy probabilities are signed 8-bit integer in the range
[0,100]. Unknown is -1.
.. container:: message-rst-navigation-occupancygrid2dint-source
:download:`Download this file /home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/OccupancyGrid2DInt.proto>`
.. literalinclude:: //home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/OccupancyGrid2DInt.proto
:lines: 16-54
:language: protobuf
:emphasize-lines: 7-7,12-12,17-17,29-29,37-37
.. _message-rst-navigation-executionparameters:
Message ExecutionParameters
---------------------------
.. container:: message-rst-navigation-executionparameters-multi
.. container:: message-rst-navigation-executionparameters-documentation
.. py:class:: rst.navigation.ExecutionParameters
Defines parameters that specify the execution semantics of a
navigation command. In case a parameter is not set, the robot
driver may arbitrarily decide on an appropriate value.
.. codeauthor:: Johannes Wienke
.. codeauthor:: Leon Ziegler
.. codeauthor:: Jan Moringen
.. py:attribute:: timeout
:type: :py:class:`FLOAT32`
**Unit**: second
**Constraint**: ``value >= 0``
If > 0, the movement till reaching the goal must not last
longer than the specified timeout in seconds. The robot must
stop if the timeout is reached.
.. py:attribute:: max_replan_cycles
:type: :py:class:`UINT32`
--- parameters specific to certain implementations ---
If > 0, the global path planner (if active) shall only try to
compute a valid plan for the given number of times before
giving up.
.. py:attribute:: use_fine_localization
:type: :py:class:`BOOL`
If true, after reaching the goal with the usual parameters,
try to perform a fine localization to improve the accuracy.
.. container:: message-rst-navigation-executionparameters-source
:download:`Download this file /home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/ExecutionParameters.proto>`
.. literalinclude:: //home/jenkins/workspace/rst-manual-0.12/rst-manual/../rst-proto/proto/stable/rst/navigation/ExecutionParameters.proto
:lines: 14-40
:language: protobuf
:emphasize-lines: 10-10,19-19,25-25