mapshape

Planar shape vector

expand all in page

Description

A mapshape vector is an object that represents planar vector features with either point, line, or polygon topology. The features consist of x- and y-coordinates and associated attributes.

Attributes that vary spatially are termed Vertex properties. These elements of the mapshape vector are coupled such that the length of the x- and y-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 mapshape vector after construction using standard dot (.) notation.

Creation

s = mapshape()
s = mapshape(x,y)
s = mapshape(x,y,Name,Value)
s = mapshape(structArray)
s = mapshape(x,y,structArray)

Description

example

s = mapshape() constructs an empty mapshape vector, s, with these default property settings.

s = 

 0x1 mapshape vector with properties:

 Collection properties:
    Geometry: 'line'
    Metadata: [1x1 struct]
 Vertex properties:
           X: []
           Y: []

s is always a column vector.

example

s = mapshape(x,y) constructs a mapshape vector and sets the X and Y property values equal to vectors x and y.

example

s = mapshape(x,y,Name,Value) constructs a mapshape vector, then adds dynamic properties to the mapshape vector using Name, Value argument pairs. You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

example

s = mapshape(structArray) constructs a mapshape vector, assigning the fields of the structure array, structArray, as dynamic properties. Field values in structArray that are not numeric, logical, string scalars, string arrays, character vectors, cell arrays of character vectors, or cell arrays of numeric, logical, or cell array of character vectors values are ignored. You can specify vectors within cell arrays as either row or column vectors.

example

s = mapshape(x,y,structArray) constructs a new mapshape vector, sets the X and Y properties equal to vectors x and y, and sets dynamic properties from the field values of structArray.

Properties

expand all

mapshape class is a general class that represents a variety of planar features. The 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 mapshape, see Collection Properties, Vertex Properties, and Feature Properties.

Dynamic properties are new features and vertices that are added to a mapshape vector. You can attach dynamic Feature and Vertex properties to a mapshape vector during construction with a Name,Value pair or after construction using dot (.) notation after construction. This is similar to adding new fields to a structure. For an example of adding dynamic Feature properties, see Construct a Mapshape Vector with Dynamic Properties.

Shape of all the features in the mapshape vector, specified as 'line', 'point', or 'polygon'. As a Collection Property 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 provide validation for line or polygon topologies.

Data Types: char | string

Information for all the features, specified as a scalar structure. You can add any data type to the structure. As a Collection Property type, 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 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

Planar x-coordinates, specified as a numeric row or column vector, stored as a row vector.

Data Types: double | single

Planar y-coordinates, specified as a numeric row or column vector, stored as a row vector.

Data Types: double | single

Object Functions

append Append features to geographic or planar vector
catConcatenate geographic or planar vector
dispDisplay geographic or planar vector
fieldnamesReturn dynamic property names of geographic or planar vector
isemptyDetermine if geographic or planar vector is empty
isfieldDetermine if dynamic property exists in geographic or planar vector
ispropDetermine if property exists in geographic or planar vector
length Return number of elements in geographic or planar vector
propertiesReturn property names of geographic or planar vector
rmfieldRemove dynamic property from geographic or planar vector
rmpropRemove property from geographic or planar vector
sizeReturn size of geographic or planar vector
struct Convert geographic or planar vector to scalar structure
vertcatVertically concatenate geographic or planar vectors

Examples

collapse all

Create default mapshape vector.

s = mapshape()

0x1 mapshape vector with properties:

 Collection properties:
    Geometry: 'line'
    Metadata: [1x1 struct]
 Vertex properties:
           X: []
           Y: []

Set the values of the existing X and Y properties and dynamically add the Vertex property Z.

s(1).X = 0:45:90;
s(1).Y= [10 10 10];
s(1).Z = [10 20 30]
s = 

 1x1 mapshape vector with properties:

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

Create a mapshape vector specifying x and y.

