addMesh

Add new static mesh to UAV scenario

Syntax

addMesh(scene,type,geometry,color)

addMesh(___,Name=Value)

info = addMesh(___,Verbose=true)

Description

addMesh(scene,type,geometry,color) adds a static mesh, or imports meshes from an OSM file, to the UAV scenario scene by specifying the mesh type, geometry, and color.

addMesh(___,Name=Value) specifies additional options using name-value arguments.

info = addMesh(___,Verbose=true) returns information, when importing OSM or terrain files, about the file import.

Examples

Add Meshes to UAV Scenario

Create a UAV Scenario.

scene = uavScenario("UpdateRate",100,"StopTime",1);  

Add the ground and a building as meshes.

addMesh(scene,"Polygon", {[-50 0; 50 0; 50 50; -50 50], [-3 0]}, [0.3 0.3 0.3]);
addMesh(scene,"Cylinder", {[10 5 5], [0 10]}, [0 1 1]); 

Visualize the scenario.

show3D(scene);

Import OSM Building Meshes and Terrain Mesh into UAV Scenario

Create a UAV scenario centered on New York City, and add a terrain mesh based on the Global Multi-Resolution Terrain Elevation Data (GMTED2010) data set.

scene = uavScenario(ReferenceLocation=[40.707088 -74.012146 0]);
xlimits = [-1000 1000];
ylimits = [-1000 1000];
color = [0.6 0.6 0.6];
terrainInfo = addMesh(scene,"terrain",{"gmted2010",xlimits,ylimits},color,Verbose=true)

terrainInfo = struct with fields:
       TerrainName: "gmted2010"
     LatitudeRange: [-90 90]
    LongitudeRange: [-180 180]

show3D(scene);

Add buildings by importing them from an OSM file that contains the buildings of Manhattan, manhattan.osm.[1]

xlimits = [-800 800];
ylimits = [-800 800];
color = [0 1 0];
osmInfo = addMesh(scene,"buildings",{"manhattan.osm",xlimits,ylimits,"auto"},color,Verbose=true)

osmInfo = struct with fields:
             OSMFileName: "/mathworks/devel/sbs/25/rprasad.Bdoc23a.j2033780.Aug12/matlab/toolbox/shared/openstreetmapdata/manhattan.osm"
           LatitudeRange: [40.7010 40.7182]
          LongitudeRange: [-74.0188 -74.0003]
       TotalNumBuildings: 836
    NumImportedBuildings: 657

show3D(scene);

[1] The file was downloaded from https://www.openstreetmap.org, which provides access to crowd-sourced map data all over the world. The data is licensed under the Open Data Commons Open Database License (ODbL), https://opendatacommons.org/licenses/odbl/.

Add Static Mesh from STL File

Create a default UAV scenario.

scene = uavScenario;

Create a triangulation object from STL file.

stltri = stlread("multirotor.stl");

Add a static mesh to the scenario, using the triangulation object as the input.

addMesh(scene,"custom",{stltri.Points stltri.ConnectivityList},[0.6350 0.0780 0.1840])

Show the scene.

ax = show3D(scene);
p = findobj(ax,"type","patch");
p.LineStyle = "none";

Input Arguments

scene — UAV scenario

uavScenario object

UAV scenario, specified as a uavScenario object.

type — Mesh type

"cylinder" | "surface" | "terrain" | "polygon" | "buildings" | "unreal scene" | "custom"

Mesh type, specified as "cylinder", "surface", "terrain", "polygon", "buildings", "unreal scene", or "custom". Specify the geometric parameters of the mesh using the geometry input.

Data Types: string | char

geometry — Mesh geometry

cell array

Mesh geometry, specified as a cell array of geometry parameters. Depending on the type input, the geometry parameters have different forms:

