| 1 |
# Streaming Shapefile Parser |
| 2 |
|
| 3 |
Based on the [ESRI Shapefile Technical Description](http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf) and [dBASE Table File Format](http://www.digitalpreservation.gov/formats/fdd/fdd000325.shtml). |
| 4 |
|
| 5 |
Caveat emptor: this library is a work in progress and does not currently support all shapefile geometry types (see [shp.js](https://github.com/mbostock/shapefile/blob/master/shp.js) for details). It also only supports dBASE III and has no error checking. Please contribute if you want to help! |
| 6 |
|
| 7 |
## Reading a Shapefile |
| 8 |
|
| 9 |
<a name="read" href="#read">#</a> shapefile.<b>read</b>(<i>filename</i>[, <i>options</i>], <i>callback</i>) |
| 10 |
|
| 11 |
A convenience API for reading an entire shapefile in one go. Use this method if you don’t mind putting the whole shapefile in memory; use <a href="#reader">reader</a> instead if you want to process records individually. The specified *callback* with two arguments: |
| 12 |
|
| 13 |
* *error* - the error, if any |
| 14 |
* *collection* - a [GeoJSON feature collection](http://geojson.org/geojson-spec.html#feature-collection-objects) |
| 15 |
|
| 16 |
The *collection* has a `bbox` property containing representing the bounding box of all records in this shapefile. The bounding box is specified as [xmin, ymin, xmax, ymax], where *x* and *y* represent longitude and latitude in spherical coordinates. |
| 17 |
|
| 18 |
## Streaming a Shapefile |
| 19 |
|
| 20 |
<a name="reader" href="#reader">#</a> shapefile.<b>reader</b>(<i>filename</i>[, <i>options</i>]) |
| 21 |
|
| 22 |
The main API for reading a shapefile. The supported options are: |
| 23 |
|
| 24 |
* *encoding* - the DBF encoding (defaults to ISO-8859-1) |
| 25 |
* *ignore-properties* - if true, don’t read properties (faster; defaults to false) |
| 26 |
|
| 27 |
This method returns a reader object. |
| 28 |
|
| 29 |
<a name="reader_readHeader" href="#reader_readHeader">#</a> reader.<b>readHeader</b>(<i>callback</i>) |
| 30 |
|
| 31 |
Reads the shapefile header, invoking the specified *callback* with two arguments: |
| 32 |
|
| 33 |
* *error* - the error, if any |
| 34 |
* *header* - the header object |
| 35 |
|
| 36 |
The *header* object is simply an object with a `bbox` property representing the bounding box of all records in this shapefile. The bounding box is specified as [xmin, ymin, xmax, ymax], where *x* and *y* represent longitude and latitude in spherical coordinates. |
| 37 |
|
| 38 |
<a name="reader_readRecord" href="#reader_readRecord">#</a> reader.<b>readRecord</b>(<i>callback</i>) |
| 39 |
|
| 40 |
Reads the next shapefile record, invoking the specified *callback* with two arguments: |
| 41 |
|
| 42 |
* *error* - the error, if any |
| 43 |
* *record* - the record object, or <a href="#end">shapefile.end</a> |
| 44 |
|
| 45 |
The *record* object is a [GeoJSON feature](http://geojson.org/geojson-spec.html#feature-objects). (GeoJSON objects are the standard representation of geometry in JavaScript, and they are convenient. If you want to access the shapefile primitives directly, use the private [shp](https://github.com/mbostock/shapefile/blob/master/shp.js) and [dbf](https://github.com/mbostock/shapefile/blob/master/dbf.js) classes instead.) |
| 46 |
|
| 47 |
If there are no more records in this shapefile, the *record* is the special value <a href="#end">shapefile.end</a>. |
| 48 |
|
| 49 |
<a name="reader_close" href="#reader_close">#</a> reader.<b>close</b>(<i>callback</i>) |
| 50 |
|
| 51 |
Closes the underlying files for this reader. You should call this when you are done reading. If an error occurs during <a href="#reader_readHeader">readHeader</a> or <a href="#reader_readRecord">readRecord</a>, the reader will be closed automatically. |
| 52 |
|
| 53 |
<a name="end" href="#end">#</a> shapefile.<b>end</b> |
| 54 |
|
| 55 |
A sentinel value used <a href="#reader_readRecord">readRecord</a> to indicate that the end of the file has been reached, and no more records are available. (Note that if the end of file is reached when <a href="#reader_readHeader">readHeader</a> is called, this is considered an error because the header is required by the shapefile format.) |