Function File: [outstruct ] = shaperead (shp_filename)

Function File: [outstruct ] = shaperead (shp_filename, outstyle)

Function File: [outstruct ] = shaperead (shp_filename, outstyle, opts)

Function File: [outstruct, atts ] = shaperead (shp_filename, ...)

Read an ArcGis shapefile set (shp, shx and dbf).

Depending on the value of outstyle some different output formats will be returned:

0 (numeric)

ml (case-insensitive)

m

Return a Matlab-compatible M X 1 struct with a separate entry for each shape feature in the shape file. Each struct element contains fields "Geometry" (shape type), "BoundingBox" ([minX minY ; maxX maxY]), X, Y (coordinates of points in the shape item as row vectors). For multi-part items, the coordinates of each part are separated by NaNs. This output format supports neither M and Z type nor MultiPatch shape features. For M and Z type shape features the M and Z values will simply be ignored. The struct is augmented with attributes found in the accompanying .dbf file, if found.

For ML-style output, if only one output argument is requested the attributes in the .dbf file will be augmented to that struct. If two output arguments are requested, the attributes will be returned separately in output struct atts.

1 (numeric)

ext (case-insensitive)

e

Same as 1 but M and Z type and MultiPatch shape features are accepted. The resulting output struct is no more ML-compatible. If the shapefile contains M and/or Z type shape features the mapstruct or geostruct has extra fields M and -optionally- Z. Note that MultiPatch shape features may not have M-values even if Z-values are present. For MultiPatch shapes another field Parts is added, a Px2 array with zero-based indices to the first vertex of each subfeature in the XYZ fields in column 1 and the type of each subfeature in column 2; P is the number of shape feature parts.

2 (numeric)

oct (case-insensitive)

o

Return a struct containing a N X 6 double array "vals" containing the X, Y, and Z coordinates, M-values, record nr. and type of each point in the shape file. If no M or Z values were present the relevant columns contain NaNs. Individual shape features and shape parts are separated by a row of NaN values. The field "idx" contains 1-based pointers into field vals to the first vertex of each shape feature. Field "bbox" contains an 8 X M double array of XYZ coordinates of the bounding boxes and min/max M-values corresponding to the M items found in the .shp file; for point shapes these contain NaNs. Field "npt" contains a 1 X M array of the number of points for each item. Field "npr" contains a 1 X M cell array containing a row of P part indices (zero-based) for each Polyline, Polygon or MultiPatch part in the shape file; for multipatch each cell contains another row with the part types; for other item types (point etc.) the cell array contains empty rows. A separate field "shpbox" contains the overall bounding box X, Y and Z coordinates and min/max M-values in a 4 X 2 double array. If the shape file contains no Z or M values the corresponding columns are filled with NaNs.

The struct field "fields" contains a cellstr array with names of the columns. If a corresponding .dbf file was read, the struct array also contains a field for each attribute found in the .dbf file with the corresponding field name, each containing a 1 X M array of attribute values matching the M items in the .shp file. These arrays can be double, char or logical, depending on the type found in the .dbf file.

3 (numeric)

dat (case-insensitive)

d

Same as OCT or 0 but without a row of NaN values between each shape file item in the VALS array.

If a character option is given, just one character will suffice. The default for outstyle is "ml".

The output of ’shaperead’ can be influenced by property-value pairs. The following properties are recognized (of which only the first three characters are significant, case doesn’t matter):

Attributes

Normally all attributes associated with the shape features will be read and returned in the output struct(s). To limit this to just some attributes, enter a value consisting of a cell array of attribute names to be read. To have no attributes read at all, specify {}, an empty cell array.
Attributes "Geometry", "BoundingBox", "X", "Y", "Lat", and "Lon" are contained within the .shp file and will be returned in any case. If specified these values will be ignored. In the unlikely case that the associated .dbf file also contains these attributes (truncated to 10 characters) they will be prepended with an underscore (_).

BoundingBox

Select only those shape items (features) whose bounding box lies within, or intersects in at least one point with the limits of the BoundingBox value (a 2 X 2 double array [Minx, MinY; MaxX, MaxY]). No intersection or clipping with the BoundingBox value will be done by default!

Clip

(only useful in conjuction with the BoundingBox property) If a value of 1 or true is supplied, clip all shapes to the bounding box limits. This option may take quite a bit of processing time. If a value of "0" or false is given, do not perform clipping. The default value is 0. Clipping is merely meant to be performed in the XY plane. Clipping 3D shapes is supported but may lead to unexpected results. For Z and M type polylines and polygons including MultiPatch and Longitude/Latitude/Height types, Z (Height) and M values for each vertex in the clipped shape feature are simply copied over from the nearest vertex in the original shape feature. This implies that Z and M values of new vertices created on the bounding box edges may be less optimal.

For clipping polylines and polygons the Octave-Forge geometry package needs to be installed and loaded.

Debug

If a value of ’true’ or 1 is given, shaperead echoes the current record number while reading. Can be useful for very big shapefiles. The default value is 0 (no feedback). If a Matlab-compatible output structarray is requested and the Bounding Box property is specified, the extracted shape feature indices are added to the field "___Shape_feature_nr___".

RecordNumbers

Select only those records whose numbers are listed as integer values in an array following RecordNumbers property. Neither the size nor the class of the array matters as long as it is a numeric array.

UseGeoCoords

(Only applicable if a Matlab-style output struct is requested). If a value of ’true’ (or 1) is supplied, return a geostruct rather than a mapstruct. If a value of 0 or false is given, return a mapstruct. The mere difference is that in a geostruct the fields ’X’ and ’Y’ (and optionally ’Z’) are replaced by ’Long’ and ’Lat’ (and ’Hght’). The default value is ’false’ (return a mapstruct’).

Ref: http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf

See also: geoshow, mapshow, shapedraw, shapeinfo.

Package: mapping