lazycogs 0.1.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.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Development Seed
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 all
13
+ 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 THE
21
+ SOFTWARE.
@@ -0,0 +1,121 @@
1
+ Metadata-Version: 2.3
2
+ Name: lazycogs
3
+ Version: 0.1.0
4
+ Summary: Lazily load COG assets from STAC items into xarray DataArrays using async-geotiff
5
+ Keywords: COG,STAC,xarray,geotiff,raster,geospatial
6
+ Author: Henry Rodman
7
+ Author-email: Henry Rodman <henry.rodman@gmail.com>
8
+ License: MIT License
9
+
10
+ Copyright (c) 2026 Development Seed
11
+
12
+ Permission is hereby granted, free of charge, to any person obtaining a copy
13
+ of this software and associated documentation files (the "Software"), to deal
14
+ in the Software without restriction, including without limitation the rights
15
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
16
+ copies of the Software, and to permit persons to whom the Software is
17
+ furnished to do so, subject to the following conditions:
18
+
19
+ The above copyright notice and this permission notice shall be included in all
20
+ copies or substantial portions of the Software.
21
+
22
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
25
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
27
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
28
+ SOFTWARE.
29
+ Classifier: Development Status :: 3 - Alpha
30
+ Classifier: Intended Audience :: Science/Research
31
+ Classifier: Programming Language :: Python :: 3
32
+ Classifier: Programming Language :: Python :: 3.12
33
+ Classifier: Programming Language :: Python :: 3.13
34
+ Classifier: Programming Language :: Python :: 3.14
35
+ Classifier: Topic :: Scientific/Engineering :: GIS
36
+ Classifier: Topic :: Scientific/Engineering :: Image Processing
37
+ Requires-Dist: async-geotiff>=0.4.0
38
+ Requires-Dist: cql2>=0.5.5
39
+ Requires-Dist: numpy>=2.4.4
40
+ Requires-Dist: obstore>=0.9.2
41
+ Requires-Dist: pyproj>=3.7.2
42
+ Requires-Dist: rustac[arrow]>=0.9.10
43
+ Requires-Dist: xarray>=2026.2.0
44
+ Requires-Dist: dask>=2026.3.0 ; extra == 'dask'
45
+ Requires-Python: >=3.12
46
+ Project-URL: Repository, https://github.com/developmentseed/lazycogs
47
+ Project-URL: Documentation, https://developmentseed.org/lazycogs
48
+ Provides-Extra: dask
49
+ Description-Content-Type: text/markdown
50
+
51
+ ![lazycogs](./lazycogs.svg)
52
+
53
+ Open a lazy `(time, band, y, x)` xarray DataArray from thousands of cloud-optimized geotiffs (COGs). No GDAL required.
54
+
55
+ ## What is lazycogs?
56
+
57
+ [stackstac](https://stackstac.readthedocs.io) and [odc-stac](https://odc-stac.readthedocs.io) established the pattern that lazycogs builds on: take a STAC item collection and expose it as a spatially-aligned xarray DataArray ready for dask-parallel computation. Both are excellent tools that cover most satellite imagery workflows well. They rely on the trusty combination of rasterio and GDAL for data i/o and warping operations.
58
+
59
+ lazycogs takes the same approach but replaces GDAL and rasterio with a Rust-native stack: [rustac](https://stac-utils.github.io/rustac-py) for STAC queries over stac-geoparquet files, [async-geotiff](https://developmentseed/async-geotiff) for COG i/o, and [obstore](https://developmentseed.org/obstore) for cloud storage access.
60
+
61
+ The result is a tool that can instantly expose a lazy xarray DataArray view of massive STAC item archives in any CRS and resolution. Each array operation triggers a targeted spatial query on the stac-geoparquet file to find only the assets needed for that specific chunk — no upfront scan of every item required.
62
+
63
+ One constraint worth naming: lazycogs only reads Cloud Optimized GeoTIFFs. If your assets are in another format, this is not the right tool.
64
+
65
+ | Task | Library |
66
+ |---|---|
67
+ | STAC search + spatial indexing | `rustac` (DuckDB + geoparquet) |
68
+ | COG I/O | `async-geotiff` (Rust, no GDAL) |
69
+ | Cloud storage | `obstore` |
70
+ | Reprojection | `pyproj` + numpy |
71
+ | Lazy dataset construction | xarray `BackendEntrypoint` + `LazilyIndexedArray` |
72
+
73
+ ## Installation
74
+
75
+ Not yet published to PyPI. Install directly from GitHub:
76
+
77
+ ```bash
78
+ pip install git+https://github.com/developmentseed/lazycogs.git
79
+ ```
80
+
81
+ ## Example
82
+
83
+ ```python
84
+ import rustac
85
+ import lazycogs
86
+ from pyproj import Transformer
87
+
88
+ # set a target CRS and extent
89
+ dst_crs = "EPSG:32615"
90
+ dst_bbox = (380000.0, 4928000.0, 420000.0, 4984000.0)
91
+
92
+ # transform to 4326 for STAC search
93
+ transformer = Transformer.from_crs(dst_crs, "epsg:4326", alwaysxy=True)
94
+ bbox_4326 = transformer.transform_bounds(*dst_bbox)
95
+
96
+ # Search a STAC API and cache results to a local stac-geoparquet file.
97
+ await rustac.search_to(
98
+ "items.parquet",
99
+ "https://earth-search.aws.element84.com/v1",
100
+ collections=["sentinel-2-l2a"],
101
+ datetime="2023-06-01/2023-08-31",
102
+ bbox=bbox_4326,
103
+ )
104
+
105
+ # Open a fully lazy (time, band, y, x) DataArray. No COGs are read yet.
106
+ da = lazycogs.open(
107
+ "items.parquet",
108
+ bbox=dst_bbox,
109
+ crs=dst_crs,
110
+ resolution=10.0,
111
+ )
112
+ ```
113
+
114
+ ## Documentation
115
+
116
+ - [Home](https://developmentseed.github.io/lazycogs/) — quickstart and full usage guide
117
+ - [Example: Midwest US daily array](https://developmentseed.github.io/lazycogs/demo_midwest_daily/)
118
+ - [Example: Southwest US monthly composite](https://developmentseed.github.io/lazycogs/demo_southwest_monthly/)
119
+ - [Architecture](https://developmentseed.github.io/lazycogs/architecture/)
120
+ - [API Reference](https://developmentseed.github.io/lazycogs/api/)
121
+ - [Contributing](CONTRIBUTING.md)
@@ -0,0 +1,71 @@
1
+ ![lazycogs](./lazycogs.svg)
2
+
3
+ Open a lazy `(time, band, y, x)` xarray DataArray from thousands of cloud-optimized geotiffs (COGs). No GDAL required.
4
+
5
+ ## What is lazycogs?
6
+
7
+ [stackstac](https://stackstac.readthedocs.io) and [odc-stac](https://odc-stac.readthedocs.io) established the pattern that lazycogs builds on: take a STAC item collection and expose it as a spatially-aligned xarray DataArray ready for dask-parallel computation. Both are excellent tools that cover most satellite imagery workflows well. They rely on the trusty combination of rasterio and GDAL for data i/o and warping operations.
8
+
9
+ lazycogs takes the same approach but replaces GDAL and rasterio with a Rust-native stack: [rustac](https://stac-utils.github.io/rustac-py) for STAC queries over stac-geoparquet files, [async-geotiff](https://developmentseed/async-geotiff) for COG i/o, and [obstore](https://developmentseed.org/obstore) for cloud storage access.
10
+
11
+ The result is a tool that can instantly expose a lazy xarray DataArray view of massive STAC item archives in any CRS and resolution. Each array operation triggers a targeted spatial query on the stac-geoparquet file to find only the assets needed for that specific chunk — no upfront scan of every item required.
12
+
13
+ One constraint worth naming: lazycogs only reads Cloud Optimized GeoTIFFs. If your assets are in another format, this is not the right tool.
14
+
15
+ | Task | Library |
16
+ |---|---|
17
+ | STAC search + spatial indexing | `rustac` (DuckDB + geoparquet) |
18
+ | COG I/O | `async-geotiff` (Rust, no GDAL) |
19
+ | Cloud storage | `obstore` |
20
+ | Reprojection | `pyproj` + numpy |
21
+ | Lazy dataset construction | xarray `BackendEntrypoint` + `LazilyIndexedArray` |
22
+
23
+ ## Installation
24
+
25
+ Not yet published to PyPI. Install directly from GitHub:
26
+
27
+ ```bash
28
+ pip install git+https://github.com/developmentseed/lazycogs.git
29
+ ```
30
+
31
+ ## Example
32
+
33
+ ```python
34
+ import rustac
35
+ import lazycogs
36
+ from pyproj import Transformer
37
+
38
+ # set a target CRS and extent
39
+ dst_crs = "EPSG:32615"
40
+ dst_bbox = (380000.0, 4928000.0, 420000.0, 4984000.0)
41
+
42
+ # transform to 4326 for STAC search
43
+ transformer = Transformer.from_crs(dst_crs, "epsg:4326", alwaysxy=True)
44
+ bbox_4326 = transformer.transform_bounds(*dst_bbox)
45
+
46
+ # Search a STAC API and cache results to a local stac-geoparquet file.
47
+ await rustac.search_to(
48
+ "items.parquet",
49
+ "https://earth-search.aws.element84.com/v1",
50
+ collections=["sentinel-2-l2a"],
51
+ datetime="2023-06-01/2023-08-31",
52
+ bbox=bbox_4326,
53
+ )
54
+
55
+ # Open a fully lazy (time, band, y, x) DataArray. No COGs are read yet.
56
+ da = lazycogs.open(
57
+ "items.parquet",
58
+ bbox=dst_bbox,
59
+ crs=dst_crs,
60
+ resolution=10.0,
61
+ )
62
+ ```
63
+
64
+ ## Documentation
65
+
66
+ - [Home](https://developmentseed.github.io/lazycogs/) — quickstart and full usage guide
67
+ - [Example: Midwest US daily array](https://developmentseed.github.io/lazycogs/demo_midwest_daily/)
68
+ - [Example: Southwest US monthly composite](https://developmentseed.github.io/lazycogs/demo_southwest_monthly/)
69
+ - [Architecture](https://developmentseed.github.io/lazycogs/architecture/)
70
+ - [API Reference](https://developmentseed.github.io/lazycogs/api/)
71
+ - [Contributing](CONTRIBUTING.md)
@@ -0,0 +1,70 @@
1
+ [project]
2
+ name = "lazycogs"
3
+ version = "0.1.0"
4
+ description = "Lazily load COG assets from STAC items into xarray DataArrays using async-geotiff"
5
+ readme = "README.md"
6
+ license = {file = "LICENSE"}
7
+ authors = [
8
+ { name = "Henry Rodman", email = "henry.rodman@gmail.com" }
9
+ ]
10
+ requires-python = ">=3.12"
11
+ keywords = ["COG", "STAC", "xarray", "geotiff", "raster", "geospatial"]
12
+ classifiers = [
13
+ "Development Status :: 3 - Alpha",
14
+ "Intended Audience :: Science/Research",
15
+ "Programming Language :: Python :: 3",
16
+ "Programming Language :: Python :: 3.12",
17
+ "Programming Language :: Python :: 3.13",
18
+ "Programming Language :: Python :: 3.14",
19
+ "Topic :: Scientific/Engineering :: GIS",
20
+ "Topic :: Scientific/Engineering :: Image Processing",
21
+ ]
22
+ dependencies = [
23
+ "async-geotiff>=0.4.0",
24
+ "cql2>=0.5.5",
25
+ "numpy>=2.4.4",
26
+ "obstore>=0.9.2",
27
+ "pyproj>=3.7.2",
28
+ "rustac[arrow]>=0.9.10",
29
+ "xarray>=2026.2.0",
30
+ ]
31
+
32
+ [project.optional-dependencies]
33
+ dask = [
34
+ "dask>=2026.3.0",
35
+ ]
36
+
37
+ [project.urls]
38
+ Repository = "https://github.com/developmentseed/lazycogs"
39
+ Documentation = "https://developmentseed.org/lazycogs"
40
+
41
+ [build-system]
42
+ requires = ["uv_build>=0.11.6,<0.12.0"]
43
+ build-backend = "uv_build"
44
+
45
+ [dependency-groups]
46
+ dev = [
47
+ "lazycogs[dask]",
48
+ "jupyter>=1.1.1",
49
+ "lab>=8.9",
50
+ "pytest>=9.0.3",
51
+ "pytest-benchmark>=5.2.3",
52
+ "rasterio>=1.5.0",
53
+ "pre-commit>=4.6.0",
54
+ ]
55
+ docs = [
56
+ "mkdocs-jupyter>=0.26.2",
57
+ "mkdocs-material>=9.7.6",
58
+ "mkdocstrings[python]>=1.0.3",
59
+ ]
60
+
61
+ [tool.ruff]
62
+ exclude = []
63
+
64
+ [tool.pytest.ini_options]
65
+ testpaths = ["tests"]
66
+ addopts = "-vv --benchmark-disable --ignore=tests/benchmarks"
67
+ python_files = ["test_*.py", "bench_*.py"]
68
+ markers = [
69
+ "benchmark: performance benchmarks (run with --benchmark-enable)",
70
+ ]
@@ -0,0 +1,41 @@
1
+ """lazycogs: lazy xarray DataArrays from STAC COG collections."""
2
+
3
+ from lazycogs._core import open, open_async
4
+ from lazycogs._executor import set_reproject_workers
5
+ from lazycogs._grid import align_bbox
6
+ from lazycogs._store import store_for
7
+ from lazycogs._explain import ( # noqa: F401 — registers da.stac_cog accessor
8
+ ChunkRead,
9
+ ExplainPlan,
10
+ CogRead,
11
+ StacCogAccessor,
12
+ )
13
+ from lazycogs._mosaic_methods import (
14
+ CountMethod,
15
+ FirstMethod,
16
+ HighestMethod,
17
+ LowestMethod,
18
+ MeanMethod,
19
+ MedianMethod,
20
+ MosaicMethodBase,
21
+ StdevMethod,
22
+ )
23
+
24
+ __all__ = [
25
+ "open",
26
+ "open_async",
27
+ "align_bbox",
28
+ "store_for",
29
+ "set_reproject_workers",
30
+ "ExplainPlan",
31
+ "ChunkRead",
32
+ "CogRead",
33
+ "MosaicMethodBase",
34
+ "FirstMethod",
35
+ "HighestMethod",
36
+ "LowestMethod",
37
+ "MeanMethod",
38
+ "MedianMethod",
39
+ "StdevMethod",
40
+ "CountMethod",
41
+ ]