rename /crop endpoints to /bbox or /feature (#704)

* rename /crop endpoints to /bbox or /feature

* update test requirements

* pydantic update

CHANGES.md

@@ -1,5 +1,34 @@
 # Release Notes
 
+## 0.15.0 (TBD)
+
+### titiler.core
+
+- added `PartFeatureParams` dependency
+
+**breaking changes**
+
+- `max_size` is now set to `None` for `/statistics [POST]`, `/bbox` and `/feature` endpoints, meaning the tiler will create image from the highest resolution.
+
+- renamed `titiler.core.dependencies.ImageParams` to `PreviewParams`
+
+- split TileFactory `img_dependency` attribute in two:
+  - `img_preview_dependency`: used in `/preview` and `/statistics [GET]`, default to `PreviewParams` (with `max_size=1024`)
+
+  - `img_part_dependency`: used in `/bbox`, `/feature` and `/statistics [POST]`, default to `PartFeatureParams` (with `max_size=None`)
+
+- renamed `/crop` endpoints to `/bbox/...` or `/feature/...`
+  - `/crop/{minx},{miny},{maxx},{maxy}.{format}` -> `/bbox/{minx},{miny},{maxx},{maxy}.{format}`
+
+  - `/crop/{minx},{miny},{maxx},{maxy}/{width}x{height}.{format}` -> `/bbox/{minx},{miny},{maxx},{maxy}/{width}x{height}.{format}`
+
+  - `/crop [POST]` -> `/feature [POST]`
+
+  - `/crop.{format} [POST]` -> `/feature.{format} [POST]`
+
+  - `/crop/{width}x{height}.{format}  [POST]` -> `/feature/{width}x{height}.{format} [POST]`
+
+
 ## 0.14.1 (2023-09-14)
 
 ### titiler.extension

docs/src/advanced/dependencies.md

@@ -273,14 +273,14 @@ class MetadataParams(DefaultDependency):
             self.kwargs["hist_options"] = hist_options
 ```
 
-#### img_dependency
+#### img_preview_dependency
 
-Used in Crop/Preview to define size of the output image.
+Used in Statistics/Preview to define size of the output image.
 
 ```python
 @dataclass
-class ImageParams(DefaultDependency):
-    """Common Preview/Crop parameters."""
+class PreviewParams(DefaultDependency):
+    """Common Preview parameters."""
 
     max_size: Optional[int] = Query(
         1024, description="Maximum image size to read onto."
@@ -294,6 +294,20 @@ class ImageParams(DefaultDependency):
             self.max_size = None
 ```
 
+#### img_part_dependency
+
+Same as `PreviewParams` but without default `max_size`. Used in `/bbox`, `/feature` and `/statistics [POST]` endpoints.
+
+```python
+@dataclass
+class PartFeatureParams(PreviewParams):
+    """Common parameters for bbox and feature."""
+
+    max_size: Annotated[Optional[int], "Maximum image size to read onto."] = None
+    height: Annotated[Optional[int], "Force output image height."] = None
+    width: Annotated[Optional[int], "Force output image width."] = None
+```
+
 ### MultiBaseTilerFactory
 
 The `MultiBaseTilerFactory` inherits dependency from `TilerFactory` and `BaseTilerFactory`.

docs/src/advanced/tiler_factories.md

@@ -25,8 +25,8 @@ app.include_router(cog.router, tags=["Cloud Optimized GeoTIFF"])
 | `GET`  | `[/{tileMatrixSetId}]/WMTSCapabilities.xml`                     | XML                                         | return OGC WMTS Get Capabilities
 | `GET`  | `/point/{lon},{lat}`                                            | JSON ([Point][point_model])                 | return pixel values from a dataset
 | `GET`  | `/preview[.{format}]`                                           | image/bin                                   | create a preview image from a dataset (**Optional**)
-| `GET`  | `/crop/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin                                   | create an image from part of a dataset (**Optional**)
-| `POST` | `/crop[/{width}x{height}][.{format}]`                           | image/bin                                   | create an image from a GeoJSON feature (**Optional**)
+| `GET`  | `/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin                                   | create an image from part of a dataset (**Optional**)
+| `POST` | `/feature[/{width}x{height}][.{format}]`                           | image/bin                                   | create an image from a GeoJSON feature (**Optional**)
 | `GET`  | `/map`                                                          | HTML                                        | return a simple map viewer
 | `GET`  | `[/{tileMatrixSetId}]/map`                                      | HTML                                        | return a simple map viewer
 
@@ -59,8 +59,8 @@ app.include_router(cog.router, tags=["STAC"])
 | `GET`  | `/{tileMatrixSetId}/WMTSCapabilities.xml`                       | XML                                              | return OGC WMTS Get Capabilities
 | `GET`  | `/point/{lon},{lat}`                                            | JSON ([Point][multipoint_model])                 | return pixel values from assets
 | `GET`  | `/preview[.{format}]`                                           | image/bin                                        | create a preview image from assets (**Optional**)
-| `GET`  | `/crop/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin                                        | create an image from part of assets (**Optional**)
-| `POST` | `/crop[/{width}x{height}][.{format}]`                           | image/bin                                        | create an image from a geojson feature intersecting assets (**Optional**)
+| `GET`  | `/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin                                        | create an image from part of assets (**Optional**)
+| `POST` | `/feature[/{width}x{height}][.{format}]`                           | image/bin                                        | create an image from a geojson feature intersecting assets (**Optional**)
 | `GET`  | `[/{tileMatrixSetId}]/map`                                      | HTML                                             | return a simple map viewer
 
 ### `titiler.core.factory.MultiBandTilerFactory`
@@ -97,8 +97,8 @@ app.include_router(cog.router, tags=["Landsat"])
 | `GET`  | `/{tileMatrixSetId}/WMTSCapabilities.xml`                       | XML                                          | return OGC WMTS Get Capabilities
 | `GET`  | `/point/{lon},{lat}`                                            | JSON ([Point][point_model])                  | return pixel value from a dataset
 | `GET`  | `/preview[.{format}]`                                           | image/bin                                    | create a preview image from a dataset
-| `GET`  | `/crop/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin                                    | create an image from part of a dataset
-| `POST` | `/crop[/{width}x{height}][.{format}]`                           | image/bin                                    | create an image from a geojson feature
+| `GET`  | `/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin                                    | create an image from part of a dataset
+| `POST` | `/feature[/{width}x{height}][.{format}]`                           | image/bin                                    | create an image from a geojson feature
 | `GET`  | `[/{tileMatrixSetId}]/map`                                      | HTML                                         | return a simple map viewer
 
 ### `titiler.mosaic.factory.MosaicTilerFactory`

docs/src/endpoints/cog.md

@@ -19,8 +19,8 @@ The `/cog` routes are based on `titiler.core.factory.TilerFactory` but with `cog
 | `GET`  | `/cog[/{tileMatrixSetId}]/WMTSCapabilities.xml`                     | XML       | return OGC WMTS Get Capabilities
 | `GET`  | `/cog/point/{lon},{lat}`                                            | JSON      | return pixel values from a dataset
 | `GET`  | `/cog/preview[.{format}]`                                           | image/bin | create a preview image from a dataset
-| `GET`  | `/cog/crop/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin | create an image from part of a dataset
-| `POST` | `/cog/crop[/{width}x{height}][].{format}]`                          | image/bin | create an image from a GeoJSON feature
+| `GET`  | `/cog/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin | create an image from part of a dataset
+| `POST` | `/cog/feature[/{width}x{height}][].{format}]`                          | image/bin | create an image from a GeoJSON feature
 | `GET`  | `/cog[/{tileMatrixSetId}]/map`                                      | HTML      | simple map viewer
 | `GET`  | `/cog/validate`                                                     | JSON      | validate a COG and return dataset info (from `titiler.extensions.cogValidateExtension`)
 | `GET`  | `/cog/viewer`                                                       | HTML      | demo webpage (from `titiler.extensions.cogViewerExtension`)
@@ -97,11 +97,11 @@ Example:
 - `https://myendpoint/cog/preview.jpg?url=https://somewhere.com/mycog.tif&bidx=3&bidx=1&bidx2`
 - `https://myendpoint/cog/preview?url=https://somewhere.com/mycog.tif&bidx=1&rescale=0,1000&colormap_name=cfastie`
 
-### Crop / Part
+### BBOX/Feature
 
-`:endpoint:/cog/crop/{minx},{miny},{maxx},{maxy}.{format}`
+`:endpoint:/cog/bbox/{minx},{miny},{maxx},{maxy}.{format}`
 
-`:endpoint:/cog/crop/{minx},{miny},{maxx},{maxy}/{width}x{height}.{format}`
+`:endpoint:/cog/bbox/{minx},{miny},{maxx},{maxy}/{width}x{height}.{format}`
 
 - PathParams:
     - **minx,miny,maxx,maxy** (str): Comma (',') delimited bounding box in WGS84.
@@ -114,7 +114,7 @@ Example:
     - **bidx** (array[int]): Dataset band indexes (e.g `bidx=1`, `bidx=1&bidx=2&bidx=3`).
     - **expression** (str): rio-tiler's band math expression (e.g `expression=b1/b2`).
     - **coord_crs** (str): Coordinate Reference System of the input coordinates. Default to `epsg:4326`.
-    - **max_size** (int): Max image size, default is 1024.
+    - **max_size** (int): Max image size.
     - **nodata** (str, int, float): Overwrite internal Nodata value.
     - **unscale** (bool): Apply dataset internal Scale/Offset.
     - **resampling** (str): rasterio resampling method. Default is `nearest`.
@@ -131,11 +131,11 @@ Example:
 
 Example:
 
-- `https://myendpoint/cog/crop/0,0,10,10.png?url=https://somewhere.com/mycog.tif`
-- `https://myendpoint/cog/crop/0,0,10,10.png?url=https://somewhere.com/mycog.tif&bidx=1&rescale=0,1000&colormap_name=cfastie`
+- `https://myendpoint/cog/bbox/0,0,10,10.png?url=https://somewhere.com/mycog.tif`
+- `https://myendpoint/cog/bbox/0,0,10,10.png?url=https://somewhere.com/mycog.tif&bidx=1&rescale=0,1000&colormap_name=cfastie`
 
 
-`:endpoint:/cog/crop[/{width}x{height}][].{format}] - [POST]`
+`:endpoint:/cog/feature[/{width}x{height}][].{format}] - [POST]`
 
 - Body:
     - **feature** (JSON): A valid GeoJSON feature (Polygon or MultiPolygon)
@@ -150,7 +150,7 @@ Example:
     - **bidx** (array[int]): Dataset band indexes (e.g `bidx=1`, `bidx=1&bidx=2&bidx=3`).
     - **expression** (str): rio-tiler's band math expression (e.g `expression=b1/b2`).
     - **coord_crs** (str): Coordinate Reference System of the input geometry coordinates. Default to `epsg:4326`.
-    - **max_size** (int): Max image size, default is 1024.
+    - **max_size** (int): Max image size.
     - **nodata** (str, int, float): Overwrite internal Nodata value.
     - **unscale** (bool): Apply dataset internal Scale/Offset.
     - **resampling** (str): rasterio resampling method. Default is `nearest`.
@@ -167,9 +167,9 @@ Example:
 
 Example:
 
-- `https://myendpoint/cog/crop?url=https://somewhere.com/mycog.tif`
-- `https://myendpoint/cog/crop.png?url=https://somewhere.com/mycog.tif`
-- `https://myendpoint/cog/crop/100x100.png?url=https://somewhere.com/mycog.tif&bidx=1&rescale=0,1000&colormap_name=cfastie`
+- `https://myendpoint/cog/feature?url=https://somewhere.com/mycog.tif`
+- `https://myendpoint/cog/feature.png?url=https://somewhere.com/mycog.tif`
+- `https://myendpoint/cog/feature/100x100.png?url=https://somewhere.com/mycog.tif&bidx=1&rescale=0,1000&colormap_name=cfastie`
 
 Note: if `height` and `width` are provided `max_size` will be ignored.
 
@@ -324,7 +324,7 @@ Example:
     - **bidx** (array[int]): Dataset band indexes (e.g `bidx=1`, `bidx=1&bidx=2&bidx=3`).
     - **expression** (str): rio-tiler's band math expression (e.g `expression=b1/b2`).
     - **coord_crs** (str): Coordinate Reference System of the input geometry coordinates. Default to `epsg:4326`.
-    - **max_size** (int): Max image size from which to calculate statistics, default is 1024.
+    - **max_size** (int): Max image size from which to calculate statistics.
     - **height** (int): Force image height from which to calculate statistics.
     - **width** (int): Force image width from which to calculate statistics.
     - **nodata** (str, int, float): Overwrite internal Nodata value.

docs/src/endpoints/stac.md

@@ -21,8 +21,8 @@ The `/stac` routes are based on `titiler.core.factory.MultiBaseTilerFactory` but
 | `GET`  | `/stac[/{tileMatrixSetId}]/WMTSCapabilities.xml`                       | XML       | return OGC WMTS Get Capabilities
 | `GET`  | `/stac/point/{lon},{lat}`                                            | JSON      | return pixel value from assets
 | `GET`  | `/stac/preview[.{format}]`                                           | image/bin | create a preview image from assets
-| `GET`  | `/stac/crop/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin | create an image from part of assets
-| `POST` | `/stac/crop[/{width}x{height}][].{format}]`                          | image/bin | create an image from a geojson covering the assets
+| `GET`  | `/stac/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin | create an image from part of assets
+| `POST` | `/stac/feature[/{width}x{height}][].{format}]`                          | image/bin | create an image from a geojson covering the assets
 | `GET`  | `/stac[/{tileMatrixSetId}]/map`                                      | HTML      | simple map viewer
 | `GET`  | `/stac/viewer`                                                       | HTML      | demo webpage (from `titiler.extensions.stacViewerExtension`)
 
