@math.gl/geoarrow 5.0.0-alpha.2

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.
Files changed (47) hide show
  1. package/LICENSE +140 -0
  2. package/README.md +311 -0
  3. package/dist/builder.d.ts +90 -0
  4. package/dist/builder.d.ts.map +1 -0
  5. package/dist/builder.js +428 -0
  6. package/dist/builder.js.map +1 -0
  7. package/dist/codecs.d.ts +10 -0
  8. package/dist/codecs.d.ts.map +1 -0
  9. package/dist/codecs.js +122 -0
  10. package/dist/codecs.js.map +1 -0
  11. package/dist/index.cjs +1651 -0
  12. package/dist/index.cjs.map +6 -0
  13. package/dist/index.d.ts +12 -0
  14. package/dist/index.d.ts.map +1 -0
  15. package/dist/index.js +10 -0
  16. package/dist/index.js.map +1 -0
  17. package/dist/kernels.d.ts +51 -0
  18. package/dist/kernels.d.ts.map +1 -0
  19. package/dist/kernels.js +359 -0
  20. package/dist/kernels.js.map +1 -0
  21. package/dist/layout.d.ts +52 -0
  22. package/dist/layout.d.ts.map +1 -0
  23. package/dist/layout.js +669 -0
  24. package/dist/layout.js.map +1 -0
  25. package/dist/tessellate.d.ts +31 -0
  26. package/dist/tessellate.d.ts.map +1 -0
  27. package/dist/tessellate.js +102 -0
  28. package/dist/tessellate.js.map +1 -0
  29. package/dist/types.d.ts +113 -0
  30. package/dist/types.d.ts.map +1 -0
  31. package/dist/types.js +41 -0
  32. package/dist/types.js.map +1 -0
  33. package/dist/worker.cjs +73 -0
  34. package/dist/worker.cjs.map +6 -0
  35. package/dist/worker.d.ts +11 -0
  36. package/dist/worker.d.ts.map +1 -0
  37. package/dist/worker.js +10 -0
  38. package/dist/worker.js.map +1 -0
  39. package/package.json +48 -0
  40. package/src/builder.ts +569 -0
  41. package/src/codecs.ts +155 -0
  42. package/src/index.ts +93 -0
  43. package/src/kernels.ts +463 -0
  44. package/src/layout.ts +833 -0
  45. package/src/tessellate.ts +133 -0
  46. package/src/types.ts +200 -0
  47. package/src/worker.ts +20 -0
