Main Content


Create tracking scenario


trackingScenario creates a tracking scenario object. A tracking scenario simulates a 3-D arena containing multiple platforms. Platforms represent anything that you want to simulate, such as aircraft, ground vehicles, or ships. Some platforms carry sensors, such as radar, sonar, or infrared. Other platforms act as sources of signals or reflect signals. Platforms can also include stationary obstacles that can influence the motion of other platforms. Platforms can be modeled as points or cuboids by specifying the 'Dimension' property when calling platform. Platforms can have aspect-dependent properties including radar cross-section or sonar target strength. You can populate a tracking scenario by calling the platform method for each platform you want to add. Platforms are Platform objects. You can create trajectories for any platform using the kinematicTrajectory, waypointTrajectory, or geoTrajectory System objects. After creating the scenario, run the simulation by calling the advance object function.


sc = trackingScenario creates an empty tracking scenario with default property values. In this case, you can specify platform trajectories in the scenario as Cartesian states using the kinematicTrajectory or waypointTrajectory objects.

sc = trackingScenario('IsEarthCentered',true) creates an empty Earth-centered tracking scenario with default property values. In this case, you can specify platform trajectories in the scenario as geodetic states using the geoTrajectory object.

sc = trackingScenario(Name,Value) configures a trackingScenario object with properties using one or more Name,Value pair arguments. Name is a property name and Value is the corresponding value. Name must appear inside single quotes (''). You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN. Any unspecified properties take default values.


expand all

Enable Earth-centered reference frame and trajectories, specified as true or false.

  • If specified as false, you must use the kinematicTrajectory or waypointTrajectory object to define the trajectories of platforms as Cartesian states in the tracking scenario.

  • If specified as true, you must use the geoTrajectory object to define the trajectories of platforms as geodetic coordinates in the tracking scenario. In this case, you must specify the IsEarthCentered property during the tracking scenario creation.

Data Types: logical

Stop time of simulation, specified as a positive scalar. A simulation stops when either of these conditions is met:

  • The stop time is reached.

  • Any platform reaches the end of its trajectory and you have specified the platform Motion property using waypoints, waypointTrajectory.

Units are in seconds.

Example: 60.0

Data Types: double

This property is read-only.

Current time of the simulation, defined as a positive scalar. To reset the simulation time to zero and restart the simulation, call the restart method. Units are in seconds.

Data Types: double

Frequency of simulation updates, specified as a nonnegative scalar in hertz.

  • When specified as a positive scalar, the scenario advances with the time step of 1/F, where F is the value of the UpdateRate property.

  • When specified as zero, the simulation advances based on the necessity of updating sensors or emitters mounted on platforms of the scenario. Create a platform using the platform function.

Example: 2.0

Data Types: double

Initial advance when calling the advance object function, specified as 'Zero' or 'UpdateInterval'. When specified as

  • 'Zero' — The scenario simulation starts at time 0 in the first call of the advance function.

  • 'UpdateInterval' — The scenario simulation starts at time 1/F, where F is the value of a non-zero UpdateRate property. If the UpdateRate property is specified as 0, the scenario neglects the InitialAdvance property and starts at time 0.

Data Types: enumeration

This property is read-only.

Simulation status, specified as

  • NotStarted — When the advance object function has not been used on the tracking scenario.

  • InProgress — When the advance object function has been used on the tracking scenario at least once and the scenario has not reached the Completed status.

  • Completed — When the scenario reaches the stop time specified by the StopTime property or any Platform in the scenario reaches the end of its trajectory.

You can restart a scenario simulation by using the restart object function.

Data Types: enumeration

This property is read-only.

Platforms in the scenario, returned as a cell or cell array of Platform objects. To add a platform to the scenario, use the platform object function.