x = [40, 50, 60];
y = [10, 20, 30];
shape = mapshape(x, y)
shape = 

 1x1 mapshape vector with properties:

 Collection properties:
    Geometry: 'line'
    Metadata: [1x1 struct]
 Vertex properties:
           X: [40 50 60]
           Y: [10 20 30]

Create mapshape vector specifying a Name-Value pair.

x = 1:10;
y = 21:30;
temperature = {61:70};
shape = mapshape(x, y, 'Temperature', temperature)
shape = 

 1x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
              X: [1 2 3 4 5 6 7 8 9 10]
              Y: [21 22 23 24 25 26 27 28 29 30]
    Temperature: [61 62 63 64 65 66 67 68 69 70]

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

Create structure array and then create mapshape vector with array.

    structArray = shaperead('concord_roads');
    shape = mapshape(structArray)

shape = 

 609x1 mapshape vector with properties:

 Collection properties:
      Geometry: 'line'
      Metadata: [1x1 struct]
 Vertex properties:
  (609 features concatenated with 608 delimiters)
             X: [1x5422 double]
             Y: [1x5422 double]
 Feature properties:
    STREETNAME: {1x609 cell}
     RT_NUMBER: {1x609 cell}
         CLASS: [1x609 double]
    ADMIN_TYPE: [1x609 double]
        LENGTH: [1x609 double]

Read data from a shapefile into a structure.

[structArray, A] = shaperead('concord_hydro_area');

structArray = 

98x1 struct array with fields:

    Geometry
    BoundingBox
    X
    Y


A = 

98x1 struct array with fields:

    AREA
    PERIMETER

Create a mapshape vector specifying the structure.

shape = mapshape({structArray.X}, {structArray.Y}, A);
shape.Geometry = structArray(1).Geometry
shape = 

 98x1 mapshape vector with properties:

 Collection properties:
     Geometry: 'polygon'
     Metadata: [1x1 struct]
 Vertex properties:
  (98 features concatenated with 97 delimiters)
            X: [1x4902 double]
            Y: [1x4902 double]
 Feature properties:
         AREA: [1x98 double]
    PERIMETER: [1x98 double]

This example shows how to add a single feature after construction of the mapshape vector using dot (.) notation.

Create a mapshape vector.

x = 0:10:100;
y = 0:10:100;
shape = mapshape(x, y)
shape = 

 1x1 mapshape vector with properties:

 Collection properties:
    Geometry: 'line'
    Metadata: [1x1 struct]
 Vertex properties:
           X: [0 10 20 30 40 50 60 70 80 90 100]
           Y: [0 10 20 30 40 50 60 70 80 90 100]

Add a dynamic Feature property.

shape.FeatureName = 'My Feature'
shape = 

 1x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
              X: [0 10 20 30 40 50 60 70 80 90 100]
              Y: [0 10 20 30 40 50 60 70 80 90 100]
 Feature properties:
    FeatureName: 'My Feature'

Add a dynamic Vertex property to the first feature.

shape(1).Temperature = [60 61 63 65 66 68 69 70 72 75 80];
shape = 

 1x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
              X: [0 10 20 30 40 50 60 70 80 90 100]
              Y: [0 10 20 30 40 50 60 70 80 90 100]
    Temperature: [60 61 63 65 66 68 69 70 72 75 80]
 Feature properties:
    FeatureName: 'My Feature

This extended example adds multiple features that are both Vertex and Feature properties. It also demonstrates property behaviors when vector lengths are either changed or set to [ ].

Create a mapshape vector.

x = {1:3, 4:6};
y = {[0 0 0], [1 1 1]};
shape = mapshape(x, y)

shape = 

 2x1 mapshape vector with properties:

 Collection properties:
    Geometry: 'line'
    Metadata: [1x1 struct]
 Vertex properties:
  (2 features concatenated with 1 delimiter)
           X: [1 2 3 NaN 4 5 6]
           Y: [0 0 0 NaN 1 1 1]

Add a two element dynamic Feature property.

