satimg 0.3.0__tar.gz

satimg-0.3.0/.gitignore

@@ -0,0 +1,168 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+data/*
+examples/*
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+
+# macOS stores DS_Store files on remote file systems.
+.DS_Store
+/.idea/
+/tests/**/tmp/

satimg-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 peachfuzz11
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

satimg-0.3.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.5
+Name: satimg
+Version: 0.3.0
+Summary: A uniform, tile-friendly wrapper over satellite imagery
+Project-URL: Homepage, https://github.com/peachfuzz11/satimg
+Project-URL: Repository, https://github.com/peachfuzz11/satimg
+Project-URL: Issues, https://github.com/peachfuzz11/satimg/issues
+Author-email: peachfuzz11 <pederh11@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: deep-zoom,geospatial,imagery,landsat,raster,remote-sensing,satellite,sentinel,tiling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.14.2
+Requires-Dist: dask[array]>=2025.10.0
+Requires-Dist: onnxruntime>=1.23.2
+Requires-Dist: pillow>=12.0.0
+Requires-Dist: pystac-client>=0.9.0
+Requires-Dist: rasterio>=1.4.3
+Requires-Dist: rioxarray>=0.19.0
+Requires-Dist: roaring-landmask>=0.10.1
+Requires-Dist: xarray>=2025.10.1
+Description-Content-Type: text/markdown
+
+# satimg
+
+A uniform, tile-friendly wrapper over satellite imagery. Point it at a product
+directory and you get the same interface regardless of sensor: three views on the
+pixels and one clean way to walk them in windows without ever losing track of
+where a window came from.
+
+Supported products: Sentinel-1 GRD (IW / EW), Sentinel-2 L1C, Landsat C2 L1.
+
+## Concepts
+
+| Object | What it is |
+| --- | --- |
+| `Product` | A product directory. Exposes `.raw`, `.rgb`, `.gray`, `.patches(...)`, metadata. |
+| `Raster` | A lazy `(band, y, x)` array. Reads nothing until you ask for values. |
+| `Window` | An immutable pixel rectangle (`col`, `row`, `width`, `height`). Pure geometry. |
+| `Grid` | Lays `Window`s over an image with a step and an edge policy. |
+| `Patch` | A `Window` bound to the `Raster` it came from. `.array` (lazy) / `.values` (numpy) + geo helpers. |
+
+### Three views on the pixels
+
+```python
+import satimg
+
+product = satimg.open("/data/S2A_MSIL1C_20220114T103401_..._T33UUB_....SAFE")
+
+product.raw    # every native band, merged onto one grid, native dtype   -> Raster
+product.rgb    # 3-band uint8 true-colour visualisation                  -> Raster
+product.gray   # 1-band uint8 visualisation                              -> Raster
+```
+
+All three are lazy `Raster`s over the same grid, so a `Window` means the same
+thing in each.
+
+### Walking the image in patches
+
+```python
+for patch in product.patches(512, overlap=64, kind="rgb"):
+    tile = patch.values            # np.ndarray, (3, 512, 512), uint8
+    x0, y0 = patch.col, patch.row  # exact offset in the full image
+    lat, lon = patch.center_latlon # where the patch sits on Earth
+    ...
+```
+
+`for patch in product` is shorthand for `product.patches()` (raw bands,
+512 px, no overlap).
+
+`kind=` picks the view (`"raw"` / `"rgb"` / `"gray"`). `batch=n` yields lists of
+`n` patches instead of one at a time.
+
+### Edge handling
+
+`product.patches(size, edge=...)` decides what happens at the right / bottom border:
+
+| `edge` | behaviour | use for |
+| --- | --- | --- |
+| `"trim"` (default) | last row/col of patches is smaller — you get exactly the pixels that exist | analysis, lossless re-assembly |
+| `"pad"` | every patch is exactly `size`, overhang zero-filled | batched model inference |
+| `"skip"` | drop partial patches, keep only full interior tiles | training-set extraction |
+
+Indices are always conserved: `patch.window` tells you where the tile belongs,
+`patch.window.clip(product.width, product.height)` gives its valid region.
+
+### Mapping results back
+
+```python
+patch = next(product.patches(1024, kind="rgb"))
+boxes = detect(patch.values)            # boxes in patch pixels
+boxes[:, [0, 2]] += patch.window.col    # -> full-image pixels
+boxes[:, [1, 3]] += patch.window.row
+latlon = product.transformer.rowcol_to_latlon(boxes[:, [1, 0]])
+```
+
+## Working with a single window
+
+```python
+from satimg import Window
+
+win = Window(col=4096, row=2048, width=1024, height=1024)
+chip = product.raw.read(win)     # lazy xarray.DataArray, dims (band, y, x)
+chip = product.raw.values(win)   # numpy, zero-padded if the window overhangs
+```
+
+## Rasters compose
+
+```python
+ndwi = product.raw.map(lambda d: (d.isel(band=2) - d.isel(band=7))
+                                 / (d.isel(band=2) + d.isel(band=7)),
+                       name="ndwi")
+for patch in ndwi.patches(512):
+    ...
+```
+
+## Downloading
+
+`search` is anonymous; `download` needs a (free) account for the archive.
+Pass credentials to the connector, or set environment variables
+(`CDSE_USERNAME` / `CDSE_PASSWORD` for Copernicus, `USGS_USERNAME` /
+`USGS_PASSWORD` / optional `USGS_TOKEN` for USGS).
+
+```python
+from satimg import get_connector
+
+connector = get_connector("sentinel-2-l1c")                     # search only
+items = connector.search(geojson=aoi, start_datetime=start, stop_datetime=stop)
+
+connector = get_connector("sentinel-2-l1c",
+                          username="me@example.com", password="...")
+connector.download(items[0], "/data/scene.zip")
+
+with satimg.open_zip("/data/scene.zip") as product:
+    ...
+```
+
+## Deep Zoom
+
+```python
+from satimg.deepzoom import DeepZoom
+
+DeepZoom(tile_size=512).build(product.rgb, "/tmp/scene")  # -> /tmp/scene.dzi
+```
+
+## Adding a product
+
+Subclass `Product`, implement `raw`, `_render_rgb`, and the metadata properties,
+and register a filename pattern:
+
+```python
+from satimg.registry import register
+
+@register(r"^MY_SENSOR_\d{8}.*$")
+class MySensorProduct(Product):
+    ...
+```
+
+Importing `satimg.products` registers the built-ins.
+
+## Development
+
+```sh
+uv sync
+uv run pytest                      # fast unit tests + product integration tests
+uv run pytest tests/test_geometry.py tests/test_raster.py   # just the fast ones
+```
+
+Integration tests run against minified scenes under `tests/data/` — real
+georeferencing and metadata, zeroed pixels.

