Main Content

addMesh

Add new static mesh to UAV scenario

Since R2020b

    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.

    example

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

    example

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

    example

    Examples

    collapse all

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

    Figure contains an axes object. The axes object with xlabel East (m), ylabel North (m) contains 2 objects of type patch.

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

    Figure contains an axes object. The axes object contains an object of type patch.

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

    Figure contains an axes object. The axes object contains 658 objects of type patch.

    [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/.

    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";

    Figure contains an axes object. The axes object with xlabel East (m), ylabel North (m) contains an object of type patch.

    Input Arguments

    collapse all

    UAV scenario, specified as a uavScenario object.

    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

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

    type Input ArgumentGeometry ParametersDescription
    "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.

    • xBoundx-axis boundaries of the imported OSM buildings, specified as a two-element row vector in meters.

    • yBoundy-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.

    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)

    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.

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

    collapse all

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

    File TypeFields
    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

    expand all