@@ -106,11 +106,11 @@ Example:
 - `https://myendpoint/stac/preview.jpg?url=https://somewhere.com/item.json&assets=B01`
 - `https://myendpoint/stac/preview?url=https://somewhere.com/item.json&assets=B01&rescale=0,1000&colormap_name=cfastie`
 
-### Crop / Part
+### BBOX/Feature
 
-`:endpoint:/stac/crop/{minx},{miny},{maxx},{maxy}.{format}`
+`:endpoint:/stac/bbox/{minx},{miny},{maxx},{maxy}.{format}`
 
-`:endpoint:/stac/crop/{minx},{miny},{maxx},{maxy}/{width}x{height}.{format}`
+`:endpoint:/stac/bbox/{minx},{miny},{maxx},{maxy}/{width}x{height}.{format}`
 
 - PathParams:
     - **minx,miny,maxx,maxy** (str): Comma (',') delimited bounding box in WGS84.
@@ -125,7 +125,7 @@ Example:
     - **asset_as_band** (bool): tell rio-tiler that each asset is a 1 band dataset, so expression `Asset1/Asset2` can be passed.
     - **asset_bidx** (array[str]): Per asset band math expression (e.g `Asset1|1,2,3`).
     - **coord_crs** (str): Coordinate Reference System of the input coordinates. Default to `epsg:4326`.
