Main Content

geoshape

Geographic shape vector

expand all in page

Description

A geoshape vector is an object that represents geographic vector features with either point, line, or polygon topology. The features consist of latitude and longitude coordinates and associated attributes.

Attributes that vary spatially are termed Vertex properties. These elements of the geoshape vector are coupled such that the length of the latitude and longitude coordinate property values are always equal in length to any additional dynamic Vertex properties.

Attributes that only pertain to the overall feature (point, line, polygon) are termed Feature properties. Feature properties are not linked to the autosizing mechanism of the Vertex properties. Both property types can be added to a geoshape vector during construction or by using standard dot (.) notation after construction.

To create a geographic point, line, or polygon shape for use with a geospatial table, create a geopointshape, geolineshape, or geopolyshape object instead.

Creation

Syntax

s = geoshape()
s = geoshape(latitude,longitude)
s = geoshape(latitude,longitude,Name,Value)
s = geoshape(structArray)
s = geoshape(latitude,longitude,structArray)

Description

example

s = geoshape() constructs an empty geoshape vector, s, with these default property settings.

s = 

 0x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
     Latitude: []
    Longitude: []

s is always a column vector.

example

s = geoshape(latitude,longitude) sets the Latitude and Longitude properties of geoshape vector s.

example

s = geoshape(latitude,longitude,Name,Value) sets the Latitude and Longitude properties, then adds dynamic properties to the geoshape vector using Name,Value argument pairs. You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

example

s = geoshape(structArray) constructs a geoshape vector from the fields of the structure array, structArray.

  • If structArray contains the field Lat, and does not contain the field Latitude, then the Latitude property values are set equal to the Lat field values. Similar behavior occurs when structArray contains the field Lon and does not contain the field Longitude.

  • If structArray contains both Lat and Latitude fields, then the Latitude property values are set equal to the Latitude field values. Also, a Lat dynamic property is created and its values are set equal to the Lat field values. Similar behavior occurs for Lon and Longitude fields when both are present in structArray.

  • Other structArray fields are assigned to s and become dynamic properties. Field values in structArray that are not numeric values, string scalars, string arrays, character vectors, logical, or cell arrays of numeric values, logical, or character vectors are ignored. You can specify vectors within cell arrays as either row or column vectors.

example

s = geoshape(latitude,longitude,structArray) sets the Latitude and Longitude properties, and sets dynamic properties from the field values of structArray.

  • If structArray contains the fields Lat, Latitude, Lon or Longitude, then those field values are ignored since the latitude and longitude input vectors set the Latitude and Longitude property values.

Properties

expand all

The geoshape class is a general class that represents various geographic features. This class permits features to have more than one vertex and can thus represent lines and polygons in addition to multipoints. For more about the property types in geoshape, see Collection Properties, Vertex Properties, and Feature Properties.

Dynamic properties are new features and vertices that are added to a geoshape vector. You can attach dynamic properties to a geoshape vector during construction using a Name,Value argument, or after construction using dot (.) notation. This is similar to adding new fields to a structure. For an example of adding dynamic Feature properties, see Construct a Geoshape Vector with Dynamic Properties.

Shape of every feature in the geoshape vector, specified as 'line', 'point', or 'polygon'. Geometry is a Collection property so there can be only one value per object instance and its purpose is purely informational. The three allowable values for Geometry do not change class behavior. The class does not validate line or polygon topologies.

Data Types: char | string

Latitude coordinates, specified as a numeric row or column vector. Latitude is stored as a row vector. Latitude is a Vertex property.

Data Types: double | single

Longitude coordinates, specified as a row or column vector. Longitude is stored as a row vector. Longitude is a Vertex property.

Data Types: double | single

Information for every feature, specified as a scalar structure. You can add any data type to the structure. Metadata is a Collection property, so only one instance per object is allowed.

  • If 'Metadata' is provided as a dynamic property name in the constructor, and the corresponding value is a scalar structure, then the Value is copied to the Metadata property. Otherwise, an error is issued.

  • If a Metadata field is provided by structArray, and both Metadata and structArray are scalar structures, then the Metadata field value is copied to the Metadata property value. If structArray is a scalar but the Metadata field is not a structure, then an error is issued. If structArray is not scalar, then the Metadata field is ignored.

