shapewrite

Write geographic vector data structure to shapefile

Syntax

shapewrite(S,filename)

shapewrite(S,filename,'DbfSpec',dbfspec)

Description

shapewrite(S,filename) writes the vector geographic features stored in S to the file specified by filename in shapefile format.

shapewrite(S,filename,'DbfSpec',dbfspec) writes a shapefile in which the content and layout of the DBF file is controlled by dbfspec, a DBF specification.

Examples

Write Feature Data to Shapefile

Import a shapefile, remove a subset of the data, and write the modified data to a new shapefile.

Get information about a shapefile as a structure. The shapefile contains a network of road segments in Concord, MA.

shapeinfo("concord_roads.shp")

ans = struct with fields:
                     Filename: [3x72 char]
                    ShapeType: 'PolyLine'
                  BoundingBox: [2x2 double]
                  NumFeatures: 609
                   Attributes: [5x1 struct]
    CoordinateReferenceSystem: [1x1 projcrs]

The NumFeatures field indicates that the shapefile contains 609 features.

Import the shapefile as a geospatial table.

GT = readgeotable("concord_roads.shp");

The CLASS attribute of the shapefile includes information about road types. For example, a value of 2 indicates a multilane highway and a value of 6 indicates a minor road. Create a subtable containing major roads such that the value of CLASS is less than 4.

rows = GT.CLASS < 4;
majorGT = GT(rows,:);

Export the geospatial table as a shapefile.

shapewrite(majorGT,"main_concord_roads.shp")

Get information about the new shapefile as a structure.

shapeinfo("main_concord_roads.shp")

ans = struct with fields:
                     Filename: [3x77 char]
                    ShapeType: 'PolyLine'
                  BoundingBox: [2x2 double]
                  NumFeatures: 107
                   Attributes: [5x1 struct]
    CoordinateReferenceSystem: []

The new shapefile has 107 features instead of 609 features.

Write Data Stored in Planar Point Vector to Shapefile

Read a shapefile containing a vector of world cities. Store the data as a planar point vector using the mappoint function.

S = shaperead("worldcities.shp");
p = mappoint(S)

p = 
 318x1 mappoint vector with properties:

 Collection properties:
    Geometry: 'point'
    Metadata: [1x1 struct]
 Feature properties:
           X: [-3.9509 54.7589 -0.2121 35.3894 38.7575 138.8528 44.5408 72.2474 30.4098 3.0397 77.0010 35.9214 75.0498 4.8892 -149.1074 32.9496 122.8003 47.5258 -71.4434 40.6098 58.6638 38.8593 -57.5113 23.5183 -84.3489 174.7379 44.4258 -62.2566 49.8658 ... ]
           Y: [5.2985 24.6525 5.6106 37.0613 9.0235 -34.6645 12.8767 22.7778 31.3044 36.7870 43.3620 31.7444 31.7744 52.3699 61.6040 39.7831 41.4673 -18.9141 -16.3867 64.7383 38.0316 15.3042 -25.1162 38.0164 33.7657 -36.9126 33.3449 -38.7281 40.4047 ... ]
        Name: {1x318 cell}

Append Paderborn, Germany to the point vector.

x = 51.715254;
y = 8.75213;
p = append(p,x,y,"Name","Paderborn")

p = 
 319x1 mappoint vector with properties:

 Collection properties:
    Geometry: 'point'
    Metadata: [1x1 struct]
 Feature properties:
           X: [-3.9509 54.7589 -0.2121 35.3894 38.7575 138.8528 44.5408 72.2474 30.4098 3.0397 77.0010 35.9214 75.0498 4.8892 -149.1074 32.9496 122.8003 47.5258 -71.4434 40.6098 58.6638 38.8593 -57.5113 23.5183 -84.3489 174.7379 44.4258 -62.2566 49.8658 ... ]
           Y: [5.2985 24.6525 5.6106 37.0613 9.0235 -34.6645 12.8767 22.7778 31.3044 36.7870 43.3620 31.7444 31.7744 52.3699 61.6040 39.7831 41.4673 -18.9141 -16.3867 64.7383 38.0316 15.3042 -25.1162 38.0164 33.7657 -36.9126 33.3449 -38.7281 40.4047 ... ]
        Name: {1x319 cell}

