geopoint class

Geographic point vector

Syntax

p = geopoint()
p = geopoint(lat,lon)
p = geopoint(lat,lon,Name,Value)
p = geopoint(structArray)
p = geopoint(lat,lon,structArray)

Description

A geopoint vector is a container object that holds geographic point coordinates and attributes. The points are coupled, such that the size of the latitude and longitude coordinate arrays are always equal and match the size of any dynamically added attribute arrays. Each entry of a coordinate pair and associated attributes, if any, represent a discrete element in the geopoint vector.

Construction

p = geopoint() constructs an empty geopoint vector, p, with these default property settings:

p = 

 0x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: []
    Longitude: []

p = geopoint(lat,lon) constructs a new geopoint vector and assigns the Latitude and Longitude properties to the numeric array inputs, lat and lon. For examples, see Construct geopoint Vector Using Latitude and Longitude Coordinates .

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

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

See Construct geopoint Vector Using Name-Value Pairs for examples.

p = geopoint(structArray) constructs a new geopoint vector from the fields of the structure, structArray.

  • If structArray contains the field Lat, and does not contain a field Latitude, then the Lat values are assigned to the Latitude property.

  • If structArray contains both Lat and Latitude fields, then both field values are assigned to p.

  • If structArray contains the field, Lon, and does not contain a field, Longitude, then the Lon values are assigned to the Longitude property.

  • If structArray contains both Lon and Longitude fields, then both field values are assigned to p.

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

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

See Construct geopoint Vector From a Structure Array for an example.

p = geopoint(lat,lon,structArray) constructs a new geopoint vector and assigns the Latitude and Longitude properties to the numeric arrays, lat and lon, and sets dynamic properties from the field values of the structure, structArray.

  • If structArray contains the fields Lat, Latitude, Lon or Longitude, then those field values are ignored.

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

See Construct a geopoint Vector Using Numeric Arrays and a Structure Array.

Input Arguments

expand all

lat — Vector of latitude coordinatesnumeric array

Vector of latitude coordinates, specified as a numeric array.

Data Types: double | single

lon — Vector of longitude coordinatesnumeric array

Vector of longitude coordinates, specified as a numeric array.

Data Types: double | single

structArray — Dynamic propertiesstructure

Dynamic properties, specified as a structure.

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 as a numeric, logical, char, or a cell array of strings.

Output Arguments

expand all

p — New objectgeopoint vector

New object, returned as a geopoint vector

Properties

expand all

Each element in a geopoint vector is considered a feature. Feature properties contain one value (a scalar number or a string) for each element in the geopoint vector. The Latitude and Longitude coordinate properties are feature properties as there is one value for each feature.

Geometry and Metadata are collection properties. These properties contain only one value per class instance. The term collection is used to distinguish these two properties from other feature properties which have values associated with each feature (element in a geopoint vector). See Metadata and Array Assignment for usage examples.

You can attach new dynamic feature properties to the object by using dot ‘.' notation. This is similar to adding dynamic fields to a structure. Dynamic feature properties apply to each individual feature in the geopoint vector.

GeometryType of geometry'point' (default) | string

Type of geometry, specified as a string. For geopoint, Geometry is always 'point'.

Attributes:

Geometrystring

MetadataInformation for the entire set of geopoint vector elementsscalar structure

Information for the entire set of geopoint vector elements, specified as a scalar structure. You can add any data type to the structure.

Attributes:

MetadataScalar struct

LatitudeLatitude coordinatesnumeric row or column vector

Latitude coordinates, specified as a numeric row or column vector.

Attributes:

Latitudesingle | double vector

LongitudeLongitude coordinatesnumeric row or column vector

Longitude coordinates, specified as a numeric row or column vector.

Attributes:

Longitudesingle | double vector

Methods

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

Copy Semantics

To learn how Value classes affect copy operations, see Copying Objects.

Class Behaviors

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

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

  • If a dynamic property is set with fewer values than the number of features contained in the object, 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 string if the value is a cell array.

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

See Manipulate a geopoint vector for examples of these behaviors.

Examples

expand all

Construct geopoint Vector Using Latitude and Longitude Coordinates

This example shows how to create a geopoint vector specifying latitude and longitude coordinates. The example then adds a field to the object dynamically.

Construct a geopoint vector from latitude and longitude values.

lat = 51.519;
lon = -.13;
p = geopoint(lat,lon)
p = 

 1x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: 51.5190
    Longitude: -0.1300

Add a property to the object dynamically.

p.Name = 'London'
p = 

 1x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: 51.5190
    Longitude: -0.1300
         Name: 'London'

Construct geopoint Vector from File

Construct a geopoint vector from a file

coast = load('coast');
p = geopoint(coast.lat, coast.long);
figure
worldmap world
geoshow(p.Latitude, p.Longitude) 

Construct geopoint Vector Using Name-Value Pairs

Create a geopoint vector, specifying Latitude, Longitude, and Temperature, where Temperature is part of a Name-Value pair.

 point = geopoint(42, -72, 'Temperature', 89)
point = 

 1x1 geopoint vector with properties:

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

