.. _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"] "14" [label=<
LabelCommand
ASCII-STRINGgoal
MotionParametersmotion_parameters
ExecutionParametersexecution_parameters
>,shape=box,style=filled,fillcolor="white"]; "11" [label=<
CoordinateCommand
Posegoal
MotionParametersmotion_parameters
ExecutionParametersexecution_parameters
>,shape=box,style=filled,fillcolor="white"]; "13" [label=<
ExecutionParameters
FLOAT32timeout
UINT32max_replan_cycles
BOOLuse_fine_localization
>,shape=box,style=filled,fillcolor="white"]; "12" [label=<
MotionParameters
FLOAT32max_velocity
FLOAT32max_acceleration
FLOAT32translation_accuracy
FLOAT32orientation_accuracy
BOOLprefer_forward_orientation
>,shape=box,style=filled,fillcolor="white"]; "10" [label=<
PlatformCapabilities
FLOAT32max_velocity
FLOAT32max_acceleration
BOOLhas_fine_localization
>,shape=box,style=filled,fillcolor="white"]; "8" [label=<
CommandResult
Resulttype
UINT32code
ASCII-STRINGdescription
>,shape=box,style=filled,fillcolor="white"]; "9" [label=<
Result
SUCCESS0
SUPERSEDED1
CANCELLED2
EMERGENCY_STOPPED3
PATH_BLOCKED4
TIMEOUT5
CUSTOM_ERROR100
UNKNOWN_ERROR101
>,shape=box,style=filled,fillcolor="white"]; "6" [label=<
OccupancyGrid2DIntCollection
OccupancyGrid2DIntelement
>,shape=box,style=filled,fillcolor="white"]; "7" [label=<
OccupancyGrid2DInt
FLOAT32resolution
UINT32width
UINT32height
Poseorigin
OCTET-VECTORmap
>,shape=box,style=filled,fillcolor="white"]; "1" [label=<
PathCollection
Pathelement
>,shape=box,style=filled,fillcolor="white"]; "2" [label=<
Path
Poseposes
>,shape=box,style=filled,fillcolor="white"]; "3" [label=<
Pose
Translationtranslation
Rotationrotation
>,shape=box,style=filled,fillcolor="white"]; "5" [label=<
Rotation
FLOAT64qw
FLOAT64qx
FLOAT64qy
FLOAT64qz
ASCII-STRINGframe_id
>,shape=box,style=filled,fillcolor="white"]; "4" [label=<
Translation
FLOAT64x
FLOAT64y
FLOAT64z
ASCII-STRINGframe_id
>,shape=box,style=filled,fillcolor="white"]; "14":execution_parameters -> "13" []; "14":motion_parameters -> "12" []; "11":execution_parameters -> "13" []; "11":motion_parameters -> "12" []; "11":goal -> "3" []; "8" -> "9" []; "8":type -> "9" []; "6":element -> "7" []; "7":origin -> "3" []; "1":element -> "2" []; "2":poses -> "3" []; "3":rotation -> "5" []; "3":translation -> "4" []; .. container:: mess4ge-list .. container:: messages * :ref:`PathCollection ` * :ref:`OccupancyGrid2DIntCollection ` * :ref:`CommandResult ` * :ref:`Path ` * :ref:`PlatformCapabilities ` * :ref:`CoordinateCommand ` * :ref:`LabelCommand ` * :ref:`MotionParameters ` * :ref:`ExecutionParameters ` * :ref:`OccupancyGrid2DInt ` .. container:: clearer clearer: should be made invisible via css .. _message-rst-navigation-pathcollection: Message PathCollection ---------------------- .. container:: message-rst-navigation-pathcollection-multi .. container:: message-rst-navigation-pathcollection-documentation .. py:class:: rst.navigation.PathCollection Collection of :py:class:`Path ` instances. Auto-generated. .. py:attribute:: element :type: array of :py:class:`rst.navigation.Path` The individual elements of the collection. Constraints regarding the empty collection, sorting, duplicated entries etc. are use case specific. .. container:: message-rst-navigation-pathcollection-source :download:`Download this file ` .. literalinclude:: //home/jenkins/workspace/rst-manual-0.15-merge-simulator/upstream/RST-0.15.0-Linux/share/rst0.15/proto/stable/rst/navigation/PathCollection.proto :lines: 12-22 :language: protobuf :emphasize-lines: 9-9 .. _message-rst-navigation-occupancygrid2dintcollection: Message OccupancyGrid2DIntCollection ------------------------------------ .. container:: message-rst-navigation-occupancygrid2dintcollection-multi .. container:: message-rst-navigation-occupancygrid2dintcollection-documentation .. py:class:: rst.navigation.OccupancyGrid2DIntCollection Collection of :py:class:`OccupancyGrid2DInt ` instances. Auto-generated. .. py:attribute:: element :type: array of :py:class:`rst.navigation.OccupancyGrid2DInt` The individual elements of the collection. Constraints regarding the empty collection, sorting, duplicated entries etc. are use case specific. .. container:: message-rst-navigation-occupancygrid2dintcollection-source :download:`Download this file ` .. literalinclude:: //home/jenkins/workspace/rst-manual-0.15-merge-simulator/upstream/RST-0.15.0-Linux/share/rst0.15/proto/stable/rst/navigation/OccupancyGrid2DIntCollection.proto :lines: 12-22 :language: protobuf :emphasize-lines: 9-9 .. _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 ` .. literalinclude:: //home/jenkins/workspace/rst-manual-0.15-merge-simulator/upstream/RST-0.15.0-Linux/share/rst0.15/proto/stable/rst/navigation/CommandResult.proto :lines: 14-84 :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 ` .. literalinclude:: //home/jenkins/workspace/rst-manual-0.15-merge-simulator/upstream/RST-0.15.0-Linux/share/rst0.15/proto/stable/rst/navigation/CommandResult.proto :lines: 16-64 :language: protobuf :emphasize-lines: 6-6,11-11,16-16,22-22,29-29,34-34,41-41,47-47 .. _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 @create_collection .. 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 ` .. literalinclude:: //home/jenkins/workspace/rst-manual-0.15-merge-simulator/upstream/RST-0.15.0-Linux/share/rst0.15/proto/stable/rst/navigation/Path.proto :lines: 15-24 :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 ` .. literalinclude:: //home/jenkins/workspace/rst-manual-0.15-merge-simulator/upstream/RST-0.15.0-Linux/share/rst0.15/proto/stable/rst/navigation/PlatformCapabilities.proto :lines: 15-37 :language: protobuf :emphasize-lines: 8-8,15-15,21-21 .. _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 ` .. literalinclude:: //home/jenkins/workspace/rst-manual-0.15-merge-simulator/upstream/RST-0.15.0-Linux/share/rst0.15/proto/stable/rst/navigation/CoordinateCommand.proto :lines: 19-37 :language: protobuf :emphasize-lines: 6-6,11-11,17-17 .. _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 ` .. literalinclude:: //home/jenkins/workspace/rst-manual-0.15-merge-simulator/upstream/RST-0.15.0-Linux/share/rst0.15/proto/stable/rst/navigation/LabelCommand.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 ` .. literalinclude:: //home/jenkins/workspace/rst-manual-0.15-merge-simulator/upstream/RST-0.15.0-Linux/share/rst0.15/proto/stable/rst/navigation/MotionParameters.proto :lines: 21-59 :language: protobuf :emphasize-lines: 8-8,15-15,23-23,31-31,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 ` .. literalinclude:: //home/jenkins/workspace/rst-manual-0.15-merge-simulator/upstream/RST-0.15.0-Linux/share/rst0.15/proto/stable/rst/navigation/ExecutionParameters.proto :lines: 16-42 :language: protobuf :emphasize-lines: 10-10,19-19,25-25 .. _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 @create_collection .. 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 ` .. literalinclude:: //home/jenkins/workspace/rst-manual-0.15-merge-simulator/upstream/RST-0.15.0-Linux/share/rst0.15/proto/stable/rst/navigation/OccupancyGrid2DInt.proto :lines: 19-57 :language: protobuf :emphasize-lines: 7-7,12-12,17-17,29-29,37-37