append

Append features to geographic or planar vector

collapse all in page

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.

example

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.

example

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.

example

Examples

collapse all

Open Live Script

Create a geopoint vector.

p = geopoint(42,-110)
p = 
 1×1 geopoint vector with properties:

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

 Collection properties:
     Geometry: 'point'
     Metadata: [1×1 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.

Open Live Script

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

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

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

Open Live Script

Create a mappoint vector with a dynamic property Temperature.

mp = mappoint(42,-110,'Temperature',65)
mp = 
 1×1 mappoint vector with properties:

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

 Collection properties:
       Geometry: 'point'
       Metadata: [1×1 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.

Open Live Script

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

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

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

collapse all

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

Latitude values, specified as a numeric scalar or vector.

Data Types: single | double

Longitude values, specified as a numeric scalar or vector.

Data Types: single | double

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

Data Types: single | double

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

Data Types: single | double

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

collapse all

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

See Also