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

| Function | Purpose | Toolbox | |----------|---------|---------| | uavScenario | Create simulation scenario | UAV Toolbox | | addMesh | Add terrain, buildings, or custom meshes | UAV Toolbox | | uavPlatform | Add UAV platform to scenario | UAV Toolbox | | updateMesh | Set platform body mesh | UAV Toolbox | | uavSensor | Attach sensor to platform | UAV Toolbox | | setup | Initialize scenario for simulation | UAV Toolbox | | advance | Step simulation forward one time step | UAV Toolbox | | updateSensors | Update all sensors at current time | UAV Toolbox | | show3D | 3D visualization | UAV Toolbox | | waypointTrajectory | Define flight path from waypoints | Navigation Toolbox | | gpsSensor | GPS noise model | Navigation Toolbox | | insSensor | INS/IMU noise model | Navigation Toolbox |

Patterns

Create Scenario with Reference Location

matlab
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:

matlab
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:

matlab
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.

matlab
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)

matlab
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:

matlab
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

matlab
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.

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

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

For INS:

matlab
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

matlab
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

matlab
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:

matlab
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:

matlab
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

| Mistake | Consequence | Fix | |---------|-------------|-----| | addMesh(...,latLim,lonLim) without UseLatLon=true | 0 buildings imported, terrain at wrong location | Add UseLatLon=true when passing geographic coordinates | | updateMesh(plat,"multirotor",...) | Error — invalid mesh type | Use "quadrotor" | | updateMesh with [1 0 0 0] (identity quaternion) in NED scenario | Inverted or invisible mesh — body frame is z-down | Use [0 1 0 0] (180-degree roll) to flip mesh upright | | [pos, orient, vel] = read(plat) | Error — too many outputs | Use [motion, lla] = read(plat) (2 outputs) | | [isUpdated, data] = read(sensor) | Gets timestamp instead of readings | Use [isUpdated, t, sensorReadings] = read(sensor) (3 outputs) | | Feeding gpsSensor manually each step | Works but bypasses the scenario framework | Use uavSensor adaptor + updateSensors(scene) | | Missing color argument in addMesh | Error — not enough input arguments | Always provide RGB triplet as 4th argument | | waypointTrajectory in ENU with NED platform | Error — reference frame mismatch | Set "ReferenceFrame","NED" on trajectory | | Forgetting setup(scene) before loop | Sensors not initialized, no readings | Always call setup(scene) before advance | | Sensor UpdateRate > scenario UpdateRate | Error — rate must divide evenly | Sensor rate must be ≤ scenario rate and divide evenly into it |

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.