xih / geojson2h3

Conversion utilities between H3 indexes and GeoJSON

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

---

geojson2h3.featureToH3Set(feature, resolution) ⇒ Array.<String>

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.

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

---

geojson2h3.h3ToFeature(hexAddress, [properties]) ⇒ Feature

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

---

geojson2h3.h3SetToFeature(hexagons, [properties]) ⇒ Feature

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

---

geojson2h3.h3SetToMultiPolygonFeature(hexagons, [properties]) ⇒ Feature

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

---

geojson2h3.h3SetToFeatureCollection(hexagons, [getProperties]) ⇒ FeatureCollection

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(hexAddress) => 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.