shape.FeatureName = {'Feature 1', 'Feature 2'}
shape = 

 2x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
  (2 features concatenated with 1 delimiter)
              X: [1 2 3 NaN 4 5 6]
              Y: [0 0 0 NaN 1 1 1]
 Feature properties:
    FeatureName: {'Feature 1' 'Feature 2'}

Add a dynamic Vertex property.

z = {101:103, [115, 114, 110]}
shape.Z = z

z = 

    [1x3 double]    [1x3 double]


shape = 

 2x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
  (2 features concatenated with 1 delimiter)
              X: [1 2 3 NaN 4 5 6]
              Y: [0 0 0 NaN 1 1 1]
              Z: [101 102 103 NaN 115 114 110]
 Feature properties:
    FeatureName: {'Feature 1' 'Feature 2'}

Display the second feature.

shape(2)
ans = 

 1x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
              X: [4 5 6]
              Y: [1 1 1]
              Z: [115 114 110]
 Feature properties:
    FeatureName: 'Feature 2'

Add a third feature. The lengths of all the properties are synchronized.

shape(3).X = 5:9
shape = 

 3x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
  (3 features concatenated with 2 delimiters)
              X: [1 2 3 NaN 4 5 6 NaN 5 6 7 8 9]
              Y: [0 0 0 NaN 1 1 1 NaN 0 0 0 0 0]
              Z: [101 102 103 NaN 115 114 110 NaN 0 0 0 0 0]
 Feature properties:
    FeatureName: {'Feature 1' 'Feature 2' ''}

Set the values for the Z vertex property with fewer values than contained in X or Y. The Z values expand to match the length of X and Y.

shape(3).Z = 1:3
shape = 

 3x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
  (3 features concatenated with 2 delimiters)
              X: [1 2 3 NaN 4 5 6 NaN 5 6 7 8 9]
              Y: [0 0 0 NaN 1 1 1 NaN 0 0 0 0 0]
              Z: [101 102 103 NaN 115 114 110 NaN 1 2 3 0 0]
 Feature properties:
    FeatureName: {'Feature 1' 'Feature 2' ''}

Set the values for either coordinate property (X or Y) and all properties shrink in size to match the new vertex length of that feature.

shape(3).Y = 1
shape = 

 3x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
  (3 features concatenated with 2 delimiters)
              X: [1 2 3 NaN 4 5 6 NaN 5]
              Y: [0 0 0 NaN 1 1 1 NaN 1]
              Z: [101 102 103 NaN 115 114 110 NaN 1]
 Feature properties:
    FeatureName: {'Feature 1' 'Feature 2' ''}

Set the values for the Z vertex property with more values than contained in X or Y. All properties expand in length to match Z.

shape(3).Z = 1:6
shape = 

 3x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'line'
       Metadata: [1x1 struct]
 Vertex properties:
  (3 features concatenated with 2 delimiters)
              X: [1 2 3 NaN 4 5 6 NaN 5 0 0 0 0 0]
              Y: [0 0 0 NaN 1 1 1 NaN 1 0 0 0 0 0]
              Z: [101 102 103 NaN 115 114 110 NaN 1 2 3 4 5 6]
 Feature properties:
    FeatureName: {'Feature 1' 'Feature 2' ''}

Remove the FeatureName property.

shape.FeatureName = []
shape = 

 3x1 mapshape vector with properties:

 Collection properties:
    Geometry: 'line'
    Metadata: [1x1 struct]
 Vertex properties:
  (3 features concatenated with 2 delimiters)
           X: [1 2 3 NaN 4 5 6 NaN 5 0 0 0 0 0]
           Y: [0 0 0 NaN 1 1 1 NaN 1 0 0 0 0 0]
           Z: [101 102 103 NaN 115 114 110 NaN 1 2 3 4 5 6]

Remove all dynamic properties and set the object to empty.

shape.X = []
shape = 

 0x1 mapshape vector with properties:

 Collection properties:
    Geometry: 'line'
    Metadata: [1x1 struct]
 Vertex properties:
           X: []
           Y: []

This example shows how to include multiple dynamic features during object construction.

