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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: lazycogs
3
- Version: 0.2.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.2.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
- Converts logical ascending y indices (south-to-north, as exposed to
403
- xarray) to physical top-down row offsets (north-to-south, as stored in
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
- y_start_logical = y_key.start if y_key.start is not None else 0
430
- y_stop_logical = y_key.stop if y_key.stop is not None else self.dst_height
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
- # logical index 0 = southernmost = physical row (dst_height - 1)
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, y_start_physical)
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
- ) -> xr.DataArray:
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, x_coords, y_coords = compute_output_grid(
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 = xr.Variable(("band", "time", "y", "x"), lazy)
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
- da = xr.DataArray(
353
- var,
354
- coords={
355
- "band": resolved_bands,
356
- "time": time_coord,
357
- "y": y_coords,
358
- "x": x_coords,
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
- # Store explain metadata so that da.lazycogs.explain() can reconstruct
362
- # which DuckDB queries to run without re-specifying all open() parameters.
363
- da.attrs["_stac_backend"] = multi
364
- da.attrs["_stac_time_coords"] = _CompactDateArray(time_coord)
365
- return da
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
- ) -> xr.DataArray:
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()[-1])) / resolution - 0.5,
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, np.ndarray, np.ndarray]:
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 increasing bottom-to-top (ascending), so that label-based slicing
23
- with ``xarray.sel`` works naturally with ``(low, high)`` ranges.
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 five-tuple ``(transform, width, height, x_coords, y_coords)`` where
31
- ``transform`` is the affine mapping from pixel space to CRS space,
32
- ``width`` and ``height`` are the grid dimensions, and ``x_coords`` /
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
- x_coords = minx + resolution / 2 + np.arange(width) * resolution
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