Manager of ground surfaces in the tracking scenario, specified as a SurfaceManager object.

  • To control whether the tracking scenario models occlusion due to scenario surfaces, specify the UseOclussion property of the SurfaceManager object as true (default) or false. Note that when the UseOcclusion property is specified as true and when the IsEarthCentered property of the tracking scenario is also specified as true, the tracking scenario also models horizon occlusion based on the WGS84 Earth model.

  • To query the height of surfaces at a location in the scenario, use the height object function of the SurfaceManager object.

  • To determine if the surfaces in the scenario occlude the line-of-sight between two points, use the occlusion object function of the SurfaceManager object.

Object Functions

platformAdd platform to tracking scenario
groundSurfaceAdd surface to tracking scenario
advanceAdvance tracking scenario simulation by one time step
restartRestart tracking scenario simulation
recordRun tracking scenario and record platform, sensor, and emitter information
emitCollect emissions from emitters in tracking scenario
propagatePropagate emissions in tracking scenario
detectCollect detections from all the sensors in tracking scenario
lidarDetectReport point cloud detections from all lidar sensor in trackingScenario
platformPosesPositions, velocities, and orientations of all platforms in tracking scenario
platformProfilesProfiles of platforms in tracking scenario
coverageConfigSensor and emitter coverage configuration
playPlay tracking scenario simulation in player
perturbApply perturbations to tracking scenario
cloneCreate copy of tracking scenario


collapse all

Construct a tracking scenario with 2 Hz sample rate.

sc = trackingScenario(UpdateRate=2);

Create two platforms with different appearance and disappearance time. Run the simulation and display platform position.

platfm1 = platform(sc,Trajectory=waypointTrajectory([0 0 0;10 -10 0],[2.5;4.5]));
platfm2 = platform(sc,Trajectory=waypointTrajectory([0 0 0;-24 24 0],[1;5]));
while advance(sc)
    poses = platformPoses(sc);
    platformIDs = [poses.PlatformID];
    if ismember(platfm1.PlatformID, platformIDs)
        idx = find(platformIDs == platfm1.PlatformID);
        msg1 = ": Platform 1 position " + mat2str(poses(idx).Position) + "; ";
        msg1 = ": Platform 1 not defined; ";
    if ismember(platfm2.PlatformID, platformIDs)
        idx = find(platformIDs == platfm2.PlatformID);
        msg2 = "Platform 2 position " + mat2str(poses(idx).Position) + ".";
        msg2 = "Platform 2 not defined.";

    disp("t=" + sc.SimulationTime + msg1 + msg2);
t=0: Platform 1 not defined; Platform 2 not defined.
t=0.5: Platform 1 not defined; Platform 2 not defined.
t=1: Platform 1 not defined; Platform 2 position [0 0 0].
t=1.5: Platform 1 not defined; Platform 2 position [-3 3 0].
t=2: Platform 1 not defined; Platform 2 position [-6 6 0].
t=2.5: Platform 1 position [0 0 0]; Platform 2 position [-9 9 0].
t=3: Platform 1 position [2.5 -2.5 0]; Platform 2 position [-12 12 0].
t=3.5: Platform 1 position [5 -5 0]; Platform 2 position [-15 15 0].
t=4: Platform 1 position [7.5 -7.5 0]; Platform 2 position [-18 18 0].
t=4.5: Platform 1 position [10 -10 0]; Platform 2 position [-21 21 0].
t=5: Platform 1 not defined; Platform 2 position [-24 24 0].

Construct a tracking scenario with two platforms that follow different trajectories.

sc = trackingScenario('UpdateRate',100.0,'StopTime',1.2);

Create two platforms.

platfm1 = platform(sc);
platfm2 = platform(sc);

Platform 1 follows a circular path of radius 10 m for one second. This is accomplished by placing waypoints in a circular shape, ensuring that the first and last waypoint are the same.

wpts1 = [0 10 0; 10 0 0; 0 -10 0; -10 0 0; 0 10 0];
time1 = [0; 0.25; .5; .75; 1.0];
platfm1.Trajectory = waypointTrajectory(wpts1, time1);

Platform 2 follows a straight path for one second.

wpts2 = [-8 -8 0; 10 10 0];
time2 = [0; 1.0];
platfm2.Trajectory = waypointTrajectory(wpts2,time2);