satimg-0.3.0/README.md

@@ -0,0 +1,147 @@
+# satimg
+
+A uniform, tile-friendly wrapper over satellite imagery. Point it at a product
+directory and you get the same interface regardless of sensor: three views on the
+pixels and one clean way to walk them in windows without ever losing track of
+where a window came from.
+
+Supported products: Sentinel-1 GRD (IW / EW), Sentinel-2 L1C, Landsat C2 L1.
+
+## Concepts
+
+| Object | What it is |
+| --- | --- |
+| `Product` | A product directory. Exposes `.raw`, `.rgb`, `.gray`, `.patches(...)`, metadata. |
+| `Raster` | A lazy `(band, y, x)` array. Reads nothing until you ask for values. |
+| `Window` | An immutable pixel rectangle (`col`, `row`, `width`, `height`). Pure geometry. |
+| `Grid` | Lays `Window`s over an image with a step and an edge policy. |
+| `Patch` | A `Window` bound to the `Raster` it came from. `.array` (lazy) / `.values` (numpy) + geo helpers. |
+
+### Three views on the pixels
+
+```python
+import satimg
+
+product = satimg.open("/data/S2A_MSIL1C_20220114T103401_..._T33UUB_....SAFE")
+
+product.raw    # every native band, merged onto one grid, native dtype   -> Raster
+product.rgb    # 3-band uint8 true-colour visualisation                  -> Raster
+product.gray   # 1-band uint8 visualisation                              -> Raster
+```
+
+All three are lazy `Raster`s over the same grid, so a `Window` means the same
+thing in each.
+
+### Walking the image in patches
+
+```python
+for patch in product.patches(512, overlap=64, kind="rgb"):
+    tile = patch.values            # np.ndarray, (3, 512, 512), uint8
+    x0, y0 = patch.col, patch.row  # exact offset in the full image
+    lat, lon = patch.center_latlon # where the patch sits on Earth
+    ...
+```
+
+`for patch in product` is shorthand for `product.patches()` (raw bands,
+512 px, no overlap).
+
+`kind=` picks the view (`"raw"` / `"rgb"` / `"gray"`). `batch=n` yields lists of
+`n` patches instead of one at a time.
+
+### Edge handling
+
+`product.patches(size, edge=...)` decides what happens at the right / bottom border:
+
+| `edge` | behaviour | use for |
+| --- | --- | --- |
+| `"trim"` (default) | last row/col of patches is smaller — you get exactly the pixels that exist | analysis, lossless re-assembly |
+| `"pad"` | every patch is exactly `size`, overhang zero-filled | batched model inference |
+| `"skip"` | drop partial patches, keep only full interior tiles | training-set extraction |
+
+Indices are always conserved: `patch.window` tells you where the tile belongs,
+`patch.window.clip(product.width, product.height)` gives its valid region.
+
+### Mapping results back
+
+```python
+patch = next(product.patches(1024, kind="rgb"))
+boxes = detect(patch.values)            # boxes in patch pixels
+boxes[:, [0, 2]] += patch.window.col    # -> full-image pixels
+boxes[:, [1, 3]] += patch.window.row
+latlon = product.transformer.rowcol_to_latlon(boxes[:, [1, 0]])
+```
+
+## Working with a single window
+
+```python
+from satimg import Window
+
+win = Window(col=4096, row=2048, width=1024, height=1024)
+chip = product.raw.read(win)     # lazy xarray.DataArray, dims (band, y, x)
+chip = product.raw.values(win)   # numpy, zero-padded if the window overhangs
+```
+
+## Rasters compose
+
+```python
+ndwi = product.raw.map(lambda d: (d.isel(band=2) - d.isel(band=7))
+                                 / (d.isel(band=2) + d.isel(band=7)),
+                       name="ndwi")
+for patch in ndwi.patches(512):
+    ...
+```
+
+## Downloading
+
+`search` is anonymous; `download` needs a (free) account for the archive.
+Pass credentials to the connector, or set environment variables
+(`CDSE_USERNAME` / `CDSE_PASSWORD` for Copernicus, `USGS_USERNAME` /
+`USGS_PASSWORD` / optional `USGS_TOKEN` for USGS).
+
+```python
+from satimg import get_connector
+
+connector = get_connector("sentinel-2-l1c")                     # search only
+items = connector.search(geojson=aoi, start_datetime=start, stop_datetime=stop)
+
+connector = get_connector("sentinel-2-l1c",
+                          username="me@example.com", password="...")
+connector.download(items[0], "/data/scene.zip")
+
+with satimg.open_zip("/data/scene.zip") as product:
+    ...
+```
+
+## Deep Zoom
+
+```python
+from satimg.deepzoom import DeepZoom
+
+DeepZoom(tile_size=512).build(product.rgb, "/tmp/scene")  # -> /tmp/scene.dzi
+```
+
+## Adding a product
+
+Subclass `Product`, implement `raw`, `_render_rgb`, and the metadata properties,
+and register a filename pattern:
+
+```python
+from satimg.registry import register
+
+@register(r"^MY_SENSOR_\d{8}.*$")
+class MySensorProduct(Product):
+    ...
+```
+
+Importing `satimg.products` registers the built-ins.
+
+## Development
+
+```sh
+uv sync
+uv run pytest                      # fast unit tests + product integration tests
+uv run pytest tests/test_geometry.py tests/test_raster.py   # just the fast ones
+```
+
+Integration tests run against minified scenes under `tests/data/` — real
+georeferencing and metadata, zeroed pixels.

