geocomb_flutter

geocomb lets you convert locations into uniquiely identifiable hexagons for given resolutions and vice versa. Sounds simple but man, it was tough to get this working in flutter. Anyway, below is some of the setup and how to use it.

how it works

geocomb generates points on the geocomb grid, which depends on 3 things: resolution, map orientation, and rotation method. The geocomb grid is broken up into rows and columns.

The points on a geocomb grid (GPoint3) store resolution, row, and column.

Based on some pretty nice relationships, hexagons/pentagons (phex, phexes) can be generated from points on a geocomb grid based on point row and col numbers, and this is how locations are stored: given a point, geocomb finds the phex that contains it for a given resolution, map orientation, and rotation method, and returns the HashProperties of that phex. HashProperties pretty much just contains info about a phex's center point, from which a phex or point can later be generated.

This means that geocomb can be used to store locations with hexagons, instead of traditional methods like geohashing which depend on rectangles. An other benefit is hexagons closely approximate circles, which can come in handy for findng locations within a certain distance from other locations (burger restaurants within 5 km or something like that)

Aside from this, browserify is awesome for creating bundles to run on web browsers, and unpkg is awesome for loading scripts & other stuff. If you're making a plugin, consider checking them out.

usage

web setup

the web version runs js code from dart, and it needs to load some code before it can work. How you do this is, just copy & paste the below code into your web/index.html inside the <body> tag at the top.

<!-- adds geocomb web for geocomb_flutter web, nice -->
<script src="https://unpkg.com/geocomb-web@latest/web_bundle/geocomb_bundle.js"></script>

Thats it! It should work now.

Phase 1: convert coordinates to hash properties

1. import

import 'package:geocomb_flutter/geocomb_flutter.dart';

2. create Icosahedron object

// ┏→ map orientation (default is "ECEF")
// ┃ rotation method (default is "gnomonic") ←━━━━━━━━━━━━━━━━┓
// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓         ┃
final Icosahedron ico = await Icosahedron.onReady("ECEF", "gnomonic");

you may be wondering "hold on, await to create an object?", and that's the thing, since geocomb_flutter depends on geocomb-web which depends on WebAssembly, it needs to do some setup in order to run code. Make sure to either await here, or make sure Icosahedron.isReady returns true before using anything from this package. Icosahedron & other classes depend on some stuff that's loaded along with the runtime.

3. create point from coordinates

double lat = 71; // latitude  (must be in range [-90, 90])
double lon = 27; // longitude (must be in range [-180, 180])
final Point3 point = ico.pointFromCoords(lat, lon);

4. get geocomb hash properties for point (specifies hexagon location on geocomb grid for resolution)

final HashProperties props = ico.hash(point, res);

hash properties store:

  • rm - rotation mathod
  • mo - map orientation
  • res - resolution
  • row - phex row
  • col - phex column

5. figure out way to store hash properties (sorry for this one lol)

geocomb doesn't have a default hash encoder/decoder yet

Phase 2: convert hash properties back to coordinates

1. convert however you store hash properties to hash properties obj

you're on your own here, but it'll probably look something like this:

final HashProperties props = functionThatConvertsObjToHashProperties(yourObj);

whatever is inside that function is your secret sauce

2. re-create icosahedron

in order to parse a hash, you need an icosahedron so, once again:

final Icosahedron ico = new Icosahedron("ECEF", "gnomonic");

Note: icosahedron map orientation and rotation method will override hash property map orientation and rotation method. Make sure to be consistent.

3. parse hash

final GPoint3 parsedPoint = ico.parseHash(props);

4. celebrate

that's pretty much it for storing and recovering locations. The returned point, parsedPoint, is a phex center for the given resolution.

Libraries

geocomb_flutter
geocomb_flutter_platform_interface
geocomb_flutter_web
gw