geoshape class

Geographic shape vector

Syntax

s = geoshape()
s = geoshape(lat,lon)
s = geoshape(lat,lon,Name,Value)
s = geoshape(structArray)
s = geoshape(lat,lon,structArray)

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. If these attributes vary spatially they 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 which only pertain to the overall feature (point, line, polygon) are termed Feature properties. Feature properties are not linked to the auto-sizing mechanism of the Vertex properties. Both of the property types can be dynamically added to a geoshape vector using the standard dot notation.

A geoshape vector is always a column vector.

Construction

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

s = 

 0x1 geoshape vector with properties:

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

For an additional example see: Construct a Default geoshape Vector

s = geoshape(lat,lon) constructs a geoshape vector and sets the Latitude and Longitude property values equal to vectors lat and lon. lat and lon may be either numeric vectors of class single or double, or cell arrays containing numeric vectors of class single or double. For an example, see Construct a geoshape vector Specifying Latitude and Longitude Values.

s = geoshape(lat,lon,Name,Value) constructs a geoshape vector from the input lat and lon vectors, and then adds dynamic properties to the geoshape vector using the Name, Value argument pairs.

  • If Value is in a cell array containing numeric, logical or cell array of strings, then this property is designated as a Vertex property. Otherwise, this property is designated as a Feature property.

  • If the specified Name is Metadata and the corresponding Value is a scalar structure, then Value is copied to the Metadata property. Otherwise, an error is issued.

For an example, see: Construct a geoshape Vector Specifying a Name-Value Pair.

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 a field Latitude, then the Latitude property values are set equal to the Lat field values. If structArray contains the field, Lon, and does not contain a field Longitude, then the Longitude property values are set equal to the Lon field values.

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

  • If structArray is a scalar structure which contains the field Metadata and the field value is a scalar structure, then the Metadata field is copied to the Metadata property. If structArray is a scalar structure and the Metadata field is present and is not a scalar structure, then an error is issued. If structArray is not scalar then the Metadata field is ignored.

  • Other fields of structArray are assigned to s and become dynamic properties. Field values in structArray that are not numeric, strings, logical, or cell arrays of numeric, logical, or string values are ignored.

For an example, see Construct a geoshape vector from a Structure Array.

s = geoshape(lat,lon,structArray) constructs a new geoshape vector and sets the Latitude and Longitude properties equal to the numeric vectors, lat and lon, and sets the field values of struct structArray as dynamic properties.

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

  • If structArray is a scalar structure and contains the field Metadata, and the field value is a scalar structure, then it is copied to the Metadata property value. Otherwise, an error is issued if the Metadata field is not a structure, or ignored if structArray is not scalar.

For an example, see Construct a geoshape vector Using Cell Arrays.

Input Arguments

expand all

lat — Vector of latitude coordinatesnumeric array

Vector of latitude coordinates, specified as a numeric array.

Data Types: double | single | cell

lon — Vector of longitude coordinatesnumeric array

Vector of longitude coordinates, specified as a numeric array.

Data Types: double | single | cell

structArray — Dynamic propertiesstructure

Dynamic properties, specified as an array of structures containing fields to be assigned.

Name — Name of dynamic propertystring

Name of dynamic property, specified as a string.

Data Types: char

Value — Value associated with a dynamic property specified in Namenumeric, logical, char, or a cell array of strings

Value associated with a dynamic property specified in Name, specified as numeric, logical, cell array of strings, or a cell array of numeric, logical, or cell array of strings, for Vertex dynamic properties. The class type of the values for the Feature dynamic properties may be either numeric, logical, char, or a cell array of strings.

Output Arguments

s

geoshape vector.

Properties

geoshape class is a general class that represents a variety of geographic features. The class permits features to have more than one vertex and can thus represent lines and polygons in addition to multipoints. The class has the following property types.

Types of PropertiesDescription
Collection PropertiesCollection properties contain only one value per class instance. This is in contrast to the other two property types which can have attribute values associated with each feature or with each vertex in a set that defines a feature. Geometry and Metadata are the only two Collection properties.
Vertex Properties Vertex properties provide a scalar number or a string for each vertex in a geoshape object. Vertex properties are suitable for attributes that vary spatially from point to point (vertex to vertex) along a line. Examples of such spatially varying attributes could be elevation, speed, temperature, or time. Latitude and Longitude are vertex properties since they contain a scalar number for each vertex in a geoshape vector. Attribute values can be dynamically associated with each vertex by using dot notation. This is similar to adding dynamic fields to a structure. The dynamically added vertex property values of an individual feature match its Latitude and Longitude values in length.
Feature Properties Feature properties provide one value (a scalar number or a string) for each feature in a geoshape vector. They are suitable for properties, such as name, owner, serial number, age, etc., that describe a given feature (an element of a geoshape vector) as a whole. Like Vertex properties, Feature properties can be added dynamically.

