Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

geoshape class

Geographic shape vector

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

Construction

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. For an additional example, see Construct a Default Geoshape Vector, Then Add Properties.

s = geoshape(lat,lon) constructs a geoshape vector and sets the Latitude and Longitude property values equal to lat and lon. For an example, see Construct a geoshape Vector Specifying Latitude and Longitude Values.

s = geoshape(lat,lon,Name,Value) constructs a geoshape vector, 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. For an example, see Construct a Geoshape Vector with Dynamic Properties.

s = geoshape(structArray) constructs a geoshape vector from the fields of the structure array, structArray. For an example, see the first method in Construct a Geoshape Vector from a Structure Array.

  • 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 Lonand 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, character vectors, logical, or cell arrays of numeric values, logical, or character vectors are ignored.

s = geoshape(lat,lon,structArray) constructs a new geoshape vector, sets the Latitude and Longitude properties equal to the numeric vectors lat and lon, and sets dynamic properties from the field values of structArray. For an example, see Construct a Geoshape Vector Using Cell Arrays.

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

Input Arguments

expand all

Latitude coordinates, specified as a numeric vector of class single or double, or a cell array containing numeric vectors of class single or double.

Data Types: double | single | cell

Longitude coordinates, specified as a numeric vector of class single or double, or a cell array containing numeric vectors of class single or double

Data Types: double | single | cell

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

Name-Value Pair Arguments

Construct a geoshape vector with dynamic properties using comma-separated pairs of Name,Value arguments. Name is the name of the dynamic property and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several dynamic properties as Name1,Value1,...,NameN,ValueN.

If Value is specified as a numeric, logical, character vector, or cell array of character vectors, then the property is designated a Feature property. If Value is specified as a cell array of numeric, logical, or cell array of character vectors, then the property is designated a Vertex property. If Value is any other type, then the field is ignored and no dynamic property Name is added to the geoshape vector.

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

Methods

appendAppend features to geoshape vector
catConcatenate geoshape vectors
dispDisplay geoshape vector
fieldnamesReturn dynamic property names of geoshape vector
isemptyReturn true if geoshape vector is empty
isfieldReturn true if dynamic property exists
ispropReturn true if property exists
lengthReturn number of elements in geoshape vector
propertiesReturn property names of geoshape vector
rmfieldRemove dynamic property from geoshape vector
rmpropRemove properties from geoshape vector
sizeReturn size of geoshape vector
structConvert geoshape vector to scalar structure
vertcatVertically concatenate geoshape vectors

Copy Semantics

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

Examples

expand all

Construct an empty geoshape vector.

s = geoshape()
s = 

 0×1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1×1 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 = 
 1×1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1×1 struct]
 Vertex properties:
     Latitude: [0 45 90]
    Longitude: [10 10 10]

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

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

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

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 = 
 1×1 geoshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1×1 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 = 
 1×1 geoshape vector with properties:

 Collection properties:
            Geometry: 'line'
            Metadata: [1×1 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 = 
 1×1 geoshape vector with properties:

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

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', '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: [2×2 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 = 
 128×1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1×1 struct]
 Vertex properties:
  (128 features concatenated with 127 delimiters)
     Latitude: [1×5542 double]
    Longitude: [1×5542 double]
 Feature properties:
         Name: {1×128 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 = 
 128×1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1×1 struct]
 Vertex properties:
  (128 features concatenated with 127 delimiters)
     Latitude: [1×5542 double]
    Longitude: [1×5542 double]
 Feature properties:
    RiverName: {1×128 cell}

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', '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 = 
 3×1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1×1 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', '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]

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

trk1 = gpxread('sample_tracks')
trk1 = 
 1851×1 geopoint vector with properties:

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

trk2 = gpxread('sample_tracks', '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 = 
 2×1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1×1 struct]
 Vertex properties:
  (2 features concatenated with 1 delimiter)
     Latitude: [1×2591 double]
    Longitude: [1×2591 double]
    Elevation: [1×2591 double]
         Time: {1×2591 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 = 
 2×1 geoshape vector with properties:

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

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

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 = 
 1×1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1×1 struct]
 Vertex properties:
     Latitude: [1×9865 double]
    Longitude: [1×9865 double]

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 = 
 1×1 geoshape vector with properties:

 Collection properties:
     Geometry: 'line'
     Metadata: [1×1 struct]
 Vertex properties:
     Latitude: [1×19730 double]
    Longitude: [1×19730 double]

Definitions

expand all

Tips

  • 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

Was this topic helpful?