Skip to content

Commit c680c5c

Browse files
vincentsaragovincentsarago
authored
update rio-tiler to allow optional output size (#1149)
1 parent 391d5d0 commit c680c5c

12 files changed

Lines changed: 188 additions & 86 deletions

File tree

‎CHANGES.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77
* rename `/map` endpoint to `/map.html` **breaking change**
88
* add `name` attribute to `BaseFactory` to define endpoint's `operationId`
99
* add `operationId` on all endpoints
10+
* add `/preview/{width}x{height}.{format}` endpoints
11+
* update rio-tiler requirement to `>=7.7,<8.0`
12+
* allow users to pass only one of `width` or `heigh` size parameters for `preview`, `part` and `feature` requests
1013

1114
### titiler.application
1215

‎docs/src/advanced/dependencies.md‎

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -771,16 +771,23 @@ Same as `PreviewParams` but without default `max_size`.
771771

772772
```python
773773
@dataclass
774-
class PartFeatureParams(DefaultDependency):
775-
"""Common parameters for bbox and feature."""
774+
class PreviewParams(DefaultDependency):
775+
"""Common Preview parameters."""
776776

777-
max_size: Annotated[Optional[int], "Maximum image size to read onto."] = None
778-
height: Annotated[Optional[int], "Force output image height."] = None
779-
width: Annotated[Optional[int], "Force output image width."] = None
777+
# NOTE: sizes dependency can either be a Query or a Path Parameter
778+
max_size: Annotated[int, Field(description="Maximum image size to read onto.")] = (
779+
1024
780+
)
781+
height: Annotated[
782+
Optional[int], Field(description="Force output image height.")
783+
] = None
784+
width: Annotated[Optional[int], Field(description="Force output image width.")] = (
785+
None
786+
)
780787

781788
def __post_init__(self):
782789
"""Post Init."""
783-
if self.width and self.height:
790+
if self.width or self.height:
784791
self.max_size = None
785792
```
786793

@@ -1130,7 +1137,7 @@ class DatasetParams(DefaultDependency):
11301137
</details>
11311138

11321139

1133-
#### DatasetParams
1140+
#### PartFeatureParams
11341141

11351142
Same as `titiler.core.dependencies.PartFeatureParams` but with `resampling` option
11361143

@@ -1149,9 +1156,16 @@ Same as `titiler.core.dependencies.PartFeatureParams` but with `resampling` opti
11491156
class PartFeatureParams(DefaultDependency):
11501157
"""Common parameters for bbox and feature."""
11511158

1152-
max_size: Annotated[Optional[int], "Maximum image size to read onto."] = None
1153-
height: Annotated[Optional[int], "Force output image height."] = None
1154-
width: Annotated[Optional[int], "Force output image width."] = None
1159+
# NOTE: the part sizes dependency can either be a Query or a Path Parameter
1160+
max_size: Annotated[
1161+
Optional[int], Field(description="Maximum image size to read onto.")
1162+
] = None
1163+
height: Annotated[
1164+
Optional[int], Field(description="Force output image height.")
1165+
] = None
1166+
width: Annotated[Optional[int], Field(description="Force output image width.")] = (
1167+
None
1168+
)
11551169
resampling_method: Annotated[
11561170
Optional[RIOResampling],
11571171
Query(
@@ -1162,9 +1176,8 @@ class PartFeatureParams(DefaultDependency):
11621176

11631177
def __post_init__(self):
11641178
"""Post Init."""
1165-
if self.width and self.height:
1179+
if self.width or self.height:
11661180
self.max_size = None
1167-
11681181
```
11691182

11701183
</details>

‎docs/src/advanced/endpoints_factories.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -95,9 +95,9 @@ app.include_router(cog.router)
9595
| `GET` | `/{tileMatrixSetId}/tilejson.json` | JSON ([TileJSON][tilejson_model]) | return a Mapbox TileJSON document
9696
| `GET` | `/{tileMatrixSetId}/WMTSCapabilities.xml` | XML | return OGC WMTS Get Capabilities
9797
| `GET` | `/point/{lon},{lat}` | JSON ([Point][point_model]) | return pixel values from a dataset
98-
| `GET` | `/preview[.{format}]` | image/bin | create a preview image from a dataset **Optional**
9998
| `GET` | `/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin | create an image from part of a dataset **Optional**
10099
| `POST` | `/feature[/{width}x{height}][.{format}]` | image/bin | create an image from a GeoJSON feature **Optional**
100+
| `GET` | `/preview[/{width}x{height}][.{format}]` | image/bin | create a preview image from a dataset **Optional**
101101

102102

103103
### MultiBaseTilerFactory
@@ -142,9 +142,9 @@ app.include_router(stac.router)
142142
| `GET` | `/{tileMatrixSetId}/tilejson.json` | JSON ([TileJSON][tilejson_model]) | return a Mapbox TileJSON document
143143
| `GET` | `/{tileMatrixSetId}/WMTSCapabilities.xml` | XML | return OGC WMTS Get Capabilities
144144
| `GET` | `/point/{lon},{lat}` | JSON ([Point][multipoint_model]) | return pixel values from assets
145-
| `GET` | `/preview[.{format}]` | image/bin | create a preview image from assets **Optional**
146145
| `GET` | `/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin | create an image from part of assets **Optional**
147146
| `POST` | `/feature[/{width}x{height}][.{format}]` | image/bin | create an image from a geojson feature intersecting assets **Optional**
147+
| `GET` | `/preview[/{width}x{height}][.{format}]` | image/bin | create a preview image from assets **Optional**
148148

149149
### MultiBandTilerFactory
150150

@@ -198,9 +198,9 @@ app.include_router(landsat.router)
198198
| `GET` | `/{tileMatrixSetId}/tilejson.json` | JSON ([TileJSON][tilejson_model]) | return a Mapbox TileJSON document
199199
| `GET` | `/{tileMatrixSetId}/WMTSCapabilities.xml` | XML | return OGC WMTS Get Capabilities
200200
| `GET` | `/point/{lon},{lat}` | JSON ([Point][point_model]) | return pixel value from a dataset
201-
| `GET` | `/preview[.{format}]` | image/bin | create a preview image from a dataset **Optional**
202201
| `GET` | `/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin | create an image from part of a dataset **Optional**
203202
| `POST` | `/feature[/{width}x{height}][.{format}]` | image/bin | create an image from a geojson feature **Optional**
203+
| `GET` | `/preview[/{width}x{height}][.{format}]` | image/bin | create a preview image from a dataset **Optional**
204204

205205

206206
### TMSFactory
@@ -327,13 +327,13 @@ Endpoints factory for mosaics, built on top of [MosaicJSON](https://github.com/d
327327
| `GET` | `/tiles` | JSON | List of OGC Tilesets available
328328
| `GET` | `/tiles/{tileMatrixSetId}` | JSON | OGC Tileset metadata
329329
| `GET` | `/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]` | image/bin | create a web map tile image from a MosaicJSON
330+
| `GET` | `/tiles/{tileMatrixSetId}/{z}/{x}/{y}/assets` | JSON | return list of assets intersecting a XYZ tile
330331
| `GET` | `/{tileMatrixSetId}/map.html` | HTML | return a simple map viewer **Optional**
331332
| `GET` | `/{tileMatrixSetId}/tilejson.json` | JSON ([TileJSON][tilejson_model]) | return a Mapbox TileJSON document
332333
| `GET` | `/{tileMatrixSetId}/WMTSCapabilities.xml` | XML | return OGC WMTS Get Capabilities
333334
| `GET` | `/point/{lon},{lat}` | JSON ([Point][mosaic_point]) | return pixel value from a MosaicJSON dataset
334-
| `GET` | `/{z}/{x}/{y}/assets` | JSON | return list of assets intersecting a XYZ tile
335-
| `GET` | `/{lon},{lat}/assets` | JSON | return list of assets intersecting a point
336-
| `GET` | `/{minx},{miny},{maxx},{maxy}/assets` | JSON | return list of assets intersecting a bounding box
335+
| `GET` | `/point/{lon},{lat}/assets` | JSON | return list of assets intersecting a point
336+
| `GET` | `/bbox/{minx},{miny},{maxx},{maxy}/assets` | JSON | return list of assets intersecting a bounding box
337337

338338
## titiler.xarray
339339

‎docs/src/endpoints/cog.md‎

Lines changed: 29 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,9 @@ The `/cog` routes are based on `titiler.core.factory.TilerFactory` but with `cog
2121
| `GET` | `/cog/{tileMatrixSetId}/tilejson.json` | JSON | return a Mapbox TileJSON document
2222
| `GET` | `/cog/{tileMatrixSetId}/WMTSCapabilities.xml` | XML | return OGC WMTS Get Capabilities
2323
| `GET` | `/cog/point/{lon},{lat}` | JSON | return pixel values from a dataset
24-
| `GET` | `/cog/preview[.{format}]` | image/bin | create a preview image from a dataset
2524
| `GET` | `/cog/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin | create an image from part of a dataset
26-
| `POST` | `/cog/feature[/{width}x{height}][].{format}]` | image/bin | create an image from a GeoJSON feature
25+
| `POST` | `/cog/feature[/{width}x{height}][.{format}]` | image/bin | create an image from a GeoJSON feature
26+
| `GET` | `/cog/preview[/{width}x{height}][.{format}]` | image/bin | create a preview image from a dataset
2727
| `GET` | `/cog/validate` | JSON | validate a COG and return dataset info (from `titiler.extensions.cogValidateExtension`)
2828
| `GET` | `/cog/viewer` | HTML | demo webpage (from `titiler.extensions.cogViewerExtension`)
2929
| `GET` | `/cog/stac` | GeoJSON | create STAC Items from a dataset (from `titiler.extensions.stacExtension`)
@@ -69,18 +69,23 @@ Example:
6969

7070
### Preview
7171

72-
`:endpoint:/cog/preview[.{format}]`
72+
`:endpoint:/cog/preview`
73+
74+
`:endpoint:/cog/preview.{format}`
75+
76+
`:endpoint:/cog/preview/{width}x{height}.{format}`
7377

7478
- PathParams:
75-
- **format** (str): Output [image format](../user_guide/output_format.md), default is set to None and will be either JPEG or PNG depending on masked value. **Optional**
79+
- **format** (str, optional): Output [image format](../user_guide/output_format.md), default is set to None and will be either JPEG or PNG depending on masked value. **Also a QueryParam**
80+
- **height** (int, optional): Force output image height. **Also a QueryParam**
81+
- **width** (int, optional): Force output image width. **Also a QueryParam**
7682

7783
- QueryParams:
7884
- **url** (str): Cloud Optimized GeoTIFF URL. **Required**
7985
- **bidx** (array[int]): Dataset band indexes (e.g `bidx=1`, `bidx=1&bidx=2&bidx=3`).
8086
- **expression** (str): rio-tiler's band math expression (e.g `expression=b1/b2`).
8187
- **max_size** (int): Max image size, default is 1024.
82-
- **height** (int): Force output image height.
83-
- **width** (int): Force output image width.
88+
8489
- **nodata** (str, int, float): Overwrite internal Nodata value.
8590
- **unscale** (bool): Apply dataset internal Scale/Offset.
8691
- **resampling** (str): RasterIO resampling algorithm. Defaults to `nearest`.
@@ -94,25 +99,26 @@ Example:
9499
- **algorithm_params** (str): JSON encoded algorithm parameters.
95100

96101
!!! important
97-
if **height** and **width** are provided **max_size** will be ignored.
102+
if **height** or **width** is provided **max_size** will be ignored.
98103

99104
Example:
100105

101106
- `https://myendpoint/cog/preview?url=https://somewhere.com/mycog.tif`
102107
- `https://myendpoint/cog/preview.jpg?url=https://somewhere.com/mycog.tif&bidx=3&bidx=1&bidx2`
108+
- `https://myendpoint/cog/preview/100x100.jpg?url=https://somewhere.com/mycog.tif&bidx=3&bidx=1&bidx2`
103109
- `https://myendpoint/cog/preview?url=https://somewhere.com/mycog.tif&bidx=1&rescale=0,1000&colormap_name=cfastie`
104110

105-
### BBOX/Feature
111+
### Bbox
106112

107113
`:endpoint:/cog/bbox/{minx},{miny},{maxx},{maxy}.{format}`
108114

109115
`:endpoint:/cog/bbox/{minx},{miny},{maxx},{maxy}/{width}x{height}.{format}`
110116

111117
- PathParams:
112118
- **minx,miny,maxx,maxy** (str): Comma (',') delimited bounding box in WGS84.
113-
- **format** (str): Output [image format](../user_guide/output_format.md).
114-
- **height** (int): Force output image height.
115-
- **width** (int): Force output image width.
119+
- **format** (str): Output [image format](../user_guide/output_format.md)
120+
- **height** (int, optional): Force output image height. **Also a QueryParam**
121+
- **width** (int, optional): Force output image width. **Also a QueryParam**
116122

117123
- QueryParams:
118124
- **url** (str): Cloud Optimized GeoTIFF URL. **Required**
@@ -134,23 +140,28 @@ Example:
134140
- **algorithm_params** (str): JSON encoded algorithm parameters.
135141

136142
!!! important
137-
if **height** and **width** are provided **max_size** will be ignored.
143+
if **height** or **width** is provided **max_size** will be ignored.
138144

139145
Example:
140146

141-
- `https://myendpoint/cog/bbox/0,0,10,10.png?url=https://somewhere.com/mycog.tif`
142147
- `https://myendpoint/cog/bbox/0,0,10,10.png?url=https://somewhere.com/mycog.tif&bidx=1&rescale=0,1000&colormap_name=cfastie`
148+
- `https://myendpoint/cog/bbox/0,0,10,10/100x100.png?url=https://somewhere.com/mycog.tif`
143149

150+
### Feature
144151

145-
`:endpoint:/cog/feature[/{width}x{height}][].{format}] - [POST]`
152+
`:endpoint:/cog/feature - [POST]`
153+
154+
`:endpoint:/cog/feature.{format} - [POST]`
155+
156+
`:endpoint:/cog/feature/{width}x{height}.{format} - [POST]`
146157

147158
- Body:
148159
- **feature** (JSON): A valid GeoJSON feature (Polygon or MultiPolygon)
149160

150161
- PathParams:
151-
- **height** (int): Force output image height. **Optional**
152-
- **width** (int): Force output image width. **Optional**
153-
- **format** (str): Output [image format](../user_guide/output_format.md), default is set to None and will be either JPEG or PNG depending on masked value. **Optional**
162+
- **height** (int, optional): Force output image height. **Also a QueryParam**
163+
- **width** (int, optional): Force output image width. **Also a QueryParam**
164+
- **format** (str, optional): Output [image format](../user_guide/output_format.md), default is set to None and will be either JPEG or PNG depending on masked value. **Also a QueryParam**
154165

155166
- QueryParams:
156167
- **url** (str): Cloud Optimized GeoTIFF URL. **Required**
@@ -172,16 +183,14 @@ Example:
172183
- **algorithm_params** (str): JSON encoded algorithm parameters.
173184

174185
!!! important
175-
if **height** and **width** are provided **max_size** will be ignored.
186+
if **height** or **width** is provided **max_size** will be ignored.
176187

177188
Example:
178189

179190
- `https://myendpoint/cog/feature?url=https://somewhere.com/mycog.tif`
180191
- `https://myendpoint/cog/feature.png?url=https://somewhere.com/mycog.tif`
181192
- `https://myendpoint/cog/feature/100x100.png?url=https://somewhere.com/mycog.tif&bidx=1&rescale=0,1000&colormap_name=cfastie`
182193

183-
Note: if `height` and `width` are provided `max_size` will be ignored.
184-
185194
### Point
186195

187196
`:endpoint:/cog/point/{lon},{lat}`

‎docs/src/endpoints/mosaic.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,9 @@ Read Mosaic Info/Metadata and create Web map Tiles from a multiple COG. The `mos
2020
| `GET` | `/mosaicjson/{tileMatrixSetId}/tilejson.json` | JSON | return a Mapbox TileJSON document
2121
| `GET` | `/mosaicjson/{tileMatrixSetId}/WMTSCapabilities.xml` | XML | return OGC WMTS Get Capabilities
2222
| `GET` | `/mosaicjson/point/{lon},{lat}` | JSON | return pixel value from a mosaic assets
23-
| `GET` | `/mosaicjson/{z}/{x}/{y}/assets` | JSON | return list of assets intersecting a XYZ tile
24-
| `GET` | `/mosaicjson/{lon},{lat}/assets` | JSON | return list of assets intersecting a point
25-
| `GET` | `/mosaicjson/{minx},{miny},{maxx},{maxy}/assets` | JSON | return list of assets intersecting a bounding box
23+
| `GET` | `/mosaicjson/tiles/{tileMatrixSetId}/{z}/{x}/{y}/assets` | JSON | return list of assets intersecting a XYZ tile
24+
| `GET` | `/mosaicjson/point/{lon},{lat}/assets` | JSON | return list of assets intersecting a point
25+
| `GET` | `/mosaicjson/bbox/{minx},{miny},{maxx},{maxy}/assets` | JSON | return list of assets intersecting a bounding box
2626

2727
## Description
2828

0 commit comments

Comments
 (0)