-    - **max_size** (int): Max image size, default is 1024.
+    - **max_size** (int): Max image size.
     - **nodata** (str, int, float): Overwrite internal Nodata value.
     - **unscale** (bool): Apply dataset internal Scale/Offset.
     - **resampling** (str): rasterio resampling method. Default is `nearest`.
@@ -144,10 +144,10 @@ Example:
 
 Example:
 
-- `https://myendpoint/stac/crop/0,0,10,10.png?url=https://somewhere.com/item.json&assets=B01`
-- `https://myendpoint/stac/crop/0,0,10,10.png?url=https://somewhere.com/item.json&assets=B01&rescale=0,1000&colormap_name=cfastie`
+- `https://myendpoint/stac/bbox/0,0,10,10.png?url=https://somewhere.com/item.json&assets=B01`
+- `https://myendpoint/stac/bbox/0,0,10,10.png?url=https://somewhere.com/item.json&assets=B01&rescale=0,1000&colormap_name=cfastie`
 
-`:endpoint:/stac/crop[/{width}x{height}][].{format}] - [POST]`
+`:endpoint:/stac/feature[/{width}x{height}][].{format}] - [POST]`
 
 - Body:
     - **feature** (JSON): A valid GeoJSON feature (Polygon or MultiPolygon)
@@ -164,7 +164,7 @@ Example:
     - **asset_as_band** (bool): tell rio-tiler that each asset is a 1 band dataset, so expression `Asset1/Asset2` can be passed.
     - **asset_bidx** (array[str]): Per asset band math expression (e.g `Asset1|1,2,3`).
     - **coord_crs** (str): Coordinate Reference System of the input geometry coordinates. Default to `epsg:4326`.
