Main Content

uavPlatform

UAV platform for sensors in scenario

Description

The uavPlatform object represents an unmanned aerial vehicle (UAV) platform in a given UAV scenario. Use the platform to define and track the trajectory of an object in the scenario. To simulate sensor readings for the platform, mount sensors like the gpsSensor, insSensor , or uavLidarPointCloudGenerator objects with a set of uavSensor objects. Add a body mesh for visualization using updateMesh. Set geofencing limitations using addGeoFence and check those limits using checkPermission.

Creation

Syntax

Description

platform = uavPlatform(name,scenario) create a platform with a specified name and adds it to the given scenario as a uavScenario.

example

platform = uavPlatform(name,scenario,Name,Value) specifies options using one or more name-value pair arguments in addition to the input arguments in the previous syntax. You can specify properties as name-value pairs as well. For example, 'StartTime',10 sets the initial time for the platform trajectory to 10 seconds.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'StartTime',10 sets the initial time of the platform trajectory to 10 seconds.

Initial time of the platform trajectory, specified as the comma-separated pair consisting of 'StartTime' and a scalar in seconds.

Data Types: double

Initial platform position for UAV, specified as the comma-separated pair consisting of 'InitialPosition' and a vector of the form [x y z]. Only specify this name-value pair if not specifying the Trajectory property.

Data Types: double

Initial platform orientation for UAV, specified as the comma-separated pair consisting of 'InitialOrientation' and a vector of the form [w x y z], representing a quaternion. Only specify this name-value pair if not specifying the Trajectory property.

Data Types: double

Initial platform velocity for UAV, specified as the comma-separated pair consisting of 'InitialVelocity' and a vector of the form [vx vy vz]. Only specify this name-value pair if not specifying the Trajectory property.

Data Types: double

Initial platform acceleration for UAV, specified as the comma-separated pair consisting of 'InitialAcceleration' and a vector of the form [ax ay az]. Only specify this name-value pair if not specifying the Trajectory property.

Data Types: double

Initial platform angular velocity for UAV, specified as the comma-separated pair consisting of 'InitialAngularVelocity' and a three-element vector of the form [x y z]. The magnitude of the vector defines the angular speed in radians per second. The xyz-coordinates define the axis of clockwise rotation. Only specify this name-value pair if not specifying the Trajectory property.

Data Types: double

Trajectory for UAV platform motion, specified as a waypointTrajectory object. By default, the platform is assumed to be stationary and at the origin. To move the platform at each simulation step of the scenario, use the move object function .

Note

The uavPlatform object must specify the same ReferenceFrame property as the specified waypointTrajectory object.

Reference frame for computing UAV platform motion, specified as string scalar, which matches any reference frame in the uavScenario. All platform motion is computed relative to this inertial frame.

Data Types: string

Properties

expand all

Identifier for the UAV platform, specified as a string scalar or character vector.

Example: "uav1"

Data Types: string | char

Trajectory for UAV platform motion, specified as a waypointTrajectory object. By default, the object assumes the platform is stationary and at the scenario origin. To move the platform at each simulation step of the scenario, use the move object function .

Note

The uavPlatform object must specify the same ReferenceFrame property as the specified waypointTrajectory object.

Reference frame for computing UAV platform motion, specified as string scalar or character vector, which matches any reference frame in the uavScenario. The object computes all platform motion relative to this inertial frame.

Data Types: string | char

UAV platform body mesh, specified as an extendedObjectMesh object. The body mesh describes the 3-D model of the platform for visualization purposes.

UAV platform body mesh color when displayed in the scenario, specified as an RGB triplet.

Data Types: double

Transform between UAV platform body and mesh frame, specified as a 4-by-4 homogeneous transformation matrix that maps points in the platform mesh frame to points in the body frame.

Data Types: double

Sensors mount on UAV platform, specified as an array of uavSensor objects.

Geofence restrictions for UAV platform, specified as a structure array with these fields:

  • Geometry — An extendedObjectMesh object representing the 3-D space for the geofence in the scenario frame.

  • Permission — A logical scalar that indicates if the platform is permitted inside the geofence (true) or not permitted (false).

Data Types: double

Object Functions

moveMove UAV platform in scenario
readRead UAV motion vector
updateMeshUpdate body mesh for UAV platform
addGeoFenceAdd geographical fencing to UAV platform
checkPermissionCheck UAV platform permission based on geofencing

Examples

collapse all

Create a scenario to simulate unmanned aerial vechicle (UAV) flights between a set of buildings. The example demonstates updating the UAV pose in open-loop simulations. Use the UAV scenario to visualize the UAV flight and generate simulated point cloud sensor readings.

Introduction

To test autonomous algorithms, a UAV scenario enables you to generate test cases and generate sensor data from the environment. You can specify obstacles in the workspace, provide trajectories of UAVs in global coordinates, and convert data between coordinate frames. The UAV scenario enables you to visualize this information in the reference frame of the environment.

Create Scenario with Polygon Building Meshes

A uavScenario object is model consisting of a set of static obstacles and movable objects called platforms. Use uavPlatform objects to model fixed-wing UAVs, multirotors, and other objects within the scenario. This example builds a scenario consisting of a ground plane and 11 buildings as by extruded polygons. The polygon data for the buildings is loaded and used to add polygon meshes.

% Create the UAV scenario.
scene = uavScenario("UpdateRate",2,"ReferenceLocation",[75 -46 0]);

% Add a ground plane.
color.Gray = 0.651*ones(1,3);
color.Green = [0.3922 0.8314 0.0745];
color.Red = [1 0 0];
addMesh(scene,"polygon",{[-250 -150; 200 -150; 200 180; -250 180],[-4 0]},color.Gray)