Verify the number of platforms in the scenario.

    {1x1 fusion.scenario.Platform}    {1x1 fusion.scenario.Platform}

Run the simulation and plot the current position of each platform. Use an animated line to plot the position of each platform.

axis equal
axis([-12 12 -12 12])
line1 = animatedline('DisplayName','Trajectory 1','Color','b','Marker','.');
line2 = animatedline('DisplayName','Trajectory 2','Color','r','Marker','.');
p1 = pose(platfm1);
p2 = pose(platfm2);

while advance(sc)
    p1 = pose(platfm1);
    p2 = pose(platfm2);

Plot the waypoints for both platforms.

hold on
plot(wpts1(:,1),wpts1(:,2),' ob')
text(wpts1(:,1),wpts1(:,2),"t = " + string(time1),'HorizontalAlignment','left','VerticalAlignment','bottom')
plot(wpts2(:,1),wpts2(:,2),' or')
text(wpts2(:,1),wpts2(:,2),"t = " + string(time2),'HorizontalAlignment','left','VerticalAlignment','bottom')
hold off

Create a tracking scenario with a specified update rate.

scene = trackingScenario('IsEarthCentered',true,'UpdateRate',0.01);

Add an airplane in the scenario. The trajectory of the airplane changes in latitude and altitude.

plane = platform(scene,'Trajectory',geoTrajectory([-12.338,-71.349,10600;42.390,-71.349,0],[0 36000]));

Advance the tracking scenario and record the geodetic and Cartesian positions of the plane target.

positions = [];
while advance(scene)
    poseLLA = pose(plane,'CoordinateSystem','Geodetic');
    poseCart = pose(plane,'CoordinateSystem','Cartesian');
    positions = [positions;poseCart.Position];%#ok<AGROW> Allow the buffer to grow.

Visualize the trajectory in the ECEF frame.

km = 1000;
% Plot the trajectory.
plot3(positions(1,1)/km,positions(1,2)/km,positions(1,3)/km, 'b*');
hold on;
plot3(positions(end,1)/km,positions(end,2)/km,positions(end,3)/km, 'bo');

% Plot the Earth radial lines.
plot3([0 positions(1,1)]/km,[0 positions(1,2)]/km,[0 positions(1,3)]/km,'k:');
plot3([0 positions(end,1)]/km,[0 positions(end,2)]/km,[0 positions(end,3)]/km,'k:');
xlabel('x (km)'); ylabel('y (km)'); zlabel('z (km)');
legend('Start position','End position','Trajectory')

Create a trackingScenario object and set its update rate to 0.

scene = trackingScenario(UpdateRate=0);

Add two platforms.

car = platform(scene);
truck = platform(scene);

Define the trajectory for each platform using the waypointTrajectory object.

carTraj = waypointTrajectory([0 0 0; 10 10 -10],[0 100]);
truckTraj = waypointTrajectory([-5 -5 -5; 20 20 -20],[0.1 100.1]);
car.Trajectory = carTraj;
truck.Trajectory = truckTraj;

Define two sensors and add each sensor to the corresponding platform.

carSensor = fusionRadarSensor(1,"Rotator",UpdateRate=1);
truckSensor = fusionRadarSensor(2,"Rotator",UpdateRate=1);
car.Sensors = {carSensor};
truck.Sensors = {truckSensor};

Run the scenario and detect platforms. Notice that the scenario determines the update rate based on the times of arrival of trajectories and the sensor update rates.

while scene.advance()
    if scene.SimulationTime < 5
        disp("Time = " + scene.SimulationTime)
    detections = detect(scene);
    if ~isempty(detections)
        disp("Time = " + scene.SimulationTime)
Time = 0
Time = 0.1
Time = 1
Time = 1.1
Time = 2
Time = 2.1
Time = 3
Time = 3.1
Time = 4
Time = 4.1
Time = 38
    {1x1 objectDetection}

Version History

Introduced in R2018b

expand all