Create UAV Scenario

Build and simulate UAV scenarios with terrain, buildings, sensor-equipped platforms, and 3D visualization using the UAV Toolbox uavScenario framework.

When to Use

• Creating a UAV simulation environment with real-world terrain or buildings
• Adding sensor-equipped UAV platforms (GPS, IMU, lidar) to a scenario
• Running a time-stepping simulation loop with sensor readings
• Visualizing UAV flight in 3D with show3D

When NOT to Use

• Generating flight trajectories (waypoint design, min-snap) — use trajectory skill instead
• Simulink-based UAV simulation (UAV Toolbox Simulink blocks)
• Path planning and obstacle avoidance algorithms
• Coordinate conversion only (ned2lla, lla2ned) — use these directly

Workflow

1. Create scenario — uavScenario with ReferenceLocation and UpdateRate
2. Add terrain — addMesh(scene,"terrain",...) with GMTED2010 or custom DTED
3. Add buildings — addMesh(scene,"buildings",...) from OSM file
4. Add platform — uavPlatform with trajectory, then updateMesh
5. Attach sensors — uavSensor adaptor binding sensor to platform
6. Run simulation — setup → advance → updateSensors → read loop
7. Visualize — show3D with FastUpdate for animation

Key Functions

Patterns

Create Scenario with Reference Location

scene = uavScenario( ...
    "UpdateRate", 10, ...
    "StopTime", 60, ...
    "ReferenceLocation", [42.355 -71.066 0]);

ReferenceLocation is [lat lon alt] in degrees and meters. All local coordinates are relative to this origin. Set this before adding any meshes or platforms.

Add Terrain (GMTED2010)

Use geographic coordinates with UseLatLon=true:

latLim = [42.350 42.360];
lonLim = [-71.072 -71.060];
addMesh(scene, "terrain", {"gmted2010", latLim, lonLim}, [0.3 0.6 0.2], ...
    UseLatLon=true);

Or use local ENU coordinates (meters) without UseLatLon:

xLim = [-500 500];
yLim = [-500 500];
addMesh(scene, "terrain", {"gmted2010", xLim, yLim}, [0.3 0.6 0.2]);

The geometry cell for terrain is 3 elements: {"gmted2010", xOrLatLim, yOrLonLim}.

The color argument is required — it is not optional.

If user used addCustomTerrain to import DTED file with a terrain name, this terrain can be used in addition to gmted2010.

addCustomTerrain("myterrain", "myterrain.dt1");
xLim = [-500 500];
yLim = [-500 500];
addMesh(scene, "terrain", {"myterrain", xLim, yLim}, [0.3 0.6 0.2]);

Add Buildings (OSM File)

osmFile = "boston_common.osm";
latLim = [42.350 42.360];
lonLim = [-71.072 -71.060];

addMesh(scene, "buildings", {osmFile, latLim, lonLim, 'auto'}, ...
    [0.6 0.6 0.6], UseLatLon=true);

Or use local ENU coordinates (meters) without UseLatLon:

xLim = [-500 500];
yLim = [-500 500];
addMesh(scene, "buildings", {osmFile, xLim, yLim, 'auto'}, [0.3 0.6 0.2]);

The geometry cell for buildings is 4 elements: {osmFile, latOrXLim, lonOrYLim, height}. height can either be 'auto' or a numerical scalar. Auto will snap buildings to terrain height if available.

The color argument is required — it is not optional.

Add Platform with Mesh

traj = waypointTrajectory( ...
    "Waypoints", [0 0 -50; 200 0 -50; 200 200 -50; 0 0 -50], ...
    "TimeOfArrival", [0 20 40 60], ...
    "ReferenceFrame", "NED");

plat = uavPlatform("UAV1", scene, "Trajectory", traj);
updateMesh(plat, "quadrotor", {1}, [0 0.4 0.8], [0 0 0], [0 1 0 0]);

updateMesh requires all arguments: (platform, type, geometries, color, position, orientation).

• geometries — 1-element cell: {scaleFactor} for "quadrotor"/"fixedwing", {[L W H]} for "cuboid"
• color — RGB triplet (required, not optional)
• position — [x y z] offset, use [0 0 0] for default
• orientation — quaternion [w x y z], use [0 1 0 0] for NED scenarios (180-degree roll to flip z-down body frame upright)

Valid mesh types: "fixedwing", "quadrotor", "cuboid", "custom".

There is NO "multirotor" type — use "quadrotor" for any multirotor UAV.

