shaperead - Read vector features and attributes from shapefile

Syntax

s = shaperead(filename) [s, a] = shaperead(filename) [s, a] = shaperead(filename, param1, val1, param2, val2,...)

Description

s = shaperead(filename) returns an N-by-1 geographic data structure (mapstruct or geostruct) array, S, containing an element for each nonnull spatial feature in the shapefile. S combines feature coordinates/geometry and attribute values. The extension of filename can be .shp, .dbf or .shx, or be omitted (see Remarks, below).

[s, a] = shaperead(filename) returns an N-by-1 mapstruct or geostruct array, s, and a parallel N-by-1 attribute structure array, a. Each array contains an element for each nonnull spatial feature in the shapefile. The attributes are read from the file filename.dbf (see Remarks, below).

[s, a] = shaperead(filename, param1, val1, param2, val2,...) returns a subset of the shapefile contents in s or [s,a], as determined by the parameters 'RecordNumbers', 'BoundingBox', 'Selector', or 'Attributes'. In addition, the parameter 'UseGeoCoords' can be used in cases where you know that the x- and y-coordinates in the shapefile actually represent longitude and latitude.

Remarks

The shapefile format was defined by the Environmental Systems Research Institute (ESRI) to store nontopological vector geometry and attribute information for spatial features. A shapefile consists of a main file, an index file, and an xBASE table. All three files have the same base name and are distinguished by the extensions .shp, .shx, and .dbf, respectively (e.g., given the base name 'concord_roads' the shapefile filenames would be 'concord_roads.shp', 'concord_roads.shx', and 'concord_roads.dbf').

filename can be the base name or the full name of any one of the component files. shaperead reads all three files as long as they exist in the same directory and have valid file extensions. If the main file (with extension .SHP) is missing, shaperead returns an error. If either of the other files is missing, shaperead returns a warning.

Supported Shape Types

shaperead supports the ordinary 2-D shape types: 'Point', 'Multipoint', 'PolyLine', and 'Polygon'. ('Null Shape' features can also be present in a Point, Multipoint, PolyLine, or Polygon shapefile, but are ignored.) shaperead does not support any 3-D or "measured" shape types: 'PointZ', 'PointM', 'MultipointZ', 'MultipointM', 'PolyLineZ', 'PolyLineM', 'PolygonZ', 'PolylineM', or 'Multipatch'.

Output Structure

The fields in the output structure arrays s and a depend on (1) the type of shape contained in the file and (2) the names and types of the attributes included in the file:

Field Name	Field Contents	Comment
`Geometry`	Shape type string	`'Point'`, `'Multipoint'`, `'PolyLine'`, or `'Polygon'`
`BoundingBox`	`[minX minY; maxX maxY]`	Omitted for shape type `'Point'`
`X` or `Lon`	Coordinate vector	NaN separators used in multipart PolyLine and Polygon shapes
`Y` or `Lat`	Coordinate vector	NaN separators used in multipart PolyLine and Polygon shapes
`attr1`	Value of first attribute	Included in output `s` if output `a` is omitted
`attr2`	Value of second attribute	Included in output `s` if output `a` is omitted
`...`	...	...

The names of the attribute fields (listed above as Attr1, Attr2, ...) are determined at run-time from the xBASE table (with extension .DBF) and/or optional, user-specified parameters. There can be many attribute fields, or none at all.

Field Descriptions