type Input Argument	Geometry Parameters	Description
"cylinder"	{[centerx centery radius],[zmin zmax]}	centerx and centery are the x- and y-coordinates of the center of the cylinder, respectively. radius is the radius of the cylinder in meters. zmin and zmax are the minimum and maximum z-axis coordinates of the cylinder in meters, respectively.
"surface"	{meshGridX,meshGridY,z}	meshGridX, meshGridY and z are all 2-D matrices of the same size that define the xyz-points of the surface mesh.
"terrain"	{terrainName,XLimits,YLimits}	You must first call the addCustomTerrain function to load the terrain data and specify a terrain name. Specify the minimum and maximum xy-limits as two separate two-element vectors in local coordinates, or latitude-longitude coordinates if the 'UseLatLon' name-value pair is true. The xy-coordinates must be specified in the ENU reference frame.
"polygon"	{cornerPoints,[zmin zmax]}	zmin and zmax are the minimum and maximum z-axis coordinates of the polygon in meters, respectively. cornerPoints contains the corner points of the polygon, specified as a N-by-2 matrix, where N is the number of corner points. The first column contains the x-coordinates and the second column contains the y-coordinates in meters.
"buildings"	{osmFile,xBound,yBound,altitude}	osmFile — File name of the OSM file in the current folder or on the MATLAB path, or the full or relative path to the OSM file, specified as a character vector or string scalar. xBound — x-axis boundaries of the imported OSM buildings, specified as a two-element row vector in meters. yBound — y-axis boundaries of the imported OSM buildings, specified as a two-element row vector in meters. altitude — Height of the bases for all imported buildings, specified as a scalar or "auto". If specified as "auto", the base heights of the buildings are defined by the height of the terrain in the scene. If the scene has no terrain, this value is 0.
"unreal scene"	{sceneName,[centerX centerY centerZ],sceneYaw}	sceneName — Name of the Unreal Engine scene that you want to import into the scenario as a mesh. Specify as "urban" to use the US City Block scene, or "suburban" to use the Suburban scene. centerX, centerY, and centerZ are the x-, y-, and z-coordinates, respectively, of the center of the imported scene in meters. If UseLatLon is true, specify the coordinates as latitude, longitude, and altitude. sceneYaw — Rotation angle of the imported scene in radians. A positive value corresponds to a clockwise rotation when looking in the positive z-direction (up) .
"custom"	{vertices,faces}	vertices is an n-by-3 matrix of mesh points in local coordinates. faces is an n-by-3 integer matrix of indexes indicating the triangular faces of the mesh.

color — Mesh color

RGB triplet

Mesh color, specified as a RGB triplet.

Example: [1 0 0]

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: addMesh(scene,"Cylinder",{[46 42 5],[0 20]},[0 1 0],UseLatLon=true)

UseLatLon — Enable latitude and longitude coordinates

false (default) | true

Enable latitude and longitude coordinates, specified as true or false.

• When specified as true, the x, y, and z coordinates in the geometry input are interpreted as latitude, longitude, and altitude, respectively. Vertices for custom mesh use east-north-up (ENU) as the reference frame.

• When specified as false, the x, y, and z coordinates in the geometry input are interpreted as Cartesian coordinates.

ReferenceFrame — Reference frame of geometry input

"ENU" (default) | name of defined inertial frame

Reference frame of the geometry input, specified as an inertial frame name defined in the InertialFrames property of the uavScenario object scene. You can add new inertial frames to the scenario using the addInertialFrame object function.

The scenario only accepts frames that have z-axis rotation with respect to the "ENU" frame.

For terrain, building, and Unreal scene import, the reference frame must be "ENU".

Verbose — Verbose mode for OSM building or terrain file imports

false or 0 (default) | true or 1

Verbose mode for OSM building or terrain file imports, specified as a logical true (1) or false (0). When you specify this argument as true, addMesh returns information about the file and import process. The information returned depends on the type of file.

If you specify an output argument, verbose mode returns the import information as a structure, info. Otherwise, verbose mode prints the import information in the Command Window.

Output Arguments

info — File import information

structure

File import information, returned as a structure. The fields contained depend on the type of file:

File Type	Fields
OSM Building	OSMFileName — OSM file name as a string scalar LatitudeRange — Latitude range as a two-element row vector LongitudeRange — Longitude range as a two-element row vector TotalNumBuildings — Total number of buildings in the OSM file as an integer NumImportedBuildings — Number of buildings imported from the OSM file as an integer
Terrain	TerrainName — Terrain file name as a string scalar LatitudeRange — Latitude range as a two-element row vector LongitudeRange — Longitude range as a two-element row vector

To return this output argument, you must specify the Verbose name-value argument as true.

Tips

• OSM files may load slowly when a high number of buildings are specified in the file. If you experience long load times, consider reducing the number of buildings to load more quickly.

Version History

Introduced in R2020b

R2024b: Import Unreal Engine scene as mesh

The addMesh function now supports importing a Suburban scene or US City Block scene as a mesh into a UAV scenario by specifying the mesh geometry as "unreal scene".