make reader.read public (#334)

* make reader.read public

* fix bad sub

* typo2

CHANGES.md

@@ -14,6 +14,7 @@
 * renamed input parameter `arr` to `data` in `rio_tiler.utils.mapzen_elevation_rgb`
 * made `rio_tiler.io.stac.to_pystac_item` private (renamed to `_to_pystac_item`)
 * renamed `rio_tiler.colormap.DEFAULTS_CMAPS` to `rio_tiler.colormap.DEFAULT_CMAPS_FILES`
+* made `rio_tiler.reader._read` public (renamed to rio_tiler.reader.read) (ref: https://github.com/cogeotiff/rio-tiler/issues/332)
 
 ## 2.0.0rc4 (2020-12-18)
 

docs/v2_migration.md

@@ -89,7 +89,7 @@ Internal tile/data reading functions have been refactored and moved to a new `ri
 
 ### tile
 
-In `rio_tiler` v1 most of the magic was happening in [`rio_tiler.utils._tile_read`](https://github.com/cogeotiff/rio-tiler/blob/4286e55d43172040b4027575a845532e55a0fdf9/rio_tiler/utils.py#L337-L458). In the version 2, this function is now split in two, `rio_tiler.reader.part` and `rio_tiler_reader._read`, to reduce code reutilisation and to make the code more robust. The `part` function now takes `height` and `width` instead of a unique `tilesize` to specify the output array size.
+In `rio_tiler` v1 most of the magic was happening in [`rio_tiler.utils._tile_read`](https://github.com/cogeotiff/rio-tiler/blob/4286e55d43172040b4027575a845532e55a0fdf9/rio_tiler/utils.py#L337-L458). In the version 2, this function is now split in two, `rio_tiler.reader.part` and `rio_tiler_reader.read`, to reduce code reutilisation and to make the code more robust. The `part` function now takes `height` and `width` instead of a unique `tilesize` to specify the output array size.
 
 ```python
 # v1
@@ -98,7 +98,7 @@ with rasterio.open("my_tif.tif") as src_dst:
     mercator_tile = mercantile.Tile(x=tile_x, y=tile_y, z=tile_z)
     tile_bounds = mercantile.xy_bounds(mercator_tile)
 
-    t, m = rio_tiler.utils._tile_read(src, tile_bounds, 256)
+    t, m = rio_tiler.utils._tile_read(src_dst, tile_bounds, 256)
 
 # v2
 with rasterio.open("my_tif.tif") as src_dst:
@@ -110,7 +110,7 @@ with rasterio.open("my_tif.tif") as src_dst:
     t, m = rio_tiler.reader.part(src_dst, tile_bounds, 256, 256)
 ```
 
-*Options changes*
+*Options changes:*
 
 - `tile_edge_padding` -> `padding`, and set to **0** by default
 - `minimum_tile_cover` -> `minimum_overlap`
@@ -124,7 +124,7 @@ with rasterio.open("my_tif.tif") as src_dst:
 with rasterio.open("my_tif.tif") as src_dst:
     mercator_tile = mercantile.Tile(x=tile_x, y=tile_y, z=tile_z)
     tile_bounds = mercantile.xy_bounds(mercator_tile)
-    t, m = rio_tiler.utils._tile_read(src, tile_bounds, 256, tile_edge_padding=4, minimum_tile_cover=0.3)
+    t, m = rio_tiler.utils._tile_read(src_dst, tile_bounds, 256, tile_edge_padding=4, minimum_tile_cover=0.3)
 
 # v2
 with rasterio.open("my_tif.tif") as src_dst:
@@ -140,7 +140,7 @@ In version 2, when no `indexes` options are passed, **we remove the alpha channe
 ```python
 # v1
 with rasterio.open("my_tif_alpha.tif") as src_dst:
-    t, m = rio_tiler.utils._tile_read(src, tile_bounds, 256, indexes=(1,2,3))
+    t, m = rio_tiler.utils._tile_read(src_dst, tile_bounds, 256, indexes=(1,2,3))
 
 # v2
 with rasterio.open("my_tif_alpha.tif") as src_dst:
@@ -277,6 +277,4 @@ See [models](/models/)
 
 ## Mission specific changes
 
-**Mission-specific tilers have been moved to the [`rio-tiler-pds`][rio-tiler-pds] package.**
-
-[`rio-tiler-pds`]: https://github.com/cogeotiff/rio-tiler-pds
+**Mission-specific tilers have been moved to the [`rio-tiler-pds`](https://github.com/cogeotiff/rio-tiler-pds) package.**

rio_tiler/io/cogeo.py

@@ -69,7 +69,7 @@ class COGReader(BaseReader):
     maxzoom: int = attr.ib(default=None)
     colormap: Dict = attr.ib(default=None)
 
-    # Define global options to be forwarded to functions reading the data (e.g rio_tiler.reader._read)
+    # Define global options to be forwarded to functions reading the data (e.g `rio_tiler.reader.read`)
     nodata: Optional[Union[float, int, str]] = attr.ib(default=None)
     unscale: Optional[bool] = attr.ib(default=None)
     resampling_method: Optional[Resampling] = attr.ib(default=None)
@@ -566,7 +566,7 @@ class GCPCOGReader(COGReader):
     maxzoom: int = attr.ib(default=None)
     colormap: Dict = attr.ib(default=None)
 
-    # Define global options to be forwarded to functions reading the data (e.g rio_tiler.reader._read)
+    # Define global options to be forwarded to functions reading the data (e.g `rio_tiler.reader.read`)
     nodata: Optional[Union[float, int, str]] = attr.ib(default=None)
     unscale: Optional[bool] = attr.ib(default=None)
     resampling_method: Optional[Resampling] = attr.ib(default=None)

rio_tiler/reader.py

@@ -21,7 +21,7 @@
 from .utils import get_vrt_transform, has_alpha_band, has_mask_band, non_alpha_indexes
 
 
-def _read(
+def read(
     src_dst: Union[DatasetReader, DatasetWriter, WarpedVRT],
     height: Optional[int] = None,
     width: Optional[int] = None,
@@ -36,7 +36,7 @@ def _read(
         Callable[[numpy.ndarray, numpy.ndarray], Tuple[numpy.ndarray, numpy.ndarray]]
     ] = None,
 ) -> Tuple[numpy.ndarray, numpy.ndarray]:
-    """Create a WarpedVRT and read data and mask.
+    """Low level read function.
 
     Args:
         src_dst (rasterio.io.DatasetReader or rasterio.io.DatasetWriter or rasterio.vrt.WarpedVRT): Rasterio dataset.
@@ -138,7 +138,7 @@ def part(
         minimum_overlap (float, optional): Minimum % overlap for which to raise an error with dataset not covering enought of the tile.
         vrt_options (dict, optional): Options to be passed to the rasterio.warp.WarpedVRT class.
         max_size (int, optional): Limit output size array if not widht and height.
-        kwargs (optional): Additional options to forward to `rio_tiler.reader._read()`.
+        kwargs (optional): Additional options to forward to `rio_tiler.reader.read`.
 
     Returns:
         tuple: Data (numpy.ndarray) and Mask (numpy.ndarray) values.
@@ -216,7 +216,7 @@ def part(
         }
     )
 
-    return _read(
+    return read(
         src_dst,
         out_height,
         out_width,
@@ -240,7 +240,7 @@ def preview(
         max_size (int, optional): Limit output size array if not widht and height. Defaults to `1024`.
         height (int, optional): Output height of the array.
         width (int, optional): Output width of the array.
-        kwargs (optional): Additional options to forward to `rio_tiler.reader._read()`.
+        kwargs (optional): Additional options to forward to `rio_tiler.reader.read`.
 
     Returns:
         tuple: Data (numpy.ndarray) and Mask (numpy.ndarray) values.
@@ -258,7 +258,7 @@ def preview(
                 width = max_size
                 height = math.ceil(width * ratio)
 
-    return _read(src_dst, height, width, **kwargs)
+    return read(src_dst, height, width, **kwargs)
 
 
 def point(