Create a mapshape vector specifying several name-value pairs.

x = {1:3, 4:6};
y = {[0 0 0], [1 1 1]};
z = {41:43, [56 50 59]};
name = {'Feature 1', 'Feature 2'};
id = [1 2];
shape = mapshape(x, y, 'Z', z, 'Name', name, 'ID', id)
shape = 

 2x1 mapshape vector with properties:

 Collection properties:
    Geometry: 'line'
    Metadata: [1x1 struct]
 Vertex properties:
  (2 features concatenated with 1 delimiter)
           X: [1 2 3 NaN 4 5 6]
           Y: [0 0 0 NaN 1 1 1]
           Z: [41 42 43 NaN 56 50 59]
 Feature properties:
        Name: {'Feature 1' 'Feature 2'}
          ID: [1 2]

Load the data and create x, y, and z arrays. Create a level list to use to bin the z values.

seamount = load('seamount');
x = seamount.x; y = seamount.y; z = seamount.z;

levels = [unique(floor(seamount.z/1000)) * 1000; 0];

Construct a mapshape object and assign the X and Y Vertex properties to the binned x and y values. Create a new Z Vertex property to contain the binned z values. Add a Levels Feature property to contain the lowest level value per feature.

shape = mapshape;
for k = 1:length(levels) - 1
   index = z >= levels(k) & z < levels(k+1);
   shape(k).X = x(index);
   shape(k).Y = y(index);
   shape(k).Z = z(index);
   shape(k).Level = levels(k);
end

Add a Color Feature property to denote a color for that feature, and specify that the geometry is 'point'

shape.Color = {'red', 'green', 'blue', 'cyan', 'black'};
shape.Geometry = 'point'
shape = 

 5x1 mapshape vector with properties:

 Collection properties:
    Geometry: 'point'
    Metadata: [1x1 struct]
 Vertex properties:
  (5 features concatenated with 4 delimiters)
           X: [1x298 double]
           Y: [1x298 double]
           Z: [1x298 double]
 Feature properties:
       Level: [-5000 -4000 -3000 -2000 -1000]
       Color: {'red' 'green' 'blue' 'cyan' 'black'}

Add metadata information. Metadata is a scalar structure containing information for the entire set of properties. Any type of data may be added to the structure.

shape.Metadata.Caption = seamount.caption;
shape.Metadata
ans = 

    Caption: [1x229 char]

Display the point data in 2-D.

figure
for k=1:length(shape)
  mapshow(shape(k).X, shape(k).Y, ...
   'MarkerEdgeColor', shape(k).Color, ...
   'Marker', 'o', ...
   'DisplayType', shape.Geometry)
