plan

Plan coverage path between takeoff and landing

Since R2023a

Syntax

[path,solninfo] = plan(planner,takeoff)

[path,solninfo] = plan(planner,takeoff,landing)

[___] = plan(___,VerboseMode=mode)

Description

The plan function returns a coverage path that enables you to optimally surveys a geographical area with a UAV for precision agriculture and image mapping applications.

[path,solninfo] = plan(planner,takeoff) returns a path consisting of 2D waypoints path, and information about the order of visitation of polygons and sweep permutations solnInfo. The landing position is the same as the takeoff position.

[path,solninfo] = plan(planner,takeoff,landing) specifies a landing position in addition to the takeoff position.

[___] = plan(___,VerboseMode=mode) specifies the diagnostic printing mode.

Examples

Plan Coverage Path Using Geodetic Coordinates

This example shows how to plan a coverage path that surveys the parking lots of the MathWorks Lakeside campus.

Get the geodetic coordinates for the MathWorks Lakeside campus. Then create the limits for our map.

mwLS = [42.3013 -71.375 0];
latlim = [mwLS(1)-0.003 mwLS(1)+0.003];
lonlim = [mwLS(2)-0.003 mwLS(2)+0.003];

Create a figure containing the map with the longitude and latitude limits.

fig = figure;
g = geoaxes(fig,Basemap="satellite");
geolimits(latlim,lonlim)

Get the outline of the first parking lot in longitude and latitude coordinates. Then create the polygon by concatenating them.

pl1lat = [42.3028 42.30325 42.3027 42.3017 42.3019]';
pl1lon = [-71.37527 -71.37442 -71.3736 -71.37378 -71.375234]';
pl1Poly = [pl1lat pl1lon];

Repeat the process for the second parking lot.

pl2lat = [42.30035 42.2999 42.2996 42.2999]';
pl2lon = [-71.3762 -71.3734 -71.37376 -71.37589]';
pl2poly = [pl2lat pl2lon];

Create the coverage space with both of those polygons, set the coverage space to use geodetic coordinates, and set the reference location to the MathWorks Lakeside campus location.

cs = uavCoverageSpace(Polygons={pl1Poly,pl2poly},UseLocalCoordinates=false,ReferenceLocation=mwLS);

Set the height at which to fly the UAV to 25 meters, and the sensor footprint width to 20 meters. Then show the coverage space on the map.

ReferenceHeight = 25;
cs.UnitWidth = 20;
show(cs,Parent=g);

Set the sweep angle for polygons 1 and 2 to 85 and 5 degrees, respectively, to have paths that are parallel to the roads in the parking lots. Then create the coverage planner for that coverage space with the exhaustive solver algorithm.

setCoveragePattern(cs,1,SweepAngle=85)
setCoveragePattern(cs,2,SweepAngle=5)
cp = uavCoveragePlanner(cs,Solver="Exhaustive");

Set the takeoff position to a location in the courtyard, then plan the coverage path.

takeoff = [42.30089 -71.3752, 0];
[wp,soln] = plan(cp,takeoff);
hold on
geoplot(wp(:,1),wp(:,2),LineWidth=1.5);
geoplot(takeoff(1),takeoff(2),MarkerSize=25,Marker=".")
legend("","","Path","Takeoff/Landing")
hold off

Plan Coverage Path for Defined Region

This example shows how to plan a coverage path for a region in local coordinates and compares the results of using the exhaustive solver with the results of using the minimum traversal solver.

Define the vertices for a coverage space.

area = [5 8.75; 5 27.5; 17.5 22.5; 25 31.25; 35 31.25; 30 20; 15 6.25];

Because vertices define a concave polygon and the coverage planner requires convex polygons, decompose the polygon into convex polygons. Then create a coverage space with the polygons from decomposition.

polygons = coverageDecomposition(area);
cs = uavCoverageSpace(Polygons=polygons);

Define the takeoff and landing positions at [0 0 0] and [32.25 37.25 0], respectively. Then show the coverage space and plot the takeoff and landing positions.

takeoff = [0 0 0];
landing = [32.25 37.25 0];
show(cs);
exampleHelperPlotTakeoffLandingLegend(takeoff,landing)

Create a coverage planner with the exhaustive solver algorithm and another coverage planner with a minimum traversal solver algorithm. Because Polygon 2 is closer to the takeoff position, set the visiting sequence of the solver parameters such that we traverse Polygon 2 first.

