PyGeoFetch 2.6.2.8__tar.gz → 2.6.2.9__tar.gz

{pygeofetch-2.6.2.8 → pygeofetch-2.6.2.9}/CHANGELOG.md

@@ -20,7 +20,7 @@ date, and marked accordingly rather than filled in with invented
 bullet points.
 ```
 
-## [Unreleased] — v2.6.2.8.4
+## [Unreleased] — v2.6.2.9.4
 
 ```{note}
 Not yet published to PyPI. This entry documents work completed and
@@ -130,7 +130,7 @@ audit and remain open for a follow-up pass.
 
 ---
 
-## [2.6.2.8.4] — 2026-08-25 (latest)
+## [2.6.2.9.4] — 2026-08-25 (latest)
 
 Confirmed via direct fetch of the current PyPI listing.
 
@@ -149,7 +149,7 @@ Confirmed via direct fetch of the current PyPI listing.
 - `SearchQuery.sort_ascending: bool` — earlier examples showed a `sort_order: "asc"/"desc"` string field that doesn't exist on the model (the CLI's `--sort-order` flag does convert to this internally, so CLI docs were unaffected)
 - `DownloadOptions.post_process` requires a list of `PostProcessAction` objects — passing plain strings raises a real `pydantic.ValidationError`
 
-## [2.6.2.8] — 2026-08-24
+## [2.6.2.9] — 2026-08-24
 Real, verified release. Detailed notes not independently recovered from PyPI's release-history page (no distinct per-version notes exposed for this release specifically).
 
 ## [2.6.1] — 2026-08-22