Attach Sensors (uavSensor Adaptor Pattern)

Always use `uavSensor` to bind sensors to platforms. Do not feed sensor models manually.

% Create sensor model
gps = gpsSensor("SampleRate", 10, "ReferenceFrame", "NED");

% Bind to platform via uavSensor adaptor
gpsSensorObj = uavSensor("GPS", plat, gps, "UpdateRate", 10);

For INS:

ins = insSensor;
insSensorObj = uavSensor("INS", plat, ins, "UpdateRate", 10);

Sensor UpdateRate must divide evenly into the scenario UpdateRate. For example, a 10 Hz scenario supports sensor rates of 1, 2, 5, or 10 Hz — not 100 Hz.

Simulation Loop

setup(scene);

while advance(scene)
    updateSensors(scene);

    % Read sensor data (3 outputs: isUpdated, timestamp, readings)
    [isUpdated, t, position, velocity, groundspeed, course] = read(gpsSensorObj);
    if isUpdated
        % position is 1x3 [lat lon alt] for gpsSensor
        gpsLLA = position;
    end

    % Read platform state directly
    [motion, lla] = read(plat);
    % motion: 1x16 vector [pos(3) orient(4) vel(3) acc(3) angvel(3)]
    % lla: [lat lon alt]
end

read(sensor) returns variable number outputs:

• isUpdated — logical, true when sensor has new data at this time step
• t — timestamp in seconds
• sensorReadings1 to sensorReadingsN — sensor-specific output (position, velocity, groundspeed, course for gpsSensor)

read(plat) returns exactly 2 outputs:

• motion — 16-element vector: position(1:3), orientation quaternion(4:7), velocity(8:10), acceleration(11:13), angular velocity(14:16)
• lla — 3-element vector: [latitude, longitude, altitude]

Visualize with show3D

setup(scene);
ax = show3D(scene);

while advance(scene)
    updateSensors(scene);
    show3D(scene, "FastUpdate", true, "Parent", ax);
    drawnow limitrate
end

Use "FastUpdate", true after the first call for efficient animation.

Trajectory Trail (Flight Path Line)

show3D only renders the UAV at its current position — it does NOT draw the flight path. To show the trajectory trail, create a line object once, then update its data each step:

setup(scene);
[ax, plottedFrames] = show3D(scene);
hold(ax, "on");
% Draw trajectory in the platform's reference frame
trajLine = plot3(plottedFrames.(plat.ReferenceFrame), NaN, NaN, NaN, "r-", "LineWidth", 1.5);
hold(ax, "off");

% acceptable for short loops; pre-allocate for long simulations
xHist = []; yHist = []; zHist = [];
while advance(scene)
    show3D(scene, "FastUpdate", true, "Parent", ax);
    [motion, ~] = read(plat);
    xHist(end+1) = motion(1); 
    yHist(end+1) = motion(2);
    zHist(end+1) = motion(3);
    set(trajLine, "XData", xHist, "YData", yHist, "ZData", zHist);
    drawnow limitrate
end

Do NOT call plot3 inside the loop — it creates a new graphics object each step and kills performance.

Body-Frame Marker (Visibility in Large Scenes)

When scenes span 500m+, the platform mesh becomes invisible regardless of scale factor. Instead of inflating the scale (which distorts the mesh), parent a marker to the platform's body frame so it tracks at any zoom level:

setup(scene);
[ax, plottedFrames] = show3D(scene);
hold(ax, "on");
bodyFrame = plottedFrames.UAV1.BodyFrame;
plot3(ax, 0, 0, 0, "r^", "MarkerSize", 15, "MarkerFaceColor", "r", ...
    "Parent", bodyFrame);
hold(ax, "off");

while advance(scene)
    show3D(scene, "FastUpdate", true, "Parent", ax);
    drawnow limitrate
end

Replace UAV1 with the actual platform name. The marker moves with the UAV automatically via the parent transform.

Gotchas

Conventions

• NED frame is the default for uavPlatform. Match all trajectories and sensors to NED.
• `ReferenceLocation` must be set at scenario creation — it is read-only after construction.
• `UpdateRate` on the scenario controls the simulation time step. Sensor UpdateRate can differ (sensors skip steps when not due).
• OSM files must be downloaded separately (e.g., via Overpass API or export from openstreetmap.org). addMesh("buildings",...) expects a file path, not a URL.
• `addCustomTerrain` for DTED files when GMTED2010 resolution is insufficient.

Copyright 2026 The MathWorks, Inc.