cpeExh = uavCoveragePlanner(cs,Solver="Exhaustive");
cpMin = uavCoveragePlanner(cs,Solver="MinTraversal");
cpeExh.SolverParameters.VisitingSequence = [2 1];
cpMin.SolverParameters.VisitingSequence = [2 1];

Plan with both solver algorithms using the same takeoff and landing positions.

[wptsExh,solnExh] = plan(cpeExh,takeoff,landing);
[wptsMin,solnMin] = plan(cpMin,takeoff,landing);

Show the planned path for both the exhaustive and the minimum traversal algorithms.

figure
show(cs);
title("Exhaustive Solver Algorithm")
exampleHelperPlotTakeoffLandingLegend(takeoff,landing,wptsExh)

figure
show(cs);
title("Minimum Traversal Solver Algorithm")
exampleHelperPlotTakeoffLandingLegend(takeoff,landing,wptsMin)

Export the waypoints from the minimum traversal solver to a .waypoints file with the reference frame set to north-east-down.

exportWaypointsPlan(cpMin,solnMin,"coveragepath.waypoints",ReferenceFrame="NED")

Input Arguments

planner — Coverage path planner

uavCoveragePlanner object

Coverage path planner, specified as a uavCoveragePlanner object.

takeoff — UAV takeoff position

three-element row vector

UAV takeoff position, specified as a three-element row vector.

The format depends on the UseLocalCoordinates property of the CoverageSpace property of planner:

• When UseLocalCoordinates is true the format is local xyz-coordinates in the form [x y z], in meters. UseLocalCoordinates is true by default.

• When UseLocalCoordinates is false the format is geodetic coordinates in the form [latitude longitude altitude]. latitude and longitude are in degrees, and altitude is in meters.

Data Types: double

landing — UAV landing position

three-element row vector

UAV landing position, specified as a three-element row vector.

The format depends on the UseLocalCoordinates property of the CoverageSpace property of planner:

• UseLocalCoordinates=true — Format is local xyz-coordinates in the form [x y z], in meters. UseLocalCoordinates is true by default.

• UseLocalCoordinates=false — Format is geodetic coordinates in the form [latitude longitude altitude]. latitude and longitude are in degrees, and altitude is in meters.

Data Types: double

mode — Verbose mode

false or 0 (default) | true or 1

Verbose mode, specified as true or (1) to output diagnostic information about the planning algorithm to the Command Window, or false or (0) to output no information.

Output Arguments

path — Waypoint path

N-by-2 matrix

Waypoint path, specified as a N-by-2 matrix.

The format depends on the UseLocalCoordinates property of the CoverageSpace property of planner:

• UseLocalCoordinates=true — Format is local xy-coordinates in the form [x y], in meters. UseLocalCoordinates is true by default.

• UseLocalCoordinates=false — Format is geodetic coordinates in the form [latitude longitude]. latitude and longitude are in degrees.

solninfo — Solution information

structure

Solution plan, returned as a structure containing these fields:

• VisitingSequence — N-element row vector denoting the order of visitation of polygons, where N is the total number of polygons in the coverage space. For example, [2 1 3] specifies that the UAV should visit polygon 2 first, polygon 1 second, and polygon 3 last.

• SweepPattern — N-element row vector of integers denoting the sweep pattern for each polygon, where N is the total number of polygons in the coverage space. Each element is an integer in the range [1, 4] that indicates a sweep pattern:

  • 1 — Forward sweep pattern

  • 2 — Counter-clockwise sweep pattern

  • 3 — Reverse sweep pattern

  • 4 — Reverse counter-clockwise sweep pattern

  For example, [3 1 2] specifies that the UAV should use the reverse sweep pattern for polygon 1, the forward sweep pattern for polygon 2, and the counter-clockwise sweep pattern for polygon 3.

• TransitionCost — Euclidean distance cost for transitioning between polygons including takeoff and landing distance.

• Takeoff — Takeoff location, specified as a three-element row vector in LLA format.

• Landing — Takeoff location, specified as a three-element row vector in LLA format.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Generating code containing the plan requires you to enable dynamic memory allocation. For more information about enabling dynamic memory allocation, see Set Dynamic Memory Allocation Threshold (MATLAB Coder).

Deploying to embedded real time (ERT) targets is not supported.

Version History

Introduced in R2023a

R2023b: Code generation support with dynamic memory allocation

plan now supports code generation with dynamic memory allocation enabled. For more information about enabling dynamic memory allocation, see Set Dynamic Memory Allocation Threshold (MATLAB Coder).

Deploying to embedded real time (ERT) targets is not supported.