geojson2h3
The geojson2h3
library includes a set of utilities for conversion between GeoJSON polygons and H3 hexagon indexes, using h3-js.
- Post bug reports or feature requests to the Github Issues page
- Ask questions by posting to the H3 tag on StackOverflow
Installation
npm install geojson2h3
Example Usage
import geojson2h3 from 'geojson2h3';
const polygon = {
type: 'Feature',
geometry: {
type: 'Polygon',
coordinates: [[
[-122.47485823276713, 37.85878356045377],
[-122.47504834087829, 37.86196795698972],
[-122.47845104316997, 37.86010614563313],
[-122.47485823276713, 37.85878356045377]
]]
}
};
const hexagons = geojson2h3.featureToH3Set(polygon, 10);
// -> ['8a2830855047fff', '8a2830855077fff', '8a283085505ffff', '8a283085506ffff']
const feature = geojson2h3.h3SetToFeature(hexagons);
// -> {type: 'Feature', properties: {}, geometry: {type: 'Polygon', coordinates: [...]}}
API Reference
geojson2h3
- geojson2h3
- .featureToH3Set(feature, resolution) ⇒
Array.<String>
- .h3ToFeature(hexAddress, [properties]) ⇒
Feature
- .h3SetToFeature(hexagons, [properties]) ⇒
Feature
- .h3SetToMultiPolygonFeature(hexagons, [properties]) ⇒
Feature
- .h3SetToFeatureCollection(hexagons, [getProperties]) ⇒
FeatureCollection
- .featureToH3Set(feature, resolution) ⇒
Array.<String>
geojson2h3.featureToH3Set(feature, resolution) ⇒ Convert a GeoJSON feature to a set of hexagons. Only hexagons whose centers fall within the feature will be included. Note that conversion from GeoJSON is lossy; the resulting hexagon set only approximately describes the original shape, at a level of precision determined by the hexagon resolution.
If the polygon is small in comparison with the chosen resolution, there may be
no cell whose center lies within it, resulting in an empty set. To fall back
to a single H3 cell representing the centroid of the polygon in this case, use
the ensureOutput
option.
Kind: static method of geojson2h3
Returns: Array.<String>
- H3 indexes
Param | Type | Description |
---|---|---|
feature | Object |
Input GeoJSON: type must be either Feature or FeatureCollection , and geometry type must be either Polygon or MultiPolygon |
resolution | Number |
Resolution of hexagons, between 0 and 15 |
[options.ensureOutput] | Boolean |
Whether to ensure that at least one cell is returned in the set |
Feature
geojson2h3.h3ToFeature(hexAddress, [properties]) ⇒ Convert a single H3 hexagon to a Polygon
feature
Kind: static method of geojson2h3
Returns: Feature
- GeoJSON Feature object
Param | Type | Description |
---|---|---|
hexAddress | String |
Hexagon address |
[properties] | Object |
Optional feature properties |
Feature
geojson2h3.h3SetToFeature(hexagons, [properties]) ⇒ Convert a set of hexagons to a GeoJSON Feature
with the set outline(s). The
feature's geometry type will be either Polygon
or MultiPolygon
depending on
the number of outlines required for the set.
Kind: static method of geojson2h3
Returns: Feature
- GeoJSON Feature object
Param | Type | Description |
---|---|---|
hexagons | Array.<String> |
Hexagon addresses |
[properties] | Object |
Optional feature properties |
Feature
geojson2h3.h3SetToMultiPolygonFeature(hexagons, [properties]) ⇒ Convert a set of hexagons to a GeoJSON MultiPolygon
feature with the
outlines of each individual hexagon.
Kind: static method of geojson2h3
Returns: Feature
- GeoJSON Feature object
Param | Type | Description |
---|---|---|
hexagons | Array.<String> |
Hexagon addresses |
[properties] | Object |
Optional feature properties |
FeatureCollection
geojson2h3.h3SetToFeatureCollection(hexagons, [getProperties]) ⇒ Convert a set of hexagons to a GeoJSON FeatureCollection
with each hexagon
in a separate Polygon
feature with optional properties.
Kind: static method of geojson2h3
Returns: FeatureCollection
- GeoJSON FeatureCollection object
Param | Type | Description |
---|---|---|
hexagons | Array.<String> |
Hexagon addresses |
[getProperties] | function |
Optional function returning properties for a hexagon: f(h3Index) => Object |
Development
The geojson2h3
library uses yarn
as the preferred package manager. To install the dev dependencies, just run:
yarn
To run the tests in both native ES6 (requires Node >= 6) and transpiled ES5:
yarn test
To format the code:
yarn prettier
To rebuild the API documentation in the README file:
yarn build-docs
Contributing
Pull requests and Github issues are welcome. Please include tests for new work, and keep the library test coverage at 100%. Before we can merge your changes, you must agree to the Uber Contributor License Agreement.
Legal and Licensing
The geojson2h3
library is licensed under the Apache 2.0 License.