Construct a geopoint object specifying names.

    p = geopoint([51.519 48.871], [-.13 2.4131],...
       'Name', {'London', 'paris'}) 
p = 

 2x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [51.5190 48.8710]
    Longitude: [-0.1300 2.4131]
         Name: {'London' 'paris'}

Construct geopoint Vector From a Structure Array

Read shape data into a geostruct (a structure array containing Lat and Lon fields).

S = shaperead('worldcities', 'UseGeoCoords', true)
S = 

318x1 struct array with fields:

    Geometry
    Lon
    Lat
    Name

Create a geopoint vector specifying the geostruct.

p = geopoint(S)
p = 

 318x1 geopoint vector with properties:

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

Add a Filename field to the Metadata structure. The Metadata property pertains to all elements of a geopoint vector.

p.Metadata.Filename = 'worldcities.shp';
m = p.Metadata
ans = 

    Filename: 'worldcities.shp'

Construct a geopoint Vector Using Numeric Arrays and a Structure Array

Create a structure array.

[structArray, A] = shaperead('worldcities', 'UseGeoCoords', true)
structArray = 

318x1 struct array with fields:
    Geometry
    Lon
    Lat

A = 

318x1 struct array with fields:
    Name

Use the numeric arrays and the structure containing the list of names to construct a geopoint vector.

p = geopoint([structArray.Lat], [structArray.Lon], A)
p = 

 318x1 geopoint vector with properties:

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

Add Coordinate and Dynamic properties

Generate an empty geopoint vector using the default constructor and then populate the geopoint vector by adding properties from data fields in structure structArray via assignment statements.

structArray = shaperead('worldcities', 'UseGeoCoords', true);
p = geopoint();
p.Latitude  = [structArray.Lat];
p.Longitude = [structArray.Lon];
p.Name = structArray.Name;
p
p = 

 318x1 geopoint vector with properties:

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

Add New Values to Existing geopoint Vector

This example shows how to add new values to an existing geopoint vector. The example appends data about Paderborn Germany to the geopoint vector of data about world cities.

Read world cities data using the shaperead command. shaperead returns a structure array.

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

Create a geopoint vector from the structure array. Display the last of the 318 elements in the vector.

p = geopoint(structArray);
p(end)
ans = 

 1x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: 34.8519
    Longitude: 113.8061
         Name: 'Zhengzhou'

Add the Paderborn data to the end of the geopoint vector. Display the last of the existing elements and the new element.

lat = 51.715254;
lon = 8.75213;
p = append(p, lat, lon, 'Name', 'Paderborn');
p(end-1:end)
ans = 

 2x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [34.8519 51.7153]
    Longitude: [113.8061 8.7521]
         Name: {'Zhengzhou'  'Paderborn'}

Another way to add a point at the end of a vector is to use linear indexing. For example, add data about Arlington, Massachusetts to the end of the world cities vector. Notice how, after the initial assignment statement appends a value to the Latitude property vector, using end+1 , all other property vectors automatically expand by one element. Display the last of the existing elements and the new element.

p(end+1).Latitude = 42.417060
p(end).Longitude = -71.170200;
p(end).Name = 'Arlington';
p(end-1:end)
p = 

 320x1 geopoint vector with properties:

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


ans = 

 2x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [51.7153 42.4171]
    Longitude: [8.7521 -71.1702]
         Name: {'Paderborn'  'Arlington'}

Manipulate a geopoint vector

Construct a geopoint vector containing two features and then add two dynamic properties.

lat = [51.519 48.871];
lon = [-.13 2.4131];
p = geopoint(lat, lon);
 
p.Name = {'London', 'paris'};   % Add character feature dynamic property
p.ID = [1 2] 			% Add numeric feature dynamic property
p = 

 2x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [51.5190 48.8710]
    Longitude: [-0.1300 2.4131]
         Name: {'London' 'paris'}
           ID: [1 2]

Add the coordinates for a third feature.

p(3).Latitude = 45.472;
p(3).Longitude = 9.184
p = 

 3x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [51.5190 48.8710 45.4720]
    Longitude: [-0.1300 2.4131 9.1840]
         Name: {'London' 'paris' ''}
           ID: [1 2 0]

Note that lengths of all feature properties are synchronized with default values.

Set the values for the ID feature dynamic property with more values than contained in Latitude or Longitude.

p.ID = 1:4
p = 

 4x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [51.5190 48.8710 45.4720 0]
    Longitude: [-0.1300 2.4131 9.1840 0]
         Name: {'London' 'paris' '' ''}
           ID: [1 2 3 4]

Note that all feature properties are expanded to match in size.

Set the values for the ID feature dynamic property with fewer values than contained in the Latitude or Longitude properties.

p.ID = 1:2
p = 

 4x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [51.5190 48.8710 45.4720 0]
    Longitude: [-0.1300 2.4131 9.1840 0]
         Name: {'London' 'paris' '' ''}
           ID: [1 2 0 0]

The ID property values expand to match the length of the Latitude and Longitude property values.

Set the value of either coordinate property (Latitude or Longitude) with fewer values.

 p.Latitude = [51.519 48.871]