Data Types: struct

Object Functions

append Append features to geographic or planar vector
catConcatenate geographic or planar vector
dispDisplay geographic or planar vector
fieldnamesReturn dynamic property names of geographic or planar vector
isemptyDetermine if geographic or planar vector is empty
isfieldDetermine if dynamic property exists in geographic or planar vector
ispropDetermine if property exists in geographic or planar vector
length Return number of elements in geographic or planar vector
propertiesReturn property names of geographic or planar vector
rmfieldRemove dynamic property from geographic or planar vector
rmpropRemove property from geographic or planar vector
sizeReturn size of geographic or planar vector
struct Convert geographic or planar vector to scalar structure
vertcatVertically concatenate geographic or planar vectors

Examples

collapse all

Open Live Script

Construct an empty geoshape vector.

s = geoshape()
s = 

 0x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
     Latitude: []
    Longitude: []

Set the Latitude and Longitude property values using dot notation.

s.Latitude = 0:45:90;
s.Longitude = [10 10 10];

Display the updated geoshape vector.

s
s = 
 1x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
     Latitude: [0 45 90]
    Longitude: [10 10 10]
Open Live Script

Create a geoshape vector specifying latitude and longitude values as input arguments.

s = geoshape([42 43 45],[10 11 15])
s = 
 1x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
     Latitude: [42 43 45]
    Longitude: [10 11 15]
Open Live Script

Create a geoshape vector using a Name-Value pair to define a new Feature property. This example defines a property called 'Temperature' and assigns it the value 89.

point = geoshape(42, -72, 'Temperature', 89)
point = 
 1x1 geoshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
       Latitude: 42
      Longitude: -72
 Feature properties:
    Temperature: 89

To add dynamic properties to a geoshape vector after it has been constructed, use standard dot notation. Add a dynamic property called 'TemperatureUnits' with the value 'Fahrenheit'.

point.TemperatureUnits = 'Fahrenheit'
point = 
 1x1 geoshape vector with properties:

 Collection properties:
            Geometry: 'line'
            Metadata: [1x1 struct]
 Vertex properties:
            Latitude: 42
           Longitude: -72
 Feature properties:
         Temperature: 89
    TemperatureUnits: 'Fahrenheit'

To modify properties, use standard dot notation. Update the temperature, and change 'Geometry' to 'point'.

point.Temperature = 86;
point.Geometry = 'point'
point = 
 1x1 geoshape vector with properties:

 Collection properties:
            Geometry: 'point'
            Metadata: [1x1 struct]
 Vertex properties:
            Latitude: 42
           Longitude: -72
 Feature properties:
         Temperature: 86
    TemperatureUnits: 'Fahrenheit'
Open Live Script

This example highlights the two ways by which a geoshape vector with the same features can be created. The first way uses a structure array in the constructor for a geoshape vector. The second way adds fields of the structure array to a geoshape vector after construction.

First, read data into a structure array. The array in this example contains 128 elements. Each element defines a river as a line using multiple location vertices.

structArray = shaperead('worldrivers.shp', 'UseGeoCoords', true);

Display the first element in structArray. Note that the Lat and Lon vectors are terminated with a NaN delimiter, which separates the Vertex feature data in the geoshape class.

structArray(1)
ans = struct with fields:
       Geometry: 'Line'
    BoundingBox: [2x2 double]
            Lon: [126.7796 126.5321 126.3121 126.2383 126.0362 NaN]
            Lat: [73.4571 73.0669 72.8343 72.6010 72.2894 NaN]
           Name: 'Lena'

Method 1: Provide the structure as an argument to the constructor that builds the geoshape vector.

Create a geoshape vector, providing the structure array as an argument to the constructor.

shape1 = geoshape(structArray)
shape1 = 
 128x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
  (128 features concatenated with 127 delimiters)
     Latitude: [73.4571 73.0669 72.8343 72.6010 72.2894 NaN NaN 72.2894 ... ]
    Longitude: [126.7796 126.5321 126.3121 126.2383 126.0362 NaN NaN ... ]
 Feature properties:
         Name: {1x128 cell}