-    - **max_size** (int): Max image size, default is 1024.
+    - **max_size** (int): Max image size.
     - **nodata** (str, int, float): Overwrite internal Nodata value.
     - **unscale** (bool): Apply dataset internal Scale/Offset.
     - **resampling** (str): rasterio resampling method. Default is `nearest`.
@@ -183,9 +183,9 @@ Example:
 
 Example:
 
-- `https://myendpoint/stac/crop?url=https://somewhere.com/item.json&assets=B01`
-- `https://myendpoint/stac/crop.png?url=https://somewhere.com/item.json&assets=B01`
-- `https://myendpoint/stac/crop/100x100.png?url=https://somewhere.com/item.json&assets=B01&rescale=0,1000&colormap_name=cfastie`
+- `https://myendpoint/stac/feature?url=https://somewhere.com/item.json&assets=B01`
+- `https://myendpoint/stac/feature.png?url=https://somewhere.com/item.json&assets=B01`
+- `https://myendpoint/stac/feature/100x100.png?url=https://somewhere.com/item.json&assets=B01&rescale=0,1000&colormap_name=cfastie`
 
 ### Point
 
@@ -393,7 +393,7 @@ Example:
     - **asset_as_band** (bool): tell rio-tiler that each asset is a 1 band dataset, so expression `Asset1/Asset2` can be passed.
     - **asset_bidx** (array[str]): Per asset band math expression (e.g `Asset1|1,2,3`).
     - **coord_crs** (str): Coordinate Reference System of the input geometry coordinates. Default to `epsg:4326`.
