shaperead

Read vector features and attributes from shapefile

Syntax

S = shaperead(filename)

S = shaperead(filename,Name,Value)

[S,A] = shaperead(___)

Description

S = shaperead(filename) reads the shapefile specified by filename and returns a geographic data structure array in projected map coordinates (a mapstruct). The geographic data structure combines geometric and feature attribute information. shaperead supports the ordinary 2-D shape types: 'Point', 'Multipoint', 'PolyLine', and 'Polygon'.

S = shaperead(filename,Name,Value) returns a subset of the shapefile contents in S, as determined by the name-value pair arguments. Use RecordNumbers, BoundingBox, and Selector to select which features to read. If you use more than one of these parameters in the same call, you receive the intersection of the records that match the individual specifications. For instance, if you specify values for both RecordNumbers and BoundingBox, you import only those features with record numbers that appear in your list and that also have bounding boxes intersecting the specified bounding box.

If you do not specify any parameters, shaperead returns an entry for every non-null feature and creates a field for every attribute.

[S,A] = shaperead(___) returns an N-by-1 geographic data structure array, S, containing geometric information, and a parallel N-by-1 attribute structure array, A, containing feature attribute information.

Examples

Read Entire Shapefile

Read the entire shapefile called concord_hydro_line.shp, including the attributes in concord_hydro_line.dbf. The shaperead function returns a mapstruct with x and y coordinate vectors.

S = shaperead('concord_hydro_line.shp')

S=237×1 struct array with fields:
    Geometry
    BoundingBox
    X
    Y
    LENGTH

Read Portion of Shapefile Based on Bounding Box

Specify a bounding box to limit the data returned by shaperead. In addition, specify the names of the attributes you want to read.

bbox = [2.08 9.11; 2.09 9.12] * 1e5;
S = shaperead('concord_roads.shp','BoundingBox',bbox,...
              'Attributes',{'STREETNAME','CLASS'})

S=87×1 struct array with fields:
    Geometry
    BoundingBox
    X
    Y
    STREETNAME
    CLASS

Read road data by class from shapefile

Read road data only for class 4 and higher road segments that are at least 200 meters in length. Note the use of an anonymous function in the selector.

S = shaperead('concord_roads.shp','Selector',...
           {@(v1,v2) (v1 >= 4) && (v2 >= 200),'CLASS','LENGTH'})

S=115×1 struct array with fields:
    Geometry
    BoundingBox
    X
    Y
    STREETNAME
    RT_NUMBER
    CLASS
    ADMIN_TYPE
    LENGTH

Determine the number of roads of each class.

n = histcounts([S.CLASS],'BinLimits',[1 7],'BinMethod','integer')

n = 1×7

     0     0     0     7    93    15     0

Display a histogram of the number of roads that fall in each category of length.

figure
histogram([S.LENGTH])

Read Shapefile with Geographic Coordinates

Specify that a shapefile uses latitude and longitude coordinates using the 'UseGeoCoords' name-value pair.

For instance, return information about a shapefile as a structure. Verify the shapefile uses latitude and longitude coordinates by querying the CoordinateReferenceSystem field. The shapefile uses latitude and longitude coordinates if the field contains a geocrs object.

info = shapeinfo('landareas.shp');
crs = info.CoordinateReferenceSystem

crs = 
  geocrs with properties:

             Name: "WGS 84"
            Datum: "World Geodetic System 1984"
         Spheroid: [1x1 referenceEllipsoid]
    PrimeMeridian: 0
        AngleUnit: "degree"

Read the shapefile by using the shaperead function. Indicate that the shapefile uses latitude and longitude coordinates using the 'UseGeoCoords' name-value pair.

S = shaperead('landareas.shp','UseGeoCoords',true)

S=537×1 struct array with fields:
    Geometry
    BoundingBox
    Lon
    Lat
    Name

Note that the shaperead function returns a geographic data structure with latitude and longitude fields (a geostruct).

Input Arguments

filename — File name

character vector | string scalar

File name, specified as a string scalar or character vector. filename refers to the base name or full name of one of the component files in a shapefile. If the main file (with extension .shp) is missing, shaperead throws an error. If either of the other files is missing, shaperead issues a warning.

Make sure that your machine is set to the same character encoding scheme as the data you are importing. For example, if you are trying to import a shapefile that contains Japanese characters, configure your machine to support the Shift-JIS encoding scheme.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Attributes',{'STREETNAME','LENGTH'}

RecordNumbers — Record numbers

vector of integers

Record numbers, specified as the comma-separated pair consisting of 'RecordNumbers' and a vector of integers. Use the parameter RecordNumbers to import only features with listed record numbers.

