webdggrid 1.0.4 → 1.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/webdggrid.js +1 -1
- package/dist/webdggrid.js.map +1 -1
- package/dist/webdggrid.umd.js +1 -1
- package/dist/webdggrid.umd.js.map +1 -1
- package/lib-esm/libdggrid.wasm.js +1 -1
- package/lib-esm/webdggrid.js +414 -71
- package/lib-esm/webdggrid.js.map +1 -1
- package/lib-wasm/Makefile +3205 -0
- package/lib-wasm/libdggrid.js +6 -6
- package/lib-wasm/libdggrid.wasm +0 -0
- package/package.json +8 -5
- package/readme.md +72 -2
- package/src-ts/webdggrid.ts +541 -88
- package/types/webdggrid.d.ts +431 -45
- package/types/webdggrid.d.ts.map +1 -1
- package/lib-wasm/libdggrid.html +0 -1
package/types/webdggrid.d.ts
CHANGED
|
@@ -1,118 +1,504 @@
|
|
|
1
|
+
import { FeatureCollection, GeoJsonProperties, Polygon, Position } from 'geojson';
|
|
1
2
|
/**
|
|
2
|
-
*
|
|
3
|
+
* The shape of each cell in the Discrete Global Grid System.
|
|
4
|
+
*
|
|
5
|
+
* DGGRID supports four cell topologies. The most common choice for geospatial
|
|
6
|
+
* analysis is `HEXAGON` because hexagonal cells have equal adjacency (every
|
|
7
|
+
* neighbour shares an edge), uniform area, and minimal boundary-to-area ratio.
|
|
3
8
|
*
|
|
4
9
|
* @export
|
|
5
|
-
* @enum {
|
|
10
|
+
* @enum {string}
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* ```ts
|
|
14
|
+
* import { Topology } from 'webdggrid';
|
|
15
|
+
*
|
|
16
|
+
* dggs.setDggs({ topology: Topology.HEXAGON, ... }, 4);
|
|
17
|
+
* ```
|
|
6
18
|
*/
|
|
7
19
|
export declare enum Topology {
|
|
20
|
+
/** Six-sided cells — the default and most widely used topology. */
|
|
8
21
|
'HEXAGON' = "HEXAGON",
|
|
22
|
+
/** Three-sided cells. */
|
|
9
23
|
'TRIANGLE' = "TRIANGLE",
|
|
10
|
-
|
|
24
|
+
/** Four-sided diamond cells (squares rotated 45°). */
|
|
11
25
|
'DIAMOND' = "DIAMOND"
|
|
12
26
|
}
|
|
13
27
|
/**
|
|
14
|
-
*
|
|
28
|
+
* The map projection used to place the polyhedron faces onto the sphere.
|
|
29
|
+
*
|
|
30
|
+
* - **ISEA** (Icosahedral Snyder Equal Area) — preserves cell area at the cost
|
|
31
|
+
* of shape distortion. Recommended for most analytical use-cases.
|
|
32
|
+
* - **FULLER** (Fuller/Dymaxion) — minimises shape distortion but does not
|
|
33
|
+
* preserve equal area.
|
|
15
34
|
*
|
|
16
35
|
* @export
|
|
17
|
-
* @enum {
|
|
36
|
+
* @enum {string}
|
|
37
|
+
*
|
|
38
|
+
* @example
|
|
39
|
+
* ```ts
|
|
40
|
+
* import { Projection } from 'webdggrid';
|
|
41
|
+
*
|
|
42
|
+
* dggs.setDggs({ projection: Projection.ISEA, ... }, 4);
|
|
43
|
+
* ```
|
|
18
44
|
*/
|
|
19
45
|
export declare enum Projection {
|
|
46
|
+
/** Icosahedral Snyder Equal Area projection — equal-area cells. */
|
|
20
47
|
'ISEA' = "ISEA",
|
|
48
|
+
/** Fuller/Dymaxion projection — shape-preserving cells. */
|
|
21
49
|
'FULLER' = "FULLER"
|
|
22
50
|
}
|
|
51
|
+
/**
|
|
52
|
+
* A simple geographic coordinate expressed as latitude and longitude in
|
|
53
|
+
* decimal degrees (WGS-84).
|
|
54
|
+
*
|
|
55
|
+
* @example
|
|
56
|
+
* ```ts
|
|
57
|
+
* const coord: Coordinate = { lat: 51.5, lng: -0.1 };
|
|
58
|
+
* ```
|
|
59
|
+
*/
|
|
23
60
|
export interface Coordinate {
|
|
61
|
+
/** Latitude in decimal degrees. Range: −90 to 90. */
|
|
24
62
|
lat: number;
|
|
63
|
+
/** Longitude in decimal degrees. Range: −180 to 180. */
|
|
25
64
|
lng: number;
|
|
26
65
|
}
|
|
66
|
+
/**
|
|
67
|
+
* GeoJSON `properties` object attached to every cell feature returned by
|
|
68
|
+
* {@link Webdggrid.sequenceNumToGridFeatureCollection}.
|
|
69
|
+
*
|
|
70
|
+
* All numeric identifiers are `BigInt` because DGGRID cell sequence numbers
|
|
71
|
+
* can exceed the safe integer range of IEEE-754 doubles at high resolutions.
|
|
72
|
+
*
|
|
73
|
+
* > **Note for MapLibre / Mapbox users:** structured-clone (used internally
|
|
74
|
+
* > by these libraries' Web Workers) cannot serialise `BigInt`. Convert `id`
|
|
75
|
+
* > to a string before calling `source.setData()`.
|
|
76
|
+
*/
|
|
77
|
+
export type DGGSGeoJsonProperty = GeoJsonProperties & {
|
|
78
|
+
/**
|
|
79
|
+
* The DGGS sequence number (cell ID) of this feature.
|
|
80
|
+
* Unique within a given DGGS configuration and resolution.
|
|
81
|
+
*/
|
|
82
|
+
id?: BigInt;
|
|
83
|
+
/** Column index in an (i, j) address scheme, if available. */
|
|
84
|
+
i?: BigInt;
|
|
85
|
+
/** Row index in an (i, j) address scheme, if available. */
|
|
86
|
+
j?: BigInt;
|
|
87
|
+
};
|
|
88
|
+
/**
|
|
89
|
+
* Full configuration of a Discrete Global Grid System.
|
|
90
|
+
*
|
|
91
|
+
* A DGGS is fully defined by its polyhedron orientation (`poleCoordinates`,
|
|
92
|
+
* `azimuth`), the subdivision scheme (`aperture`), the cell shape
|
|
93
|
+
* (`topology`), and the map projection (`projection`).
|
|
94
|
+
*
|
|
95
|
+
* Pass this object to {@link Webdggrid.setDggs} to switch between grid
|
|
96
|
+
* configurations at runtime.
|
|
97
|
+
*
|
|
98
|
+
* @example
|
|
99
|
+
* ```ts
|
|
100
|
+
* const myDggs: IDGGSProps = {
|
|
101
|
+
* poleCoordinates: { lat: 58.28, lng: 11.25 }, // Snyder orientation
|
|
102
|
+
* azimuth: 0,
|
|
103
|
+
* aperture: 4,
|
|
104
|
+
* topology: Topology.HEXAGON,
|
|
105
|
+
* projection: Projection.ISEA,
|
|
106
|
+
* };
|
|
107
|
+
* dggs.setDggs(myDggs, 5);
|
|
108
|
+
* ```
|
|
109
|
+
*/
|
|
27
110
|
export interface IDGGSProps {
|
|
111
|
+
/**
|
|
112
|
+
* Geographic location of the icosahedron pole used to orient the grid.
|
|
113
|
+
* Changing this rotates the entire grid on the globe, which can be used
|
|
114
|
+
* to minimise cell distortion over a region of interest.
|
|
115
|
+
* Defaults to `{ lat: 0, lng: 0 }`.
|
|
116
|
+
*/
|
|
28
117
|
poleCoordinates: Coordinate;
|
|
118
|
+
/**
|
|
119
|
+
* Azimuth of the icosahedron pole in decimal degrees.
|
|
120
|
+
* Rotates the grid around the pole axis. Defaults to `0`.
|
|
121
|
+
*/
|
|
29
122
|
azimuth: number;
|
|
123
|
+
/**
|
|
124
|
+
* Subdivision aperture — the number of child cells each parent cell is
|
|
125
|
+
* divided into when moving to the next finer resolution.
|
|
126
|
+
*
|
|
127
|
+
* | Aperture | Cells at res *r* (HEXAGON/ISEA) |
|
|
128
|
+
* |---|---|
|
|
129
|
+
* | 3 | 2 + 10 × 3^r |
|
|
130
|
+
* | 4 | 2 + 10 × 4^r |
|
|
131
|
+
* | 7 | 2 + 10 × 7^r |
|
|
132
|
+
*
|
|
133
|
+
* Aperture `4` is the most common choice and is the default.
|
|
134
|
+
*/
|
|
30
135
|
aperture: 3 | 4 | 5 | 7;
|
|
136
|
+
/** Shape of each cell. See {@link Topology}. */
|
|
31
137
|
topology: Topology;
|
|
138
|
+
/** Projection used to map the polyhedron faces onto the sphere. See {@link Projection}. */
|
|
32
139
|
projection: Projection;
|
|
33
140
|
}
|
|
141
|
+
/**
|
|
142
|
+
* Rewraps a polygon ring that crosses the antimeridian so that all longitudes
|
|
143
|
+
* are in a contiguous range (some may exceed 180°). This is the format
|
|
144
|
+
* expected by MapLibre GL / Mapbox GL globe projection for antimeridian cells.
|
|
145
|
+
* For renderers that require standard [-180, 180] coordinates, use the raw
|
|
146
|
+
* output from {@link Webdggrid.sequenceNumToGrid} directly.
|
|
147
|
+
*/
|
|
148
|
+
export declare function unwrapAntimeridianRing(ring: Position[]): Position[];
|
|
149
|
+
/**
|
|
150
|
+
* Main entry point for the WebDggrid library.
|
|
151
|
+
*
|
|
152
|
+
* `Webdggrid` wraps the DGGRID C++ library compiled to WebAssembly and exposes
|
|
153
|
+
* methods for:
|
|
154
|
+
* - **Grid configuration** — choose topology, projection, aperture, and
|
|
155
|
+
* resolution via {@link setDggs} / {@link setResolution}.
|
|
156
|
+
* - **Coordinate conversion** — convert between geographic coordinates and
|
|
157
|
+
* DGGS cell IDs (sequence numbers) with {@link geoToSequenceNum} and
|
|
158
|
+
* {@link sequenceNumToGeo}.
|
|
159
|
+
* - **Grid geometry** — retrieve the polygon boundary of any cell with
|
|
160
|
+
* {@link sequenceNumToGrid} or export a ready-to-render GeoJSON
|
|
161
|
+
* `FeatureCollection` with {@link sequenceNumToGridFeatureCollection}.
|
|
162
|
+
* - **Grid statistics** — query cell counts, areas, and spacings with
|
|
163
|
+
* {@link nCells}, {@link cellAreaKM}, and {@link cellDistKM}.
|
|
164
|
+
*
|
|
165
|
+
* ## Quick start
|
|
166
|
+
*
|
|
167
|
+
* ```ts
|
|
168
|
+
* import { Webdggrid } from 'webdggrid';
|
|
169
|
+
*
|
|
170
|
+
* const dggs = await Webdggrid.load();
|
|
171
|
+
*
|
|
172
|
+
* // Convert a geographic point to its DGGS cell ID at resolution 5
|
|
173
|
+
* const [cellId] = dggs.geoToSequenceNum([[-73.9857, 40.7484]], 5);
|
|
174
|
+
*
|
|
175
|
+
* // Get the polygon boundary of that cell as GeoJSON
|
|
176
|
+
* const geojson = dggs.sequenceNumToGridFeatureCollection([cellId], 5);
|
|
177
|
+
* ```
|
|
178
|
+
*
|
|
179
|
+
* ## Lifecycle
|
|
180
|
+
*
|
|
181
|
+
* The WASM module is a singleton. Call {@link Webdggrid.load} once and reuse
|
|
182
|
+
* the returned instance throughout your application. Call
|
|
183
|
+
* {@link Webdggrid.unload} when you are completely done to free memory.
|
|
184
|
+
*/
|
|
34
185
|
export declare class Webdggrid {
|
|
35
186
|
protected _module: any;
|
|
187
|
+
/**
|
|
188
|
+
* The active DGGS configuration used by all conversion and statistics
|
|
189
|
+
* methods. Change it at any time via {@link setDggs}.
|
|
190
|
+
*
|
|
191
|
+
* Defaults to ISEA4H (ISEA projection, aperture 4, hexagon topology,
|
|
192
|
+
* pole at 0° N 0° E, azimuth 0°).
|
|
193
|
+
*/
|
|
36
194
|
dggs: IDGGSProps;
|
|
195
|
+
/**
|
|
196
|
+
* The active grid resolution. Higher values produce finer, smaller cells.
|
|
197
|
+
* The valid range depends on the aperture — for aperture 4 the practical
|
|
198
|
+
* limit is around resolution 15 before cell counts become unwieldy.
|
|
199
|
+
*
|
|
200
|
+
* Change via {@link setResolution} or pass an explicit `resolution`
|
|
201
|
+
* argument to any conversion method.
|
|
202
|
+
*
|
|
203
|
+
* Defaults to `1`.
|
|
204
|
+
*/
|
|
37
205
|
resolution: number;
|
|
38
206
|
private constructor();
|
|
39
207
|
/**
|
|
40
|
-
* Compiles and instantiates the
|
|
208
|
+
* Compiles and instantiates the DGGRID WebAssembly module.
|
|
209
|
+
*
|
|
210
|
+
* This is the only way to construct a `Webdggrid` instance. The method is
|
|
211
|
+
* asynchronous because WebAssembly compilation is prohibited on the main
|
|
212
|
+
* thread for buffers larger than 4 KB.
|
|
213
|
+
*
|
|
214
|
+
* ```ts
|
|
215
|
+
* const dggs = await Webdggrid.load();
|
|
216
|
+
* ```
|
|
41
217
|
*
|
|
42
218
|
* ::: info
|
|
43
|
-
* In general WebAssembly compilation is disallowed on the main thread if
|
|
219
|
+
* In general WebAssembly compilation is disallowed on the main thread if
|
|
220
|
+
* the buffer size is larger than 4 KB, hence forcing `load` to be
|
|
221
|
+
* asynchronous.
|
|
44
222
|
* :::
|
|
45
223
|
*
|
|
46
|
-
* @returns A promise to
|
|
224
|
+
* @returns A promise that resolves to a fully initialised `Webdggrid` instance.
|
|
47
225
|
*/
|
|
48
226
|
static load(): Promise<typeof Webdggrid>;
|
|
49
227
|
/**
|
|
50
|
-
*
|
|
228
|
+
* Releases the compiled WASM instance and frees its memory.
|
|
229
|
+
*
|
|
230
|
+
* Call this when your application no longer needs the library. After
|
|
231
|
+
* calling `unload`, any existing `Webdggrid` instances become unusable —
|
|
232
|
+
* you must call {@link load} again to create a new one.
|
|
51
233
|
*/
|
|
52
234
|
static unload(): void;
|
|
53
235
|
/**
|
|
54
|
-
*
|
|
236
|
+
* Returns the version string of the underlying DGGRID C++ library.
|
|
237
|
+
*
|
|
238
|
+
* ```ts
|
|
239
|
+
* console.log(dggs.version()); // e.g. "8.3b"
|
|
240
|
+
* ```
|
|
241
|
+
*
|
|
242
|
+
* @returns The DGGRID C++ library version string.
|
|
55
243
|
*/
|
|
56
244
|
version(): string;
|
|
57
245
|
/**
|
|
58
|
-
*
|
|
59
|
-
*
|
|
246
|
+
* Sets both the DGGS configuration and the resolution in one call.
|
|
247
|
+
*
|
|
248
|
+
* All subsequent conversion and statistics methods will use this
|
|
249
|
+
* configuration unless they receive an explicit `resolution` argument.
|
|
250
|
+
*
|
|
251
|
+
* ```ts
|
|
252
|
+
* dggs.setDggs({
|
|
253
|
+
* poleCoordinates: { lat: 0, lng: 0 },
|
|
254
|
+
* azimuth: 0,
|
|
255
|
+
* aperture: 4,
|
|
256
|
+
* topology: Topology.HEXAGON,
|
|
257
|
+
* projection: Projection.ISEA,
|
|
258
|
+
* }, 5);
|
|
259
|
+
* ```
|
|
260
|
+
*
|
|
261
|
+
* @param dggs - The new DGGS configuration. Defaults to ISEA4H at pole (0,0).
|
|
262
|
+
* @param resolution - The new resolution level. Defaults to `1`.
|
|
60
263
|
*/
|
|
61
264
|
setDggs(dggs?: IDGGSProps, resolution?: number): void;
|
|
62
265
|
/**
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
266
|
+
* Returns the currently active grid resolution.
|
|
267
|
+
*
|
|
268
|
+
* ```ts
|
|
269
|
+
* dggs.setResolution(7);
|
|
270
|
+
* console.log(dggs.getResolution()); // 7
|
|
271
|
+
* ```
|
|
272
|
+
*
|
|
273
|
+
* @returns The current resolution level.
|
|
66
274
|
*/
|
|
67
275
|
getResolution(): number;
|
|
68
276
|
/**
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
277
|
+
* Sets the grid resolution used by default in all conversion and
|
|
278
|
+
* statistics methods.
|
|
279
|
+
*
|
|
280
|
+
* ```ts
|
|
281
|
+
* dggs.setResolution(5);
|
|
282
|
+
* const count = dggs.nCells(); // uses resolution 5
|
|
283
|
+
* ```
|
|
284
|
+
*
|
|
285
|
+
* @param resolution - The new resolution level. Must be a positive integer.
|
|
72
286
|
*/
|
|
73
287
|
setResolution(resolution: number): void;
|
|
74
288
|
/**
|
|
75
|
-
* test
|
|
76
|
-
*
|
|
77
|
-
* @
|
|
78
|
-
* @memberof WebDggrid
|
|
289
|
+
* Internal test helper that invokes the WASM module's `_main` entry point.
|
|
290
|
+
* Not intended for production use.
|
|
291
|
+
* @internal
|
|
79
292
|
*/
|
|
80
293
|
_main(): any;
|
|
81
294
|
/**
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
*
|
|
295
|
+
* Returns the total number of cells that tile the entire globe at the
|
|
296
|
+
* given resolution under the current DGGS configuration.
|
|
297
|
+
*
|
|
298
|
+
* Cell counts grow exponentially with resolution. For the default ISEA4H
|
|
299
|
+
* grid:
|
|
300
|
+
*
|
|
301
|
+
* | Resolution | Approx. cell count |
|
|
302
|
+
* |---|---|
|
|
303
|
+
* | 1 | 42 |
|
|
304
|
+
* | 2 | 162 |
|
|
305
|
+
* | 3 | 642 |
|
|
306
|
+
* | 4 | 2 562 |
|
|
307
|
+
* | 5 | 10 242 |
|
|
308
|
+
* | 6 | 40 962 |
|
|
309
|
+
*
|
|
310
|
+
* ```ts
|
|
311
|
+
* const total = dggs.nCells(3); // 642
|
|
312
|
+
* ```
|
|
313
|
+
*
|
|
314
|
+
* @param resolution - Resolution level to query. Defaults to the instance's
|
|
315
|
+
* current {@link resolution}.
|
|
316
|
+
* @returns Total number of cells at the given resolution.
|
|
87
317
|
*/
|
|
88
318
|
nCells(resolution?: number): number;
|
|
319
|
+
/**
|
|
320
|
+
* Returns the average area of a single cell in square kilometres at the
|
|
321
|
+
* given resolution.
|
|
322
|
+
*
|
|
323
|
+
* Because ISEA guarantees equal-area cells, all cells have the same area
|
|
324
|
+
* when using the `ISEA` projection. With `FULLER` the value is an average.
|
|
325
|
+
*
|
|
326
|
+
* ```ts
|
|
327
|
+
* const areakm2 = dggs.cellAreaKM(5);
|
|
328
|
+
* ```
|
|
329
|
+
*
|
|
330
|
+
* @param resolution - Resolution level to query. Defaults to the instance's
|
|
331
|
+
* current {@link resolution}.
|
|
332
|
+
* @returns Average cell area in km².
|
|
333
|
+
*/
|
|
89
334
|
cellAreaKM(resolution?: number): number;
|
|
335
|
+
/**
|
|
336
|
+
* Returns the average centre-to-centre distance between neighbouring cells
|
|
337
|
+
* in kilometres at the given resolution.
|
|
338
|
+
*
|
|
339
|
+
* This is useful for estimating spatial join radii or selecting a
|
|
340
|
+
* resolution that matches a target spatial scale.
|
|
341
|
+
*
|
|
342
|
+
* ```ts
|
|
343
|
+
* const spacingKm = dggs.cellDistKM(5);
|
|
344
|
+
* ```
|
|
345
|
+
*
|
|
346
|
+
* @param resolution - Resolution level to query. Defaults to the instance's
|
|
347
|
+
* current {@link resolution}.
|
|
348
|
+
* @returns Average cell spacing in km.
|
|
349
|
+
*/
|
|
90
350
|
cellDistKM(resolution?: number): number;
|
|
351
|
+
/**
|
|
352
|
+
* Returns the characteristic length scale (CLS) of the grid at the given
|
|
353
|
+
* resolution — defined as the square root of the average cell area.
|
|
354
|
+
*
|
|
355
|
+
* CLS provides a single scalar that summarises the spatial granularity of
|
|
356
|
+
* the grid, useful for comparing resolutions across different DGGS
|
|
357
|
+
* configurations.
|
|
358
|
+
*
|
|
359
|
+
* ```ts
|
|
360
|
+
* const cls = dggs.gridStatCLS(4);
|
|
361
|
+
* ```
|
|
362
|
+
*
|
|
363
|
+
* @param resolution - Resolution level to query. Defaults to the instance's
|
|
364
|
+
* current {@link resolution}.
|
|
365
|
+
* @returns Grid CLS value.
|
|
366
|
+
*/
|
|
91
367
|
gridStatCLS(resolution?: number): number;
|
|
92
368
|
/**
|
|
93
|
-
* Converts an array of
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
*
|
|
369
|
+
* Converts an array of geographic coordinates to their corresponding DGGS
|
|
370
|
+
* cell sequence numbers (cell IDs) at the given resolution.
|
|
371
|
+
*
|
|
372
|
+
* Each coordinate is mapped to the single cell whose boundary contains it.
|
|
373
|
+
* Multiple coordinates that fall within the same cell will return the same
|
|
374
|
+
* sequence number.
|
|
375
|
+
*
|
|
376
|
+
* Coordinates must be supplied in **`[lng, lat]`** order (GeoJSON
|
|
377
|
+
* convention), **not** `[lat, lng]`.
|
|
378
|
+
*
|
|
379
|
+
* ```ts
|
|
380
|
+
* // New York City
|
|
381
|
+
* const ids = dggs.geoToSequenceNum([[-74.006, 40.7128]], 5);
|
|
382
|
+
* console.log(ids); // [12345n]
|
|
383
|
+
*
|
|
384
|
+
* // Multiple points at once
|
|
385
|
+
* const ids2 = dggs.geoToSequenceNum(
|
|
386
|
+
* [[-74.006, 40.7128], [2.3522, 48.8566]],
|
|
387
|
+
* 5
|
|
388
|
+
* );
|
|
389
|
+
* ```
|
|
390
|
+
*
|
|
391
|
+
* @param coordinates - Array of `[lng, lat]` pairs in decimal degrees.
|
|
392
|
+
* @param resolution - Resolution at which to perform the lookup. Defaults
|
|
393
|
+
* to the instance's current {@link resolution}.
|
|
394
|
+
* @returns Array of `BigInt` sequence numbers, one per input coordinate,
|
|
395
|
+
* in the same order.
|
|
97
396
|
*/
|
|
98
397
|
geoToSequenceNum(coordinates: number[][], resolution?: number): bigint[];
|
|
99
398
|
/**
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
399
|
+
* Converts an array of DGGS cell sequence numbers to the geographic
|
|
400
|
+
* coordinates of their centroids.
|
|
401
|
+
*
|
|
402
|
+
* The returned coordinates are in **`[lng, lat]`** order (GeoJSON
|
|
403
|
+
* convention).
|
|
404
|
+
*
|
|
405
|
+
* ```ts
|
|
406
|
+
* const centroids = dggs.sequenceNumToGeo([1n, 2n, 3n], 3);
|
|
407
|
+
* // [[lng0, lat0], [lng1, lat1], [lng2, lat2]]
|
|
408
|
+
* ```
|
|
409
|
+
*
|
|
410
|
+
* @param sequenceNum - Array of `BigInt` cell IDs to look up.
|
|
411
|
+
* @param resolution - Resolution at which the IDs were generated. Defaults
|
|
412
|
+
* to the instance's current {@link resolution}.
|
|
413
|
+
* @returns Array of `[lng, lat]` centroid positions, one per input ID, in
|
|
414
|
+
* the same order.
|
|
415
|
+
*/
|
|
416
|
+
sequenceNumToGeo(sequenceNum: bigint[], resolution?: number): Position[];
|
|
417
|
+
/**
|
|
418
|
+
* Snaps an array of geographic coordinates to the centroid of the DGGS
|
|
419
|
+
* cell that contains each point.
|
|
420
|
+
*
|
|
421
|
+
* This is equivalent to calling {@link geoToSequenceNum} followed by
|
|
422
|
+
* {@link sequenceNumToGeo} but is more efficient because it avoids
|
|
423
|
+
* returning the intermediate sequence numbers.
|
|
424
|
+
*
|
|
425
|
+
* Useful for spatial aggregation: all points that fall within the same
|
|
426
|
+
* cell will map to the identical centroid coordinate.
|
|
427
|
+
*
|
|
428
|
+
* Coordinates must be in **`[lng, lat]`** order.
|
|
429
|
+
*
|
|
430
|
+
* ```ts
|
|
431
|
+
* const snapped = dggs.geoToGeo(
|
|
432
|
+
* [[-74.006, 40.7128], [-74.010, 40.720]],
|
|
433
|
+
* 5
|
|
434
|
+
* );
|
|
435
|
+
* // Both points snap to the same centroid if they share a cell
|
|
436
|
+
* ```
|
|
437
|
+
*
|
|
438
|
+
* @param coordinates - Array of `[lng, lat]` pairs in decimal degrees.
|
|
439
|
+
* @param resolution - Resolution at which to perform the snapping. Defaults
|
|
440
|
+
* to the instance's current {@link resolution}.
|
|
441
|
+
* @returns Array of `[lng, lat]` cell centroid positions, one per input
|
|
442
|
+
* coordinate, in the same order.
|
|
443
|
+
*/
|
|
444
|
+
geoToGeo(coordinates: number[][], resolution?: number): Position[];
|
|
445
|
+
/**
|
|
446
|
+
* Returns the polygon boundary vertices for each cell in `sequenceNum`.
|
|
447
|
+
*
|
|
448
|
+
* Each cell is represented as an array of `[lng, lat]` vertex positions.
|
|
449
|
+
* The ring is **not** automatically closed (the first and last vertex are
|
|
450
|
+
* different) — close it yourself if your renderer requires it.
|
|
451
|
+
*
|
|
452
|
+
* Prefer {@link sequenceNumToGridFeatureCollection} when you need
|
|
453
|
+
* GeoJSON output ready for a mapping library.
|
|
454
|
+
*
|
|
455
|
+
* ```ts
|
|
456
|
+
* const rings = dggs.sequenceNumToGrid([1n, 2n], 3);
|
|
457
|
+
* // rings[0] = [[lng0,lat0], [lng1,lat1], ..., [lng5,lat5]] (hexagon)
|
|
458
|
+
* ```
|
|
459
|
+
*
|
|
460
|
+
* @param sequenceNum - Array of `BigInt` cell IDs whose boundaries to
|
|
461
|
+
* retrieve.
|
|
462
|
+
* @param resolution - Resolution at which the IDs were generated. Defaults
|
|
463
|
+
* to the instance's current {@link resolution}.
|
|
464
|
+
* @returns A 2-D array: `result[i]` is the vertex ring of `sequenceNum[i]`.
|
|
465
|
+
* Each vertex is a `[lng, lat]` position.
|
|
466
|
+
* @throws If the WASM module encounters an invalid cell ID.
|
|
104
467
|
*/
|
|
105
|
-
|
|
468
|
+
sequenceNumToGrid(sequenceNum: bigint[], resolution?: number): Position[][];
|
|
106
469
|
/**
|
|
107
|
-
* Converts
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
*
|
|
470
|
+
* Converts an array of DGGS cell IDs into a GeoJSON `FeatureCollection`
|
|
471
|
+
* where each `Feature` is a `Polygon` representing the cell boundary.
|
|
472
|
+
*
|
|
473
|
+
* This is the primary method for rendering DGGS cells with mapping
|
|
474
|
+
* libraries such as MapLibre GL JS, Leaflet, or deck.gl.
|
|
475
|
+
*
|
|
476
|
+
* Each feature includes:
|
|
477
|
+
* - `geometry` — a closed `Polygon` in `[lng, lat]` coordinate order.
|
|
478
|
+
* - `id` — the cell sequence number (converted to `string` recommended
|
|
479
|
+
* before passing to MapLibre to avoid BigInt serialisation errors).
|
|
480
|
+
* - `properties.id` — same value as `id`, accessible inside layer
|
|
481
|
+
* expressions.
|
|
482
|
+
*
|
|
483
|
+
* ```ts
|
|
484
|
+
* const ids = dggs.geoToSequenceNum([[-74.006, 40.7128]], 5);
|
|
485
|
+
* const fc = dggs.sequenceNumToGridFeatureCollection(ids, 5);
|
|
486
|
+
*
|
|
487
|
+
* // MapLibre / structured-clone safe: convert BigInt → string
|
|
488
|
+
* fc.features.forEach(f => {
|
|
489
|
+
* if (typeof f.id === 'bigint') f.id = f.id.toString();
|
|
490
|
+
* if (f.properties?.id) f.properties.id = f.properties.id.toString();
|
|
491
|
+
* });
|
|
492
|
+
*
|
|
493
|
+
* map.getSource('grid').setData(fc);
|
|
494
|
+
* ```
|
|
495
|
+
*
|
|
496
|
+
* @param sequenceNum - Array of `BigInt` cell IDs to convert.
|
|
497
|
+
* @param resolution - Resolution at which the IDs were generated. Defaults
|
|
498
|
+
* to the instance's current {@link resolution}.
|
|
499
|
+
* @returns A GeoJSON `FeatureCollection` of `Polygon` features, one per
|
|
500
|
+
* input cell ID.
|
|
111
501
|
*/
|
|
112
|
-
|
|
113
|
-
_is2dArray(array: any): boolean;
|
|
114
|
-
_arrayToVector(array: any): any;
|
|
115
|
-
_vectorToArray(vector: any): any[];
|
|
116
|
-
_wVectorToArray: (vector: any) => any[];
|
|
502
|
+
sequenceNumToGridFeatureCollection(sequenceNum: bigint[], resolution?: number): FeatureCollection<Polygon, DGGSGeoJsonProperty>;
|
|
117
503
|
}
|
|
118
504
|
//# sourceMappingURL=webdggrid.d.ts.map
|
package/types/webdggrid.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"webdggrid.d.ts","sourceRoot":"","sources":["../src-ts/webdggrid.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"webdggrid.d.ts","sourceRoot":"","sources":["../src-ts/webdggrid.ts"],"names":[],"mappings":"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"}
|
package/lib-wasm/libdggrid.html
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
<!doctypehtml><html lang=en-us><head><meta charset=utf-8><meta content="text/html; charset=utf-8"http-equiv=Content-Type><title>Emscripten-Generated Code</title><style>.emscripten{padding-right:0;margin-left:auto;margin-right:auto;display:block}textarea.emscripten{font-family:monospace;width:80%}div.emscripten{text-align:center}div.emscripten_border{border:1px solid #000}canvas.emscripten{border:0 none;background-color:#000}.spinner{height:50px;width:50px;margin:0 auto;-webkit-animation:rotation .8s linear infinite;-moz-animation:rotation .8s linear infinite;-o-animation:rotation .8s linear infinite;animation:rotation .8s linear infinite;border-left:10px solid #0096f0;border-right:10px solid #0096f0;border-bottom:10px solid #0096f0;border-top:10px solid #6400c8;border-radius:100%;background-color:#c864fa}@-webkit-keyframes rotation{from{-webkit-transform:rotate(0)}to{-webkit-transform:rotate(360deg)}}@-moz-keyframes rotation{from{-moz-transform:rotate(0)}to{-moz-transform:rotate(360deg)}}@-o-keyframes rotation{from{-o-transform:rotate(0)}to{-o-transform:rotate(360deg)}}@keyframes rotation{from{transform:rotate(0)}to{transform:rotate(360deg)}}</style></head><body><hr><figure id=spinner style=overflow:visible><div class=spinner></div><center style=margin-top:.5em><strong>emscripten</strong></center></figure><div class=emscripten id=status>Downloading...</div><div class=emscripten><progress hidden id=progress max=100 value=0></progress></div><div class=emscripten_border><canvas class=emscripten id=canvas oncontextmenu=event.preventDefault() tabindex=-1></canvas></div><hr><div class=emscripten><input type=checkbox id=resize>Resize canvas <input type=checkbox id=pointerLock checked>Lock/hide mouse pointer <input type=button onclick='Module.requestFullscreen(document.getElementById("pointerLock").checked,document.getElementById("resize").checked)'value=Fullscreen></div><hr><textarea class=emscripten id=output rows=8></textarea><hr><script>var statusElement=document.getElementById("status"),progressElement=document.getElementById("progress"),spinnerElement=document.getElementById("spinner"),Module={preRun:[],postRun:[],print:function(){var e=document.getElementById("output");return e&&(e.value=""),function(t){arguments.length>1&&(t=Array.prototype.slice.call(arguments).join(" ")),console.log(t),e&&(e.value+=t+"\n",e.scrollTop=e.scrollHeight)}}(),canvas:function(){var e=document.getElementById("canvas");return e.addEventListener("webglcontextlost",(function(e){alert("WebGL context lost. You will need to reload the page."),e.preventDefault()}),!1),e}(),setStatus:function(e){if(Module.setStatus.last||(Module.setStatus.last={time:Date.now(),text:""}),e!==Module.setStatus.last.text){var t=e.match(/([^(]+)\((\d+(\.\d+)?)\/(\d+)\)/),n=Date.now();t&&n-Module.setStatus.last.time<30||(Module.setStatus.last.time=n,Module.setStatus.last.text=e,t?(e=t[1],progressElement.value=100*parseInt(t[2]),progressElement.max=100*parseInt(t[4]),progressElement.hidden=!1,spinnerElement.hidden=!1):(progressElement.value=null,progressElement.max=null,progressElement.hidden=!0,e||(spinnerElement.hidden=!0)),statusElement.innerHTML=e)}},totalDependencies:0,monitorRunDependencies:function(e){this.totalDependencies=Math.max(this.totalDependencies,e),Module.setStatus(e?"Preparing... ("+(this.totalDependencies-e)+"/"+this.totalDependencies+")":"All downloads complete.")}};Module.setStatus("Downloading..."),window.onerror=function(){Module.setStatus("Exception thrown, see JavaScript console"),spinnerElement.style.display="none",Module.setStatus=function(e){e&&console.error("[post-exception status] "+e)}}</script><script type=module>import initModule from"./libdggrid.js";initModule(Module)</script></body></html>
|