Documentation Center

  • Trial Software
  • Product Updates

mapshape class

Planar shape vector

Syntax

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

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. If these attributes vary spatially they 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 which only pertain to the overall feature (point, line, polygon) are termed Feature properties. Feature properties are not linked to the auto-sizing mechanism of the Vertex properties. Both of the property types can be dynamically added to a mapshape vector using the standard dot notation.

A mapshape vector is always a column vector.

Construction

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

s = 

 0x1 mapshape vector with properties:

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

For an additional example see: Construct a Default mapshape Vector and Set and Add Properties

s = mapshape(x,y) constructs a mapshape vector and sets the X and Y property values equal to vectors x and y. x and y may be either numeric vectors of class single or double, or cell arrays containing numeric vectors of class single or double. For an example, see Construct a mapshape Vector Specifying x and y Values.

s = mapshape(x,y,Name,Value) constructs a mapshape vector from the input x and y vectors, and then adds dynamic properties to the mapshape vector using the Name, Value argument pairs.

  • If Value is in a cell array containing numeric, logical or cell array of strings, then this property is designated as a Vertex property. Otherwise, this property is designated as a Feature property.

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

For an example, see: Construct a mapshape vector Specifying a Name-Value Pair.

s = mapshape(structArray) constructs a mapshape vector from the fields of the structure array, structArray.

  • If structArray is a scalar structure which contains the field Metadata and the field value is a scalar structure, then the Metadata field is copied to the Metadata property. If structArray is a scalar structure and the Metadata field is present and is not a scalar structure, then an error is issued. If structArray is not scalar then the Metadata field is ignored.

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

For an example, see Construct a mapshape Vector from a Structure Array.

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

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

For an example, see Construct a mapshape Vector Using Cell Arrays and Structures to Define Multiple Features and Properties.

Input Arguments

x

vector of X coordinates

y

vector of Y coordinates

structArray

An array of structures containing fields to be assigned as dynamic properties.

Name

Name of dynamic property

Value

Property value associated with dynamic property Name. The class type of the values for the Feature dynamic properties may be either numeric, logical, char, or a cell array of strings. Values for the Vertex dynamic properties may be either numeric, logical, cell array of strings, or a cell array of numeric, logical, or cell array of strings.

Output Arguments

s

mapshape vector.

Properties

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. The class has the following property types.

Types of PropertiesDescription
Collection PropertiesCollection properties contain only one value per class instance. This is in contrast to the other two property types which can have attribute values associated with each feature or with each vertex in a set that defines a feature. Geometry and Metadata are the only two Collection properties.
Vertex Properties Vertex properties provide a scalar number or a string for each vertex in a mapshape object. Vertex properties are suitable for attributes that vary spatially from point to point (vertex to vertex) along a line. Examples of such spatially varying attributes could be elevation, speed, temperature, or time. X and Y are vertex properties since they contain a scalar number for each vertex in a mapshape vector. Attribute values can be dynamically associated with each vertex by using dot notation. This is similar to adding dynamic fields to a structure. The dynamically added vertex property values of an individual feature match its X and Y values in length.
Feature Properties Feature properties provide one value (a scalar number or a string) for each feature in a mapshape vector. They are suitable for properties, such as name, owner, serial number, age, etc., that describe a given feature (an element of a mapshape vector) as a whole. Like Vertex properties, Feature properties can be added dynamically.

Geometry

The Geometry property is a string that denotes the shape type for all the features in the mapshape vector. As a Collection Property there is only one value per object instance. Its purpose is purely informational; the three allowable string values for Geometry do not change class behavior. Additionally, the class does not provide validation for line or polygon topologies.

Default value for Geometry is ‘line'.

Geometry'point', 'line', 'polygon'

Metadata

Metadata is a scalar structure containing information for all the features. You can add any data type to the structure. As a Collection Property type, only one instance per object is allowed.

MetadataScalar struct

X

Vector of X coordinates. The values can be either a row or column vector, but are stored as a row vector.

Attributes:

Xsingle | double vector

Y

Vector of Y coordinates. The values can be either a row or column vector, but are stored as a row vector.

Attributes:

Ysingle | double vector

Methods

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

Copy Semantics

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

Class Behaviors

Examples

expand all

Construct a Default mapshape Vector and Set and Add Properties

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]

Construct a mapshape Vector Specifying x and y Values

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]

Construct a mapshape vector Specifying a Name-Value Pair

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 strings, it is construed as a Vertex property. Otherwise the Name-Value pair is designated as being a Feature property.

Construct a mapshape Vector from a Structure Array

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]

Construct a mapshape Vector Using Cell Arrays and Structures to Define Multiple Features and Properties

Read data from a shape file 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]

Construct a mapshape Vector and Add a Feature Property

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 feature dynamic 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 vertex dynamic property to the first feature.

shape(1).Temperature = 65 + rand(1, length(shape.X))
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: [1x11 double]
 Feature properties:
    FeatureName: 'My Feature

Construct a mapshape Vector and Manipulate Features

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 feature dynamic 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 vertex dynamic 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: []

Construct a mapshape Vector Specifying Several Name-Value Pairs

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]

Construct a mapshape vector Containing Multiple Features and Indexing Behaviors

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

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)

Construct a mapshape Vector and Add Metadata and Indexing

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

Construct a mapshape Vector and Sort the Dynamic Properties

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

See Also

| | | |

Was this topic helpful?