readgeotable

Read geospatial table from vector data file

Since R2021b

Syntax

T = readgeotable(filename)

T = readgeotable(filename,Name=Value)

Description

T = readgeotable(filename) creates a geospatial table by reading geographic or projected vector data from a file. Supported file formats include shapefile, KML, and Esri file geodatabase. For a full list of supported formats, see Supported Formats and Extensions.

T = readgeotable(filename,Name=Value) specifies options using name-value arguments. For example, specify the coordinate system type using the CoordinateSystemType name-value argument.

Examples

Read Shapefile as Geospatial Table

Read a shapefile, containing a network of roads in Concord, MA, into the workspace as a geospatial table.

T = readgeotable("concord_roads.shp");

The Shape variable of the table contains information about the road shapes, including the coordinate reference system (CRS). The road shapes in this shapefile use a projected CRS.

T.Shape.ProjectedCRS

ans = 
  projcrs with properties:

                    Name: "NAD83 / Massachusetts Mainland"
           GeographicCRS: [1x1 geocrs]
        ProjectionMethod: "Lambert Conic Conformal (2SP)"
              LengthUnit: "meter"
    ProjectionParameters: [1x1 map.crs.ProjectionParameters]

Display the roads on a map.

mapshow(T)
xlabel("x (meters)")
ylabel("y (meters)")

Read Shapefile with No Projection File

An optional projection file (.prj) determines the coordinate system type for a shapefile. When your shapefile does not have a projection file, but you know the coordinate system type, you can specify it by using the CoordinateSystemType name-value argument.

Read a shapefile called tsunamis.shp, containing information about tsunami events, into the workspace. The metadata accompanying the file indicates that the shapefile uses geographic coordinates.

T = readgeotable("tsunamis.shp",CoordinateSystemType="geographic");

View the Shape variable of the geospatial table. The tsunami source locations are stored as points.

T.Shape

ans = 
  162×1 geopointshape array with properties:

               NumPoints: [162×1 double]
                Latitude: [162×1 double]
               Longitude: [162×1 double]
                Geometry: "point"
    CoordinateSystemType: "geographic"
           GeographicCRS: []

Plot the source locations on a web map.

wmmarker(T)

Read Layers from GPX Files

GPX files can contain up to five layers: waypoints, tracks, track points, routes, and route points. When you read a layer containing track points or route points, the geospatial table contains an ID variable that associates the points with a track or route.

Import the tracks layer of a GPX file with two tracks. The Shape variable for each track is a geolineshape object.

T = readgeotable("sample_tracks.gpx",Layer="tracks")

T=2×3 table
       Shape                                                  Name                                               Number
    ____________    _________________________________________________________________________________________    ______

    geolineshape    "Track logs from walking the perimeter of the MathWorks campus in Natick on May 21, 2007"      1   
    geolineshape    "Track logs from biking from Concord to the MathWorks campus in Natick on June 30, 2011"       2   

View the shape of each track. The first track has one segment and the second track has five segments.

T.Shape(1)

ans = 
  geolineshape with properties:

                NumParts: 1
                Geometry: "line"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

T.Shape(2)

ans = 
  geolineshape with properties:

                NumParts: 5
                Geometry: "line"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Import the track points layer. The Shape variable for each point is a geopointshape object.

T2 = readgeotable("sample_tracks.gpx",Layer="track_points");
T2.Shape

ans = 
  2586×1 geopointshape array with properties:

               NumPoints: [2586×1 double]
                Latitude: [2586×1 double]
               Longitude: [2586×1 double]
                Geometry: "point"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Create a subtable that contains points in the second track only. For this file, points in the second track have a TrackFID value of 1.

rows = (T2.TrackFID == 1);
T3 = T2(rows,:);

Plot the points in the subtable as a blue line.

wmline(T3,Color="b")

Read GeoJSON File from Web Service

Read GeoJSON data from a website and save it in the file storms.geojson. The data contains day 1 convective outlooks from the NOAA/NWS Storm Prediction Center. For more information about convective outlooks, see [1]. For links to the data, see [2].

websave("storms.geojson","https://www.spc.noaa.gov/products/outlook/day1otlk_cat.lyr.geojson");

Read the data into a geospatial table. If the file contains no data for the readgeotable function to read, such as when there are no severe thunderstorm threats, create a geospatial table with an empty polygon shape instead.

try
    GT = readgeotable("storms.geojson");
catch
    GT = table(geopolyshape,"No Data","none",VariableNames=["Shape" "LABEL2" "fill"]);
end

View the Shape variable of the geospatial table. The table stores the geographic areas as polygons.

GT.Shape

ans=3×1 object
  3×1 geopolyshape array with properties:

              NumRegions: [3×1 double]
                NumHoles: [3×1 double]
                Geometry: "polygon"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Day 1 convective outlooks change from day to day, so your results can be different.

Display the convective outlooks over a satellite basemap. To create a legend from the thunderstorm risk categories, plot each row of the table as a separate polygon.

figure
geobasemap satellite
hold on
for k = 1:height(GT)
    row = GT(k,:);
    geoplot(row,"DisplayName",row.LABEL2,"FaceColor",row.fill)
