Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add GeoPoseStamped interface for REP-147 to help clarify geographic orientation #407

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Add GeoPoseStamped interface for REP-147 to help clarify geographic orientation #407

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
02bfa52
Add GeoPoseStamped interface for REP-147
Sep 12, 2024
5f600aa
Specify level flight
Ryanf55 Sep 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions rep-0103.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,12 +168,15 @@ There are many ways to represent rotations. The preferred order is listed below,
default.

By the right hand rule, the yaw component of orientation increases as the child frame
rotates counter-clockwise, and for geographic poses, yaw is zero when pointing east.
rotates counter-clockwise.
For geographic poses, yaw is zero when pointing east, and is thus 90 degrees when the
vehicle is facing north.

This requires special mention only because it differs from a traditional compass bearing,
This requires special mention only because it differs from a traditional `compass bearing`_,
which is zero when pointing north and increments clockwise. Hardware drivers should make
the appropriate transformations before publishing standard ROS messages.

.. _compass bearing: https://en.wikipedia.org/wiki/Bearing_(navigation)

Covariance Representation
-------------------------
Expand Down Expand Up @@ -207,7 +210,6 @@ References
.. [1] Bureau International des Poids et Mesures
(http://www.bipm.org/en/home/)


Copyright
=========

Expand Down
48 changes: 47 additions & 1 deletion rep-0147.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,9 @@ A higher level view of the system uses the following abstraction.
Coordinate Frames
=================

It is expected that users of this interface will also follow the coordinate frame conventions layed out in REP 105 [#rep105]_.
It is expected that users of this interface will also follow the coordinate frame conventions layed out in REP 105 [#REP105]_.
As mentioned in REP 103 [#REP103]_, if using the NED convention, the frame ID must end in ``_ned``.
If unspecified, ENU can be assumed.

Proposed Interfaces
===================
Expand Down Expand Up @@ -341,6 +343,33 @@ To send a series of goals a list of GlobalPositions can be used.
nav_msgs/GlobalPosition[] waypoints


Pose Reporting
------------------

An aerial vehicle can share its geographic pose via ``geographic_msgs/GeoPoseStamped`` [#geoposestamped]_.
The position coordinates should follow WGS-84 [#wgs84]_.

EGM2008 [#egm]_ can be assumed as the altitude datum unless otherwise stated.
If and when EGM2020 is released, this REP can be updated.
Take caution integrating GPS data and terrain data as they frequently use different datums.

The orientation field follows REP 103's [#REP103]_ recommendation. The orientation is the transform from the
local tangent plane [#ltpc]_ to the body frame.

A vehicle in level flight facing east will have a unit identity quaternion for its orientation.

x,y,z=0, w=1
Copy link
Contributor Author

@Ryanf55 Ryanf55 Sep 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If there is a more standard way to document the value for the quaternion (perhaps yaml), please supply a reference to the syntax I should use. Or, if we can find an authoritative reference on this definition of unit identity quaternion, that would be great. The Wikipedia does not directly mention it.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
x,y,z=0, w=1
`x,y,z=[0,0,0], w=1`


.. image:: rep-0147/geopose-default-orientation.png

Remember that per REP 103 [#REP103]_, when the orientation is decomposed to its yaw component,
this yaw value is NOT equal to the traditional compass bearing.

In the situation that the position is known but orientation it not known, or vise versa,
the unknown fields should be populated with ``NaN`` to avoid Null Island [#null_island]_.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
the unknown fields should be populated with ``NaN`` to avoid Null Island [#null_island]_.
the unknown fields should be populated with ``NaN`` to avoid Null Island [#null_island]_.
It is up to the platform to decide at what accuracy threshold the data will stop being published
or switch to ``NaN`.

Thoughts on this for addressing accuracy?


TODO add link to ArduPilot test code for orientation.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For reference, I would also add the following quaternion transformations, which can be used to convert between Ardupilot's and REP-103 reference frames.

  • Assuming that quaternion is expressed as q = [w, x, y, z];
  • ned is North, East, Down, standard inertial Ardupilot's frame;
  • fru is Forward, Right, Up, standard Ardupilot's body frame;
  • enu is East, North, Up, REP-103 inertial frame;
  • flu is Forward, Left, Up, REP-103 body frame;
sq2_2 = sqrt(2)/2;
q_ned_2_enu = [0, sq2_2, sq2_2, 0];
q_enu_2_ned = [0, sq2_2, sq2_2, 0];
q_frd_2_flu = [0, 1, 0, 0];
q_flu_2_frd = [0, 1, 0, 0];

Assuming that we start from vehicle's quaternion q_frd_2_enu from Ardupilot's telemetry, and we want to obtain its correspondent in REP-103 q_flu_2_enu, then the following transformation is to be applied (where * is the quaternion product):

q_flu_2_enu = q_ned_2_enu * q_frd_2_ned * q_flu_2_frd

Of course the inverse can be applied: if an orientation is known in RED-103 q_flu_2_enu , that can be transformed into Ardupilot's frame q_frd_2_ned with:

q_frd_2_ned = q_enu_2_ned  * q_flu_2_enu  * q_frd_2_flu

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good, although I wonder if the maintainers want the REP to be language agnostic. If they prefer code language agnostic, I can write it up in Latex or something.

Currently Unspecified
---------------------

Expand Down Expand Up @@ -960,6 +989,9 @@ References
.. [#twiststamped] geometry_msgs/TwistStamped
(http://docs.ros.org/api/geometry_msgs/html/msg/TwistStamped.html)

.. [#rep103] REP 103: Standard Units of Measure and Coordinate Conventions
(http://www.ros.org/reps/rep-0103.html)

.. [#rep105] REP 105: Coordinate Frames for Mobile Platforms
(http://www.ros.org/reps/rep-0105.html)

Expand All @@ -978,6 +1010,20 @@ References
.. [#ss_trigger] ``std_srvs/Trigger``
(http://docs.ros.org/melodic/api/std_srvs/html/srv/Trigger.html)

.. [#geoposestamped] odometry
(https://docs.ros.org/en/api/geographic_msgs/html/msg/GeoPoseStamped.html)

.. [#egm] Earth Gravity Model
(https://en.wikipedia.org/wiki/Earth_Gravitational_Model)

.. [#wgs84] WGS 84
(https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84)

.. [#ltpc] Local Tangent Plane coordinates
(https://en.wikipedia.org/wiki/Local_tangent_plane_coordinates)

.. [#null_island] Null Island
(https://en.wikipedia.org/wiki/Null_Island)

Copyright
=========
Expand Down
Binary file added rep-0147/geopose-default-orientation.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading