table2geotable

Convert table to geospatial table

Since R2021b

Syntax

GT = table2geotable(T)

GT = table2geotable(T,coordinateSystemType,varnames)

GT = table2geotable(___,Name=Value)

Description

GT = table2geotable(T) converts the table or timetable T to a geospatial table GT. The function creates the Shape variable of GT by using the latitude-longitude or x-y coordinates in T. Each variable of T is a variable of GT.

GT = table2geotable(T,coordinateSystemType,varnames) creates the Shape variable of GT by using the coordinate system type coordinateSystemType and table variables varnames. Use this syntax to create the Shape variable from well-known text (WKT) string representations of geometry or from coordinate data.

GT = table2geotable(___,Name=Value) specifies options using name-value arguments. For example, specify that coordinates represent points, lines, or polygons by using the GeometryType name-value argument. Use this syntax with any of the input arguments in the previous syntaxes.

Examples

Convert Table to Geospatial Table

Import data about tsunami events as a table. The latitude and longitude coordinates of the origin points are in the Latitude and Longitude table variables.

T = readtable("tsunamis.xlsx");

Convert the table to a geospatial table. The table2geotable function detects the Latitude and Longitude variables and uses them to create the Shape variable.

GT = table2geotable(T);

View the Shape variable.

GT.Shape

ans = 
  162x1 geopointshape array with properties:

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

Convert Table with WKT Strings to Geospatial Table

Create a sample table. The first table variable (WKTString) contains the WKT string representation of geometry for lines in planar coordinates. The second variable (Name) contains names.

wkt1 = "LINESTRING (210320.1875 913333.8125,210320.140625 913366.6875)";
wkt2 = "LINESTRING (210320.4375 913170.9375,210320.34375 913231.1875)";
name1 = "Line 1";
name2 = "Line 2";
T = table([wkt1;wkt2],[name1;name2],VariableNames={'WKTString','Name'})

T=2×2 table
                               WKTString                                  Name  
    ________________________________________________________________    ________

    "LINESTRING (210320.1875 913333.8125,210320.140625 913366.6875)"    "Line 1"
    "LINESTRING (210320.4375 913170.9375,210320.34375 913231.1875)"     "Line 2"

Convert the table to a geospatial table. Create the Shape variable of the table by using the WKT strings. For this example, specify the projected CRS as World Equidistant Cylindrical, which has the EPSG authority code 4087.

GT = table2geotable(T,"planar","WKTString", ...
    CoordinateReferenceSystem=projcrs(4087))

GT=2×3 table
       Shape                                   WKTString                                  Name  
    ____________    ________________________________________________________________    ________

    maplineshape    "LINESTRING (210320.1875 913333.8125,210320.140625 913366.6875)"    "Line 1"
    maplineshape    "LINESTRING (210320.4375 913170.9375,210320.34375 913231.1875)"     "Line 2"

View the Shape variable of the geospatial table.

GT.Shape

ans=2×1 maplineshape array with properties:
                NumParts: [2x1 double]
                Geometry: "line"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1x1 projcrs]

Input Arguments

T — Input table

table object | timetable object

Input table, specified as a table or timetable object.

The table2geotable function detects the coordinates when the table variables have these names, ignoring case.

• Latitude coordinates — Latitude or Lat

• Longitude coordinates — Longitude, Lon, or Long

• x-coordinates — X

• y-coordinates — Y

If you specify an input table with a variable called Shape, then the table2geotable function overwrites it.

Data Types: table

coordinateSystemType — Coordinate system type

"planar" | "geographic"

Coordinate system type, specified as one of these options:

• "planar" — Coordinates are in a planar coordinate system.

• "geographic" — Coordinates are in a geographic coordinate system.

Data Types: string

varnames — Names of table variables

string scalar | two-element string vector

Names of the table variables used to create the Shape variable of the geospatial table, specified as a string scalar or two-element string vector.

• Create the Shape variable from one table variable that contains WKT string representations of geometry by specifying varnames as a string scalar, such as "WKT"

• Create the Shape variable from two table variables that contain latitude-longitude or x-y coordinates by specifying varnames as a two-element string vector, such as ["Lats" "Lons"].

Data Types: 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: table2geotable(T,CoordinateReferenceSystem=geocrs(4326)) specifies the geographic CRS as the World Geodetic System of 1984, which has EPSG code 4326.

CoordinateReferenceSystem — Coordinate reference system

projcrs object | geocrs object

Coordinate reference system (CRS) to use when creating the Shape variable of the geospatial table, specified as a projcrs or geocrs object.

Specify a projcrs object when coordinateSystemType is "planar" and specify a geocrs object when coordinateSystemType is "geographic".

GeometryType — Geometry type

"point" (default) | "line" | "polygon"

Geometry type of the coordinate variables, specified as one of these options:

• "point" — The coordinate fields represent points.

• "line" — The coordinate fields represent lines.

• "polygon" — The coordinate fields represent polygons.

When you specify the geometry type as "polygon", the table2geotable function assumes that the coordinates define polygons with a valid topology. A polygon has a valid topology when:

• Region interiors are to the right as you trace boundaries from vertex to vertex.

• The boundaries have no self-intersections.

In general, the outer boundaries of polygons with a valid topology have vertices in a clockwise order and the interior holes have vertices in a counterclockwise order.

If you specify varnames as a table variable containing WKT string representations of geometry, then the table2geotable function ignores this argument.

Output Arguments

GT — Output geospatial table

geospatial table

Output geospatial table. A geospatial table is a table or timetable object with a Shape variable that contains geopointshape, geolineshape, geopolyshape, mappointshape, maplineshape, or mappolyshape objects.

For an input table of size M-by-N, the size of GT is M-by-(N + 1).

Tips

• When the input table has latitude-longitude fields and x-y variables, the table2geotable function creates the geospatial table using the latitude-longitude variables. Create the geospatial table using the x-y variables by specifying the coordinateSystemType and varnames arguments.

Version History

Introduced in R2021b