Add H3 layers #2808

Pessimistress · 2019-03-16T03:40:26Z

For #2443

H3HexagonLayer (instanced):

H3ClusterLayer (renders geojson polygons):

Change List

Add H3HexagonLayer and H3ClusterLayer
API documentation
Tests

coveralls · 2019-03-16T03:50:08Z

Coverage increased (+0.2%) to 58.982% when pulling d8993c1 on h3-layers into 5aa5714 on master.

akre54

This looks great and will help us a ton, thanks @Pessimistress!

heshan0131 · 2019-03-19T19:35:06Z

modules/geo-layers/src/h3-layers/h3-hexagon-layer.js

+  renderLayers() {
+    const {data, getHexagon, updateTriggers} = this.props;
+
+    const SubLayerClass = this.getSubLayerClass('hexagon-cell', ColumnLayer);


Does ColumnLayer handle calculation of normals based on vertices in the primitive geometry?

Not yet, it currently assumes that normals are close enough to the regular polygon. We do not render normals correctly anyways (normals are interpolated instead of flat for each side).

normals are interpolated instead of flat for each side

Unless we have some other good ideas, the standard solution is to duplicate vertices for the edges. Since this leads to a bigger geometry, we may want to have that as an option/prop on the ColumnLayer: shading: 'flat' or shading; 'smooth'.

The ColumnLayer is currently using CylinderGeometry from luma. I feel this option needs to be added at the source.

That could make sense. Opened luma issue visgl/luma.gl#994, so that deck can reference this in a follow-up tracker ticket for the H3 layers.

heshan0131 · 2019-03-19T19:37:03Z

test/render/test-cases.js

+        data: h3.kRing('882830829bfffff', 4),
+        getHexagon: d => d,
+        getColor: (d, {index}) => [255, index * 5, 0],
+        getElevation: (d, {index}) => index * 100


is it possible to add another getCoverage accessor?

Yes? What is the use case, do we need different coverage for each hexagon?

As shown here https://twitter.com/carnby/status/1059530716269154306
It's useful for odt analysis

kepler.gl currently edited shader to enable instanceCoverage
https://github.com/uber/kepler.gl/blob/master/src/deckgl-layers/h3-hexagon-cell-layer/h3-hexagon-cell-layer.js#L26-L41

Will do in a follow up PR.

ibgreen

Looks quite thorough, nice work!

The best validation of the updates would be to update internal apps to use the open source versions.
Do we want to give ourself some freedom until then by marking these as experiments (could just be marked after title, no underscore or similar)?

ibgreen · 2019-03-19T19:46:51Z

docs/layers/h3-cluster-layer.md

+
+# H3ClusterLayer
+
+The H3ClusterLayer Layer renders regions represented by hexagon sets from the [h3](https://uber.github.io/h3/) geospatial indexing system.


Nit: backticks around class names

Perhaps worth auditing the naming with H3 folks. At the time I was working with the library, a cluster wasn't a thing, maybe there is a term that fits better?

@nrabinowitz @isaacbrodsky

An idea is that it would ultimately be nice to offer some level of "parity" between H3 and S2 layers, so a similar cluster layer could be on the roadmap for S2 layers...

docs/layers/h3-hexagon-layer.md

ibgreen · 2019-03-19T19:52:55Z

docs/layers/h3-hexagon-layer.md

+
+## Remarks
+
+* Each hexagon in the H3 indexing system is [slightly different in shape](https://uber.github.io/h3/#/documentation/core-library/coordinate-systems). To draw a large number of hexagons efficiently, the H3HexagonLayer assumes that all hexagons within the current viewport have the same shape as the one at the center of the current viewport. This strategy is usually sufficient. However, the discrepancy may become visually significant at rare geolocations. In that case, the [H3ClusterLayer] can be used as an alternative by trading performance for accuracy.


Backticks.

In spite of being a composite layer, this only handles one H3 aperture, maybe mention that?

Top aperture has mix of hexagons and pentagons, comment that this is not covered?

It is mentioned in the description of getHexagon.

If I can interject, every aperture has a mix of hexagons and pentagons. The pentagons have simply been placed in water so common use-cases do not run into them.

This will require some changes in the ColumnLayer, will do in a follow up PR. Do you have a hex id I can test with?

Sure. One example pentagon at resolution 9 is 891c0000003ffff.

(To be fair, when I said "a mix of hexagons and pentagons" there are always 12 pentagons at each resolution, so the higher the resolution it becomes far, far less likely to run into one.)

You may also want to run a kRing of 10 or 20 around that pentagon, since pentagons are at the epicenter of the hexagon distortions and you're going to run into essentially 5 different hexagon shapes in that area (one for each of the icosahedron faces the hexagons are on, and technically some really weird ones that are split across the icosahedron boundaries).

ibgreen · 2019-03-19T19:53:32Z

examples/layer-browser/src/examples/additional-layers.js

@@ -4,11 +4,14 @@ import {
  MeshLayer,
  ScenegraphLayer,
  GreatCircleLayer,
-  S2Layer
+  S2Layer,


Playing with alignment... S2CellLayer?

ibgreen · 2019-03-19T19:57:52Z

modules/geo-layers/src/h3-layers/h3-hexagon-layer.js

+  renderLayers() {
+    const {data, getHexagon, updateTriggers} = this.props;
+
+    const SubLayerClass = this.getSubLayerClass('hexagon-cell', ColumnLayer);


normals are interpolated instead of flat for each side

Unless we have some other good ideas, the standard solution is to duplicate vertices for the edges. Since this leads to a bigger geometry, we may want to have that as an option/prop on the ColumnLayer: shading: 'flat' or shading; 'smooth'.

ibgreen · 2019-03-19T20:01:47Z

website/contents/pages.js

@@ -407,6 +407,14 @@ export const docPages = generatePath([
            name: 'GridCellLayer',
            content: getDocUrl('layers/grid-cell-layer.md')
          },
+          {
+            name: 'H3HexagonLayer',
+            content: getDocUrl('layers/h3-hexagon-layer.md')


Nit: I think we should have a separate index rather than duplicate layers in two places just to get an alphabetic list. An index could be easily auto-generated by ocular once we port the deck website after v7 release. The docs should just contain folders corresponding to the modules. If keeping this.

modules/geo-layers/src/h3-layers/h3-hexagon-layer.js

docs/layers/h3-cluster-layer.md

docs/layers/h3-hexagon-layer.md

isaacbrodsky · 2019-03-19T21:25:49Z

docs/layers/h3-hexagon-layer.md

+
+<p class="badges">
+  <img src="https://img.shields.io/badge/64--bit-support-blue.svg?style=flat-square" alt="64-bit" />
+  <img src="https://img.shields.io/badge/extruded-yes-blue.svg?style=flat-square" alt="extruded" />


Do we want to add an H3 version badge, similar to what we have on the binding readme: http://github.com/uber/h3-js?

I don't expect the JavaScript API to be important here, but the version of the indexing system definitely matters. How stable is the h3-js API? Could we relax the dependency to something like ">=2" so users may pick their version?

As long as it's the same major version it should be fine. cc @nrabinowitz

Honestly even the major version of the library shouldn't matter, as long as it's the same index version.

isaacbrodsky · 2019-03-19T21:29:14Z

modules/geo-layers/src/h3-layers/h3-hexagon-layer.js

+    if (resolution < 0) {
+      return;
+    }
+    const hex = geoToH3(viewport.latitude, viewport.longitude, resolution);


What happens if this is a pentagon?

Discussed offline with @Pessimistress - the responsibility is on the user to use this fast version only if they're willing to deal with occasional issues arising from pentagons and crossing icosahedron edges.

Pessimistress requested review from nrabinowitz, ericsoco, heshan0131, ibgreen and akre54 March 16, 2019 03:40

akre54 approved these changes Mar 18, 2019

View reviewed changes

Pessimistress force-pushed the h3-layers branch from fcda927 to 7bb036f Compare March 18, 2019 20:37

heshan0131 reviewed Mar 19, 2019

View reviewed changes

Pessimistress force-pushed the h3-layers branch from d565af9 to 79e57f4 Compare March 19, 2019 19:50

ibgreen approved these changes Mar 19, 2019

View reviewed changes

isaacbrodsky reviewed Mar 19, 2019

View reviewed changes

Ib Green and others added 6 commits March 19, 2019 16:39

Add h3-layers catalog

4c6a388

move h3-layers into geo-layers module

b9eca82

add tests

41124ea

address comments

eef3f60

address comments

feee12d

rebase master

d8993c1

Pessimistress force-pushed the h3-layers branch from 374c8f5 to d8993c1 Compare March 19, 2019 23:47

Pessimistress merged commit 7c693e7 into master Mar 20, 2019

Pessimistress deleted the h3-layers branch March 20, 2019 00:23

ibgreen mentioned this pull request Mar 20, 2019

Support Flat Shading in Geometries, esp. CylinderGeometry visgl/luma.gl#994

Closed

6 tasks

Pessimistress mentioned this pull request Mar 29, 2019

Add highPrecision prop to H3HexagonLayer #2866

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add H3 layers #2808

Add H3 layers #2808

Pessimistress commented Mar 16, 2019

coveralls commented Mar 16, 2019 •

edited

Loading

akre54 left a comment

heshan0131 Mar 19, 2019

Pessimistress Mar 19, 2019 •

edited

Loading

ibgreen Mar 19, 2019

Pessimistress Mar 19, 2019

ibgreen Mar 20, 2019

heshan0131 Mar 19, 2019

Pessimistress Mar 19, 2019

heshan0131 Mar 19, 2019

Pessimistress Mar 19, 2019

ibgreen left a comment

ibgreen Mar 19, 2019

ibgreen Mar 19, 2019

ibgreen Mar 19, 2019

Pessimistress Mar 19, 2019

dfellis Mar 19, 2019

Pessimistress Mar 19, 2019

dfellis Mar 20, 2019

dfellis Mar 20, 2019

ibgreen Mar 19, 2019

ibgreen Mar 19, 2019

ibgreen Mar 19, 2019

isaacbrodsky Mar 19, 2019

Pessimistress Mar 19, 2019 •

edited

Loading

isaacbrodsky Mar 20, 2019

nrabinowitz Mar 20, 2019

isaacbrodsky Mar 19, 2019

nrabinowitz Mar 20, 2019


		# H3ClusterLayer

		The H3ClusterLayer Layer renders regions represented by hexagon sets from the [h3](https://uber.github.io/h3/) geospatial indexing system.


		## Remarks

		* Each hexagon in the H3 indexing system is [slightly different in shape](https://uber.github.io/h3/#/documentation/core-library/coordinate-systems). To draw a large number of hexagons efficiently, the H3HexagonLayer assumes that all hexagons within the current viewport have the same shape as the one at the center of the current viewport. This strategy is usually sufficient. However, the discrepancy may become visually significant at rare geolocations. In that case, the [H3ClusterLayer] can be used as an alternative by trading performance for accuracy.

Add H3 layers #2808

Add H3 layers #2808

Conversation

Pessimistress commented Mar 16, 2019

Change List

coveralls commented Mar 16, 2019 • edited Loading

akre54 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Pessimistress Mar 19, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ibgreen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Pessimistress Mar 19, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Mar 16, 2019 •

edited

Loading

Pessimistress Mar 19, 2019 •

edited

Loading

Pessimistress Mar 19, 2019 •

edited

Loading