Local and body frames

[korigod]

We have now four main local frames in MAVLink:

• LOCAL_NED,
• LOCAL_OFFSET_NED,
• BODY_NED,
• BODY_OFFSET_NED.

Unfortunately, description of these frames in MAVLink itself is not very clear. APM docs say:

In frames, _OFFSET_ means “relative to vehicle position” while _LOCAL_ is “relative to home position” (these have no impact on velocity directions). _BODY_ means that velocity components are relative to the heading of the vehicle rather than the NED frame.

Everyone agrees on this definition? What's with positions in BODY_NED? Same docs say:

BODY_NED: Positions are relative to the vehicle’s home position in the North, East, Down (NED) frame. Use this to specify a position x metres north, y metres east and (-) z metres above the home position. Velocity directions are relative to the current vehicle heading. Use this to specify the speed forward, right and down (or the opposite if you use negative values).

It seems quite inconsistent to use different heading in one frame for positions and velocities, isn't it? The most confusing part, though, is _NED as part of BODY_OFFSET_NED, which is, as I understand, never really mean NED.

[hamishwillee]

The simple way of looking at this is that "Body" implies that velocity is relative to vehicle heading, while "Local_Offset" implies "Position" is relative to vehicle current position. If those aren't specified the position and velocity are relative to NED.

1. So positions in Body NED are NED.
2. Yes, BODY_OFFSET_NED is a misnomer - the only part of "NED" that is used is the "D" and the way that the axis are defined relative to each other.

It is consistent. I would have quite liked the first frame to just be called NED.

[hamishwillee]

Some of this could be captured in the MAVLink docs -e.g. https://mavlink.io/en/messages/common.html#MAV_FRAME_LOCAL_OFFSET_NED

Won't do anything for now though - lets see what other's say. E.g. might be a more clear way than "BODY" to say "Velocity relative to vehicle heading frame".

[korigod]

Thank you.

The simple way of looking at this is that "Body" implies that velocity is relative to vehicle heading, while "Offset" implies "Position" is relative to vehicle current position.

Not sure it really makes things simple. In BODY_OFFSET_NED position heading is related to MAV as you wrote, but in BODY_NED it is not, so this rule is not comprehensive. Have I understood correctly that for positions LOCAL_NED and BODY_NED mean the same?

I also think that some of this could be captured in the MAVLink docs: https://mavlink.io/en/messages/common.html#MAV_FRAME_LOCAL_OFFSET_NED

Ok, let's check the docs:

BODY_OFFSET_NED: Offset in body NED frame. This makes sense if adding setpoints to the current flight path, to avoid an obstacle - e.g. useful to command 2 m/s^2 acceleration to the east.

So positions are in NED, velocities are related to MAV heading and accelerations are in NED again?

[hamishwillee]

OK, you're right that BODY_OFFSET_NED is different from LOCAL_OFFSET_NED with respect to positions. Both have origin set on the vehicle, but for the later the axis is NED while for the former the axis follows vehicle positions. Yes, for positions, LOCAL_NED and BODY_NED mean the same.

I can't comment on accelerations. I don't "think" they are supported for ArduPilot. For PX4 they are supported as some kind of thrust vector (ie acceleration capped by vehicle capabilities) but I have not done the testing to see what actually happens, and I don't understand what is "supposed" to happen.

I know that the APM/ArduPilot docs were correct about 2 years ago when I wrote them, because a) Randy validated them b) I ran extensive tests in DroneKit-Python to test them. However at that time ArduPilot did not support acceleration, so I did not need to comment on that case.

[korigod]

Thanks. I mentioned APM docs just as reference, I'm interested in how it intended to be more than in current implementation details.

PX4 does not support acceleration setpoints at all IIRC, and for position setpoints supports LOCAL_NED only.

And of course it's very strange to make velocities and accelerations behave differently, I believe docs require revision at least here.

[korigod]

@thomasgubler, as author of _BODY_ and _OFFSET_ frames (https://github.com/mavlink/mavlink/commit/7ba6bc5d323f501caf01caff7ee031ce7c52915c) could you comment on their original meaning?

[thomasgubler]

I think the main confusion comes from the usage of the term NED and body frames within mavlink. It is/was used also in other places. For body fixed frames it is meant to indicate that the z axis points down. However afaik the idea was always that the x axis follows the main axis of the vehicle. Hence a better term would be front, right down for all of the BODY frames.

offset: as the description says. This is something you add to the other frame. (to the local or body frame). It could be used to describe an obstacle for example. So to get the obstacle position you do something like this for example: obstacle_position_local = vehicle_position_local + offset_local' or obstacle_position_body = vehicle_position_body + offset_body '

[korigod]

Thanks. Do I understand correctly that the original meaning of OFFSET frames does not match cited APM docs? Does OFFSET frames have origin (to which offset is being applied) in local origin or fixed to the vehicle or it's message/implementation-specific?

Where is the origin of the BODY_NED frame then? On your picture it differs from local origin, do you mean it?

[korigod]

I wrote an RFC on the frames, comments are highly appreciated. https://github.com/mavlink/rfcs/pull/2

[TSC21]

I will be following this more closely as I actually started to implement an ODOMETRY msg which fits the ROS REP for aerial vehicles. It will be a continuation of https://github.com/mavlink/mavlink/issues/721

[LorenzMeier]

The RFC is now pretty complete - please all read and comment here: https://github.com/mavlink/rfcs/blob/2b5bc9dbea620fc15e8e3a241168850297b3d8ff/text/0002-local-frames-revision.md

[hamishwillee]

@korigod @okalachev That is a really comprehensive and well worded RFC. Going to take me some time to digest. I believe the plan is for people to comment here, with more detailed discussion at the Dev call in two weeks if this is not progressing. If that happens, would be great if you could attend.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. Thank you for your contributions.