Orbit location of interest using a UAV
uavOrbitFollower object is a 3-D path follower for unmanned aerial
vehicles (UAVs) to follow circular paths that is based on a lookahead distance. Given the
circle center, radius, and the pose, the orbit follower computes a desired yaw and heading to
follow a lookahead point on the path. The object also computes the cross-track error from the
UAV pose to the path and tracks how many times the circular orbit has been completed.
lookaheadDistance input to help improve path tracking.
Decreasing the distance can improve tracking, but may lead to oscillations in the path.
To orbit a location using a UAV:
uavOrbitFollower object and set its properties.
Call the object with arguments, as if it were a function.
To learn more about how System objects work, see What Are System Objects? (MATLAB).
orbit = uavOrbitFollower
orbit = uavOrbitFollower(Name,Value)
orbit = uavOrbitFollower returns an orbit follower object with
default property values.
orbit = uavOrbitFollower(Name,Value) creates an orbit follower
with additional options specified by one or more
Name is a property name and
Value is the
Name must appear inside single quotes
''). You can specify several name-value pair arguments in any order
Unless otherwise indicated, properties are nontunable, which means you cannot change their
values after calling the object. Objects lock when you call them, and the
release function unlocks them.
If a property is tunable, you can change its value at any time.
For more information on changing property values, see System Design in MATLAB Using System Objects (MATLAB).
UAV type— Type of UAV
Type of UAV, specified as either
OrbitCenter— Center of orbit
[x y z]vector
Center of orbit, specified as an
[x y z] vector.
z] is the orbit center position in NED-coordinates (north-east-down)
specified in meters.
OrbitRadius— Radius of orbit
Radius of orbit, specified as a positive scalar in meters.
TurnDirection— Direction of orbit
Direction of orbit, specified as a scalar. Positive values indicate a clockwise turn
as viewed from above. Negative values indicate a counter-clockwise turn. A value of
0 automatically determines the value based on the input
[lookaheadPoint,desiredHeading,desiredYaw,crossTrackError,numTurns] = orbit(currentPose,lookaheadDistance)
follows the set of waypoints specified in the waypoint follower object. The object takes
the current position and lookahead distance to compute the lookahead point on the path.
The desired heading, yaw, and cross track error are also based on this lookahead point
compared to the current position.
numTurns] = orbit(
status returns zero until the UAV
has navigated all the waypoints.
currentPose— Current UAV pose
[x y z heading]vector
Current UAV pose, specified as a
[x y z heading] vector. This
pose is used to calculate the lookahead point based on the input
[x y z] is the current
position in meters.
heading is the current heading in radians. The
UAV heading is the angle of direction of the velocity vector relative to north
measured in radians.
lookaheadDistance— Lookahead distance
Lookahead distance along the path, specified as a positive numeric scalar in meters.
lookaheadPoint— Lookahead point on path
[x y z]position vector
Lookahead point on path, returned as an
[x y z] position vector
desiredHeading— Desired heading
Desired heading, returned as numeric scalar in radians in the range of
[-pi, pi]. The UAV heading is the angle of direction of the
velocity vector relative to north measured in radians.
desiredYaw— Desired yaw
Desired yaw, returned as numeric scalar in radians in the range of
pi]. The UAV yaw is the forward direction of the UAV regardless of the
velocity vector relative to north measured in radians.
crossTrackError— Cross track error from UAV position to path
Cross track error from UAV position to path, returned as a positive numeric scalar in meters. The error measures the perpendicular distance from the UAV position to the closest point on the path.
numTurns— Number of times the UAV has completed the orbit
Number of times the UAV has completed the orbit, specified as a numeric scalar. As
the UAV circles the center point, this value increases or decreases based on the
Turn Direction property. Decimal values indicate
partial completion of a circle. If the UAV cross track error exceeds the lookahead
distance, the number of turns is not updated.
NumTurns is reset whenever
TurnDirection properties are
To use an object function, specify the
object™ as the first input argument. For
example, to release system resources of a System
This example shows how to use the
uavOrbitFollower to generate heading and yaw commands for orbiting a location of interest with a UAV.
NOTE: This example requires you to install the UAV Library for Robotics System Toolbox®. Call
roboticsAddons to open the Add-ons Explorer and install the library.
Create the orbit follower. Set the center of the location of interest and the radius of orbit. Set a
TurnDirection of 1 for counter-clockwise rotation around the location.
orbFollower = uavOrbitFollower; orbFollower.OrbitCenter = [1 1 5]'; orbFollower.OrbitRadius = 2.5; orbFollower.TurnDirection = 1;
Specify the pose of the UAV and the lookahead distance for tracking the path.
pose = [0;0;5;0]; lookaheadDistance = 2;
orbFollower object with the pose and lookahead distance. The object returns a lookahead point on the path, the desired heading, and yaw. You can use the desired heading and yaw to generate control commands for the UAV.
[lookaheadPoint,desiredHeading,desiredYaw,~,~] = orbFollower(pose,lookaheadDistance);