Geometry — String with one of the following values: 'Point', 'MultiPoint', 'Line', or 'Polygon'. (Note that these match the standard shapefile types, except that for shape type 'Polyline' the value of the Geometry field is simply 'Line'.)
BoundingBox — Contains a 2-by-2 numerical array specifying the minimum and maximum feature coordinate values in each dimension (min([x, y]); max([x, y], where x and y are N-by-1 and contain the combined coordinates of all parts of the feature). In the absence of documentation or metadata for the geodata in a shapefile, you can use this information to decide what kind of coordinate system (map or geographic) the shapes have.
X and Y / Lon and Lat (Coordinate vector) — 1-by-N arrays of class double. For 'Point' shapes, they are 1-by-1. In the case of multipart 'Polyline' and 'Polygon' shapes, NaNs are added to separate the lines or polygon rings. In addition, one terminating NaN is added to support horizontal concatenation of the coordinate data from multiple shapes.
Attribute fields — Attribute names, types, and values are defined within a given shapefile. The following four types are supported: Numeric, Floating, Character, and Date. shaperead skips over other attribute types. The field names in the output shape structure are taken directly from the shapefile if they contain no spaces or other illegal characters and there is no duplication of field names (e.g., an attribute named 'BoundingBox', 'PointData', etc., or two attributes with the same names).
Otherwise, the following "name mangling" is applied: Illegal characters are replaced by '_'. If the first character in the attribute name is illegal, a leading 'Z' is added. Numerals are appended if needed to avoid duplicate names. The attribute values for a feature are taken from the shapefile and stored as doubles or character arrays:
Attribute Type in Shapefile
MATLAB Storage

Numeric
double (scalar)

Float
double (scalar)

Character
char array

Date
char array

Attribute Type in Shapefile	MATLAB Storage
Numeric	double (scalar)
Float	double (scalar)
Character	char array
Date	char array

Parameter-Value Options

By default, shaperead returns an entry for every nonnull feature and creates a field for every attribute. Use the first three parameters below (RecordNumbers, BoundingBox, and Selector) to be selective about which features to read. Use the fourth parameter (Attributes) to control the attributes to keep. Use the fifth (UseGeoCoords) to control the output field names.

Name	Description of Value	Purpose
`RecordNumbers`	Integer-valued vector, class double	Screen out features whose record numbers are not listed.
`BoundingBox`	2-by-(2, 3, or 4) array, class double	Screen out features whose bounding boxes fail to intersect the selected box. No trimming of features that partially intersect the box is performed.
`Selector`	Cell array containing a function handle and one or more attribute names. Function must return a logical scalar.	Screen out features for which the function, when applied to the corresponding attribute values, returns false.
`Attributes`	Cell array of attribute names	Omit attributes that are not listed. Use `{}` to omit all attributes. Also sets the order of attributes in the structure array.
`UseGeoCoords`	Scalar logical	If `true`, replace `X` and `Y` field names with `Lon` and `Lat`, respectively. Defaults to `false`.

Note If you do not know whether a shapefile uses latitude and longitude or map (planar) coordinates (i.e. contains unprojected or projected geodata), you can read it (or use shapeinfo) to obtain the BoundingBox; the ranges of coordinates may be sufficient information for you to decide what kind of coordinates you have. In some cases you may need to reread the shapefile with or without the 'UseGeoCoords',true argument (it defaults to false), depending on whether you believe the coordinates are geographic latitude and longitude or map x and y, respectively. If you do not specify UseGeoCoords, the mapstruct is returned by shaperead containing X and Y fields rather than Lon and Lat fields. The geoshow function can sense such situations; it issues a warning and calls mapshow to plot mapstructs. The mapshow function refuses to draw geostructs, as it only accepts geographic data structures that have X and Y fields.

Examples

Example 1

Read the entire concord_roads.shp shapefile, including the attributes, in concord_roads.dbf:

S = shaperead('concord_roads.shp');
% Restrict output based on a bounding box and read only two
% of the feature attributes.
bbox = [2.08 9.11; 2.09 9.12] * 1e5;
S = shaperead('concord_roads','BoundingBox',bbox,...
              'Attributes',{'STREETNAME','CLASS'});

% Select the 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'});
N = hist([S.CLASS],1:7)
hist([S.LENGTH])

Example 2

Read worldwide city names and locations in latitude and longitude. Note presence of 'Lat' and 'Lon' fields:

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

S = 
318x1 struct array with fields:
    Geometry
    Lon
    Lat
    Name

Note For details on locating map data for download over the Internet, see the following documentation at the MathWorks Web site: http://www.mathworks.com/support/tech-notes/2100/2101.html.