package/LICENSE ADDED
@@ -0,0 +1,140 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2017 Uber Technologies, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
22
+
23
+ ---
24
+
25
+ Some primitive tessellation approaches were originally inspired by the TDL WebGL samples under
26
+ the New BSD License:
27
+
28
+ Copyright (c) 2011, Google Inc. All rights reserved.
29
+
30
+ Redistribution and use in source and binary forms, with or without modification, are permitted
31
+ provided that the following conditions are met:
32
+
33
+ 1. Redistributions of source code must retain the above copyright notice, this list of conditions
34
+ and the following disclaimer.
35
+ 2. Redistributions in binary form must reproduce the above copyright notice, this list of
36
+ conditions and the following disclaimer in the documentation and/or other materials provided
37
+ with the distribution.
38
+ 3. Neither the name of Google Inc. nor the names of its contributors may be used to endorse or
39
+ promote products derived from this software without specific prior written permission.
40
+
41
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
42
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
43
+ FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
44
+ CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
45
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
46
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
47
+ IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
48
+ OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
49
+
50
+ ---
51
+
52
+ math.gl builds on docs and code from "gl-matrix", which is MIT licensed as follows:
53
+
54
+ Copyright (c) 2015, Brandon Jones, Colin MacKenzie IV.
55
+
56
+ Permission is hereby granted, free of charge, to any person obtaining a copy
57
+ of this software and associated documentation files (the "Software"), to deal
58
+ in the Software without restriction, including without limitation the rights
59
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
60
+ copies of the Software, and to permit persons to whom the Software is
61
+ furnished to do so, subject to the following conditions:
62
+
63
+ The above copyright notice and this permission notice shall be included in
64
+ all copies or substantial portions of the Software.
65
+
66
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
67
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
68
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
69
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
70
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
71
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
72
+ THE SOFTWARE.
73
+
74
+ --
75
+
76
+ math.gl builds on docs and code from THREE.js, which is MIT licensed as follows:
77
+
78
+ The MIT License
79
+
80
+ Copyright © 2010-2017 three.js authors
81
+
82
+ Permission is hereby granted, free of charge, to any person obtaining a copy
83
+ of this software and associated documentation files (the "Software"), to deal
84
+ in the Software without restriction, including without limitation the rights
85
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
86
+ copies of the Software, and to permit persons to whom the Software is
87
+ furnished to do so, subject to the following conditions:
88
+
89
+ The above copyright notice and this permission notice shall be included in
90
+ all copies or substantial portions of the Software.
91
+
92
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
93
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
94
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
95
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
96
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
97
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
98
+ THE SOFTWARE.
99
+
100
+ ---
101
+
102
+ math.gl includes certain files from Cesium (https://github.com/AnalyticalGraphicsInc/cesium) under the Apache 2 License:
103
+
104
+ Copyright 2011-2018 CesiumJS Contributors
105
+
106
+ Licensed under the Apache License, Version 2.0 (the "License");
107
+ you may not use this file except in compliance with the License.
108
+ You may obtain a copy of the License at
109
+ http://www.apache.org/licenses/LICENSE-2.0
110
+
111
+ Unless required by applicable law or agreed to in writing, software
112
+ distributed under the License is distributed on an "AS IS" BASIS,
113
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
114
+ See the License for the specific language governing permissions and limitations under the License.
115
+
116
+ Cesium-derived code can be found in the submodule: modules/3d-tiles
117
+
118
+ ---
119
+
120
+ The @math.gl/geometry primitive tessellators are adapted from luma.gl under the MIT License:
121
+
122
+ Copyright (c) 2020 vis.gl contributors
123
+
124
+ Permission is hereby granted, free of charge, to any person obtaining a copy
125
+ of this software and associated documentation files (the "Software"), to deal
126
+ in the Software without restriction, including without limitation the rights
127
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
128
+ copies of the Software, and to permit persons to whom the Software is
129
+ furnished to do so, subject to the following conditions:
130
+
131
+ The above copyright notice and this permission notice shall be included in
132
+ all copies or substantial portions of the Software.
133
+
134
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
135
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
136
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
137
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
138
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
139
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
140
+ THE SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,311 @@
1
+ # @math.gl/geoarrow
2
+
3
+ Columnar geometry descriptors and synchronous CPU kernels for GeoArrow-compatible memory layouts.
4
+
5
+ `@math.gl/geoarrow` works directly over borrowed typed arrays. It deliberately does not require an
6
+ Arrow runtime: a loader, dataframe, database client, or application can adapt its buffers to the
7
+ small descriptor ABI and use the same validation, conversion, column-codec, and tessellation
8
+ kernels.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ npm install @math.gl/geoarrow
14
+ ```
15
+
16
+ ## Why descriptors?
17
+
18
+ Columnar geometry should not need to become GeoJSON objects before useful work can begin. A
19
+ `GeoArrowColumn` describes the physical buffers that already exist:
20
+
21
+ - primitive numeric buffers;
22
+ - interleaved fixed-size coordinate tuples or separated coordinate structs;
23
+ - Int32 or Int64 variable-list offsets;
24
+ - validity bitmaps with non-byte-aligned slice offsets;
25
+ - dense unions for mixed geometry and list-of-union geometry collections;
26
+ - binary WKB and UTF-8 WKT buffers;
27
+ - one or more chunks.
28
+
29
+ Descriptors borrow their buffers. Read-only kernels never mutate or detach them. Identity
30
+ conversions return the original column object, so callers can use descriptor and `ArrayBuffer`
31
+ identity as a reliable zero-copy signal.
32
+
33
+ ## Quick start
34
+
35
+ ```typescript
36
+ import {
37
+ GeoArrowBuilder,
38
+ getGeoArrowBounds,
39
+ getGeoArrowVertexCount,
40
+ mapGeoArrowCoordinates
41
+ } from '@math.gl/geoarrow';
42
+
43
+ const column = GeoArrowBuilder.build(
44
+ [
45
+ {type: 'LineString', coordinates: [[-122.4, 37.8], [-73.9, 40.7]]},
46
+ null
47
+ ],
48
+ {
49
+ encoding: 'geoarrow.linestring',
50
+ dimension: 'xy',
51
+ coordinateLayout: 'interleaved',
52
+ offsetType: 'int32'
53
+ }
54
+ );
55
+
56
+ getGeoArrowVertexCount(column); // 2
57
+ getGeoArrowBounds(column); // [-122.4, 37.8, -73.9, 40.7]
58
+
59
+ const shifted = mapGeoArrowCoordinates(column, ([x, y]) => [x + 360, y]);
60
+ ```
61
+
62
+ ## Physical nesting
63
+
64
+ `coord` below is either an interleaved `fixed-size-list` or a separated `struct`.
65
+
66
+ | Encoding | Physical descriptor tree |
67
+ | --- | --- |
68
+ | Point | `coord` |
69
+ | LineString | `list<coord>` |
70
+ | MultiPoint | `list<coord>` |
71
+ | Polygon | `list<list<coord>>` |
72
+ | MultiLineString | `list<list<coord>>` |
73
+ | MultiPolygon | `list<list<list<coord>>>` |
74
+ | Geometry | `dense-union<geometry children>` |
75
+ | GeometryCollection | `list<dense-union<geometry children>>` |
76
+ | Box | `struct<minimum and maximum ordinates>` |
77
+ | WKB | `serialized<binary>` |
78
+ | WKT | `serialized<utf8>` |
79
+
80
+ This example describes two XY points without copying the source coordinates:
81
+
82
+ ```typescript
83
+ import type {GeoArrowColumn} from '@math.gl/geoarrow';
84
+
85
+ const values = new Float64Array([10, 20, 30, 40]);
86
+ const points: GeoArrowColumn = {
87
+ encoding: 'geoarrow.point',
88
+ dimension: 'xy',
89
+ coordinateLayout: 'interleaved',
90
+ chunks: [{
91
+ kind: 'fixed-size-list',
92
+ length: 2,
93
+ size: 2,
94
+ child: {kind: 'primitive', length: 4, values}
95
+ }]
96
+ };
97
+ ```
98
+
99
+ For separated coordinates, use canonical ordinate names. `x` and `y` are always present; `z` and
100
+ `m` follow the semantic dimension and are never treated as interchangeable.
101
+
102
+ ```typescript
103
+ const separatedPoints: GeoArrowColumn = {
104
+ encoding: 'geoarrow.point',
105
+ dimension: 'xym',
106
+ coordinateLayout: 'separated',
107
+ chunks: [{
108
+ kind: 'struct',
109
+ length: 2,
110
+ children: {
111
+ x: {kind: 'primitive', length: 2, values: new Float64Array([10, 30])},
112
+ y: {kind: 'primitive', length: 2, values: new Float64Array([20, 40])},
113
+ m: {kind: 'primitive', length: 2, values: new Float64Array([100, 200])}
114
+ }
115
+ }]
116
+ };
117
+ ```
118
+
119
+ ## Slices, validity, and chunks
120
+
121
+ Every physical descriptor has a logical `length` and may have a validity bitmap. A set bit means
122
+ valid. `bitOffset` makes sliced null bitmaps explicit, including slices that do not begin at a byte
123
+ boundary.
124
+
125
+ Variable-width descriptors have an `offset` into their offsets buffer and an optional `offsetBase`.
126
+ The child range for row `i` is:
127
+
128
+ ```text
129
+ [offsets[offset + i] - offsetBase, offsets[offset + i + 1] - offsetBase)
130
+ ```
131
+
132
+ Both `Int32Array` and `BigInt64Array` offsets are supported. Int64 values are checked before
133
+ conversion to JavaScript numbers; values outside the safe integer range are rejected.
134
+
135
+ `sliceGeoArrowColumn` creates zero-copy descriptor views and preserves chunk boundaries.
136
+ `validateGeoArrowColumn` checks physical bounds, validity coverage, monotonic offsets, coordinate
137
+ layout, list depth, and dense-union dispatch before an expensive operation is attempted.
138
+
139
+ ## Two-pass building
140
+
141
+ `GeoArrowBuilder` has a measure pass and a write pass. This avoids growing arrays and lets an owner
142
+ allocate buffers in a pool, shared arena, or renderer-specific allocator.
143
+
144
+ ```typescript
145
+ const rows = [
146
+ {type: 'Polygon' as const, coordinates: [[[0, 0], [4, 0], [0, 4], [0, 0]]]},
147
+ null
148
+ ];
149
+ const options = {
150
+ encoding: 'geoarrow.polygon' as const,
151
+ dimension: 'xy' as const,
152
+ coordinateLayout: 'separated' as const,
153
+ offsetType: 'int64' as const
154
+ };
155
+
156
+ const measure = new GeoArrowBuilder({...options, mode: 'measure'});
157
+ rows.forEach(row => measure.append(row));
158
+
159
+ const target = measure.allocateTarget();
160
+ const write = new GeoArrowBuilder({...options, mode: 'write', target});
161
+ rows.forEach(row => write.append(row));
162
+
163
+ const polygons = write.finish(); // borrows target; no Arrow objects are constructed
164
+ ```
165
+
166
+ `GeoArrowBuilder.build(rows, options)` is the convenient form when custom allocation is not needed.
167
+
168
+ ## Inspection and read-only kernels
169
+
170
+ The following operations traverse descriptors directly and do not create per-row geometry objects:
171
+
172
+ - `inspectGeoArrowColumn`
173
+ - `validateGeoArrowColumn`
174
+ - `getGeoArrowVertexCount`
175
+ - `getGeoArrowBounds`
176
+ - `visitGeoArrowCoordinates`
177
+ - `getGeoArrowTransferList`
178
+
179
+ Allocating transforms such as coordinate mapping, physical conversion, winding normalization, and
180
+ codec decoding return new descriptors. Their inputs remain unchanged.
181
+
182
+ ## Conversion and winding
183
+
184
+ ```typescript
185
+ import {
186
+ convertGeoArrowColumn,
187
+ interleaveGeoArrowCoordinates,
188
+ rewindGeoArrow
189
+ } from '@math.gl/geoarrow';
190
+
191
+ const interleaved = interleaveGeoArrowCoordinates(separatedPoints);
192
+ const xyz = convertGeoArrowColumn(interleaved, {dimension: 'xyz'});
193
+ const normalized = rewindGeoArrow(polygons, {outer: 'counter-clockwise'});
194
+ ```
195
+
196
+ Semantic dimensions are mapped by ordinate name. Converting XYM to XYZ produces a zero Z; it does
197
+ not reinterpret M as elevation. Requesting `geoarrow.geometry` always produces a dense union, even
198
+ when every current row has the same geometry family.
199
+
200
+ ## WKB and WKT
201
+
202
+ The codecs consume and produce the same plain descriptors:
203
+
204
+ ```typescript
205
+ import {
206
+ decodeGeoArrowWKB,
207
+ encodeGeoArrowWKB,
208
+ decodeGeoArrowWKT,
209
+ encodeGeoArrowWKT
210
+ } from '@math.gl/geoarrow';
211
+
212
+ const wkb = encodeGeoArrowWKB(polygons);
213
+ const decoded = decodeGeoArrowWKB(wkb);
214
+ const wkt = encodeGeoArrowWKT(decoded);
215
+ const nativeAgain = decodeGeoArrowWKT(wkt);
216
+ ```
217
+
218
+ WKB decoding accepts little- or big-endian geometry, ISO Z/M/ZM type offsets, EWKB Z/M/SRID flags,
219
+ multi-geometries, and nested geometry collections. WKT supports all corresponding geometry
220
+ families, dimension tokens, both MultiPoint spellings, and empties. Decoding normalizes mixed-size
221
+ serialized coordinates to the column's declared semantic dimension.
222
+
223
+ Parsing or formatting one geometry is intentionally provided by the dependency-free
224
+ `@math.gl/wkb` package:
225
+
226
+ ```typescript
227
+ import {parseWKB, writeWKB, parseWKT, formatWKT} from '@math.gl/wkb';
228
+ ```
229
+
230
+ `@math.gl/geoarrow` depends on `@math.gl/wkb`; the format package never depends on GeoArrow or
231
+ Apache Arrow.
232
+
233
+ ## Polygon tessellation
234
+
235
+ ```typescript
236
+ import {tessellateGeoArrowPolygons} from '@math.gl/geoarrow';
237
+
238
+ const mesh = tessellateGeoArrowPolygons(polygons, {
239
+ positionSize: 3,
240
+ sourceRowOffset: 1000
241
+ });
242
+
243
+ // mesh.positions Float32Array
244
+ // mesh.sourceRowIndices Uint32Array
245
+ // mesh.indices Uint16Array or Uint32Array
246
+ ```
247
+
248
+ Polygon, MultiPolygon, and polygon members of dense unions or geometry collections are supported.
249
+ Holes are retained, duplicate closing coordinates are omitted from mesh vertices, and every output
250
+ vertex retains its top-level source row. Tessellation uses `@math.gl/polygon` and is synchronous.
251
+
252
+ ## Resource limits
253
+
254
+ Potentially allocating operations accept limits, and limits can also be checked directly:
255
+
256
+ ```typescript
257
+ import {assertGeoArrowResourceLimits} from '@math.gl/geoarrow';
258
+
259
+ assertGeoArrowResourceLimits(column, {
260
+ maximumRows: 1_000_000,
261
+ maximumCoordinates: 50_000_000,
262
+ maximumChunks: 10_000,
263
+ maximumNestingDepth: 8,
264
+ maximumOutputBytes: 1_000_000_000
265
+ });
266
+ ```
267
+
268
+ ## Workers and transfer ownership
269
+
270
+ Root APIs are synchronous. Worker-specific payload preparation is isolated in the optional subpath:
271
+
272
+ ```typescript
273
+ import {prepareGeoArrowTransfer} from '@math.gl/geoarrow/worker';
274
+
275
+ const payload = prepareGeoArrowTransfer(column);
276
+ worker.postMessage(payload.column, {transfer: payload.transferList});
277
+ ```
278
+
279
+ `prepareGeoArrowTransfer` only lists unique transferable buffers; it does not detach them. The
280
+ explicit `postMessage` call transfers ownership. Shared buffers are omitted because they are not
281
+ transferable.
282
+
283
+ ## Adapting another columnar runtime
284
+
285
+ Keep runtime-specific objects at the boundary. Read their physical buffers and construct a
286
+ `GeoArrowColumn`; do not call scalar `get(row)` methods. The adapter should preserve:
287
+
288
+ 1. chunk boundaries and logical lengths;
289
+ 2. typed-array byte offsets and strides;
290
+ 3. list offsets, including 64-bit offsets;
291
+ 4. validity bitmap plus bit offset;
292
+ 5. dense-union type IDs, value offsets, and child names;
293
+ 6. extension encoding, semantic dimension, coordinate layout, CRS, and edge metadata.
294
+
295
+ Run `validateGeoArrowColumn` once at the trust boundary. Downstream math then remains independent of
296
+ the producer runtime.
297
+
298
+ ## API groups
299
+
300
+ - Descriptors: `GeoArrowColumn`, `GeoArrowArray`, all physical array descriptor types
301
+ - Layout: `inspectGeoArrowColumn`, `validateGeoArrowColumn`, slicing and traversal
302
+ - Kernels: count, bounds, map, interleave, convert, rewind, union normalization, resource limits
303
+ - Construction: `GeoArrowBuilder`, `makeGeoArrowColumnFromGeometryRows`
304
+ - Column codecs: WKB/WKT descriptor encode and decode (individual parsing/formatting is tested in
305
+ `@math.gl/wkb`)
306
+ - Meshes: `tessellateGeoArrowPolygons`
307
+ - Transfer: `getGeoArrowTransferList`, plus `@math.gl/geoarrow/worker`
308
+
309
+ See the math.gl documentation for the full [physical-layout guide](../../docs/modules/geoarrow/physical-layouts.md),
310
+ [API reference](../../docs/modules/geoarrow/api-reference/geoarrow.md), and
311
+ [migration guide](../../docs/modules/geoarrow/migration-guide.md).
@@ -0,0 +1,90 @@
1
+ import type { GeoArrowColumn, GeoArrowCoordinateLayout, GeoArrowDimension, GeoArrowEncoding, GeoArrowGeometryValue, GeoArrowOffsets } from "./types.js";
2
+ /** Concrete native encodings accepted by {@link GeoArrowBuilder}. */
3
+ export type GeoArrowBuilderEncoding = Exclude<GeoArrowEncoding, 'geoarrow.geometry' | 'geoarrow.geometrycollection' | 'geoarrow.box' | 'geoarrow.wkb' | 'geoarrow.wkt'>;
4
+ /** Buffer counts produced by a measure pass. */
5
+ export type GeoArrowBuilderMeasurement = Readonly<{
6
+ length: number;
7
+ nullCount: number;
8
+ coordinateCount: number;
9
+ geometryOffsetCount: number;
10
+ partOffsetCount: number;
11
+ ringOffsetCount: number;
12
+ }>;
13
+ /** Caller-owned buffers filled by a builder write pass. */
14
+ export type GeoArrowBuilderTarget = {
15
+ validity: Uint8Array;
16
+ coordinates: Float32Array | Float64Array | {
17
+ x: Float32Array | Float64Array;
18
+ y: Float32Array | Float64Array;
19
+ z?: Float32Array | Float64Array;
20
+ m?: Float32Array | Float64Array;
21
+ };
22
+ geometryOffsets?: GeoArrowOffsets;
23
+ partOffsets?: GeoArrowOffsets;
24
+ ringOffsets?: GeoArrowOffsets;
25
+ };
26
+ /** Common builder options. */
27
+ export type GeoArrowBuilderOptions = Readonly<{
28
+ encoding: GeoArrowBuilderEncoding;
29
+ dimension?: GeoArrowDimension;
30
+ coordinateLayout?: GeoArrowCoordinateLayout;
31
+ offsetType?: 'int32' | 'int64';
32
+ coordinateType?: 'float32' | 'float64';
33
+ }>;
34
+ /** Options for materializing a column from geometry values. */
35
+ export type GeoArrowColumnFromRowsOptions = Omit<GeoArrowBuilderOptions, 'encoding'> & Readonly<{
36
+ /** Forces homogeneous values into a dense-union column. */
37
+ encoding?: 'geoarrow.geometry';
38
+ }>;
39
+ /** Measure-pass options. */
40
+ export type GeoArrowBuilderMeasureOptions = GeoArrowBuilderOptions & Readonly<{
41
+ mode: 'measure';
42
+ }>;
43
+ /** Write-pass options. */
44
+ export type GeoArrowBuilderWriteOptions = GeoArrowBuilderOptions & Readonly<{
45
+ mode: 'write';
46
+ target: GeoArrowBuilderTarget;
47
+ }>;
48
+ /** Options accepted by the incremental builder. */
49
+ export type GeoArrowBuilderModeOptions = GeoArrowBuilderMeasureOptions | GeoArrowBuilderWriteOptions;
50
+ /**
51
+ * Two-pass writer for homogeneous native GeoArrow geometry columns.
52
+ *
53
+ * Feed the same rows to a measure builder, allocate its target, and then feed them to a write
54
+ * builder. The write result borrows the supplied target buffers.
55
+ */
56
+ export declare class GeoArrowBuilder {
57
+ readonly encoding: GeoArrowBuilderEncoding;
58
+ readonly dimension: GeoArrowDimension;
59
+ readonly coordinateLayout: GeoArrowCoordinateLayout;
60
+ readonly offsetType: 'int32' | 'int64';
61
+ readonly coordinateType: 'float32' | 'float64';
62
+ private readonly mode;
63
+ private readonly target?;
64
+ private length;
65
+ private nullCount;
66
+ private coordinateCount;
67
+ private partCount;
68
+ private ringCount;
69
+ constructor(options: GeoArrowBuilderModeOptions);
70
+ /** Appends one geometry row or null. */
71
+ append(geometry: GeoArrowGeometryValue | null | undefined): this;
72
+ /** Returns current exact allocation counts. */
73
+ getMeasurement(): GeoArrowBuilderMeasurement;
74
+ /** Allocates a write target from the current measure pass. */
75
+ allocateTarget(): GeoArrowBuilderTarget;
76
+ /** Finishes a write pass and returns a one-chunk borrowed column. */
77
+ finish(): GeoArrowColumn;
78
+ /** Builds a homogeneous column using an internal measure/write pair. */
79
+ static build(rows: readonly (GeoArrowGeometryValue | null | undefined)[], options: GeoArrowBuilderOptions): GeoArrowColumn;
80
+ private appendNull;
81
+ private writeCoordinateList;
82
+ private writeCoordinate;
83
+ private writeOffset;
84
+ private initializeTargetOffsets;
85
+ }
86
+ /** Allocates exact buffers for one measured builder pass. */
87
+ export declare function allocateGeoArrowBuilderTarget(measurement: GeoArrowBuilderMeasurement, options: GeoArrowBuilderOptions): GeoArrowBuilderTarget;
88
+ /** Builds a concrete or dense-union column from materialized rows. */
89
+ export declare function makeGeoArrowColumnFromGeometryRows(rows: readonly (GeoArrowGeometryValue | null)[], options?: GeoArrowColumnFromRowsOptions): GeoArrowColumn;
90
+ //# sourceMappingURL=builder.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}