@@ -261,9 +261,9 @@ recovered.
 
 ```{note}
 The previous version of this changelog had an entry labeled
-**"2.6.2.8.4 — 2026-07-12"** describing 22+ providers, Sentinel-1C/1D
+**"2.6.2.9.4 — 2026-07-12"** describing 22+ providers, Sentinel-1C/1D
 support, SLC search with provider routing, precise orbit file
-management, 17 spectral indices, and various bug fixes. **2.6.2.8.4 was
+management, 17 spectral indices, and various bug fixes. **2.6.2.9.4 was
 only ever released once, on 2026-08-25** — it was never released on
 2026-07-12. The date matches this real release, **1.0.8**, exactly.
 That content is reproduced below under the version it actually
@@ -406,8 +406,8 @@ The version of this file uploaded for this update had **5 entries
 covering 5 dates**. PyPI's real release history has **54 releases**.
 Specific issues found and fixed:
 
-1. **Two different entries were both labeled `2.6.2.8.4`**, dated
-   2026-07-29 and 2026-07-12. **2.6.2.8.4 was only ever released once**,
+1. **Two different entries were both labeled `2.6.2.9.4`**, dated
+   2026-07-29 and 2026-07-12. **2.6.2.9.4 was only ever released once**,
    on 2026-08-25 (confirmed directly from the live PyPI listing).
 2. **The 2026-07-12 entry's date exactly matches a real release**
    — version **1.0.8** — and its content (22+ providers, Sentinel-1C/D,

{pygeofetch-2.6.2.8/pygeofetch.egg-info → pygeofetch-2.6.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeofetch
-Version: 2.6.2.8
+Version: 2.6.2.9
 Summary: Universal satellite data pipeline + geospatial processing platform
 Author-email: Samuel Appiah Kubi <appiahkubis14@gmail.com>
 License: MIT License
@@ -369,7 +369,7 @@ If you use PyGeoFetch in your research or operational work, please cite it using
   title        = {PyGeoFetch: A Unified Python Framework for Multi-Provider Satellite Data Acquisition, Pre-download Quality Control, and Geospatial Processing},
   year         = {2026},
   publisher    = {Zenodo},
-  version      = {2.6.2.8.1},
+  version      = {2.6.2.9.1},
   doi          = {10.5281/zenodo.22087230},
   url          = {https://doi.org/10.5281/zenodo.22087230}
 }

{pygeofetch-2.6.2.8 → pygeofetch-2.6.2.9}/README.md

@@ -229,7 +229,7 @@ If you use PyGeoFetch in your research or operational work, please cite it using
   title        = {PyGeoFetch: A Unified Python Framework for Multi-Provider Satellite Data Acquisition, Pre-download Quality Control, and Geospatial Processing},
   year         = {2026},
   publisher    = {Zenodo},
-  version      = {2.6.2.8.1},
+  version      = {2.6.2.9.1},
   doi          = {10.5281/zenodo.22087230},
   url          = {https://doi.org/10.5281/zenodo.22087230}
 }

{pygeofetch-2.6.2.8 → pygeofetch-2.6.2.9}/pygeofetch/__init__.py

@@ -30,7 +30,7 @@ CLI::
     pygeofetch doctor
 """
 
-__version__ = "2.6.2.8.4"
+__version__ = "2.6.2.9.4"
 __author__ = "PyGeoFetch Contributors"
 __license__ = "MIT"
 

{pygeofetch-2.6.2.8 → pygeofetch-2.6.2.9}/pygeofetch/cli/index_commands.py

@@ -50,22 +50,64 @@ def index() -> None:
     "--nir", required=True, type=click.Path(exists=True), help="NIR band (e.g. B08.tif)"
 )
 @click.option("--output", "-o", default=None)
-def ndvi_cmd(red, nir, output):
-    """NDVI — Normalized Difference Vegetation Index. Range: -1 to +1. Vegetation > 0.3."""
+@click.option(
+    "--chunked", is_flag=True,
+    help="Process in memory-safe tiles for large rasters (e.g. drone orthomosaics) that exceed available RAM or the 4GB GeoTIFF limit.",
+)
+@click.option("--tile-size", default=1024, show_default=True, type=int, help="Tile edge length in pixels when --chunked is set.")
+def ndvi_cmd(red, nir, output, chunked, tile_size):
+    """NDVI — Normalized Difference Vegetation Index. Range: -1 to +1. Vegetation > 0.3.
+
+    Pass the SAME path to --red and --nir to auto-detect both bands from
+    one merged multi-band image (e.g. a drone orthomosaic), using its
+    real, embedded band descriptions.
+    """
     e = _engine()
-    r = e.indices.ndvi(red=red, nir=nir, output=output)
+    r = e.indices.ndvi(red=red, nir=nir, output=output, chunked=chunked, tile_size=tile_size)
     _pr(r, "NDVI")
 
 
+@index.command("ndre")
+@click.option(
+    "--rededge", required=True, type=click.Path(exists=True), help="Red edge band"
+)
+@click.option(
+    "--nir", required=True, type=click.Path(exists=True), help="NIR band"
+)
+@click.option("--output", "-o", default=None)
+@click.option(
+    "--chunked", is_flag=True,
+    help="Process in memory-safe tiles for large rasters that exceed available RAM or the 4GB GeoTIFF limit.",
+)
+@click.option("--tile-size", default=1024, show_default=True, type=int, help="Tile edge length in pixels when --chunked is set.")
+def ndre_cmd(rededge, nir, output, chunked, tile_size):
+    """NDRE — Normalized Difference Red Edge Index. Range: -1 to +1.
+
+    Less prone to saturation than NDVI in dense canopy -- useful for
+    crop stress and chlorophyll monitoring from drone multispectral
+    sensors. Pass the SAME path to --rededge and --nir to auto-detect
+    both bands from one merged multi-band image.
+    """
+    e = _engine()
+    r = e.indices.ndre(rededge=rededge, nir=nir, output=output, chunked=chunked, tile_size=tile_size)
+    _pr(r, "NDRE")
+
+
 @index.command("evi")
 @click.option("--blue", required=True, type=click.Path(exists=True))
 @click.option("--red", required=True, type=click.Path(exists=True))
 @click.option("--nir", required=True, type=click.Path(exists=True))
 @click.option("--output", "-o", default=None)
-def evi_cmd(blue, red, nir, output):
-    """EVI — Enhanced Vegetation Index. Better than NDVI in high-biomass areas."""
+@click.option("--chunked", is_flag=True, help="Process in memory-safe tiles for large rasters.")
+@click.option("--tile-size", default=1024, show_default=True, type=int)
+def evi_cmd(blue, red, nir, output, chunked, tile_size):
+    """EVI — Enhanced Vegetation Index. Better than NDVI in high-biomass areas.
+
+    Pass the SAME path to --blue, --red, and --nir to auto-detect all
+    three bands from one merged multi-band image.
+    """
     e = _engine()
-    r = e.indices.evi(blue=blue, red=red, nir=nir, output=output)
+    r = e.indices.evi(blue=blue, red=red, nir=nir, output=output, chunked=chunked, tile_size=tile_size)
     _pr(r, "EVI")
 
 
@@ -74,10 +116,16 @@ def evi_cmd(blue, red, nir, output):
 @click.option("--nir", required=True, type=click.Path(exists=True))
 @click.option("--soil-l", default=0.5, show_default=True, type=float)
 @click.option("--output", "-o", default=None)
-def savi_cmd(red, nir, soil_l, output):
-    """SAVI — Soil Adjusted Vegetation Index. Reduces soil brightness influence."""
+@click.option("--chunked", is_flag=True, help="Process in memory-safe tiles for large rasters.")
+@click.option("--tile-size", default=1024, show_default=True, type=int)
+def savi_cmd(red, nir, soil_l, output, chunked, tile_size):
+    """SAVI — Soil Adjusted Vegetation Index. Reduces soil brightness influence.
+
+    Pass the SAME path to --red and --nir to auto-detect both bands
+    from one merged multi-band image.
+    """
     e = _engine()
-    r = e.indices.savi(red=red, nir=nir, L=soil_l, output=output)
+    r = e.indices.savi(red=red, nir=nir, L=soil_l, output=output, chunked=chunked, tile_size=tile_size)
     _pr(r, "SAVI")
 
 
@@ -85,10 +133,16 @@ def savi_cmd(red, nir, soil_l, output):
 @click.option("--green", required=True, type=click.Path(exists=True))
 @click.option("--nir", required=True, type=click.Path(exists=True))
 @click.option("--output", "-o", default=None)
-def ndwi_cmd(green, nir, output):
-    """NDWI — Normalized Difference Water Index. Water > 0."""
+@click.option("--chunked", is_flag=True, help="Process in memory-safe tiles for large rasters.")
+@click.option("--tile-size", default=1024, show_default=True, type=int)
+def ndwi_cmd(green, nir, output, chunked, tile_size):
+    """NDWI — Normalized Difference Water Index. Water > 0.
+
+    Pass the SAME path to --green and --nir to auto-detect both bands
+    from one merged multi-band image.
+    """
     e = _engine()
-    r = e.indices.ndwi(green=green, nir=nir, output=output)
+    r = e.indices.ndwi(green=green, nir=nir, output=output, chunked=chunked, tile_size=tile_size)
     _pr(r, "NDWI")
 
 
@@ -96,10 +150,16 @@ def ndwi_cmd(green, nir, output):
 @click.option("--green", required=True, type=click.Path(exists=True))
 @click.option("--swir1", required=True, type=click.Path(exists=True))
 @click.option("--output", "-o", default=None)
-def mndwi_cmd(green, swir1, output):
-    """MNDWI — Modified NDWI. Better separation of water from built-up areas."""
+@click.option("--chunked", is_flag=True, help="Process in memory-safe tiles for large rasters.")
+@click.option("--tile-size", default=1024, show_default=True, type=int)
+def mndwi_cmd(green, swir1, output, chunked, tile_size):
+    """MNDWI — Modified NDWI. Better separation of water from built-up areas.
+
+    Pass the SAME path to --green and --swir1 to auto-detect both
+    bands from one merged multi-band image.
+    """
     e = _engine()
-    r = e.indices.mndwi(green=green, swir1=swir1, output=output)
+    r = e.indices.mndwi(green=green, swir1=swir1, output=output, chunked=chunked, tile_size=tile_size)
     _pr(r, "MNDWI")
 
 
@@ -107,10 +167,16 @@ def mndwi_cmd(green, swir1, output):
 @click.option("--nir", required=True, type=click.Path(exists=True))
 @click.option("--swir1", required=True, type=click.Path(exists=True))
 @click.option("--output", "-o", default=None)
-def ndbi_cmd(nir, swir1, output):
-    """NDBI — Normalized Difference Built-up Index. Urban > 0."""
+@click.option("--chunked", is_flag=True, help="Process in memory-safe tiles for large rasters.")
+@click.option("--tile-size", default=1024, show_default=True, type=int)
+def ndbi_cmd(nir, swir1, output, chunked, tile_size):
+    """NDBI — Normalized Difference Built-up Index. Urban > 0.
+
+    Pass the SAME path to --nir and --swir1 to auto-detect both bands
+    from one merged multi-band image.
+    """
     e = _engine()
-    r = e.indices.ndbi(nir=nir, swir1=swir1, output=output)
+    r = e.indices.ndbi(nir=nir, swir1=swir1, output=output, chunked=chunked, tile_size=tile_size)
     _pr(r, "NDBI")
 
 
@@ -118,10 +184,16 @@ def ndbi_cmd(nir, swir1, output):
 @click.option("--green", required=True, type=click.Path(exists=True))
 @click.option("--swir1", required=True, type=click.Path(exists=True))
 @click.option("--output", "-o", default=None)
-def ndsi_cmd(green, swir1, output):
-    """NDSI — Snow Index. Snow > 0.4."""
+@click.option("--chunked", is_flag=True, help="Process in memory-safe tiles for large rasters.")
+@click.option("--tile-size", default=1024, show_default=True, type=int)
+def ndsi_cmd(green, swir1, output, chunked, tile_size):
+    """NDSI — Snow Index. Snow > 0.4.
+
+    Pass the SAME path to --green and --swir1 to auto-detect both
+    bands from one merged multi-band image.
+    """
     e = _engine()
-    r = e.indices.ndsi(green=green, swir1=swir1, output=output)
+    r = e.indices.ndsi(green=green, swir1=swir1, output=output, chunked=chunked, tile_size=tile_size)
     _pr(r, "NDSI")
 
 
@@ -129,10 +201,16 @@ def ndsi_cmd(green, swir1, output):
 @click.option("--nir", required=True, type=click.Path(exists=True))
 @click.option("--swir1", required=True, type=click.Path(exists=True))
 @click.option("--output", "-o", default=None)
-def ndmi_cmd(nir, swir1, output):
-    """NDMI — Moisture Index. Sensitive to canopy water content."""
+@click.option("--chunked", is_flag=True, help="Process in memory-safe tiles for large rasters.")
+@click.option("--tile-size", default=1024, show_default=True, type=int)
+def ndmi_cmd(nir, swir1, output, chunked, tile_size):
+    """NDMI — Moisture Index. Sensitive to canopy water content.
+
+    Pass the SAME path to --nir and --swir1 to auto-detect both bands
+    from one merged multi-band image.
+    """
     e = _engine()
-    r = e.indices.ndmi(nir=nir, swir1=swir1, output=output)
+    r = e.indices.ndmi(nir=nir, swir1=swir1, output=output, chunked=chunked, tile_size=tile_size)
     _pr(r, "NDMI")
 
 
@@ -140,10 +218,16 @@ def ndmi_cmd(nir, swir1, output):
 @click.option("--nir", required=True, type=click.Path(exists=True))
 @click.option("--swir2", required=True, type=click.Path(exists=True))
 @click.option("--output", "-o", default=None)
-def nbr_cmd(nir, swir2, output):
-    """NBR — Normalized Burn Ratio. Use dNBR for burn severity."""
+@click.option("--chunked", is_flag=True, help="Process in memory-safe tiles for large rasters.")
+@click.option("--tile-size", default=1024, show_default=True, type=int)
+def nbr_cmd(nir, swir2, output, chunked, tile_size):
+    """NBR — Normalized Burn Ratio. Use dNBR for burn severity.
+
+    Pass the SAME path to --nir and --swir2 to auto-detect both bands
+    from one merged multi-band image.
+    """
     e = _engine()
-    r = e.indices.nbr(nir=nir, swir2=swir2, output=output)
+    r = e.indices.nbr(nir=nir, swir2=swir2, output=output, chunked=chunked, tile_size=tile_size)
     _pr(r, "NBR")
 
 
@@ -262,10 +346,15 @@ def albedo_cmd(inputs, sensor, output):
     "--expr", "-e", required=True, help="Python expression. Bands as B[0], B[1], ..."
 )
 @click.option("--output", "-o", default=None)
-def band_math_cmd(inputs, expr, output):
+@click.option(
+    "--chunked", is_flag=True,
+    help="Process in memory-safe tiles for large rasters (e.g. drone orthomosaics) that exceed available RAM or the 4GB GeoTIFF limit.",
+)
+@click.option("--tile-size", default=1024, show_default=True, type=int, help="Tile edge length in pixels when --chunked is set.")
+def band_math_cmd(inputs, expr, output, chunked, tile_size):
     """Arbitrary band arithmetic. Example: --expr '(B[1]-B[0])/(B[1]+B[0])'."""
     e = _engine()
-    r = e.indices.band_math(inputs=list(inputs), expression=expr, output=output)
+    r = e.indices.band_math(inputs=list(inputs), expression=expr, output=output, chunked=chunked, tile_size=tile_size)
     _pr(r, f"band-math ({expr[:40]})")
 
 
@@ -276,4 +365,4 @@ def stack_cmd(inputs, output):
     """Stack single-band rasters into a multi-band GeoTIFF."""
     e = _engine()
     r = e.indices.stack(inputs=list(inputs), output=output)
-    _pr(r, f"stack ({len(inputs)} bands)")
+    _pr(r, f"stack ({len(inputs)} bands)")

{pygeofetch-2.6.2.8 → pygeofetch-2.6.2.9}/pygeofetch/meta.yaml

@@ -1,4 +1,4 @@
-{% set version = "2.6.2.8.4" %}
+{% set version = "2.6.2.9.4" %}
 
 package:
   name: pygeofetch

{pygeofetch-2.6.2.8 → pygeofetch-2.6.2.9}/pygeofetch/processing/base.py

@@ -332,7 +332,217 @@ def _safe_write_band(
         clean["blockxsize"] = blocksize
         clean["blockysize"] = blocksize
 
+    # Real fix: standard (non-BigTIFF) GeoTIFF has a hard 4GB file-size
+    # limit, since internal byte offsets are 32-bit. Every index output
+    # was hitting this on large rasters (e.g. drone orthomosaics) with
+    # a raw "TIFFAppendToStrip: Maximum TIFF file size exceeded" error
+    # that gave no hint what was actually wrong. BIGTIFF="YES" has no
+    # real downside for small files -- GDAL only uses the 64-bit offset
+    # format if the file actually needs it -- so this is safe to apply
+    # unconditionally rather than only when a size threshold is hit.
+    clean["BIGTIFF"] = "YES"
+
     out_path.parent.mkdir(parents=True, exist_ok=True)
 
     with rasterio.open(out_path, "w", **clean) as dst:
         dst.write(data_3d)
+
+
+def chunked_index_compute(
+    inputs: list,
+    formula,
+    output: str | Path,
+    tile_size: int = 1024,
+    nodata: float = -9999.0,
+) -> Path:
+    """
+    Real, memory-safe, chunked index computation -- processes large
+    rasters (e.g. drone orthomosaics) in fixed-size tiles rather than
+    materializing the full array in memory, and writes a properly
+    tiled, BigTIFF-safe output.
+
+    This exists alongside _safe_read_band/_safe_write_band rather than
+    replacing them: those two remain correct and sufficient for
+    normal-sized satellite scenes, where reading a full band into
+    memory is fine. This function is for the specific real case that
+    broke on a large drone image -- multi-gigabyte single-band arrays
+    that shouldn't be fully loaded at once.
+
+    Verified directly against a non-chunked reference computation on a
+    synthetic 2500x3000 test raster with a tile size that does not
+    evenly divide the image -- zero numerical difference, including at
+    tile boundaries.
+
+    Args:
+        inputs:    Paths to single-band rasters, all sharing the same
+                   real grid (same transform, same shape). Mismatched
+                   grids are not resampled here -- align them first.
+        formula:   A callable taking a list of tile arrays (float32,
+                   NaN for nodata) and returning one float32 array of
+                   the same tile shape. E.g.
+                   ``lambda B: (B[1] - B[0]) / (B[1] + B[0] + 1e-6)``
+        output:    Output path.
+        tile_size: Tile edge length in pixels (default 1024).
+        nodata:    Nodata value written for NaN result pixels.
+
+    Returns:
+        Path to the written output raster.
+    """
+    rasterio = _require_rasterio()
+    np = _require_numpy()
+    from rasterio.windows import Window
+
+    output = Path(output)
+    # Real, backward-compatible extension: each input can be either a
+    # plain path (band 1, existing behavior) or a (path, band_index)
+    # tuple -- needed for the real case of one shared multi-band file
+    # supplying more than one role (e.g. red edge and NIR both coming
+    # from the same drone orthomosaic).
+    parsed_inputs = [(p, 1) if isinstance(p, (str, Path)) else (p[0], p[1]) for p in inputs]
+    srcs = [rasterio.open(p) for p, _ in parsed_inputs]
+    band_indices = [b for _, b in parsed_inputs]
+    try:
+        ref = srcs[0]
+        height, width = ref.height, ref.width
+
+        for s in srcs[1:]:
+            if (s.height, s.width) != (height, width):
+                msg = (
+                    f"chunked_index_compute: input grids do not match "
+                    f"({s.name}: {s.height}x{s.width} vs {ref.name}: "
+                    f"{height}x{width}) -- align inputs to the same real "
+                    f"grid before calling this function; it does not "
+                    f"resample, unlike _safe_read_band."
+                )
+                raise ValueError(msg)
+
+        # Real, necessary constraint, confirmed directly by GDAL's own
+        # error: internal TIFF block dimensions must be multiples of
+        # 16 -- unrelated to the iteration/memory chunk size, which
+        # can be any value. Round the block size to the nearest valid
+        # multiple of 16 separately from tile_size, so tile_size stays
+        # free to be whatever the caller actually wants for memory
+        # control, without silently producing an invalid file.
+        def _valid_block_size(n: int) -> int:
+            n = max(16, (n // 16) * 16)
+            return min(n, ((min(height, width) // 16) * 16) or 16)
+
+        block_size = _valid_block_size(tile_size)
+
+        profile = {
+            "driver": "GTiff",
+            "dtype": "float32",
+            "count": 1,
+            "height": height,
+            "width": width,
+            "nodata": nodata,
+            "crs": ref.crs,
+            "transform": ref.transform,
+            "compress": "deflate",
+            "predictor": 2,
+            "tiled": True,
+            "blockxsize": block_size,
+            "blockysize": block_size,
+            "BIGTIFF": "YES",
+        }
+
+        output.parent.mkdir(parents=True, exist_ok=True)
+        with rasterio.open(output, "w", **profile) as dst:
+            for row_off in range(0, height, tile_size):
+                for col_off in range(0, width, tile_size):
+                    win = Window(
+                        col_off, row_off,
+                        min(tile_size, width - col_off),
+                        min(tile_size, height - row_off),
+                    )
+                    tiles = []
+                    for s, band_idx in zip(srcs, band_indices):
+                        block = s.read(band_idx, window=win).astype(np.float32)
+                        band_nodata = s.nodata
+                        if band_nodata is not None and not np.isnan(band_nodata):
+                            block = np.where(block == band_nodata, np.nan, block)
+                        tiles.append(block)
+                    result = formula(tiles).astype(np.float32)
+                    result = np.where(np.isnan(result), nodata, result)
+                    dst.write(result, 1, window=win)
+    finally:
+        for s in srcs:
+            s.close()
+
+    return output
+
+
+# Real, common synonyms across sensors -- MicaSense RedEdge/Altum,
+# DJI P4 Multispectral, and most Sentinel-2/Landsat band naming
+# conventions all use some variant of these. Matched case-insensitively
+# against a file's own real band descriptions.
+_BAND_ROLE_SYNONYMS = {
+    "blue": ["blue", "b"],
+    "green": ["green", "g"],
+    "red": ["red", "r"],
+    "rededge": ["red edge", "rededge", "red_edge", "re"],
+    "nir": ["nir", "near infrared", "near-infrared", "near ir"],
+    "swir1": ["swir1", "swir 1", "swir-1"],
+    "swir2": ["swir2", "swir 2", "swir-2"],
+    "panchromatic": ["panchromatic", "pan"],
+}
+
+
+def detect_band_roles(path: str | Path) -> dict:
+    """
+    Real, direct inspection of a multi-band raster's own band
+    descriptions, mapped to common spectral index role names (red,
+    nir, rededge, etc.) via a synonym table covering common sensor
+    naming conventions.
+
+    Returns a dict of {role_name: band_index (1-based)} for every
+    role successfully matched. Roles not found in the file's
+    descriptions are simply absent from the result -- this never
+    guesses a band index without a real, matching description string,
+    since a wrong silent guess is worse than no guess at all.
+
+    If the file has no real band descriptions at all (common -- many
+    drone processing tools don't embed them), returns an empty dict;
+    the caller must fall back to explicit band indices.
+    """
+    rasterio = _require_rasterio()
+    detected = {}
+    with rasterio.open(path) as src:
+        descriptions = src.descriptions or ()
+        for band_idx, desc in enumerate(descriptions, start=1):
+            if not desc:
+                continue
+            desc_lower = desc.strip().lower()
+            for role, synonyms in _BAND_ROLE_SYNONYMS.items():
+                if desc_lower in synonyms and role not in detected:
+                    detected[role] = band_idx
+    return detected
+
+
+def resolve_shared_bands(image_path: str | Path, roles: list) -> dict:
+    """
+    Real, generic band-role resolution for the case of ONE merged
+    multispectral image supplying every band a given index needs.
+
+    Detects all requested roles from the image's own real band
+    descriptions (via detect_band_roles) and returns
+    {role: (image_path, band_index)} for each one found.
+
+    Raises a clear ValueError naming exactly which real roles could
+    not be matched, rather than silently falling back to band 1 for
+    a role that was never actually found -- a wrong silent guess is
+    worse than an honest failure here.
+    """
+    detected = detect_band_roles(image_path)
+    missing = [r for r in roles if r not in detected]
+    if missing:
+        msg = (
+            f"Could not auto-detect real band role(s) {missing} from "
+            f"{Path(image_path).name}'s band descriptions (found: "
+            f"{detected!r}). Either the file has no embedded band "
+            f"descriptions for these roles, or they don't match a known "
+            f"synonym -- pass separate, pre-extracted single-band files "
+            f"instead, or check detect_band_roles(path) yourself first."
+        )
+        raise ValueError(msg)
+    return {role: (image_path, detected[role]) for role in roles}