@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.
- package/LICENSE +140 -0
- package/README.md +311 -0
- package/dist/builder.d.ts +90 -0
- package/dist/builder.d.ts.map +1 -0
- package/dist/builder.js +428 -0
- package/dist/builder.js.map +1 -0
- package/dist/codecs.d.ts +10 -0
- package/dist/codecs.d.ts.map +1 -0
- package/dist/codecs.js +122 -0
- package/dist/codecs.js.map +1 -0
- package/dist/index.cjs +1651 -0
- package/dist/index.cjs.map +6 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +10 -0
- package/dist/index.js.map +1 -0
- package/dist/kernels.d.ts +51 -0
- package/dist/kernels.d.ts.map +1 -0
- package/dist/kernels.js +359 -0
- package/dist/kernels.js.map +1 -0
- package/dist/layout.d.ts +52 -0
- package/dist/layout.d.ts.map +1 -0
- package/dist/layout.js +669 -0
- package/dist/layout.js.map +1 -0
- package/dist/tessellate.d.ts +31 -0
- package/dist/tessellate.d.ts.map +1 -0
- package/dist/tessellate.js +102 -0
- package/dist/tessellate.js.map +1 -0
- package/dist/types.d.ts +113 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +41 -0
- package/dist/types.js.map +1 -0
- package/dist/worker.cjs +73 -0
- package/dist/worker.cjs.map +6 -0
- package/dist/worker.d.ts +11 -0
- package/dist/worker.d.ts.map +1 -0
- package/dist/worker.js +10 -0
- package/dist/worker.js.map +1 -0
- package/package.json +48 -0
- package/src/builder.ts +569 -0
- package/src/codecs.ts +155 -0
- package/src/index.ts +93 -0
- package/src/kernels.ts +463 -0
- package/src/layout.ts +833 -0
- package/src/tessellate.ts +133 -0
- package/src/types.ts +200 -0
- 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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"}
|