p = 

 2x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [51.5190 48.8710]
    Longitude: [-0.1300 2.4131]
         Name: {'London' 'paris'}
           ID: [1 2]

All properties shrink to match in size.

Remove the ID property by setting its value to [ ].

p.ID = []
p = 

 2x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [51.5190 48.8710]
    Longitude: [-0.1300 2.4131]
         Name: {'London' 'paris'}

Remove all dynamic properties and set the object to empty by setting a coordinate property value to [ ].

p.Latitude = []
p = 

 0x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: []
    Longitude: []

Sort dynamic properties and Extract subsets

Read data from shape file. Initially the field names of the class are in random order.

structArray = shaperead('tsunamis', 'UseGeoCoords', true); % Field names in random order
p = geopoint(structArray)
p = 

 162x1 geopoint vector with properties:

 Collection properties:
       Geometry: 'point'
       Metadata: [1x1 struct]
 Feature properties:
       Latitude: [1x162 double]
      Longitude: [1x162 double]
           Year: [1x162 double]
          Month: [1x162 double]
            Day: [1x162 double]
           Hour: [1x162 double]
         Minute: [1x162 double]
         Second: [1x162 double]
       Val_Code: [1x162 double]
       Validity: {1x162 cell}
     Cause_Code: [1x162 double]
          Cause: {1x162 cell}
         Eq_Mag: [1x162 double]
        Country: {1x162 cell}
       Location: {1x162 cell}
     Max_Height: [1x162 double]
       Iida_Mag: [1x162 double]
      Intensity: [1x162 double]
     Num_Deaths: [1x162 double]
    Desc_Deaths: [1x162 double

Using the method fieldnames and typical MATLAB® vector notation, the field names in the geopoint vector are alphabetically sorted.

p = p(:, sort(fieldnames(p)))
p = 

 162x1 geopoint vector with properties:

 Collection properties:
       Geometry: 'point'
       Metadata: [1x1 struct]
 Feature properties:
       Latitude: [1x162 double]
      Longitude: [1x162 double]
          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]

Using typical MATLAB vector notation, extract a subset of data from the base geopoint vector into a geopoint vector albeit smaller in size.

subp = p(20:40,{'Location','Country','Year'}) % get subset of data
subp = 

 21x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [1x21 double]
    Longitude: [1x21 double]
     Location: {1x21 cell}
      Country: {1x21 cell}
         Year: [1x21 double]

Note that the coordinate properties, Latitude and Longitude, as well as the collection properties are retained in this subset of geopoint vectors.

Set, Get, and Remove Dynamic Property Values

To set property values, use the () operator, or assign array values to corresponding fields, or use dot '.' notation (object.property) to assign new property values.

pts = geopoint();
pts.Latitude = [42 44 45];
pts.Longitude = [-72 -72.1 -71];
pts
pts = 

 3x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [42 44 45]
    Longitude: [-72 -72.1000 -71]

Use ( ) to assign values to fields.

pts(3).Latitude = 45.5;
pts
pts = 

 3x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [42 44 45.5000]
    Longitude: [-72 -72.1000 -71]

Use dot notation to create new dynamic properties

pts.Name = {'point1', 'point2', 'point3'}
pts = 

 3x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [42 44 45.5000]
    Longitude: [-72 -72.1000 -71]
         Name: {'point1' 'point2' 'point3'}

Get property values

pts.Name
ans = 

    'point1'    'point2'    'point3'

Remove dynamic properties. To delete or remove dynamic properties, set them to [] or set the Latitude or Longitude property to [].

pts.Temperature = 1:3
pts = 

 3x1 geopoint vector with properties:

 Collection properties:
       Geometry: 'point'
       Metadata: [1x1 struct]
 Feature properties:
       Latitude: [42 44 45.5000]
      Longitude: [-72 -72.1000 -71]
           Name: {'point1' 'point2' 'point3'}
    Temperature: [1 2 3]

By setting the Temperature property to [], this dynamic property is deleted.

pts.Temperature = []
pts = 

 3x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [42 44 45.5000]
    Longitude: [-72 -72.1000 -71]
         Name: {'point1' 'point2' 'point3'}

To clear all fields in the geopoint vector, set the Latitude or Longitude property to []

pts.Latitude = []
pts = 

 0x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: []
    Longitude: []

Metadata and Array Assignment

Modify a geopoint object and its metadata.

If you typically store latitude and longitude coordinates in an N-by-2 or 2–by-M array, you can assign these numeric values to a geopoint vector. If the coordinates are N-by-2, then the first column is assigned to the Latitude property and the second column to the Longitude property. If the coordinates are 2-by-M, then the first row is assigned to the Latitude property and the second row to the Longitude property.

coast = load('coast');
ltln = [coast.lat coast.long];		% 9865x2 array
pts = geopoint;			% null constructor
pts(1:numel(coast.lat)) = ltln;		% assign array
pts.Metadata.Name = 'coastline';
pts
pts.Metadata
pts = 

 9865x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [1x9865 double]
    Longitude: [1x9865 double]


ans = 

    Name: 'coastline'
Was this topic helpful?