Note that the BoundingBox field in structArray does not get assigned to a property in shape1 because the field value is not a supported type.

Method 2: Add features to a geoshape vector after construction.

Create an empty geoshape vector.

shape2 = geoshape;

Add the Vertex properties Latitude and Longitude from each entry in the structure array using dot notation. Add a dynamic Feature property, RiverName, the name of the river from each entry in structArray. Since the default value of the Geometry Collection property is 'line' there is no need to set it explicitly in this example.

shape2.Latitude  = {structArray.Lat};
shape2.Longitude = {structArray.Lon};
shape2.RiverName = {structArray.Name}
shape2 = 
 128x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
  (128 features concatenated with 127 delimiters)
     Latitude: [73.4571 73.0669 72.8343 72.6010 72.2894 NaN NaN 72.2894 ... ]
    Longitude: [126.7796 126.5321 126.3121 126.2383 126.0362 NaN NaN ... ]
 Feature properties:
    RiverName: {1x128 cell}
Open Live Script

First, read data into a structure array. The array in this example contains 128 elements. Each element defines a river as a line using multiple location vertices.

structArray = shaperead('worldrivers.shp', 'UseGeoCoords', true)
structArray=128×1 struct array with fields:
    Geometry
    BoundingBox
    Lon
    Lat
    Name

Create latitude and longitude vectors. For illustrative purposes, the vectors do not correspond to the elements of structArray.

lat = {[0:10:40], [1:5]};
lon = {[-60:30:60], [0:2:8]};

Construct a geoshape vector using the latitude and longitude vectors and the structure array.

s = geoshape(lat,lon,structArray);

Display the first three elements of s. Features are separated with a NaN delimiter.

s(1:3)
ans = 
 3x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
  (3 features concatenated with 2 delimiters)
     Latitude: [0 10 20 30 40 NaN 1 2 3 4 5 NaN 0]
    Longitude: [-60 -30 0 30 60 NaN 0 2 4 6 8 NaN 0]
 Feature properties:
         Name: {'Lena'  'Lena'  'Mackenzie'}

Observe that geoshape uses the arguments lat and lon to populate the Latitude and Longitude properties, even though structArray provides Lat and Lon field values. Also, since lat and lon have fewer elements than features in structArray, the Latitude and Longitude properties expand in size using a value of 0.

Create a geoshape vector containing a single feature of the locations of world cities.

S = shaperead('worldcities.shp', 'UseGeoCoords', true);
cities = geoshape([S.Lat], [S.Lon], 'Name', {{S.Name}});
cities.Geometry = 'point';

Append Paderborn Germany to the geoshape vector.

lat = 51.715254;
lon = 8.75213;
cities(1).Latitude(end+1) = lat;
cities(1).Longitude(end) = lon;
cities(1).Name{end} = 'Paderborn'
cities = 

 1x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Vertex properties:
     Latitude: [1x319 double]
    Longitude: [1x319 double]
         Name: {1x319 cell}

The length of each vertex property grows by one when Latitude(end+1) is set. The remaining properties are indexed with end.

You can display the last point by constructing a geopoint vector.

paderborn = geopoint(cities.Latitude(end), cities.Longitude(end), ...
   'Name', cities.Name{end})

paderborn = 

 1x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: 51.7153
    Longitude: 8.7521
         Name: 'Paderborn'

Create a geoshape vector with two new features containing the cities in the northern and southern hemispheres. Add a Location dynamic Feature property to distinguish the different classifications.

northern = cities(1).Latitude >= 0;
southern = cities(1).Latitude < 0;
index = {northern; southern};
location = {'Northern Hemisphere', 'Southern Hemisphere'};
hemispheres = geoshape();
for k = 1:length(index)
   hemispheres = append(hemispheres, ...
      cities.Latitude(index{k}), cities.Longitude(index{k}), ...
      'Name', {cities.Name(index{k})}, 'Location', location{k});
end
hemispheres.Geometry = 'point'
hemispheres = 

 2x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Vertex properties:
  (2 features concatenated with 1 delimiter)
     Latitude: [1x320 double]
    Longitude: [1x320 double]
         Name: {1x320 cell}
 Feature properties:
     Location: {'Northern Hemisphere' 'Southern Hemisphere'}

