shp-to-geojson

shp-to-geojson

- A small library for converting shapefiles to geojson
- Usable in both node and the browser (~30kb in the browser minified with all dependencies).
- Works with remote url's, filepaths (inc zipped) in node, or arraybuffer's (eg for in drag-drop scenarios in the browser)
- Offers a streaming API as well, as a method to return the whole FeatureCollection.

$3

``
import ShpToGeoJson from 'shp-to-geojson'
// Or in the browser
import ShpToGeoJson from 'shp-to-geojson/dist/shp-to-geojson.browser.js'

// Loading From a FilePath in NodeJS
const shp = new ShpToGeoJson({
filePath: "./test/points.shp"
})

// Get a GeoJson FeatureCollection
const featureCollection = shp.getGeoJson()

// Get a stream of features
const stream = shp.streamGeoJsonFeatures()
let featureIterator = stream.next()
while (!featureIterator.done) {
const feature = featureIterator.value
featureIterator = stream.next()
}
`

More Usage Examples
- Loading data from a Remote URL
- Drag-n-Drop zipped shp uploaded by the user in the browser (demonstrating the shpBuffer and dbfBuffer options)
- Reprojecting with proj4
- Streaming individual features
- Work in progress (not yet proper streaming without reading the whole buffer)


#### Options

Option | Description | Example
------------ | ------------- | -------------
remotePath | A url to a .shp | https://someurl/points.shp
filePath | A filepath resolved in NodeJS using fs.loadFile | data/countries.shp
filePathZipped | A zipped file available in NodeJS | data/countries.zip
arraybuffers | An object containing shpBuffer, dbfBuffer, and projString keys | {shpBuffer: new ArrayBuffer(), dbfBuffer: new ArrayBuffer(), projString: ''}

#### Methods

Method | Returns | Description
------------ | ------------- | -------------
load | Promise | Required if loading using the remotePath option
getGeoJson | Geojson FeatureCollection | Returns a geojson FeatureCollection
streamGeoJsonFeatures | Generator | Returns a js generator for iterating through features


#### Properties

Property | Description
-------------- | -------------
summary | Returns the type of feature, number of features, bbox, and crs. Requires .load() to be have been called when using the remotePath option
loaded | Returns true/false whether the data has been loaded.




$3


This library appears to perform very well when there are lots of attributes compared to most other js libraries out there.
``
3,000 polygons with 40 attributes
shp-to-geojson x 13.68 ops/sec ±3.37% (39 runs sampled)
shpjs x 3.19 ops/sec ±2.75% (12 runs sampled)
shp x 10.60 ops/sec ±6.74% (31 runs sampled)
shapefile x 1.10 ops/sec ±3.14% (10 runs sampled)
- Fastest is shp-to-geojson
``
Note that the shp library while fast, it only works in NodeJS, and doesn't parse attributes nicely.

When there are minimal attributes this lib performs pretty similarly to other libs out there.
``
200 countries with a single attribute
shp-to-geojson x 67.47 ops/sec ±3.61% (63 runs sampled)
shpjs x 63.74 ops/sec ±2.83% (64 runs sampled)
shapefile x 57.47 ops/sec ±7.71% (69 runs sampled)
- Fastest is shp-to-geojson
``

$3


1. I found the API's of some of the existing libraries pretty unintuitive
2. Some of them were only compatible with node (eg shp), I wanted something that worked in both browser and node with the same API
3. Some struggled with parsing attributes nicely (eg shp`)
4. I wanted something that worked with z values.
5. I was intrigued to have a go at writing my first parsing library and getting experience with raw buffer data.

$3

- Esri Shapefile Spec
- DBF Material
- More DBF Material

Thanks

Thanks to creators/maintainers of other shapefiles parsers out there, I leaned on some of their buffer reading skills to grow my own understanding.