Feature/refactor band names (#824)

* revert band-name change and add band-descriptions

* update docs

Author: vincentsarago

CHANGES.md

@@ -3,55 +3,80 @@
 
 # 8.0.0
 
-* use **description** as band name (instead of `b{ix}`) in `Reader`'s outputs **breaking change**
+* add **band_descriptions** in ImageData and PointData objects
 
 ```python
-# before
 with Reader("tests/fixtures/cog_tags.tif") as src:
     info = src.info()
     img = src.preview()
-    stats = src.statistics()
 
     print(info.band_descriptions)
     >> [('b1', 'Green')]
 
     print(img.band_names)
     >> ['b1']
 
-    print(list(stats))
-    >> ['b1']
-
-# now
-with Reader("tests/fixtures/cog_tags.tif") as src:
-    info = src.info()
-    img = src.preview()
-    stats = src.statistics()
-
-    print(info.band_descriptions)
+    print(img.band_descriptions)
     >> [('b1', 'Green')]
+```
 
-    print(img.band_names)
-    >> ['Green']
-
-    print(list(stats))
-    >> ['Green']
-
-    # Band without description
-    with Reader("tests/fixtures/cog.tif") as src:
-        info = src.info()
-        stats = src.statistics()
-        img = src.preview()
+* use `b{idx}` as band names in `XarrayReader` result (instead of band descriptions) **breaking change**
 
-    print(info.band_descriptions)
-    >> [('b1', '')]
+```python
+    arr = numpy.arange(0.0, 33 * 35 * 2, dtype="float32").reshape(2, 33, 35)
+    data = xarray.DataArray(
+        arr,
+        dims=("time", "y", "x"),
+        coords={
+            "x": numpy.arange(-170, 180, 10),
+            "y": numpy.arange(-80, 85, 5),
+            "time": [datetime(2022, 1, 1), datetime(2022, 1, 2)],
+        },
+    )
+    data.attrs.update({"valid_min": arr.min(), "valid_max": arr.max()})
+    data.rio.write_crs("epsg:4326", inplace=True)
+   
+    # Before
+    with XarrayReader(data) as dst:
+        assert info.band_metadata == [("b1", {}), ("b2", {})]
+        assert info.band_descriptions == [
+            ("b1", "2022-01-01T00:00:00.000000000"),
+            ("b2", "2022-01-02T00:00:00.000000000"),
+        ]
+ 
+        stats = dst.statistics()
+        assert list(stats) == [
+            "2022-01-01T00:00:00.000000000",
+            "2022-01-02T00:00:00.000000000",
+        ]
+        
+        img = dst.tile(0, 0, 0)
+        assert img.band_names == [
+            "2022-01-01T00:00:00.000000000",
+            "2022-01-02T00:00:00.000000000",
+        ]
 
-    print(list(stats))
-    >> ['b1']
+    # Now
+    with XarrayReader(data) as dst:
+        stats = dst.statistics()
+        assert list(stats) == [
+            "b1",
+            "b2",
+        ]
 
-    print(list(stats))
-    >> ['b1']
+        img = dst.tile(0, 0, 0)
+        assert img.band_names == [
+            "b1",
+            "b2",
+        ]
+        assert img.band_descriptions == [
+            "2022-01-01T00:00:00.000000000",
+            "2022-01-02T00:00:00.000000000",
+        ]
 ```
 
+* rename `XarrayReader.band_names` -> `XarrayReader.band_descriptions`  **breaking change**
+
 * only cast data to `uint8` if colormap values are of type `uint8`
 
 * add `alpha_mask` attribute to `ImageData` class

docs/src/models.md

@@ -12,7 +12,8 @@ This class has helper methods like `render` which forward internal data and mask
 - **bounds**: bounds of the data ([rasterio.coords.BoundingBox](https://github.com/rasterio/rasterio/blob/main/rasterio/coords.py#L8), optional)
 - **crs**: coordinate reference system for the data ([rasterio.crs.CRS](https://github.com/rasterio/rasterio/blob/main/rasterio/crs.py#L21), optional)
 - **metadata**: additional metadata (dict, optional)
-- **band_names**: image band's names
+- **band_names**: image band's names (e.g `["b1", "b2"]`)
+- **band_descriptions**: image band's descriptions (e.g `["Green", "Red"]`)
 - **dataset_statistics**: Dataset's min/max values (list of (min,max), optional)
 - **cutline_mask**: array representing the mask for `feature` methods
 - **alpha_nask**: array reprsenting the alpha mask (allowing partial transparency)
@@ -353,7 +354,8 @@ Note: Starting with `rio-tiler==2.1`, when the output datatype is not valid for
 - **coordinates**: Coordinates of the point (Tuple[float, float], optional)
 - **crs**: coordinate reference system for the data ([rasterio.crs.CRS](https://github.com/rasterio/rasterio/blob/master/rasterio/crs.py#L21), optional)
 - **metadata**: additional metadata (dict, optional)
-- **band_names**: values band's names
+- **band_names**: image band's names (e.g `["b1", "b2"]`)
+- **band_descriptions**: image band's descriptions (e.g `["Green", "Red"]`)
 - **pixel_location**: X, Y coordinates in raster space (Tuple[float, float], optional)
 
 ```python

docs/src/readers.md

@@ -1209,10 +1209,10 @@ EPSG:4326
     # stats will be in form or {"band": BandStatistics(), ...}
     print(stats)
     >>> {
-        '2022-01-01T00:00:00.000000000': BandStatistics(...),
+        'b1': BandStatistics(...),
     }
 
-    print(stats["2022-01-01T00:00:00.000000000"].model_dump())
+    print(stats["b1"].model_dump())
     >>> {
         "min": 1,
         "max": 7872,

rio_tiler/io/base.py

@@ -620,8 +620,12 @@ def _reader(asset: str, *args: Any, **kwargs: Any) -> ImageData:
                                 "Can't use `asset_as_band` for multibands asset"
                             )
                         data.band_names = [asset]
+                        data.band_descriptions = [asset]
                     else:
                         data.band_names = [f"{asset}_{n}" for n in data.band_names]
+                        data.band_descriptions = [
+                            f"{asset}_{n}" for n in data.band_descriptions
+                        ]
 
                     return data
 
@@ -711,8 +715,12 @@ def _reader(asset: str, *args: Any, **kwargs: Any) -> ImageData:
                                 "Can't use `asset_as_band` for multibands asset"
                             )
                         data.band_names = [asset]
+                        data.band_descriptions = [asset]
                     else:
                         data.band_names = [f"{asset}_{n}" for n in data.band_names]
+                        data.band_descriptions = [
+                            f"{asset}_{n}" for n in data.band_descriptions
+                        ]
 
                     return data
 
@@ -800,8 +808,12 @@ def _reader(asset: str, **kwargs: Any) -> ImageData:
                                 "Can't use `asset_as_band` for multibands asset"
                             )
                         data.band_names = [asset]
+                        data.band_descriptions = [asset]
                     else:
                         data.band_names = [f"{asset}_{n}" for n in data.band_names]
+                        data.band_descriptions = [
+                            f"{asset}_{n}" for n in data.band_descriptions
+                        ]
 
                     return data
 
@@ -887,8 +899,12 @@ def _reader(asset: str, *args: Any, **kwargs: Any) -> PointData:
                                 "Can't use `asset_as_band` for multibands asset"
                             )
                         data.band_names = [asset]
+                        data.band_descriptions = [asset]
                     else:
                         data.band_names = [f"{asset}_{n}" for n in data.band_names]
+                        data.band_descriptions = [
+                            f"{asset}_{n}" for n in data.band_descriptions
+                        ]
 
                     return data
 
@@ -978,8 +994,12 @@ def _reader(asset: str, *args: Any, **kwargs: Any) -> ImageData:
                                 "Can't use `asset_as_band` for multibands asset"
                             )
                         data.band_names = [asset]
+                        data.band_descriptions = [asset]
                     else:
                         data.band_names = [f"{asset}_{n}" for n in data.band_names]
+                        data.band_descriptions = [
+                            f"{asset}_{n}" for n in data.band_descriptions
+                        ]
 
                     return data
 

rio_tiler/io/rasterio.py

@@ -787,6 +787,7 @@ def point(  # type: ignore
             coordinates=self.dataset.xy(x, y),
             crs=self.dataset.crs,
             band_names=img.band_names,
+            band_descriptions=img.band_descriptions,
             pixel_location=(x, y),
         )
 

rio_tiler/io/xarray.py

@@ -130,7 +130,7 @@ def maxzoom(self):
         return self._maxzoom
 
     @property
-    def band_names(self) -> List[str]:
+    def band_descriptions(self) -> List[str]:
         """
         Return list of `band descriptions` in DataArray.
 
@@ -152,7 +152,7 @@ def band_names(self) -> List[str]:
             if coords_name:
                 return [str(self.input.coords[coords_name[0]].data)]
 
-            return [self.input.name or "array"]
+            return [self.input.name or ""]
 
         return [str(band) for d in self._dims for band in self.input[d].values]
 
@@ -165,7 +165,7 @@ def info(self) -> Info:
             "crs": CRS_to_uri(self.crs) or self.crs.to_wkt(),
             "band_metadata": [(f"b{ix}", v) for ix, v in enumerate(metadata, 1)],
             "band_descriptions": [
-                (f"b{ix}", v) for ix, v in enumerate(self.band_names, 1)
+                (f"b{ix}", v) for ix, v in enumerate(self.band_descriptions, 1)
             ],
             "dtype": str(self.input.dtype),
             "nodata_type": "Nodata" if self.input.rio.nodata is not None else "None",
@@ -184,10 +184,12 @@ def info(self) -> Info:
 
     def _sel_indexes(
         self, indexes: Optional[Indexes] = None
-    ) -> Tuple[xarray.DataArray, List[str]]:
+    ) -> Tuple[xarray.DataArray, List[str], List[str]]:
         """Select `band` indexes in DataArray."""
         da = self.input
-        band_names = self.band_names
+        band_descriptions = self.band_descriptions
+        band_names = [f"b{ix + 1}" for ix in range(self.input.rio.count)]
+
         if indexes := cast_to_sequence(indexes):
             assert all(v > 0 for v in indexes), "Indexes value must be >= 1"
             if da.ndim == 2:
@@ -196,13 +198,15 @@ def _sel_indexes(
                         f"Invalid indexes {indexes} for array of shape {da.shape}"
                     )
 
-                return da, band_names
+                return da, band_names, band_descriptions
 
             indexes = [idx - 1 for idx in indexes]
+
             da = da[indexes]
-            band_names = [self.band_names[idx] for idx in indexes]
+            band_descriptions = [band_descriptions[idx] for idx in indexes]
+            band_names = [band_names[idx] for idx in indexes]
 
-        return da, band_names
+        return da, band_names, band_descriptions
 
     def statistics(
         self,
@@ -217,7 +221,7 @@ def statistics(
         """Return statistics from a dataset."""
         hist_options = hist_options or {}
 
-        da, band_names = self._sel_indexes(indexes)
+        da, band_names, _ = self._sel_indexes(indexes)
 
         if nodata is not None:
             da = da.rio.write_nodata(nodata)
@@ -268,7 +272,7 @@ def tile(
                 f"Tile(x={tile_x}, y={tile_y}, z={tile_z}) is outside bounds"
             )
 
-        da, band_names = self._sel_indexes(indexes)
+        da, band_names, band_descriptions = self._sel_indexes(indexes)
 
         if nodata is not None:
             da = da.rio.write_nodata(nodata)
@@ -312,6 +316,7 @@ def tile(
             crs=dst_crs,
             dataset_statistics=stats,
             band_names=band_names,
+            band_descriptions=band_descriptions,
             nodata=da.rio.nodata,
         )
 
@@ -357,7 +362,7 @@ def part(
 
         dst_crs = dst_crs or bounds_crs
 
-        da, band_names = self._sel_indexes(indexes)
+        da, band_names, band_descriptions = self._sel_indexes(indexes)
 
         if nodata is not None:
             da = da.rio.write_nodata(nodata)
@@ -406,6 +411,7 @@ def part(
             crs=da.rio.crs,
             dataset_statistics=stats,
             band_names=band_names,
+            band_descriptions=band_descriptions,
             nodata=da.rio.nodata,
         )
 
@@ -457,7 +463,7 @@ def preview(
                 UserWarning,
             )
 
-        da, band_names = self._sel_indexes(indexes)
+        da, band_names, band_descriptions = self._sel_indexes(indexes)
 
         if nodata is not None:
             da = da.rio.write_nodata(nodata)
@@ -500,6 +506,7 @@ def preview(
             crs=da.rio.crs,
             dataset_statistics=stats,
             band_names=band_names,
+            band_descriptions=band_descriptions,
             nodata=da.rio.nodata,
         )
 
@@ -547,7 +554,7 @@ def point(
         ):
             raise PointOutsideBounds("Point is outside dataset bounds")
 
-        da, band_names = self._sel_indexes(indexes)
+        da, band_names, band_descriptions = self._sel_indexes(indexes)
 
         if nodata is not None:
             da = da.rio.write_nodata(nodata)
@@ -568,6 +575,7 @@ def point(
             coordinates=(lon, lat),
             crs=coord_crs,
             band_names=band_names,
+            band_descriptions=band_descriptions,
             pixel_location=(x, y),
             nodata=da.rio.nodata,
         )