end
legend
alpha(0.6)

Add a title, including the access date.

dt = datetime("today",Format="MMMM d, yyyy");
title("Day 1 Convective Outlooks",string(dt))

[1] "SPC Products." NOAA/National Weather Service Storm Prediction Center. Accessed June 28, 2022. https://www.spc.noaa.gov/misc/about.html.

[2] "SPC Shapefile/KML/KMZ Links." NOAA/National Weather Service Storm Prediction Center. Accessed June 28, 2022. https://www.spc.noaa.gov/gis/.

Input Arguments

filename — Name of file to read

character vector | string scalar

Name of the file to read, specified as a character vector or string scalar. The form of filename depends on the location of your file.

• If the file is in your current folder or in a folder on the MATLAB^® path, then specify the name of the file, such as "myFile.shp".

• If the file is not in the current folder or in a folder on the MATLAB path, then specify the full or relative path name, such as "C:\myfolder\myFile.gpx" or "dataDir\myFile.kml".

For a list of supported file formats, see Supported Formats and Extensions.

To read an Esri file geodatabase, you must either specify the full or relative path name or include the geodatabase in your current folder.

Data Types: char | string

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.

Example: readgeotable("sample_tracks.gpx",Layer="track_points") reads the track points layer from the GPX file.

Layer — Layer to read

positive integer | string scalar | character vector

Layer to read when the file contains multiple layers, specified as a positive integer, a string scalar, or a character vector. If you specify an integer, then it must be less than or equal to the number of vector layers in the file.

The layers contained in a file depend on the file format. Shapefiles have one layer. The content of Esri file geodatabases and GeoJSON files determines the number of layers and the names of the layers. Each folder and subfolder of KML files corresponds to layers, and the folder names match the layer names.

For GPX files, specify the layer as one of these options:

• "waypoints" — Waypoints.

• "tracks" — Track lines.

• "track_points" — Track points. When you read track points, the geospatial table contains an ID variable, TrackFID, that associates each point with a track.

• "routes" — Route lines.

• "route_points" — Route points. When you read route points, the geospatial table contains an ID variable, RouteFID, that associates each point with a route.

Data Types: single | double | char | string

CoordinateSystemType — Coordinate system type

"auto" (default) | "geographic" | "planar"

Coordinate system type, specified as one of these values:

• "auto" — Create the Shape table variable based on the contents of the file.

• "geographic" — Create the Shape table variable using geopointshape, geolineshape, and geopolyshape objects.

• "planar" — Create the Shape table variable using mappointshape, maplineshape, and mappolyshape objects.

Specify the coordinate system type when the readgeotable function is unable to detect the coordinate system type.

For shapefiles, the coordinate system type is determined by an optional projection file (.prj). If your shapefile does not have a projection file, you can try to determine the coordinate system type using one of these options:

• Refer to the metadata.

• Ask your data provider.

• Return information about the shapefile as a structure by using the shapeinfo function. Then, view the limits of the data by querying the BoundingBox field of the structure. The limits might help you predict the coordinate system type.

VariableNamingRule — Flag to preserve variable names

"preserve" (default) | "modify"

Flag to preserve variable names, specified as one of these options:

• "preserve" — Preserve variable names that are not valid MATLAB identifiers, such as variable names that include spaces and non-ASCII characters.

• "modify" — Convert invalid variable names, as identified by the isvarname function, to valid MATLAB identifiers.

Data Types: char | string

Output Arguments

T — Geospatial table

geospatial table

Geospatial table, returned as a geospatial table. A geospatial table is a table object with a Shape variable and attribute variables.

• The Shape variable contains 2-D information about point, line, and polygon shapes. The Shape variable can contain combinations of shape types. All the shapes have the same coordinate reference system (CRS).

  The readgeotable function represents shapes with coordinates in geographic CRSs by using geopointshape, geolineshape, and geopolyshape objects.

  The readgeotable function represents shapes with coordinates in projected CRSs by using mappointshape, maplineshape, and mappolyshape objects.

• The attribute variables contain data such as names, classifications, and measurements.

When the data file contains CRS information, the readgeotable function stores the information as a projcrs or geocrs object within each shape object.

More About

Supported Formats and Extensions

The readgeotable function supports these file formats and extensions.

File Format	Extension
Esri file geodatabase	.gdb
GeoJSON	.json or .geojson
GPX	.gpx
KML	.kml
Shapefile	.shp

Some file formats consist of a main file and multiple supporting files. For example, shapefiles include a main file (.shp), an index file (.shx), and an attribute file (.dbf). When you read a data file with supporting files using the readgeotable function, specify the extension of the main file.

When the file contains 3-D points, lines, or polygons, the function reads only the 2-D information into the Shape variable of the geospatial table.

For GeoJSON files, all attributes apply to all rows in the geospatial table, even when the GeoJSON file does not apply an attribute to all elements. When the file does not apply an attribute to an element, the corresponding cell in the geospatial table contains a missing data value.

For GPX files, Garmin® extensions are not supported.

For KML files, the readgeotable function reads only shapes, names, and descriptions into the geospatial table.

Version History

Introduced in R2021b