satimg-0.3.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "satimg"
+version = "0.3.0"
+description = "A uniform, tile-friendly wrapper over satellite imagery"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "peachfuzz11", email = "pederh11@gmail.com" }]
+keywords = [
+    "satellite",
+    "imagery",
+    "remote-sensing",
+    "sentinel",
+    "landsat",
+    "raster",
+    "geospatial",
+    "tiling",
+    "deep-zoom",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "beautifulsoup4>=4.14.2",
+    "dask[array]>=2025.10.0",
+    "onnxruntime>=1.23.2",
+    "pillow>=12.0.0",
+    "pystac-client>=0.9.0",
+    "rasterio>=1.4.3",
+    "rioxarray>=0.19.0",
+    "roaring-landmask>=0.10.1",
+    "xarray>=2025.10.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/peachfuzz11/satimg"
+Repository = "https://github.com/peachfuzz11/satimg"
+Issues = "https://github.com/peachfuzz11/satimg/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/satimg"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/satimg", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-ra"

satimg-0.3.0/src/satimg/__init__.py

@@ -0,0 +1,65 @@
+"""satimg -- a uniform, tile-friendly wrapper over satellite imagery.
+
+    import satimg
+
+    product = satimg.open("/data/S2A_MSIL1C_....SAFE")
+
+    for patch in product.patches(512, overlap=64, kind="rgb"):
+        do_something(patch.values)        # (band, y, x) uint8
+        print(patch.col, patch.row)       # where it sits in the full image
+        print(patch.center_latlon)        # where it sits on Earth
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import zipfile
+from contextlib import contextmanager
+from importlib.metadata import PackageNotFoundError, version as _version
+from typing import Iterator
+
+try:
+    __version__ = _version("satimg")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0"
+
+from satimg import products as _products  # noqa: F401  (populates the registry)
+from satimg.connectors import CredentialsError, get_connector
+from satimg.geometry import Grid, Window
+from satimg.product import Product
+from satimg.raster import Patch, Raster
+from satimg.registry import UnknownProductError, resolve
+
+__all__ = [
+    "__version__",
+    "open",
+    "open_zip",
+    "get_connector",
+    "Product",
+    "Raster",
+    "Patch",
+    "Window",
+    "Grid",
+    "UnknownProductError",
+    "CredentialsError",
+]
+
+
+def open(path: str) -> Product:
+    """Open a product directory, returning the matching :class:`Product`."""
+    return resolve(path)(path)
+
+
+@contextmanager
+def open_zip(zip_path: str, dest: str | None = None) -> Iterator[Product]:
+    """Extract a zipped product to a temp dir and yield it as a :class:`Product`.
+
+    The temp dir (under ``dest``, or the system default) is removed on exit.
+    """
+    with tempfile.TemporaryDirectory(dir=dest) as tmp:
+        with zipfile.ZipFile(zip_path) as archive:
+            archive.extractall(tmp)
+        entries = [os.path.join(tmp, e) for e in os.listdir(tmp)]
+        root = entries[0] if len(entries) == 1 and os.path.isdir(entries[0]) else tmp
+        yield open(root)

satimg-0.3.0/src/satimg/connectors/__init__.py

@@ -0,0 +1,46 @@
+"""Remote archive connectors, keyed by STAC collection name.
+
+``search`` is anonymous; ``download`` needs an account -- pass ``username=`` /
+``password=`` (and ``token=`` for USGS) or set the service's environment
+variables (see :mod:`satimg.connectors._credentials`).
+"""
+
+from __future__ import annotations
+
+from satimg.connectors._credentials import Credentials, CredentialsError
+from satimg.connectors.base import Connector, STACConnector
+from satimg.connectors.landsat import LandsatConnector
+from satimg.connectors.sentinel import Sentinel1Connector, Sentinel2Connector
+
+_CONNECTORS: dict[str, type[Connector]] = {
+    "sentinel-1-grd": Sentinel1Connector,
+    "sentinel-2-l1c": Sentinel2Connector,
+    "landsat-c2l1": LandsatConnector,
+}
+
+
+def get_connector(collection: str, **credentials) -> Connector:
+    """Instantiate the connector for a STAC ``collection`` name.
+
+    Extra keyword arguments (``username``, ``password``, ``token``) are passed to
+    the connector's constructor.
+    """
+    try:
+        cls = _CONNECTORS[collection]
+    except KeyError:
+        raise ValueError(
+            f"no connector for {collection!r}; known: {sorted(_CONNECTORS)}"
+        ) from None
+    return cls(**credentials)
+
+
+__all__ = [
+    "Connector",
+    "STACConnector",
+    "Sentinel1Connector",
+    "Sentinel2Connector",
+    "LandsatConnector",
+    "Credentials",
+    "CredentialsError",
+    "get_connector",
+]