-    - **max_size** (int): Max image size from which to calculate statistics, default is 1024.
+    - **max_size** (int): Max image size from which to calculate statistics.
     - **height** (int): Force image height from which to calculate statistics.
     - **width** (int): Force image width from which to calculate statistics.
     - **nodata** (str, int, float): Overwrite internal Nodata value.

docs/src/examples/code/tiler_with_cache.md

@@ -167,7 +167,7 @@ from rio_tiler.io import BaseReader, Reader
 
 from titiler.core.factory import img_endpoint_params
 from titiler.core.factory import TilerFactory as TiTilerFactory
-from titiler.core.dependencies import ImageParams, RescalingParams
+from titiler.core.dependencies import RescalingParams
 from titiler.core.models.mapbox import TileJSON
 from titiler.core.resources.enums import ImageType
 

docs/src/examples/notebooks/Working_with_CloudOptimizedGeoTIFF.ipynb

@@ -335,7 +335,7 @@
     "xmin, ymin, xmax, ymax = bounds\n",
     "\n",
     "def fetch_bbox(file):\n",
-    "    url = f\"{titiler_endpoint}/cog/crop/{xmin},{ymin},{xmax},{ymax}.npy\"\n",
+    "    url = f\"{titiler_endpoint}/cog/bbox/{xmin},{ymin},{xmax},{ymax}.npy\"\n",
     "    params = {\n",
     "        \"url\": _url(file),\n",
     "        \"bidx\": \"1\",\n",

docs/src/examples/notebooks/Working_with_STAC.ipynb

@@ -611,7 +611,7 @@
     "`{endpoint}/stac/tiles/{z}/{x}/{y}.{format}?url={stac_item}&{otherquery params}`\n",
     "\n",
     "\n",
-    "`{endpoint}/stac/crop/{minx},{miny},{maxx},{maxy}.{format}?url={stac_item}&{otherquery params}`\n",
+    "`{endpoint}/stac/bbox/{minx},{miny},{maxx},{maxy}.{format}?url={stac_item}&{otherquery params}`\n",
     "\n",
     "\n",
     "`{endpoint}/stac/point/{minx},{miny}?url={stac_item}&{otherquery params}`\n"
@@ -1045,7 +1045,7 @@
     "    xmin, ymin, xmax, ymax = bbox\n",
     "    \n",
     "    # TiTiler required URL + asset or expression parameters\n",
-    "    params = ((\"url\", stac_item), )\n",
+    "    params = ((\"url\", stac_item), (\"max_size\", 1024))\n",
     "    if assets:\n",
     "        for asset in assets:\n",
     "            params += ((\"assets\", asset), )\n",
@@ -1057,7 +1057,7 @@
     "    params += tuple(kwargs.items())\n",
     "\n",
     "    # TITILER ENDPOINT\n",
-    "    url = f\"{titiler_endpoint}/stac/crop/{xmin},{ymin},{xmax},{ymax}.npy\"\n",
+    "    url = f\"{titiler_endpoint}/stac/bbox/{xmin},{ymin},{xmax},{ymax}.npy\"\n",
     "    r = httpx.get(url, params=params)\n",
     "    data = numpy.load(BytesIO(r.content))\n",
     "    \n",