append

Append features to geographic or planar vector

Syntax

vout = append(vin,lat,lon)

vout = append(vin,x,y)

vout = append(___,field,value)

Description

vout = append(vin,lat,lon) appends the latitude and longitude values in lat and lon to the Latitude and Longitude properties of the geographic vector vin. vin is either a geopoint or a geoshape object.

vout = append(vin,x,y) appends the planar x- and y-coordinates in x and y to the X and Y properties of the planar vector vin. vin is either a mappoint or a mapshape object.

vout = append(___,field,value) appends the values specified in value to the corresponding dynamic property, field. If the property does not exist, append adds the dynamic property to the object using the value of field for the name and assigning the field the value specified in value. You can specify multiple field-value pairs. Enclose each field name in single quotes.

Examples

Append Points to Geopoint Vector

Create a geopoint vector.

p = geopoint(42,-110)

p = 
 1x1 geopoint vector with properties:

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

Append the vector with three new geographic points.

lat1 = [42.1 44 44.1];
lon1 = [-101 -120 -121];
p = append(p,lat1,lon1)

p = 
 4x1 geopoint vector with properties:

 Collection properties:
     Geometry: 'point'
     Metadata: [1x1 struct]
 Feature properties:
     Latitude: [42 42.1000 44 44.1000]
    Longitude: [-110 -101 -120 -121]

The length of the geopoint vector increases by three, as expected, and the 'Latitude' and 'Longitude' feature properties list the new coordinates.

Append Points to Mapshape Vector

Create a mapshape vector, designating a dynamic 'Temperature' property. This vector has one feature with three vertices.

s = mapshape(42:44,30:32,'Temperature', {65:67})

s = 
 1x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
              X: [42 43 44]
              Y: [30 31 32]
    Temperature: [65 66 67]

Append the vector with two new planar points. The points are stored as a new feature with two vertices.

x1 = [44.5 45];
y1 = [32.5 33];
s = append(s,x1,y1)

s = 
 2x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
  (2 features concatenated with 1 delimiter)
              X: [42 43 44 NaN 44.5000 45]
              Y: [30 31 32 NaN 32.5000 33]
    Temperature: [65 66 67 NaN 0 0]

The features are separated by NaN. The 'Temperature' value of the new points is set to 0 by default, since no value was specified during the call to append. The mapshape vector grew from 1x1 to 2x1 in length because the number of features increased.

Append Point with New Property to Mappoint Vector

Create a mappoint vector with a dynamic property Temperature.

mp = mappoint(42,-110,'Temperature',65)

mp = 
 1x1 mappoint vector with properties:

 Collection properties:
       Geometry: 'point'
       Metadata: [1x1 struct]
 Feature properties:
              X: 42
              Y: -110
    Temperature: 65

Add a point to this vector. The point contains a new dynamic property, Pressure.

mp = append(mp,42.2,-110.5,'Temperature',65.6,'Pressure', 100.0)

mp = 
 2x1 mappoint vector with properties:

 Collection properties:
       Geometry: 'point'
       Metadata: [1x1 struct]
 Feature properties:
              X: [42 42.2000]
              Y: [-110 -110.5000]
    Temperature: [65 65.6000]
       Pressure: [0 100]

A default Pressure value of 0 is automatically added to the first point.

Append Points with New Properties to Geoshape Vector

Create a geoshape vector, designating a dynamic 'Temperature' property. The 'Temperature' values are input as a cell array so that they belong to a single feature. This vector has one feature with three vertices.

lat1 = [42, 42.2, 43];
lon1 = [-110, -110.3, -110.5];
temp1 = {[65, 65.1, 65.2]};
s = geoshape(lat1,lon1,'Temperature',temp1)

s = 
 1x1 geoshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
       Latitude: [42 42.2000 43]
      Longitude: [-110 -110.3000 -110.5000]
    Temperature: [65 65.1000 65.2000]

Add three points to the geoshape vector, including a two new dynamic properties 'Precipitation' and 'CloudCover'. The latitude and longitude values are added as a two-element cell array, so two features are added to the geoshape vector. Note that the 'Temperature' and 'Precipitation' values are specified as two-element vectors, while the new 'CloudCover' values are specified as a one-element cell array.

lat2 = {[50 50.2],60};
lon2 = {[-120 -121],-130};
temp2 = [60.2 60.4];
precip = [0.07 0.19];
cloud = {[20,80]};
s2 = append(s,lat2,lon2,'Temperature',temp2,'Precipitation',precip,'CloudCover',cloud)

s2 = 
 3x1 geoshape vector with properties:

 Collection properties:
         Geometry: 'line'
         Metadata: [1x1 struct]
 Vertex properties:
  (3 features concatenated with 2 delimiters)
         Latitude: [42 42.2000 43 NaN 50 50.2000 NaN 60]
        Longitude: [-110 -110.3000 -110.5000 NaN -120 -121 NaN -130]
      Temperature: [65 65.1000 65.2000 NaN 60.2000 0 NaN 60.4000]
       CloudCover: [0 0 0 NaN 20 80 NaN 0]
 Feature properties:
    Precipitation: [0 0.0700 0.1900]

This appended vector s2 now has three features, separated by NaN, with some Vertex properties and some Feature properties. The two cells of the latitude and longitude cell arrays form the two newly-added features, one with two vertices and the other with one vertex. Since 'Temperature' had previously been designated as a Vertex property in s, the new 'Temperature' values are added as Vertex properties. The 'Temperature' value of one new point has not been assigned, so it is set to the default value of 0.

However, the new 'Precipitation' and 'CloudCover' properties are designated as a Vertex or Feature property, whichever is more appropriate for the value format. 'Precipitation' values are provided as a two-element vector, so they are assigned as Feature properties, where each element of precip2 belongs to a separate feature of the geoshape vector. Since 'CloudCover' values are provided as a cell array, the values must belong to the same feature, so they are set as Vertex properties corresponding to the first added feature. No 'CloudCover' values have been specified for the second added feature, so vertices in the second feature are assigned the default value 0. Finally, 'Precipitation' and 'CloudCover' values for the original feature are set to the default value of 0.

Input Arguments

vin — Input geographic or planar vector

geopoint, geoshape, mappoint, or mapshape object

Input geographic or planar vector, specified as a geopoint, geoshape, mappoint, or mapshape object.

lat — Latitude values

numeric scalar or vector

Latitude values, specified as a numeric scalar or vector.

Data Types: single | double

lon — Longitude values

numeric scalar or vector

Longitude values, specified as a numeric scalar or vector.

Data Types: single | double

x — Planar x-coordinates

numeric scalar or vector

Planar x-coordinates, specified as a numeric scalar or vector.

Data Types: single | double

y — Planar y-coordinates

numeric scalar or vector

Planar y-coordinates, specified as a numeric scalar or vector.

Data Types: single | double

field — Field name

string scalar | character vector

Field name, specified as a string scalar or character vector. Field can specify the name of an existing property in the vector data, or the name you want assigned to a new property that you want to add to the vector data.

Data Types: char | string

value — Value you want to assign to the property specified by field

cell array | scalar | vector

Value you want to assign to the property specified by field, specified as a cell array, or a scalar or vector of any numeric class or logical.

• When value is a cell array, append adds the property as a Vertex property.

• When value is a numeric array, append adds the property as a Feature property.

• When value is empty, append removes the property.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | cell

Output Arguments

vout — Output geographic or planar vector

geopoint, geoshape, mappoint, or mapshape object

Output geographic or planar vector, returned as a geopoint, geoshape, mappoint, or mapshape object. The object type of vout matches the object type of vin.

Version History

Introduced in R2012a