Skip to content

H3 hexagons and categories

--h3 bins each layer’s points into H3 hexagons below a base zoom, and shows the points themselves from there. A dense layer of points becomes a map of where they are at low zooms, without dropping any.

Terminal window
manby -z14 --h3 --accumulate-attribute=capacity:sum -o plants.pmtiles plants.geojson

The hexagons go in a layer of their own, <layer>_h3, a resolution for each zoom, and the points from --h3-base-zoom, two below the maximum zoom unless given. With -zg, the base zoom must be given.

Zoom 0-1 2-3 4 5 6-7 8 9-10 11 12-13 14
Resolution 1 2 3 4 5 6 7 8 9 10

Beyond zoom 14 the resolution is seven tenths of the zoom, up to 15, as in freestiler.

  • --h3-resolutions=Z:R,... sets the resolution at the zooms given, such as --h3-resolutions=4:4,5:4 for coarser hexagons at zoom 5.
  • --h3-fade=N shows each resolution N zooms beyond its own on each side, and the points from N zooms before the base zoom, so a style can fade from one to the next.
  • --h3-no-points makes only the hexagons, at every zoom to the maximum, and leaves the points out.
Terminal window
manby -z10 --h3-no-points --h3-fade=1 -o places.pmtiles places.parquet

Each hexagon has h3, its cell, h3_resolution and point_count, the points in it.

  • --accumulate-attribute=name:op adds up an attribute of the points of each hexagon, with tippecanoe’s operations sum, product, mean, max, min and count, as it does for clusters.
  • --h3-median=name gives the median of an attribute, the mean of the middle two for an even number of values, as DuckDB’s MEDIAN gives it. It keeps every value until the hexagons are made.
  • --h3-categories=name counts the values of an attribute, as name:value. The 64 most common values are counted by name, and the rest, and points without the attribute, as name:_other. Each hexagon also gets the most common value as modal_category, its count as modal_count, its share of the points as modal_share, and modal_tie, which is true when two or more values are the most common. Then there is no modal_category.
Terminal window
manby -z14 --h3 --h3-categories=kind --h3-median=price -o places.pmtiles places.parquet

A point is binned into its cell of each resolution, as freestiler bins it, rather than into the parent of its finer cell, since H3’s cells don’t nest exactly. The hexagons are the same as freestiler’s, with the same counts, medians and modes.

The hexagons are tiled as any polygons are, so tippecanoe’s size limit and dropping apply to them as well.

A fill layer on the hexagons, colored by their points.

map.addLayer({
id: 'places-hexagons',
type: 'fill',
source: 'places',
'source-layer': 'places_h3',
paint: {
'fill-color': ['interpolate', ['linear'], ['ln', ['get', 'point_count']], 0, '#fde725', 10, '#440154'],
'fill-opacity': 0.7,
},
});

With --h3-fade, two resolutions share the zooms where they overlap. A layer for each resolution, picked by h3_resolution, can fade it in and out over its zooms. Here resolution 5, made for zooms 6 and 7 and in the tiles of 5 to 8 with --h3-fade=1, fades in from zoom 5 and out by zoom 8.

map.addLayer({
id: 'places-r5',
type: 'fill',
source: 'places',
'source-layer': 'places_h3',
filter: ['==', ['get', 'h3_resolution'], 5],
paint: {
'fill-color': ['interpolate', ['linear'], ['ln', ['get', 'point_count']], 0, '#fde725', 10, '#440154'],
'fill-opacity': ['interpolate', ['linear'], ['zoom'], 5, 0, 6, 0.7, 7, 0.7, 8, 0],
},
});

From R and Python, h3_sql gives the hexagons aggregates written in DuckDB’s SQL, any that DuckDB has, over the points of each cell. DuckDB, with its spatial and H3 extensions, computes them for each cell of every resolution, and manby puts them on the hexagons of those cells.

tile(places, "places.pmtiles", maximum_zoom = 12, h3 = TRUE,
h3_sql = c(p90 = "quantile_cont(price, 0.9)", kinds = "count(DISTINCT kind)"))
manby.tile(places, "places.pmtiles", maximum_zoom=12, h3=True,
h3_sql={"p90": "quantile_cont(price, 0.9)", "kinds": "count(DISTINCT kind)"})

It takes sf data frames and GeoDataFrames, DuckDB tables, Arrow tables, Parquet files and the files that GDAL reads, with points in WGS 84. With several layers, each is aggregated on its own.

On the command line, --h3-join=cells.parquet does the same with a table made any way: an h3 column of cells, as text or numbers, and the attributes for them. A layer column, if there is one, gives the layer of the points, and a row with no layer is for any layer’s cell. Here DuckDB makes it:

Terminal window
duckdb -c "INSTALL h3 FROM community; LOAD h3; INSTALL spatial; LOAD spatial;
COPY (SELECT h3_h3_to_string(h3_latlng_to_cell(ST_Y(geom), ST_X(geom), r::INTEGER)) AS h3,
quantile_cont(price, 0.9) AS p90
FROM ST_Read('places.gpkg'), range(0, 16) t(r) GROUP BY ALL) TO 'cells.parquet'"
manby -z12 --h3-join=cells.parquet -o places.pmtiles places.gpkg

A joined attribute takes the place of one of the same name.

manby serve shows the hexagons colored by a field picked in its map’s panel, point_count at first: a number by its quantiles among the hexagons shown, with a scale for each resolution, and text by its commonest values, such as modal_category. With --h3-fade, each resolution fades into the next over its overlap, and the points fade in as the last hexagons fade out. The tileset’s metadata has the resolutions’ zooms as manby_h3, which the map reads, and so can a map of one’s own.

Terminal window
manby -z10 --h3-fade=1 --h3-categories=kind -o places.pmtiles places.parquet
manby serve --open places.pmtiles

--cluster-categories=kind counts an attribute’s values in tippecanoe’s clusters, as kind:park and so on, which add up to each cluster’s point_count. Values after a colon are counted by name and the rest as kind:_other.

Terminal window
manby -z14 -r1 --cluster-distance=60 --cluster-maxzoom=10 \
--cluster-categories=kind:park,museum,library -o places.pmtiles places.parquet

Each feature gets kind:<value> of 1, which clustering and coalescing add up, so a point that stays on its own has a count of 1 too.

From Python and R the options are the same, as h3=True, h3_categories="kind", h3_fade=1 and h3 = TRUE, h3_categories = "kind", h3_fade = 1.