% Load building polygons.
load("buildingData.mat");

% Add sets of polygons as extruded meshes with varying heights from 10-30.
addMesh(scene,"polygon",{buildingData{1}(1:4,:),[0 30]},color.Green)
addMesh(scene,"polygon",{buildingData{2}(2:5,:),[0 30]},color.Green)
addMesh(scene,"polygon",{buildingData{3}(2:10,:),[0 30]},color.Green)
addMesh(scene,"polygon",{buildingData{4}(2:9,:),[0 30]},color.Green)
addMesh(scene,"polygon",{buildingData{5}(1:end-1,:),[0 30]},color.Green)
addMesh(scene,"polygon",{buildingData{6}(1:end-1,:),[0 15]},color.Green)
addMesh(scene,"polygon",{buildingData{7}(1:end-1,:),[0 30]},color.Green)
addMesh(scene,"polygon",{buildingData{8}(2:end-1,:),[0 10]},color.Green)
addMesh(scene,"polygon",{buildingData{9}(1:end-1,:),[0 15]},color.Green)
addMesh(scene,"polygon",{buildingData{10}(1:end-1,:),[0 30]},color.Green)
addMesh(scene,"polygon",{buildingData{11}(1:end-2,:),[0 30]},color.Green)

% Show the scenario.
show3D(scene);
xlim([-250 200])
ylim([-150 180])
zlim([0 50])

Define UAV Platform and Mount Sensor

You can define a uavPlatform in the scenario as a carrier of your sensor models and drive them through the scenario to collect simulated sensor data. You can associate the platform with various meshes, such as fixedwing, quadrotor, and cuboid meshes. You can define a custom mesh defined ones represented by vertices and faces. Specify the reference frame for describing the motion of your platform.

Load flight data into the workspace and create a quadrotor platform using an NED reference frame. Specify the initial position and orientation based on loaded flight log data. The configuration of the UAV body frame orients the x-axis as forward-positive, the y-axis as right-positive, and the z-axis downward-positive.

load("flightData.mat")

% Set up platform
plat = uavPlatform("UAV",scene,"ReferenceFrame","NED", ...
    "InitialPosition",position(:,:,1),"InitialOrientation",eul2quat(orientation(:,:,1)));

% Set up platform mesh. Add a rotation to orient the mesh to the UAV body frame.
updateMesh(plat,"quadrotor",{10},color.Red,[0 0 0],eul2quat([0 0 pi]))

You can choose to mount different sensors, such as the insSensor, gpsSensor, or uavLidarPointCloudGenerator System objects to your UAV. Mount a lidar point cloud generator and a uavSensor object that contains the lidar sensor model. Specify a mounting location of the sensor that is relative to the UAV body frame.

lidarmodel = uavLidarPointCloudGenerator("AzimuthResolution",0.3324099,...
    "ElevationLimits",[-20 20],"ElevationResolution",1.25,...
    "MaxRange",90,"UpdateRate",2,"HasOrganizedOutput",true);

lidar = uavSensor("Lidar",plat,lidarmodel,"MountingLocation",[0,0,-1]);

Fly the UAV Platform Along Pre-defined Trajectory and Collect Point Cloud Sensor Readings

Move the UAV along a pre-defined trajectory, and collect the lidar sensor readings along the way. This data could be used to test lidar-based mapping and localization algorithms.

Preallocate the traj and scatterPlot line plots and then specify the plot-specific data sources. During the simulation of the uavScenario, use the provided plotFrames output from the scene as the parent axes to visualize your sensor data in the correct coordinate frames.

% Visualize the scene
[ax,plotFrames] = show3D(scene); 

% Update plot view for better visibility.
xlim([-250 200])
ylim([-150 180])
zlim([0 50])
view([-110 30])
axis equal
hold on

% Create a line plot for the trajectory.
traj = plot3(nan,nan,nan,"Color",[1 1 1],"LineWidth",2);
traj.XDataSource = "position(:,1,1:idx+1)";
traj.YDataSource = "position(:,2,1:idx+1)";
traj.ZDataSource = "position(:,3,1:idx+1)";

% Create a scatter plot for the  point cloud.
colormap("jet")
pt = pointCloud(nan(1,1,3));
scatterplot = scatter3(nan,nan,nan,1,[0.3020 0.7451 0.9333],...
    "Parent",plotFrames.UAV.Lidar);
scatterplot.XDataSource = "reshape(pt.Location(:,:,1),[],1)";
scatterplot.YDataSource = "reshape(pt.Location(:,:,2),[],1)";
scatterplot.ZDataSource = "reshape(pt.Location(:,:,3),[],1)";
scatterplot.CDataSource = "reshape(pt.Location(:,:,3),[],1) - min(reshape(pt.Location(:,:,3),[],1))";

% Start Simulation
setup(scene)
for idx = 0:size(position, 3)-1
    [isupdated,lidarSampleTime, pt] = read(lidar);
    if isupdated
        % Use fast update to move platform visualization frames.
        show3D(scene,"Time",lidarSampleTime,"FastUpdate",true,"Parent",ax);
        % Refresh all plot data and visualize.
        refreshdata
        drawnow limitrate
    end
    % Advance scene simulation time and move platform.
    advance(scene);
    move(plat,[position(:,:,idx+1),zeros(1,6),eul2quat(orientation(:,:,idx+1)),zeros(1,3)])
    % Update all sensors in the scene.
    updateSensors(scene)
end
hold off

Introduced in R2020b