Use theaterPlot to Visualize Tracking Scenario

This example shows how to use the theaterPlot object to visualize various aspects of a tracking scenario.

Introduction

theaterPlot is an efficient tool for visualizing various aspects of a tracking scenario. It is composed of a primary object, which hosts the plotting environment based on a parent axes, and plotters to plot the desired aspects of features from the tracking scenario.

This figure shows a structural representation of a theaterPlot object.

The Parent property specifies the axes on which the theater plot is enabled. You can specify the parent axes of a theater plot during object creation. If you do not specify a parent axes, theaterPlot creates a new figure and uses the current axes of the created figure as its Parent property. You can also set the axes limits of the parent axes using the XLimits, YLimits, and Zlimits properties by using name-value pair arguments during object creation. Set the units of measurement for each axes using the AxesUnits property.

The Plotters property holds plotters that you added to the theaterPlot object.

• platformPlotter — Plot platforms in a tracking scenario

• trajectoryPlotter — Plot trajectories in a tracking scenario

• orientationPlotter — Plot orientation of platforms in a tracking scenario

• coveragePlotter — Plot sensor coverage and sensor beams in a tracking scenario

• detectionPlotter — Plot sensor detections in a tracking scenario

• trackPlotter — Plot tracks in a tracking scenario

• surfacePlotter — Plot surfaces in a tracking scenario

You can specify visual elements and effects for each plotter during the creation of the plotter. Each plotter is also paired with a theaterPlot object function, which you need to call to plot the results. For example, a coveragePlotter is paired with a plotCoverage object function that shows the sensor coverage.

This example showcases a few plotters for visualizing a tracking scenario. theaterPlot can work efficiently with a trackingScenario object even though you do not necessarily need a trackingScenario object to use the theaterPlot object.

Create theaterPlot and trackingScenario Objects

Create a trackingScenario object and a theaterPlot object.

simulationDuration = 100;
scene = trackingScenario('StopTime',simulationDuration);
tp = theaterPlot('XLimits',[-250 250],'YLimits',[-250 250],'ZLimits',[0 120]);
view(3);grid on;

Create Trajectory Plotter and Platform Plotter for Target

Create a waypoint trajectory for a target platform.

timeOfArrival = [0  simulationDuration];
waypoints = [100 -100 10; 100 100 80];
trajectory = waypointTrajectory(waypoints,timeOfArrival);

Add a cuboid target platform that follows the specified trajectory. First add a target platform to the tracking scenario.

target = platform(scene,'Trajectory',trajectory,'Dimensions', ...
    struct('Length',35,'Width',15,'Height',5.5,'OriginOffset',[0 0 0]));

Then add a trajectoryPlotter object to the theaterPlot object, and use the plotTrajectory function to plot the waypoint trajectory.

trajPlotter = trajectoryPlotter(tp,'DisplayName','Trajectory','Color','k','LineWidth',1.2);
plotTrajectory(trajPlotter,{trajectory.Waypoints})

Tip You can plot multiple same-type features (platforms, trajectories, orientations, coverages, detections, or tracks) together using one plotter. For example, you can plot multiple trajectories together by specifying a cell array of waypoints as the second argument of the plotTrajectory function. See the syntax description of plotTrajectory for more details.

Define a plotter for the target platform.

targetPlotter = platformPlotter(tp,'DisplayName','Target', ...
    'Marker','s','MarkerEdgeColor','g','MarkerSize',2);
plotPlatform(targetPlotter,target.Position, ...
    target.Dimensions,quaternion(target.Orientation,'rotvecd'))

You can add graphical objects other than the plotter objects on the theaterPlot by directly plotting on the parent axes of the theaterPlot object. Put a circle marker at the origin.

hold on
plot3(tp.Parent,0,0,0,'Color','k','Marker','o','MarkerSize',4)

Create Platform with Mounted Radar Sensor

Add a tower platform to the scenario.

tower = platform(scene,'Position',[-100,0,0],'Dimensions', ...
    struct('Length',5,'Width',5,'Height',30,'OriginOffset',[0 0 -15]));

Display the tower using a platform plotter.

towerPlotter = platformPlotter(tp,'DisplayName','Tower','Marker','s','MarkerSize',2);
plotPlatform(towerPlotter,tower.Position,tower.Dimensions,quaternion(tower.Orientation,'rotvecd'))

Mount a monostatic radar to the top of the tower.

radar = fusionRadarSensor(1,'DetectionMode','Monostatic', ...
    'UpdateRate',5, ...
    'MountingLocation',[0, 0, 30], ...
    'FieldOfView',[4, 30],...
    'MechanicalAzimuthLimits',[-60 60], ...
    'MechanicalElevationLimits',[0 0], ...
    'HasElevation',true, ...
    'RangeResolution',200, ...
    'AzimuthResolution',20, ...
    'ElevationResolution',20);
tower.Sensors = radar;

Add a coveragePlotter and plot the coverage and initial beam for the monostatic radar. When plotting the coverage, the plotCoverage object function requires a second argument that specifies the configuration of the sensor coverage. Obtain the configuration by using the coverageConfig function on the tracking scenario scene.

radarPlotter = coveragePlotter(tp,'Color','b','DisplayName','Radar beam');
plotCoverage(radarPlotter,coverageConfig(scene))

Create a detection plotter to plot the detections that the radar generates.

detPlotter = detectionPlotter(tp,'DisplayName','Detection','MarkerFaceColor','r','MarkerSize',4);

Run Scenario and Update Theater Plot

Iterate through the tracking scenario and generate radar detections. Plot the platform, radar coverage, and detections.

rng(2019) % for repeatable results
while advance(scene)
    % Plot target.
    plotPlatform(targetPlotter,target.Position, ...
        target.Dimensions,quaternion(target.Orientation,'rotvecd'))

    % Plot sensor coverage.
    plotCoverage(radarPlotter,coverageConfig(scene))

    % Extract target pose from the view of the tower and use the extracted
    % pose to generate detections.
    poseInTower = targetPoses(tower);
    [detections, numDets] = radar(poseInTower,scene.SimulationTime);
    detPos = zeros(numDets,3);
    detNoise = zeros(3,3,numDets);

    % Obtain detection pose relative to the scenario frame. Also, obtain
    % the covariance of the detection.
    for i=1:numDets
        a = detections;
        detPos(i,:) = tower.Trajectory.Position + detections{i}.Measurement';
        detNoise(:,:,i) = detections{i}.MeasurementNoise;
    end

    % Plot any generated detections with the covariance ellipses.
    if ~isempty(detPos)
        plotDetection(detPlotter,detPos,detNoise)
    end
end

You can zoom in on the detection in the figure to visualize the plotted covariance ellipses of the generated detections.

Summary

In this example, you learned about the organization of a theaterPlot object. You also learned how to visualize a simple tracking scenario using the theaterPlot object.