lazycogs 0.2.0__tar.gz → 0.3.0__tar.gz
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.
- {lazycogs-0.2.0 → lazycogs-0.3.0}/PKG-INFO +30 -1
- {lazycogs-0.2.0 → lazycogs-0.3.0}/README.md +27 -0
- {lazycogs-0.2.0 → lazycogs-0.3.0}/pyproject.toml +3 -1
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/_backend.py +28 -15
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/_core.py +76 -17
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/_explain.py +1 -1
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/_grid.py +8 -12
- {lazycogs-0.2.0 → lazycogs-0.3.0}/LICENSE +0 -0
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/__init__.py +0 -0
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/_chunk_reader.py +0 -0
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/_cql2.py +0 -0
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/_executor.py +0 -0
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/_mosaic_methods.py +0 -0
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/_reproject.py +0 -0
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/_storage_ext.py +0 -0
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/_store.py +0 -0
- {lazycogs-0.2.0 → lazycogs-0.3.0}/src/lazycogs/_temporal.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.3
|
|
2
2
|
Name: lazycogs
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.0
|
|
4
4
|
Summary: Lazily load COG assets from STAC items into xarray DataArrays using async-geotiff
|
|
5
5
|
Keywords: COG,STAC,xarray,geotiff,raster,geospatial
|
|
6
6
|
Author: Henry Rodman
|
|
@@ -42,8 +42,10 @@ Requires-Dist: numpy>=2.4.4
|
|
|
42
42
|
Requires-Dist: obstore>=0.9.2
|
|
43
43
|
Requires-Dist: pandas>=3.0.2
|
|
44
44
|
Requires-Dist: pyproj>=3.7.2
|
|
45
|
+
Requires-Dist: rasterix>=0.2.0
|
|
45
46
|
Requires-Dist: rustac[arrow]>=0.9.10
|
|
46
47
|
Requires-Dist: xarray>=2026.2.0
|
|
48
|
+
Requires-Dist: xproj>=0.2.0
|
|
47
49
|
Requires-Dist: dask>=2026.3.0 ; extra == 'dask'
|
|
48
50
|
Requires-Python: >=3.12
|
|
49
51
|
Project-URL: Repository, https://github.com/developmentseed/lazycogs
|
|
@@ -86,6 +88,16 @@ Not yet published to PyPI. Install directly from GitHub:
|
|
|
86
88
|
pip install lazycogs
|
|
87
89
|
```
|
|
88
90
|
|
|
91
|
+
## Coordinate convention
|
|
92
|
+
|
|
93
|
+
`lazycogs.open()` returns a DataArray whose `y` coordinates follow the standard
|
|
94
|
+
north-up raster convention with the origin in the top left (not bottom left). That is, `y` coordinates are **descending** from north to south. In other words,
|
|
95
|
+
y label `0` is the northernmost pixel and `y[-1]` is the southernmost. This
|
|
96
|
+
matches the affine transform and is consistent with `odc-stac`, `rioxarray`, and
|
|
97
|
+
GDAL.
|
|
98
|
+
|
|
99
|
+
Use ``sel(y=slice(north, south))`` (high to low) for spatial subsetting.
|
|
100
|
+
|
|
89
101
|
## Example
|
|
90
102
|
|
|
91
103
|
```python
|
|
@@ -119,6 +131,23 @@ da = lazycogs.open(
|
|
|
119
131
|
)
|
|
120
132
|
```
|
|
121
133
|
|
|
134
|
+
### Async loading
|
|
135
|
+
|
|
136
|
+
When you are already inside an async context (for example, a Jupyter
|
|
137
|
+
notebook running on an asyncio loop), you can trigger chunk reads
|
|
138
|
+
without blocking the event loop:
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
# Fetch data asynchronously and load into memory in-place.
|
|
142
|
+
subset = await da.isel(x=slice(0, 10), y=slice(0, 10), time=slice(0, 10).load_async()
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
`load_async` uses xarray's async protocol, which dispatches through
|
|
146
|
+
`MultiBandStacBackendArray.async_getitem` and stays on the caller's
|
|
147
|
+
event loop. Multiple concurrent chunk reads overlap naturally, so the
|
|
148
|
+
async path can be faster than the synchronous `da.compute()` when
|
|
149
|
+
reading many chunks inside an already-running loop.
|
|
150
|
+
|
|
122
151
|
## Documentation
|
|
123
152
|
|
|
124
153
|
- [Home](https://developmentseed.github.io/lazycogs/) — quickstart and full usage guide
|
|
@@ -33,6 +33,16 @@ Not yet published to PyPI. Install directly from GitHub:
|
|
|
33
33
|
pip install lazycogs
|
|
34
34
|
```
|
|
35
35
|
|
|
36
|
+
## Coordinate convention
|
|
37
|
+
|
|
38
|
+
`lazycogs.open()` returns a DataArray whose `y` coordinates follow the standard
|
|
39
|
+
north-up raster convention with the origin in the top left (not bottom left). That is, `y` coordinates are **descending** from north to south. In other words,
|
|
40
|
+
y label `0` is the northernmost pixel and `y[-1]` is the southernmost. This
|
|
41
|
+
matches the affine transform and is consistent with `odc-stac`, `rioxarray`, and
|
|
42
|
+
GDAL.
|
|
43
|
+
|
|
44
|
+
Use ``sel(y=slice(north, south))`` (high to low) for spatial subsetting.
|
|
45
|
+
|
|
36
46
|
## Example
|
|
37
47
|
|
|
38
48
|
```python
|
|
@@ -66,6 +76,23 @@ da = lazycogs.open(
|
|
|
66
76
|
)
|
|
67
77
|
```
|
|
68
78
|
|
|
79
|
+
### Async loading
|
|
80
|
+
|
|
81
|
+
When you are already inside an async context (for example, a Jupyter
|
|
82
|
+
notebook running on an asyncio loop), you can trigger chunk reads
|
|
83
|
+
without blocking the event loop:
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
# Fetch data asynchronously and load into memory in-place.
|
|
87
|
+
subset = await da.isel(x=slice(0, 10), y=slice(0, 10), time=slice(0, 10).load_async()
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
`load_async` uses xarray's async protocol, which dispatches through
|
|
91
|
+
`MultiBandStacBackendArray.async_getitem` and stays on the caller's
|
|
92
|
+
event loop. Multiple concurrent chunk reads overlap naturally, so the
|
|
93
|
+
async path can be faster than the synchronous `da.compute()` when
|
|
94
|
+
reading many chunks inside an already-running loop.
|
|
95
|
+
|
|
69
96
|
## Documentation
|
|
70
97
|
|
|
71
98
|
- [Home](https://developmentseed.github.io/lazycogs/) — quickstart and full usage guide
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "lazycogs"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.3.0"
|
|
4
4
|
description = "Lazily load COG assets from STAC items into xarray DataArrays using async-geotiff"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = {file = "LICENSE"}
|
|
@@ -28,8 +28,10 @@ dependencies = [
|
|
|
28
28
|
"obstore>=0.9.2",
|
|
29
29
|
"pandas>=3.0.2",
|
|
30
30
|
"pyproj>=3.7.2",
|
|
31
|
+
"rasterix>=0.2.0",
|
|
31
32
|
"rustac[arrow]>=0.9.10",
|
|
32
33
|
"xarray>=2026.2.0",
|
|
34
|
+
"xproj>=0.2.0",
|
|
33
35
|
]
|
|
34
36
|
|
|
35
37
|
[project.optional-dependencies]
|
|
@@ -399,10 +399,8 @@ class MultiBandStacBackendArray(BackendArray):
|
|
|
399
399
|
) -> _SpatialWindow:
|
|
400
400
|
"""Resolve spatial indexers to a concrete chunk window.
|
|
401
401
|
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
the COG), then computes the chunk affine transform and EPSG:4326
|
|
405
|
-
bounding box.
|
|
402
|
+
Computes the chunk affine transform and EPSG:4326 bounding box from
|
|
403
|
+
the top-down y/x indexers.
|
|
406
404
|
|
|
407
405
|
Args:
|
|
408
406
|
y_key: Integer or slice indexer for the y dimension.
|
|
@@ -426,19 +424,15 @@ class MultiBandStacBackendArray(BackendArray):
|
|
|
426
424
|
else:
|
|
427
425
|
squeeze_x = False
|
|
428
426
|
|
|
429
|
-
|
|
430
|
-
|
|
427
|
+
y_start = y_key.start if y_key.start is not None else 0
|
|
428
|
+
y_stop = y_key.stop if y_key.stop is not None else self.dst_height
|
|
431
429
|
x_start = x_key.start if x_key.start is not None else 0
|
|
432
430
|
x_stop = x_key.stop if x_key.stop is not None else self.dst_width
|
|
433
431
|
|
|
434
|
-
|
|
435
|
-
y_start_physical = self.dst_height - y_stop_logical
|
|
436
|
-
y_stop_physical = self.dst_height - y_start_logical
|
|
437
|
-
|
|
438
|
-
chunk_height = y_stop_physical - y_start_physical
|
|
432
|
+
chunk_height = y_stop - y_start
|
|
439
433
|
chunk_width = x_stop - x_start
|
|
440
434
|
|
|
441
|
-
chunk_affine = self.dst_affine * Affine.translation(x_start,
|
|
435
|
+
chunk_affine = self.dst_affine * Affine.translation(x_start, y_start)
|
|
442
436
|
|
|
443
437
|
minx = chunk_affine.c
|
|
444
438
|
maxy = chunk_affine.f
|
|
@@ -486,6 +480,28 @@ class MultiBandStacBackendArray(BackendArray):
|
|
|
486
480
|
self._sync_getitem,
|
|
487
481
|
)
|
|
488
482
|
|
|
483
|
+
async def async_getitem(self, key: indexing.ExplicitIndexer) -> np.typing.ArrayLike:
|
|
484
|
+
"""Return the data for the requested index without blocking the event loop.
|
|
485
|
+
|
|
486
|
+
This method implements xarray's async indexing protocol, enabling
|
|
487
|
+
callers that already have an active event loop to dispatch chunk
|
|
488
|
+
reads without spawning a background thread.
|
|
489
|
+
|
|
490
|
+
Args:
|
|
491
|
+
key: An xarray ``ExplicitIndexer``.
|
|
492
|
+
|
|
493
|
+
Returns:
|
|
494
|
+
A numpy array (or array-like) with shape determined by the
|
|
495
|
+
indexing key.
|
|
496
|
+
|
|
497
|
+
"""
|
|
498
|
+
return await indexing.async_explicit_indexing_adapter(
|
|
499
|
+
key,
|
|
500
|
+
self.shape,
|
|
501
|
+
indexing.IndexingSupport.BASIC,
|
|
502
|
+
self._async_getitem,
|
|
503
|
+
)
|
|
504
|
+
|
|
489
505
|
def _sync_getitem(self, key: tuple[Any, ...]) -> np.ndarray:
|
|
490
506
|
"""Sync adapter that runs ``_async_getitem`` on the background loop.
|
|
491
507
|
|
|
@@ -574,9 +590,6 @@ class MultiBandStacBackendArray(BackendArray):
|
|
|
574
590
|
if result is None:
|
|
575
591
|
result = np.full(out_shape, fill, dtype=self.dtype)
|
|
576
592
|
|
|
577
|
-
# Physical data is top-down; flip to ascending y order for xarray.
|
|
578
|
-
result = result[:, :, ::-1, :]
|
|
579
|
-
|
|
580
593
|
# result shape: (n_selected_bands, n_time, chunk_height, chunk_width)
|
|
581
594
|
# Apply squeezes in axis order: time (axis 1), band (axis 0), y (-2), x (-1).
|
|
582
595
|
out: np.ndarray = result
|
|
@@ -7,9 +7,10 @@ import time
|
|
|
7
7
|
from typing import TYPE_CHECKING, Any, Self
|
|
8
8
|
|
|
9
9
|
import numpy as np
|
|
10
|
-
import xarray as xr
|
|
11
10
|
from pyproj import CRS, Transformer
|
|
11
|
+
from rasterix import RasterIndex
|
|
12
12
|
from rustac import DuckdbClient
|
|
13
|
+
from xarray import Coordinates, DataArray, Variable
|
|
13
14
|
from xarray.core import indexing
|
|
14
15
|
|
|
15
16
|
from lazycogs._backend import MultiBandStacBackendArray
|
|
@@ -271,7 +272,7 @@ def _build_dataarray(
|
|
|
271
272
|
store: ObjectStore | None = None,
|
|
272
273
|
max_concurrent_reads: int = 32,
|
|
273
274
|
path_from_href: Callable[[str], str] | None = None,
|
|
274
|
-
) ->
|
|
275
|
+
) -> DataArray:
|
|
275
276
|
"""Assemble the lazy DataArray from pre-computed parameters.
|
|
276
277
|
|
|
277
278
|
This is the shared implementation used by both :func:`open` and
|
|
@@ -311,7 +312,7 @@ def _build_dataarray(
|
|
|
311
312
|
Lazy ``xr.DataArray`` with dimensions ``(band, time, y, x)``.
|
|
312
313
|
|
|
313
314
|
"""
|
|
314
|
-
dst_affine, dst_width, dst_height
|
|
315
|
+
dst_affine, dst_width, dst_height = compute_output_grid(
|
|
315
316
|
bbox=bbox,
|
|
316
317
|
resolution=resolution,
|
|
317
318
|
)
|
|
@@ -337,7 +338,7 @@ def _build_dataarray(
|
|
|
337
338
|
path_from_href=path_from_href,
|
|
338
339
|
)
|
|
339
340
|
lazy = indexing.LazilyIndexedArray(multi)
|
|
340
|
-
var =
|
|
341
|
+
var = Variable(("band", "time", "y", "x"), lazy)
|
|
341
342
|
|
|
342
343
|
# Only convert to dask when the caller explicitly requests chunking.
|
|
343
344
|
# Without this guard, xr.concat (used inside to_array) would eagerly load
|
|
@@ -347,22 +348,80 @@ def _build_dataarray(
|
|
|
347
348
|
if chunks is not None:
|
|
348
349
|
var = var.chunk(chunks)
|
|
349
350
|
|
|
351
|
+
index = RasterIndex.from_transform(
|
|
352
|
+
dst_affine,
|
|
353
|
+
width=dst_width,
|
|
354
|
+
height=dst_height,
|
|
355
|
+
x_dim="x",
|
|
356
|
+
y_dim="y",
|
|
357
|
+
crs=dst_crs,
|
|
358
|
+
)
|
|
359
|
+
spatial_coords = Coordinates.from_xindex(index)
|
|
360
|
+
|
|
350
361
|
time_coord = np.array(time_coords, dtype="datetime64[D]")
|
|
351
362
|
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
363
|
+
gt = [
|
|
364
|
+
dst_affine.a,
|
|
365
|
+
dst_affine.b,
|
|
366
|
+
dst_affine.c,
|
|
367
|
+
dst_affine.d,
|
|
368
|
+
dst_affine.e,
|
|
369
|
+
dst_affine.f,
|
|
370
|
+
]
|
|
371
|
+
|
|
372
|
+
spatial_ref = DataArray(
|
|
373
|
+
np.array(0),
|
|
374
|
+
attrs={
|
|
375
|
+
"crs_wkt": dst_crs.to_wkt(),
|
|
376
|
+
"GeoTransform": " ".join(str(v) for v in gt),
|
|
359
377
|
},
|
|
360
378
|
)
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
379
|
+
|
|
380
|
+
attributes = {
|
|
381
|
+
"grid_mapping": "spatial_ref",
|
|
382
|
+
"zarr_conventions": [
|
|
383
|
+
{
|
|
384
|
+
"schema_url": "https://raw.githubusercontent.com/zarr-experimental/geo-proj/refs/tags/v1/schema.json",
|
|
385
|
+
"spec_url": "https://github.com/zarr-experimental/geo-proj/blob/v1/README.md",
|
|
386
|
+
"uuid": "f17cb550-5864-4468-aeb7-f3180cfb622f",
|
|
387
|
+
"name": "proj:",
|
|
388
|
+
"description": (
|
|
389
|
+
"Coordinate reference system information for geospatial data"
|
|
390
|
+
),
|
|
391
|
+
},
|
|
392
|
+
{
|
|
393
|
+
"schema_url": "https://raw.githubusercontent.com/zarr-conventions/spatial/refs/tags/v1/schema.json",
|
|
394
|
+
"spec_url": "https://github.com/zarr-conventions/spatial/blob/v1/README.md",
|
|
395
|
+
"uuid": "689b58e2-cf7b-45e0-9fff-9cfc0883d6b4",
|
|
396
|
+
"name": "spatial:",
|
|
397
|
+
"description": "Spatial coordinate information",
|
|
398
|
+
},
|
|
399
|
+
],
|
|
400
|
+
"spatial:dimensions": ["y", "x"],
|
|
401
|
+
"spatial:bbox": bbox,
|
|
402
|
+
"spatial:transform_type": "affine",
|
|
403
|
+
"spatial:transform": gt,
|
|
404
|
+
"spatial:shape": [dst_height, dst_width],
|
|
405
|
+
"spatial:registration": "pixel",
|
|
406
|
+
"_stac_backend": multi,
|
|
407
|
+
"_stac_time_coords": _CompactDateArray(time_coord),
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
# Zarr geo-proj convention
|
|
411
|
+
epsg = dst_crs.to_epsg()
|
|
412
|
+
if epsg is not None:
|
|
413
|
+
attributes["proj:code"] = f"EPSG:{epsg}"
|
|
414
|
+
else:
|
|
415
|
+
attributes["proj:wkt2"] = dst_crs.to_wkt()
|
|
416
|
+
|
|
417
|
+
return DataArray(
|
|
418
|
+
var,
|
|
419
|
+
coords=Coordinates(
|
|
420
|
+
{"band": resolved_bands, "time": time_coord, "spatial_ref": spatial_ref},
|
|
421
|
+
)
|
|
422
|
+
| spatial_coords,
|
|
423
|
+
attrs=attributes,
|
|
424
|
+
)
|
|
366
425
|
|
|
367
426
|
|
|
368
427
|
def open( # noqa: A001
|
|
@@ -385,7 +444,7 @@ def open( # noqa: A001
|
|
|
385
444
|
max_concurrent_reads: int = 32,
|
|
386
445
|
path_from_href: Callable[[str], str] | None = None,
|
|
387
446
|
duckdb_client: DuckdbClient | None = None,
|
|
388
|
-
) ->
|
|
447
|
+
) -> DataArray:
|
|
389
448
|
"""Open a mosaic of STAC items as a lazy ``(band, time, y, x)`` DataArray.
|
|
390
449
|
|
|
391
450
|
``href`` must be a path to a geoparquet file (``.parquet`` or
|
|
@@ -429,7 +429,7 @@ def _roi_pixel_offsets(
|
|
|
429
429
|
x_start = round((float(da.x.to_numpy()[0]) - affine.c) / resolution - 0.5)
|
|
430
430
|
|
|
431
431
|
y_start_physical = round(
|
|
432
|
-
(affine.f - float(da.y.to_numpy()[
|
|
432
|
+
(affine.f - float(da.y.to_numpy()[0])) / resolution - 0.5,
|
|
433
433
|
)
|
|
434
434
|
|
|
435
435
|
return (
|
|
@@ -5,7 +5,6 @@ from __future__ import annotations
|
|
|
5
5
|
import math
|
|
6
6
|
from typing import TYPE_CHECKING
|
|
7
7
|
|
|
8
|
-
import numpy as np
|
|
9
8
|
from affine import Affine
|
|
10
9
|
|
|
11
10
|
if TYPE_CHECKING:
|
|
@@ -15,22 +14,22 @@ if TYPE_CHECKING:
|
|
|
15
14
|
def compute_output_grid(
|
|
16
15
|
bbox: tuple[float, float, float, float],
|
|
17
16
|
resolution: float,
|
|
18
|
-
) -> tuple[Affine, int, int
|
|
17
|
+
) -> tuple[Affine, int, int]:
|
|
19
18
|
"""Compute the output raster grid from a bounding box and resolution.
|
|
20
19
|
|
|
21
20
|
The grid is aligned to the bbox corners, with x increasing left-to-right
|
|
22
|
-
and y
|
|
23
|
-
|
|
21
|
+
and y decreasing top-to-bottom (descending), following the standard
|
|
22
|
+
north-up raster convention. Label-based slicing with ``xarray.sel`` on
|
|
23
|
+
the ``y`` dimension uses ``slice(north, south)`` (high to low).
|
|
24
24
|
|
|
25
25
|
Args:
|
|
26
26
|
bbox: ``(minx, miny, maxx, maxy)`` in the target CRS.
|
|
27
27
|
resolution: Pixel size in CRS units (assumed square).
|
|
28
28
|
|
|
29
29
|
Returns:
|
|
30
|
-
A
|
|
31
|
-
|
|
32
|
-
``
|
|
33
|
-
``y_coords`` are 1-D arrays of pixel-centre coordinates.
|
|
30
|
+
A three-tuple ``(transform, width, height)`` where ``transform`` is
|
|
31
|
+
the affine mapping from pixel space to CRS space and ``width`` /
|
|
32
|
+
``height`` are the grid dimensions.
|
|
34
33
|
|
|
35
34
|
"""
|
|
36
35
|
minx, miny, maxx, maxy = bbox
|
|
@@ -41,10 +40,7 @@ def compute_output_grid(
|
|
|
41
40
|
# Origin at the top-left corner of the top-left pixel.
|
|
42
41
|
transform = Affine(resolution, 0.0, minx, 0.0, -resolution, maxy)
|
|
43
42
|
|
|
44
|
-
|
|
45
|
-
y_coords = miny + resolution / 2 + np.arange(height) * resolution
|
|
46
|
-
|
|
47
|
-
return transform, width, height, x_coords, y_coords
|
|
43
|
+
return transform, width, height
|
|
48
44
|
|
|
49
45
|
|
|
50
46
|
def align_bbox(
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|