Added moveByVelocityBodyFrame

[ahmed-elsaharti]

Added a moveByVelocityBodyFrameAsync API that allows movement by velocity in the direction of the vehicle's X-Y frame based on the 2-D vector decomposition shown in #3138 where:

VX_world = VX_vehicle * cos(yaw) - VY_vehicle * sin(yaw)
VY_world = VX_vehicle * sin(yaw) + VY_vehicle * cos(yaw)

Usage:
moveByVelocityBodyFrameAsync(vx, vy, vz, duration, drivetrain (optional), yaw_mode (optional), vehicle_name (optional))

Demo video:
https://drive.google.com/file/d/1G5ihjNSVyxDBw8GXOCeqlGpWFwCxeelZ/view?usp=sharing

Any testing and/or review of the method would be greatly appreciated.
Thanks again to @jonyMarino for suggesting this.

[ghost]

All CLA requirements met.

[jonyMarino]

Great Ahmed! Thank you! Why are you not using the pitch and roll in the transformation? This is just for 2D?

[ahmed-elsaharti]

Hi @jonyMarino, You're right, This is to control the motion direction in the 2D plane of the vehicle similar to moveByVelocity where it's always in the horizontal direction.
Since this is to mimic the action of controlling a UAV using RC where it's just a matter of moving in the plane of the UAV relative to where its heading angle is regardless of the pitch/roll angles. Which is why I intentionally left out pitch and roll (ie: the absolute direction the UAV is pointing) to not make the API confusing and or cause misbehavior if move commands were sent while the drone was recovering from a previous command which would make this very difficult to use for users.

Example: if the drone was moving previously and the command is complete, it will still have a slight residual pitch angle while trying to stop (due to inertia), if that gets incorporated in the API, the resulting motion in the drone's X direction would not be truly horizontal if we consider pitch and roll:

This means that the user will have to wait for the vehicle to be 100% horizontal before issuing the moveByVelocityBodyFrame command, making this super difficult to control

The way it is now (without pitch and yaw):

Which is exactly like the expected behavior with RC.

Edit: another example would be the drone resisting wind (so the drone would be pitched forward while standing still) which if pitch and roll are considered would make this API impossible to use to make the drone move forward.

[ahmed-elsaharti]

Here's a screenshot from the wind example:

here the drone is hovering but is forced to be pitched forward due to wind. In this case, it would be impossible to make the drone move horizontally forward if the pitch is included in the equation.

[jonyMarino]

Thanks, Ahmed, for your excellent explanations! I will learn a lot from you! But don't get tired of generating so many graphics.

[ahmed-elsaharti]

@jonyMarino Thank you for your kind words! I'm the one who's learning from you.
And do not worry, explanation through images is the essence of my existence 😂

[zimmy87]

PR looks good to me other than my 2 comments.