Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

fix(a5): upgrade cell geometry to a5-js 1.0.0 (#3909)

Igor Dykhta8cf53496652e
diff --git a/src/layers/package.json b/src/layers/package.json
index 464f499fd..589093534 100644
--- a/src/layers/package.json
+++ b/src/layers/package.json
@@ -73,7 +73,7 @@
"@types/geojson": "^7946.0.8",
"@types/keymirror": "^0.1.1",
"@types/styled-components": "^5.1.32",
- "a5-js": "^0.7.3",
+ "a5-js": "^1.0.0",
"apache-arrow": ">=15.0.0",
"buffer": "6.0.3",
"d3-array": "^2.8.0",
diff --git a/src/layers/src/a5-layer/a5-layer.ts b/src/layers/src/a5-layer/a5-layer.ts
index eb68211d1..cf25cdcbc 100644
--- a/src/layers/src/a5-layer/a5-layer.ts
+++ b/src/layers/src/a5-layer/a5-layer.ts
@@ -3,6 +3,7 @@
import {A5Layer as DeckA5Layer} from '@deck.gl/geo-layers';
import {GeoJsonLayer} from '@deck.gl/layers';
+import {cellToBoundary, hexToU64} from 'a5-js';
import type {Feature} from 'geojson';
import {
HIGHLIGH_COLOR_3D,
@@ -85,6 +86,20 @@ export type A5GeometryLayerData = {
token: string;
};
+// deck.gl still decodes A5 0.x IDs. Use our A5 1.x dependency for the cell
+// geometry as well as centers and hover outlines, including in published packages.
+class A5Layer extends DeckA5Layer<A5GeometryLayerData> {
+ static layerName = 'A5Layer';
+
+ indexToBounds() {
+ return {
+ ...super.indexToBounds(),
+ getPolygon: ({token}: A5GeometryLayerData) =>
+ cellToBoundary(hexToU64(token), {closedRing: true, segments: 'auto'}).flat()
+ };
+ }
+}
+
const zoomFactorValue = 8;
const DEFAULT_LINE_SCALE_VALUE = 8;
@@ -356,7 +371,7 @@ export default class A5GeometryLayer extends Layer {
};
return [
- new DeckA5Layer({
+ new A5Layer({
...defaultLayerProps,
...interactionConfig,
...data,
diff --git a/src/layers/src/a5-layer/a5-utils.ts b/src/layers/src/a5-layer/a5-utils.ts
index 57d6d05cc..03037b107 100644
--- a/src/layers/src/a5-layer/a5-utils.ts
+++ b/src/layers/src/a5-layer/a5-utils.ts
@@ -1,11 +1,10 @@
// SPDX-License-Identifier: MIT
// Copyright contributors to the kepler.gl project
-import {cellToBoundary, cellToLonLat, getResolution, hexToU64, u64ToHex} from 'a5-js';
+import {cellToBoundary, cellToLonLat, hexToU64, isValidCell, u64ToHex} from 'a5-js';
import type {Feature, LineString, Polygon} from 'geojson';
const HEX_RE = /^[0-9a-fA-F]+$/;
-const MAX_A5_RESOLUTION = 30;
export function maybeStripQuotes(token: string): string {
if (token.length >= 2) {
@@ -67,8 +66,7 @@ export function validA5Token(token: unknown): boolean {
}
try {
- const resolution = getResolution(cell);
- return resolution >= 0 && resolution <= MAX_A5_RESOLUTION;
+ return cell !== 0n && isValidCell(cell);
} catch {
return false;
}
diff --git a/test/browser/layer-tests/a5-layer-specs.js b/test/browser/layer-tests/a5-layer-specs.js
index 2df3607b0..9c9f0da0a 100644
--- a/test/browser/layer-tests/a5-layer-specs.js
+++ b/test/browser/layer-tests/a5-layer-specs.js
@@ -12,16 +12,19 @@ import {a5DefaultElevation as defaultElevation, KeplerGlLayers} from '@kepler.gl
import {getGpuFilterProps, KeplerTable} from '@kepler.gl/table';
import {processCsvData} from '@kepler.gl/processors';
import {getA5Center} from '@kepler.gl/layers';
+import {a5TokenToPolygonGeo} from '../../../src/layers/src/a5-layer/a5-utils';
const {A5GeometryLayer} = KeplerGlLayers;
const dataId = 'a5-test-data';
const a5Csv = `a5,value,types
-1ae2958000000000,0.5,type_a
+9ca4cf8000000000,0.5,type_a
1ae2968000000000,1.5,type_b
1adebc8000000000,2.5,type_a
1ae2978000000000,3.5,type_c
1ae2988000000000,4.5,type_b
+100,5.5,type_a
+0,6.5,type_b
`;
const {rows, fields} = processCsvData(a5Csv);
@@ -82,7 +85,7 @@ test('#A5Geometry -> constructor', t => {
});
test('#A5Geometry -> formatLayerData', t => {
- const filteredIndex = [0, 2, 4];
+ const filteredIndex = [0, 2, 4, 5, 6];
const dataset = createA5Dataset(filteredIndex);
const TEST_CASES = [
@@ -107,12 +110,12 @@ test('#A5Geometry -> formatLayerData', t => {
assert: result => {
const {layerData, layer} = result;
const expectedData = [
- {index: 0, token: '1ae2958000000000'},
+ {index: 0, token: '9ca4cf8000000000'},
{index: 2, token: '1adebc8000000000'},
{index: 4, token: '1ae2988000000000'}
];
- t.deepEqual(layerData.data, expectedData, 'should format correct a5 layerData');
+ t.deepEqual(layerData.data, expectedData, 'should omit malformed and world cells');
t.deepEqual(layerData.getFillColor, [2, 3, 4], 'getFillColor should be a constant');
t.deepEqual(layerData.getElevation, defaultElevation, 'getElevation should be a constant');
@@ -144,7 +147,7 @@ test('#A5Geometry -> formatLayerData', t => {
});
test('#A5Geometry -> renderLayer', t => {
- const filteredIndex = [0, 2, 4];
+ const filteredIndex = [0, 2, 4, 5, 6];
const dataset = createA5Dataset(filteredIndex);
const TEST_CASES = [
@@ -166,7 +169,7 @@ test('#A5Geometry -> renderLayer', t => {
datasets: {
[dataId]: dataset
},
- assert: (deckLayers, layer) => {
+ assert: (deckLayers, layer, layerData) => {
t.equal(layer.type, 'a5', 'should create 1 a5 layer');
t.equal(deckLayers.length, 4, 'Should create 4 deck.gl layers');
@@ -183,6 +186,21 @@ test('#A5Geometry -> renderLayer', t => {
'should create composite A5 cell layers'
);
+ const sydneyCell = layerData.data[0];
+ const cellLayer = deckLayers.find(l => l.id === 'test_layer_1-cell');
+ const renderedBoundary = cellLayer.props.getPolygon(sydneyCell);
+ const outline = a5TokenToPolygonGeo(sydneyCell);
+ t.deepEqual(
+ Array.from(renderedBoundary),
+ outline.geometry.coordinates.flat(),
+ 'rendered A5 1.0 cell matches the hover outline'
+ );
+ t.ok(
+ Math.abs(renderedBoundary[0] - 151.176) < 0.1 &&
+ Math.abs(renderedBoundary[1] + 33.878) < 0.1,
+ 'renders the 1.0 cell in Sydney'
+ );
+
const {props: layerProps} = deckLayers[0];
const expectedProps = {
diff --git a/test/node/utils/a5-utils-test.js b/test/node/utils/a5-utils-test.js
index 269011790..6bf41daad 100644
--- a/test/node/utils/a5-utils-test.js
+++ b/test/node/utils/a5-utils-test.js
@@ -3,6 +3,11 @@
import test from 'tape';
import {getA5Center} from '@kepler.gl/layers';
+import {
+ a5TokenToPolygonGeo,
+ normalizeA5Token,
+ validA5Token
+} from '../../../src/layers/src/a5-layer/a5-utils';
test('Utils -> getA5Center', t => {
const token = '1ae2988000000000';
@@ -15,3 +20,35 @@ test('Utils -> getA5Center', t => {
t.equal(getA5Center('0'), null, 'world cell returns null');
t.end();
});
+
+test('Utils -> A5 1.0 cell IDs', t => {
+ // This Sydney cell has a different ID in 0.x, unlike the SF fixture above.
+ const token = '9ca4cf8000000000';
+ const center = getA5Center(token);
+ t.ok(validA5Token(token), 'accepts a valid cell');
+ t.ok(Math.abs(center[0] - 151.17625731278906) < 1e-8, '1.0 longitude is in Sydney');
+ t.ok(Math.abs(center[1] + 33.8782228122596) < 1e-8, '1.0 latitude is in Sydney');
+ t.equal(normalizeA5Token('"9CA4CF8000000000"'), token, 'normalizes a quoted hex ID');
+ t.equal(normalizeA5Token(BigInt(`0x${token}`)), token, 'normalizes a bigint ID');
+ t.deepEqual(getA5Center(BigInt(`0x${token}`)), center, 'bigint and hex centers agree');
+
+ const outline = a5TokenToPolygonGeo({token});
+ const polygon = a5TokenToPolygonGeo({token}, {isClosed: true});
+ t.equal(outline.geometry.type, 'LineString', 'outline is a line');
+ t.equal(polygon.geometry.type, 'Polygon', 'closed feature is a polygon');
+ const ring = polygon.geometry.coordinates[0];
+ t.deepEqual(ring, outline.geometry.coordinates, 'polygon and outline use the same boundary');
+ t.deepEqual(ring[0], ring[ring.length - 1], 'boundary is closed');
+ t.ok(
+ ring.every(([lng, lat]) => Math.abs(lng - center[0]) < 0.1 && Math.abs(lat - center[1]) < 0.1),
+ 'boundary surrounds the Sydney cell'
+ );
+
+ for (const invalid of ['', 'ZZZZ', '100', '0', undefined]) {
+ t.notOk(validA5Token(invalid), 'rejects missing, malformed and world cells');
+ t.equal(normalizeA5Token(invalid), null, 'missing or invalid token normalizes to null');
+ t.equal(getA5Center(invalid), null, 'missing or invalid center is null');
+ t.equal(a5TokenToPolygonGeo({token: invalid}), null, 'missing or invalid boundary is null');
+ }
+ t.end();
+});
diff --git a/yarn.lock b/yarn.lock
index 82b4f9536..1fd26e254 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -4390,7 +4390,7 @@ __metadata:
"@types/geojson": "npm:^7946.0.8"
"@types/keymirror": "npm:^0.1.1"
"@types/styled-components": "npm:^5.1.32"
- a5-js: "npm:^0.7.3"
+ a5-js: "npm:^1.0.0"
apache-arrow: "npm:>=15.0.0"
buffer: "npm:6.0.3"
d3-array: "npm:^2.8.0"
@@ -11841,7 +11841,7 @@ __metadata:
languageName: node
linkType: hard
-"a5-js@npm:^0.7.2, a5-js@npm:^0.7.3":
+"a5-js@npm:^0.7.2":
version: 0.7.3
resolution: "a5-js@npm:0.7.3"
dependencies:
@@ -11850,6 +11850,13 @@ __metadata:
languageName: node
linkType: hard
+"a5-js@npm:^1.0.0":
+ version: 1.0.0
+ resolution: "a5-js@npm:1.0.0"
+ checksum: 10c0/dc90a7959e2b2ef3283364aa79fe809ed47b8d1a64108dc743e270a2f713464b40c0d7f97799cca42324ddf7cd661f240e558bd1a71fc98a45a3b3f270623f25
+ languageName: node
+ linkType: hard
+
"abab@npm:^2.0.6":
version: 2.0.6
resolution: "abab@npm:2.0.6"