Data Types: double

BoundingBox — Bounding box

2-by-2 matrix

Bounding box, specified as the comma-separated pair consisting of 'BoundingBox' and a 2-by-2 matrix. BoundingBox has the form [xmin,ymin;xmax,ymax], for map coordinates, or [lonmin,latmin;lonmax,latmax] for geographic coordinates. Use the parameter BoundingBox to import only features whose bounding boxes intersect the specified box. The shaperead function does not trim features that partially intersect the box.

Data Types: double

Selector — Selector

cell array

Selector, specified as the comma-separated pair consisting of 'Selector' and a cell array containing a function handle and one or more attribute names. The function must return a logical scalar. Use the Selector parameter to import only features for which the function, when applied to the corresponding attribute values, returns true. For more information about function handles, see Create Function Handle.

Attributes — Attribute names

cell array

Attribute names, specified as the comma-separated pair consisting of 'Attributes' and a cell array of attribute names. Use the parameter Attributes to include listed attributes and set the order of attributes in the structure array. Use {} to omit all attributes.

UseGeoCoords — Flag to return shapefile contents in a geostruct

false (default) | true

Flag to return shapefile contents in a geostruct, specified as the comma-separated pair consisting of 'UseGeoCoords' and false or true.

When UseGeoCoords is set to true, the shapefile contents are returned in a geostruct. Use this parameter when you know that the x- and y- coordinates in the shapefile actually represent longitude and latitude data.

To determine whether a shapefile uses latitude and longitude data, first use the shapeinfo function to return information about the shapefile as a structure. Then query the CoordinateReferenceSystem field of the structure. The shapefile uses geographic coordinates if CoordinateReferenceSystem is a geocrs object.

This code shows how to query the CoordinateReferenceSystem field of a structure associated with the shapefile landareas.shp.

info = shapeinfo('landareas.shp');
info.CoordinateReferenceSystem

Output Arguments

S — Vector geographic features

geographic data structure array

Vector geographic features, returned as an N-by-1 geographic data structure array containing one element for each non-null, spatial feature in the shapefile. The structure array has these fields:

Field	Description
Geometry	Type of shape, returned as 'Point', 'Multipoint', 'Line', or 'Polygon'. Individual points, lines, and polygons can have multiple parts. For example, lines can contain disconnected line segments, and polygons can have rings. All parts of an individual shape share the attributes specified for that shape by the corresponding attribute fields. When you read PolyLine shapes, the shaperead function returns the value of this field as 'Line'. This function does not support 3-D or measured shape types (PointZ, PointM, MultipointZ, MultipointM, PolyLineZ, PolyLineM, PolygonZ, PolylineM, and Multipatch). The function also ignores null point shapes.
BoundingBox	Minimum and maximum coordinate values for the shape, returned as a 2-by-2 numeric matrix of the form [min(X) min(Y); max(X) max(Y)]. When Geometry is 'Point', this field does not apply.
X	x-coordinates, returned as a row vector of data type double. This field applies to only mapstruct arrays.
Y	y-coordinates, returned as a row vector of data type double. This field applies to only mapstruct arrays.
Lon	Longitude coordinates, returned as a row vector of data type double. This field applies to only geostruct arrays.
Lat	Latitude coordinates, returned as a row vector of data type double. This field applies to only geostruct arrays.
Attribute fields	Attribute fields, returned as character vectors or numeric scalars. The shaperead function determines the names of the attribute fields from the attributes file (.dbf). Shapefiles typically include multiple attributes. If an attribute name is not a valid field name, then the function assigns the field a different name, typically by replacing spaces with underscores.

By default, the shaperead function assumes that the shapefile contains map coordinates and reads the data into a mapstruct array. When your shapefile contains geographic coordinates, you can read the data into a geostruct array by specifying the UseGeoCoords name-value argument as true.

For more information about geographic data structures, mapstruct arrays, and geostruct arrays, see Geographic Data Structures.

A — Feature attribute information

N-by-1 attribute structure array

Feature attribute information, returned as an N-by-1 attribute structure array corresponding to array S.

The fields in the output structure arrays S and A depend on the type of shape contained in the file and the names and types of attributes included in the file. The shaperead function supports the following four attribute types: numeric and floating (stored as type double in MATLAB^®) and character and date (stored as char array).

More About

Shapefile format

Data files in the shapefile format store vector data using multiple files: a main file (.shp), an index file (.shx), and an attribute file (.dbf). All the files have the same base name, for example, myfile.shp, myfile.shx, and myfile.dbf.

Tips

To get information about the coordinate reference system (CRS) associated with a shapefile, use the shapeinfo function.

Version History

Introduced before R2006a