Geometry

The Geometry property is a string that denotes the shape type for all the features in the geoshape vector. As a Collection Property there is only one value per object instance. Its purpose is purely informational; the three allowable string values for Geometry do not change class behavior. Additionally, the class does not provide validation for line or polygon topologies.

Default value for Geometry is ‘line'.

Geometry'point', 'line', 'polygon'

Metadata

Metadata is a scalar structure containing information for all the features. You can add any data type to the structure. As a Collection Property type, only one instance per object is allowed.

MetadataScalar struct

Latitude

Vector of latitude coordinates. The values can be either a row or column vector, but are stored as a row vector.

Attributes:

Latitudesingle | double vector

Longitude

Vector of longitude coordinates. The values can be either a row or column vector, but are stored as a row vector.

Attributes:

Longitudesingle | double vector

Methods

appendAppend features to geoshape vector
catConcatenate geoshape vectors
dispDisplay geoshape vector
fieldnamesDynamic properties of geoshape vector
isemptyTrue if geoshape vector is empty
isfieldTrue if dynamic property exists
ispropTrue if property exists
lengthNumber of elements in geoshape vector
propertiesProperties of a geoshape vector
rmfieldRemove dynamic property from geoshape vector
rmpropRemove properties from geoshape vector
sizeSize of geoshape vector
structConvert geoshape vector to scalar structure
vertcatVertical concatenation for geoshape vectors

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB® documentation.

Class Behaviors

Examples

expand all

Construct a Default geoshape Vector

Create a geoshape vector and dynamically set the Latitude and Longitude property values, and dynamically add Vertex property Z

s = geoshape();
s(1).Latitude = 0:45:90;
s(1).Longitude = [10 10 10];
s(1).Z = [10 20 30]
s = 

 1x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
     Latitude: [0 45 90]
    Longitude: [10 10 10]
            Z: [10 20 30]

Construct a geoshape vector Specifying Latitude and Longitude Values

Create a geoshape vector specifying latitude and longitude values.

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]

Construct a geoshape Vector Specifying a Name-Value Pair

Create a geoshape vector using a Name-Value pair to define a new Feature property.

point = geoshape(42, -72, 'Temperature', 89);
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: 89

When Value is a cell array containing numeric, logical, or cell array of strings, it is construed as a Vertex property. Otherwise the Name-Value pair is designated as being a Feature property.

Construct a geoshape vector from a Structure Array

Create a structure array and then create a geoshape vector.

structArray = shaperead('worldrivers', 'UseGeoCoords', true);
shape = geoshape(structArray)
s = 

 128x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
  (128 features concatenated with 127 delimiters)
     Latitude: [1x5542 double]
    Longitude: [1x5542 double]
 Feature properties:
         Name: {1x128 cell}

Construct a geoshape vector Using Cell Arrays

Use cell arrays to define multiple features and a structure array to define a set of Feature properties.

[structArray2, structNames] = shaperead('worldrivers', 'UseGeoCoords', true);
s = geoshape({structArray2.Lat}, {structArray2.Lon}, structNames)
s = 

 128x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
  (128 features concatenated with 127 delimiters)
     Latitude: [1x5542 double]
    Longitude: [1x5542 double]
 Feature properties:
         Name: {1x128 cell}

Construct a geoshape Vector and Dynamically Add a Feature Property

Construct a geoshape vector with one feature from latitude and longitude coordinates.

coast = load('coast')
s = geoshape(coast.lat, coast.long);
coast = 

     lat: [9865x1 double]
    long: [9865x1 double]


s = 

 1x1 geoshape vector with properties:

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

Dynamically add a Feature property and display it.

s.Name = 'coastline'

figure
worldmap world
geoshow(s.Latitude, s.Longitude)
s = 

 1x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
     Latitude: [1x9865 double]
    Longitude: [1x9865 double]
 Feature properties:
         Name: 'coastline'

Note that the Feature property Name applies to the entire set of vertices defined by the Geometry property as representing a ‘line'.

Construct a geoshape vector and define multiple point features

Define the latitude and longitude data and create a geoshape vector.

lat = {42, 42.3};
lon = {-72, -72.85};
temperature = {89, 87.5};
s = geoshape(lat, lon, 'Temperature', temperature);
s.Geometry = 'point'
s = 

 2x1 geoshape vector with properties:

 Collection properties:
       Geometry: 'point'
       Metadata: [1x1 struct]
 Vertex properties:
  (2 features concatenated with 1 delimiter)
       Latitude: [42 NaN 42.3000]
      Longitude: [-72 NaN -72.8500]
    Temperature: [89 NaN 87.5000]

Note that the number of temperature entries match the number of lat and lon entries which causes this attribute to be classified as a Vertex property.

