Documentation

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, filename, and returns an N-by-1 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 parameters. The geographic data structure, S, is a mapstruct unless UseGeoCoords is true. 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.

Input Arguments

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 Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'RecordNumbers'

Integer-valued vector of class double. Use the parameter RecordNumbers to import only features with listed record numbers.

Use the parameters 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.

'BoundingBox'

2-by-2 array of class double. 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.

'Selector'

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.

'Attributes'

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'

Logical scalar that specifies returning shapefile contents in a geostruct, if set to true. Use this parameter when you know that the x- and y- coordinates in the shapefile actually represent longitude and latitude data. (If you do not know whether you are working with geographic or map coordinates, see Mapstructs and Geostructs in the User's Guide.)

Default: false

Output Arguments

S

An N-by-1 geographic data structure array containing an element for each non-null, spatial feature in the shapefile.

A

An N-by-1 attribute structure array, A, parallel to array S.

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 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).

Examples

Read a shapefile of Concord roads and analyze the data.

% Read the entire concord_roads.shp shapefile, including
% the attributes, in concord_roads.dbf.
S = shaperead('concord_roads.shp')

Your output appears as follows:

S = 

609x1 struct array with fields:
    Geometry
    BoundingBox
    X
    Y
    STREETNAME
    RT_NUMBER
    CLASS
    ADMIN_TYPE
    LENGTH

You have a mapstruct with X and Y coordinate vectors.

% Restrict output based on 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'})

Your output appears as follows:

S = 

87x1 struct array with fields:
    Geometry
    BoundingBox
    X
    Y
    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'})

Your output appears as follows:

S = 

115x1 struct array with fields:
    Geometry
    BoundingBox
    X
    Y
    STREETNAME
    RT_NUMBER
    CLASS
    ADMIN_TYPE
    LENGTH
% Determine the number of roads of each class.
N = hist([S.CLASS],1:7)

Your output appears as follows:

N =

     0     0     0     7    93    15     0
% Display a histogram of the number of roads 
% that fall in each category of length.
hist([S.LENGTH])

Read a shapefile of worldwide city names and locations in latitude and longitude.

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

Your output appears as follows:

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

You set 'UseGeoCoords' to true, so you received a geostruct.

Was this topic helpful?