end
legend(num2str(shape.Level'))

Display data as a 3-D scatter plot.

figure
scatter3(shape.X, shape.Y, shape.Z)

This example shows how to use selective indexing behavior of a mapshape vector, and how to add a Metadata property.

Construct a mapshape vector from a structure array

filename = 'concord_roads.shp';
S = shaperead(filename);
shape = mapshape(S)
shape = 

 609x1 mapshape vector with properties:

 Collection properties:
      Geometry: 'line'
      Metadata: [1x1 struct]
 Vertex properties:
  (609 features concatenated with 608 delimiters)
             X: [1x5422 double]
             Y: [1x5422 double]
 Feature properties:
    STREETNAME: {1x609 cell}
     RT_NUMBER: {1x609 cell}
         CLASS: [1x609 double]
    ADMIN_TYPE: [1x609 double]
        LENGTH: [1x609 double]

Add a Filename field to the Metadata structure and then construct a new mapshape object with only CLASS 4 (major road) designation.

shape.Metadata.Filename = filename;
class4 = shape(shape.CLASS == 4)
class4 = 

 26x1 mapshape vector with properties:

 Collection properties:
      Geometry: 'line'
      Metadata: [1x1 struct]
 Vertex properties:
  (26 features concatenated with 25 delimiters)
             X: [1x171 double]
             Y: [1x171 double]
 Feature properties:
    STREETNAME: {1x26 cell}
     RT_NUMBER: {1x26 cell}
         CLASS: [4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4]
    ADMIN_TYPE: [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
        LENGTH: [1x26 double]

This example show how features can be sorted by using the indexing behavior of the mapshape class.

You can create a new mapshape vector that contains a subset of dynamic properties by adding the name of a property or a cell array of property names to the last index in the ( ) operator.

Read data from file directly in mapshape constructor.

shape = mapshape(shaperead('tsunamis'))
shape = 

 162x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'point'
       Metadata: [1x1 struct]
 Vertex properties:
  (162 features concatenated with 161 delimiters)
              X: [1x323 double]
              Y: [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]

Alphabetize the Feature properties.

shape = shape(:, sort(fieldnames(shape)))
shape = 

 162x1 mapshape vector with properties:

 Collection properties:
       Geometry: 'point'
       Metadata: [1x1 struct]
 Vertex properties:
  (162 features concatenated with 161 delimiters)
              X: [1x323 double]
              Y: [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 mapshape vector to contain only the specified dynamic properties.

shape = shape(:, {'Year', 'Month', 'Day', 'Hour', 'Minute'})
shape = 

 162x1 mapshape vector with properties:

 Collection properties:
    Geometry: 'point'
    Metadata: [1x1 struct]
 Vertex properties:
  (162 features concatenated with 161 delimiters)
           X: [1x323 double]
           Y: [1x323 double]
 Feature properties:
        Year: [1x162 double]
       Month: [1x162 double]
         Day: [1x162 double]
        Hour: [1x162 double]
      Minute: [1x162 double]

Create a new mapshape vector in which each feature contains the points for the same year. Copy the data from a mappoint vector to ensure that NaN feature separators are not included. Create a subsection of data to include only Year and Country dynamic properties.

points = mappoint(shaperead('tsunamis'));
points = points(:, {'Year', 'Country'});
years = unique(points.Year);
multipoint = mapshape();
multipoint.Geometry = 'point';
for k = 1:length(years)
   index = points.Year == years(k);
   multipoint(k).X = points(index).X;
   multipoint(k).Y = points(index).Y;
   multipoint(k).Year = years(k);
   multipoint(k).Country = points(index).Country;
end
multipoint 		% Display
multipoint = 

 53x1 mapshape vector with properties:

 Collection properties:
    Geometry: 'point'
    Metadata: [1x1 struct]
 Vertex properties:
  (53 features concatenated with 52 delimiters)
           X: [1x214 double]
           Y: [1x214 double]
     Country: {1x214 cell}
 Feature properties:
        Year: [1x53 double]

Display the third from the end feature.

multipoint(end-3)
ans = 

 1x1 mapshape vector with properties:

 Collection properties:
    Geometry: 'point'
    Metadata: [1x1 struct]
 Vertex properties:
           X: [3.6340 -62.1800 143.9100]
           Y: [36.9640 16.7220 41.8150]
     Country: {'ALGERIA' 'MONTSERRAT' 'JAPAN'}
 Feature properties:
        Year: 2003

More About

expand all

Tips

  • The mapshape function separates features using NaN values. If you display a feature by using a scalar to index into the mapshape vector, such as s(1), then NaN values that separate the features do not display.

  • If X, Y, or a dynamic property is set with more values than features in the mapshape 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.

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

  • If either X or Y is 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 mapshape vector can be indexed like any MATLAB® vector. You can access any element of the vector to obtain a specific feature. The following example demonstrates this behavior:

    Construct a Mapshape Vector Containing Multiple Features and Indexing Behaviors

    This example builds a mapshape vector from a structure array; adds a Metadata property and demonstrates selective indexing behavior. Construct a Mapshape Vector and Add Metadata and Indexing

    Construct a Mapshape Vector and Sort the Dynamic Properties

See Also

Functions

Objects

Topics

Introduced in R2012a

Mapping Toolbox Documentation

Support