Construct a geoshape vector and Dynamically Add Multiple Line Features

Create a structure array, structArray, contains 128 elements. Each element defines a river as a line using multiple location vertices.

structArray = shaperead('worldrivers', 'UseGeoCoords', true)
structArray = 

128x1 struct array with fields:
    Geometry
    BoundingBox
    Lon
    Lat
    Name

Display one element in the 128 element structure array.

structArray(1)
ans = 

       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

Note that the Lat and Lon vectors are terminated with a NaN delimiter.

Dynamically add Vertex properties from each entry in the structure array. Then add a Feature property: the name of each of the 128 rivers in shape.

shape = geoshape(); 

for k=1:length(shape)
   shape(k).Latitude  = structArray(k).Lat;
   shape(k).Longitude = structArray(k).Lon;
end

shape.Name = {structArray.Name}
shape = 

 128x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
  (128 features concatenated with 127 delimiters)
     Latitude: [1x5542 double]
    Longitude: [1x5542 double]
 Feature properties:
         Name: {1x128 cell}

Note that the features are concatenated with a NaN delimiter.

Since the default value of the Geometry Collection property is 'line' there is no need to set it explicitly in this example.

Construct a geoshape vector from a Structure Array

Read in structure array containing 128 elements which define world rivers. Display one element of the array.

structArray = shaperead('worldrivers', 'UseGeoCoords', true)
structArray(1)
ans = 

       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'

Note that the Lat and Lon vectors are terminated with NaN delimiters which used to separate the Vertex feature data in the geoshape class.

The structure array contains all the data needed to construct the 128 element geoshape vector.

shape = geoshape(structArray)
shape = 

 128x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
  (128 features concatenated with 127 delimiters)
     Latitude: [1x5542 double]
    Longitude: [1x5542 double]
 Feature properties:
         Name: {1x128 cell}

Display only the first 5 feature elements of the geoshape vector.

shape(1:5)
ans = 

 5x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
  (5 features concatenated with 4 delimiters)
     Latitude: [1x52 double]
    Longitude: [1x52 double]
 Feature properties:
         Name: {'Lena' 'Lena' 'Mackenzie' 'Mackenzie' 'Kolyma'}

Note that indexing of the first five elements of the geoshape vector displays the corresponding number of Feature properties in Name.

Add a filename field to the Metadata structure which is a Collection property and thus applies to all features in the object.

shape.Metadata.Filename = 'worldcities.shp';
shape.Metadata
ans = 

    Filename: 'worldcities.shp'

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

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

Using Indexing To Sort and Modify Dynamic Features

Construct a geoshape vector and sort its dynamic properties.

shape = geoshape(shaperead('tsunamis', '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 5 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]

Construct a Two-element geoshape vector Containing GPS Track Log Data

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

trk1 = gpxread('sample_tracks')
trk2 = gpxread('sample_tracks', 'Index', 2);
trk1 = 

 1851x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [1x1851 double]
    Longitude: [1x1851 double]
    Elevation: [1x1851 double]
         Time: {1x1851 cell}

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

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

To create dynamic vertex properties (a property with a value at each coordinate), 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: [1x2592 double]
    Longitude: [1x2592 double]
    Elevation: [1x2592 double]
         Time: {1x2592 cell}

Each Latitude and Longitude coordinate pair has associated Elevation and Time values which are Vertex properties.

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, construct a geoshape vector as before and add a MaximumElevation dynamic Feature property.

tracks_max = geoshape(lat, lon, 'Elevation', elevation, 'Time', time, ...
    'MaximumElevation', [max(trk1.Elevation) max(trk2.Elevation)])
tracks_max = 

 2x1 geoshape vector with properties:

 Collection properties:
            Geometry: 'line'
            Metadata: [1x1 struct]
 Vertex properties:
  (2 features concatenated with 1 delimiter)
            Latitude: [1x2592 double]
           Longitude: [1x2592 double]
           Elevation: [1x2592 double]
                Time: {1x2592 cell}
 Feature properties:
    MaximumElevation: [92.4240 76.1000]

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

Use geoshape Vectors to Store Latitude and Longitude Values

If you store latitude and longitude coordinate values in an N-by-2 array, the Latitude property values are assigned to the first column and the Longitude property values are assigned to the second column.

coast = load('coast');
pts = [coast.lat coast.long];
shape = geoshape();
shape(1) = pts
shape = 

 1x1 geoshape vector with properties:

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

If you store latitude and longitude coordinate values in a 2-by-M array, the Latitude property values are assigned to the first row and the Longitude property values are assigned to the second row.

pts = [coast.lat'; coast.long'];
shape = geoshape();
shape(1) = pts
shape = 

 1x1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1x1 struct]
 Vertex properties:
     Latitude: [1x9865 double]
    Longitude: [1x9865 double]
Was this topic helpful?