The size of p has increased by 1.

Write the updated point vector to a shapefile.

shapewrite(p,"worldcities_updated.shp")

Input Arguments

S — Vector geographic features

geospatial table | mappoint vector | mapshape vector | mapstruct vector | geopoint vector | geoshape vector | geostruct vector

Vector geographic features, specified as one of the following:

• A geospatial table. The shapewrite function does not support geospatial tables containing more than one type of shape object. For more information about geospatial tables, see Create Geospatial Tables.

• A mappoint vector.

• A mapshape vector.

• A map structure array (mapstruct) with X and Y coordinate fields.

• A geopoint vector.

• A geoshape vector.

• A geographic structure array (geostruct) with Lat and Lon fields.

S has the following restrictions on its attribute fields:

• Each attribute field value must be either a real, finite, scalar double or a character vector.

• The type of a given attribute must be consistent across all features.

• If S is a geospatial table containing geopointshape, geolineshape, or geopolyshape objects, a geopoint vector, a geoshape vector, or a geographic structure array, the shapewrite function writes the latitude and longitude values as Y and X coordinates, respectively.

• If a given attribute is integer-valued for all features, shapewrite writes it to the [basename '.dbf'] file as an integer. If an attribute is non-integer-valued for any feature, shapewrite writes it as a fixed point decimal value with six digits to the right of the decimal place.

filename — File name

string scalar | character vector

File name and location of the shapefile to create, specified as a string scalar or character vector. If the file name includes a file extension, it must be '.shp' or '.SHP'. shapewrite creates three output files: [basename '.shp'], [basename '.shx'], and [basename '.dbf'], where basename is filename without its extension.

dbfspec — Feature attributes to include in shapefile

scalar structure

Feature attributes to include in the shapefile, specified as a scalar MATLAB^® structure containing one field for each feature attribute. Assign to that field a scalar structure with the following four fields:

• FieldName — The field name to be used in the file

• FieldType — The field type to be used in the file: 'N' (numeric) or 'C' (character)

• FieldLength — The field length in the file, in bytes

• FieldDecimalCount — For numeric fields, the number of digits to the right of the decimal place

To create a DBF spec, call makedbfspec and then modify the output to remove attributes or change the FieldName, FieldLength, or FieldDecimalCount for one or more attributes.

To include an attribute in the output file, specify a field in dbfspec with the same name as the attribute is specified in S.

Tips

• The xBASE (.dbf) file specifications require that geostruct and mapstruct attribute names are truncated to 11 characters when copied as DBF field names. Consider shortening long field names before calling shapewrite. By doing this, you make field names in the DBF file more readable and avoid introducing duplicate names as a result of truncation.

• Remember to set your character encoding scheme to match that of the geographic data structure you are exporting. For instance, if you are exporting a map that displays Japanese text, configure your machine to support Shift-JIS character encoding.

Version History

Introduced before R2006a

R2022b: shapewrite truncates text when length exceeds 254 characters or value of FieldLength

When a text attribute contains more than 254 characters, the shapewrite function issues a warning and truncates the text to 254 characters. In previous releases, the shapewrite function did not truncate the text and, as a result, created a file that does not conform to shapefile specifications.

When a text attribute contains more characters than the value stored in the FieldLength field of the dbfspec argument, the shapewrite function issues a warning and truncates the text to the number of characters equal to the value of FieldLength. In previous releases, the shapewrite function issued an error.

R2021b: Write geospatial tables to shapefile format

The shapewrite function accepts geospatial tables as input.