Plot the northern cities in red and the southern cities in blue.

hemispheres.Color = {'red', 'blue'};
figure;worldmap('world')
geoshow('landareas.shp')
for k=1:2
   geoshow(hemispheres(k).Latitude, hemispheres(k).Longitude, ...
      'DisplayType', hemispheres.Geometry, ...
      'MarkerEdgeColor', hemispheres(k).Color)
end

Construct a geoshape vector and sort its dynamic properties.

shape = geoshape(shaperead('tsunamis.shp', 'UseGeoCoords', true));
shape.Geometry = 'point';
shape = shape(:, sort(fieldnames(shape)))
shape = 

 162x1 geoshape vector with properties:

 Collection properties:
       Geometry: 'point'
       Metadata: [1x1 struct]
 Vertex properties:
  (162 features concatenated with 161 delimiters)
       Latitude: [1x323 double]
      Longitude: [1x323 double]
 Feature properties:
          Cause: {1x162 cell}
     Cause_Code: [1x162 double]
        Country: {1x162 cell}
            Day: [1x162 double]
    Desc_Deaths: [1x162 double]
         Eq_Mag: [1x162 double]
           Hour: [1x162 double]
       Iida_Mag: [1x162 double]
      Intensity: [1x162 double]
       Location: {1x162 cell}
     Max_Height: [1x162 double]
         Minute: [1x162 double]
          Month: [1x162 double]
     Num_Deaths: [1x162 double]
         Second: [1x162 double]
       Val_Code: [1x162 double]
       Validity: {1x162 cell}
           Year: [1x162 double

Modify the geoshape vector to contain only the dynamic properties, Year, Month, Day, Hour, Minute.

shape = shape(:, {'Year', 'Month', 'Day', 'Hour', 'Minute'})
shape = 

 162x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Vertex properties:
  (162 features concatenated with 161 delimiters)
     Latitude: [1x323 double]
    Longitude: [1x323 double]
 Feature properties:
         Year: [1x162 double]
        Month: [1x162 double]
          Day: [1x162 double]
         Hour: [1x162 double]
       Minute: [1x162 double]

Display the first five elements.

shape(1:5)
ans = 

 5x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Vertex properties:
  (5 features concatenated with 4 delimiters)
     Latitude: [-3.8000 NaN 19.5000 NaN -9.0200 NaN 42.1500 NaN 19.1000]
    Longitude: [128.3000 NaN -156 NaN 157.9500 NaN 143.8500 NaN -155]
 Feature properties:
         Year: [1950 1951 1951 1952 1952]
        Month: [10 8 12 3 3]
          Day: [8 21 22 4 17]
         Hour: [3 10 NaN 1 3]
       Minute: [23 57 NaN 22 58]
Open Live Script

Read multiple GPS track log data from a file. trk1 and trk2 are geopoint objects.

trk1 = gpxread('sample_tracks.gpx')
trk1 = 
 1851x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [42.2995 42.2995 42.2994 42.2994 42.2994 42.2994 42.2994 ... ]
    Longitude: [-71.3502 -71.3504 -71.3504 -71.3504 -71.3504 -71.3504 ... ]
    Elevation: [90.0206 90.0206 90.0206 90.5013 90.0206 90.0206 90.0206 ... ]
         Time: {1x1851 cell}


trk2 = gpxread('sample_tracks.gpx', 'Index', 2);

To construct a geoshape vector with multiple features, place the coordinates into cell arrays.

lat = {trk1.Latitude, trk2.Latitude};
lon = {trk1.Longitude, trk2.Longitude};

Place the elevation and time values into cell arrays.

elevation = {trk1.Elevation, trk2.Elevation};
time = {trk1.Time, trk2.Time};

Construct a geoshape vector containing two track log features that include Elevation and Time as dynamic Vertex properties.

tracks = geoshape(lat, lon, 'Elevation', elevation, 'Time', time)
tracks = 
 2x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
  (2 features concatenated with 1 delimiter)
     Latitude: [42.2995 42.2995 42.2994 42.2994 42.2994 42.2994 42.2994 ... ]
    Longitude: [-71.3502 -71.3504 -71.3504 -71.3504 -71.3504 -71.3504 ... ]
    Elevation: [90.0206 90.0206 90.0206 90.5013 90.0206 90.0206 90.0206 ... ]
         Time: {1x2591 cell}

Each Latitude and Longitude coordinate pair has associated Elevation and Time values.

To construct a geoshape vector containing a dynamic Feature property, use an array that is the same length as the coordinate cell array. For example, add a MaximumElevation dynamic Feature property.

tracks.MaximumElevation = [max(trk1.Elevation) max(trk2.Elevation)]
tracks = 
 2x1 geoshape vector with properties:

 Collection properties:
            Geometry: 'line'
            Metadata: [1x1 struct]
 Vertex properties:
  (2 features concatenated with 1 delimiter)
            Latitude: [42.2995 42.2995 42.2994 42.2994 42.2994 42.2994 42.2994 ... ]
           Longitude: [-71.3502 -71.3504 -71.3504 -71.3504 -71.3504 -71.3504 ... ]
           Elevation: [90.0206 90.0206 90.0206 90.5013 90.0206 90.0206 90.0206 ... ]
                Time: {1x2591 cell}
 Feature properties:
    MaximumElevation: [92.4240 76.1000]

The Feature property value has only two numeric values, one for each feature.

Open Live Script

Load coastline data from a MAT-file.

load coastlines

Create an n-by-2 array of coastline latitude and longitude values.

pts = [coastlat coastlon];

Create a geoshape object and store the latitude and longitude data. If you store latitude and longitude coordinate values in an n-by-2 array, geoshape assigns the Latitude property values to the first column and the Longitude property values to the second column.

shape = geoshape();
shape(1) =  pts
shape = 
 1x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
     Latitude: [-83.8300 -84.3300 -84.5000 -84.6700 -84.9200 -85.4200 ... ]
    Longitude: [-180 -178 -174 -170 -166.0000 -163 -158 -152 -146 -147 ... ]

Note that Latitude and Longitude are stored are row vectors in the geoshape vector.

Now, create a 2-by-m array of coastline latitude and longitude values. Note the semicolon inside the brackets.

pts2 = [coastlat; coastlon];

Create a geoshape object and store the latitude and longitude data. If you store latitude and longitude coordinate values in a 2-by-m array, geoshape assigns the Latitude property values to the first row and the Longitude property values to the second row.

shape2 = geoshape();
shape2(1) = pts2
shape2 = 
 1x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
     Latitude: [-83.8300 -84.3300 -84.5000 -84.6700 -84.9200 -85.4200 ... ]
    Longitude: [-83.8300 -84.3300 -84.5000 -84.6700 -84.9200 -85.4200 ... ]

More About

expand all

Tips

  • The geoshape function separates features using NaN values. If you display a feature by using a scalar to index into the geoshape vector, such as s(1), then NaN values that separate the features do not display.

  • If Latitude, Longitude, or a dynamic property is set with more values than features in the geoshape vector, then all other properties expand in size using 0 for numeric values and an empty character vector ('') for cell values.

  • If a dynamic property is set with fewer values than the number of features, then this dynamic property expands to match the size of the other properties, by inserting a 0 if the value is numeric or an empty character vector (''), if the value is a cell array.

  • If the Latitude or Longitude property of the geoshape vector is set with fewer values than contained in the object, then all other properties shrink in size.

  • If either Latitude or Longitude are set to [ ], then both coordinate properties are set to [ ] and all dynamic properties are removed.

  • If a dynamic property is set to [ ], then it is removed from the object.

  • The geoshape vector can be indexed like any MATLAB® vector. You can access any element of the vector to obtain a specific feature. The following examples demonstrate this behavior:

    Use Indexing to Append a Single Point and a Shape to a Geoshape Vector

    Use Indexing to Sort and Modify Dynamic Features

    Construct a Geoshape Vector from Multiple Objects

See Also

Functions

Objects

Topics

Introduced in R2012a

Mapping Toolbox Documentation

Support

Try MATLAB, Simulink, and Other Products

Get trial now