Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/uber/geojson2h3

Conversion utilities between H3 indexes and GeoJSON
https://github.com/uber/geojson2h3

geojson geospatial h3 hexagon javascript

Last synced: 3 months ago
JSON representation

Conversion utilities between H3 indexes and GeoJSON

Host: GitHub
URL: https://github.com/uber/geojson2h3
Owner: uber
License: apache-2.0
Created: 2018-06-22T20:46:11.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2023-07-21T19:07:30.000Z (over 1 year ago)
Last Synced: 2024-10-02T03:25:03.621Z (4 months ago)
Topics: geojson, geospatial, h3, hexagon, javascript
Language: JavaScript
Homepage:
Size: 318 KB
Stars: 225
Watchers: 16
Forks: 22
Open Issues: 6
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-starred - uber/geojson2h3 - Conversion utilities between H3 indexes and GeoJSON (javascript)

README

        

# geojson2h3

[![test](https://github.com/uber/geojson2h3/workflows/test/badge.svg)](https://github.com/uber/geojson2h3/actions)

[![Coverage Status](https://coveralls.io/repos/github/uber/geojson2h3/badge.svg?branch=master)](https://coveralls.io/github/uber/geojson2h3?branch=master)

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

[![npm version](https://badge.fury.io/js/geojson2h3.svg)](https://badge.fury.io/js/geojson2h3)

The `geojson2h3` library includes a set of utilities for conversion between GeoJSON polygons and [H3 hexagon indexes](https://h3geo.org), using [h3-js](https://github.com/uber/h3-js).

-   Post **bug reports or feature requests** to the [Github Issues page](https://github.com/uber/geojson2h3/issues)

-   Ask **questions** by posting to the [H3 tag on StackOverflow](https://stackoverflow.com/questions/tagged/h3)

## Installation

```

npm install geojson2h3

```

## Example Usage

```javascript

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](#module_geojson2h3)

    * [.featureToH3Set(feature, resolution, [options])](#module_geojson2h3.featureToH3Set) ⇒ Array.<String>

    * [.h3ToFeature(hexAddress, [properties])](#module_geojson2h3.h3ToFeature) ⇒ Feature

    * [.h3SetToFeature(hexagons, [properties])](#module_geojson2h3.h3SetToFeature) ⇒ Feature

    * [.h3SetToMultiPolygonFeature(hexagons, [properties])](#module_geojson2h3.h3SetToMultiPolygonFeature) ⇒ Feature

    * [.h3SetToFeatureCollection(hexagons, [getProperties])](#module_geojson2h3.h3SetToFeatureCollection) ⇒ FeatureCollection

* * *



### geojson2h3.featureToH3Set(feature, resolution, [options]) ⇒ 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.

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.

![featureToH3Set](./doc-files/featureToH3Set.png)

**Kind**: static method of [geojson2h3](#module_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] | Object | Options |

| [options.ensureOutput] | Boolean | Whether to ensure that at least one                              cell is returned in the set |

* * *



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

Convert a single H3 hexagon to a `Polygon` feature

**Kind**: static method of [geojson2h3](#module_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.

![h3SetToFeature](./doc-files/h3SetToFeature.png)

**Kind**: static method of [geojson2h3](#module_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.

![h3SetToMultiPolygonFeature](./doc-files/h3SetToFeatureCollection.png)

**Kind**: static method of [geojson2h3](#module_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.

![h3SetToFeatureCollection](./doc-files/h3SetToFeatureCollection.png)

**Kind**: static method of [geojson2h3](#module_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](https://github.com/uber/geojson2h3/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](http://cla-assistant.io/uber/geojson2h3).

## Legal and Licensing

The `geojson2h3` library is licensed under the [Apache 2.0 License](https://github.com/uber/geojson2h3/blob/master/LICENSE).