# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

# mapshape

Planar shape vector

## 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, character vectors, cell arrays of character vectors, or cell arrays of numeric, logical, or cell array of character vectors values are ignored.```

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 character vectors values for `Geometry` do not change class behavior. The class does not provide validation for line or polygon topologies.

Data Types: `char`

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 `cat` Concatenate geographic or planar vector `disp` Display geographic or planar vector `fieldnames` Return dynamic property names of geographic or planar vector `isempty` Determine if geographic or planar vector is empty `isfield` Determine if dynamic property exists in geographic or planar vector `isprop` Determine if property exists in geographic or planar vector `length` Return number of elements in geographic or planar vector `properties` Return property names of geographic or planar vector `rmfield` Remove dynamic property from geographic or planar vector `rmprop` Remove property from geographic or planar vector `size` Return size of geographic or planar vector `struct` Convert geographic or planar vector to scalar structure `vertcat` Vertically concatenate geographic or planar vectors

## Examples

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

expand all

## Tips

• 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

### Using Objects

#### Introduced in R2012a

Was this topic helpful?

Get trial now