Skip to content

Commit df97771

Browse files
vincentsaragovincentsarago
authored
refactor xarray dimension selection (#1134)
* refactor xarray dimension selection * refactor type and slice handling * remove slice * remove print * rename method to sel_method * update docs * more docs
1 parent 6aeb6d6 commit df97771

22 files changed

Lines changed: 766 additions & 118 deletions

‎CHANGES.md‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,27 @@
9696

9797
### titiler.xarray
9898

99-
* change `get_variable.drop_dim` parameter type from `str` to `List[str]` **breaking change**
99+
* update `rio-tiler` requirement to `>=7.6.1`
100+
* add `sel` and `sel_method` options to select dimension
101+
102+
```
103+
# before
104+
https://.../0/0/0.png?url=dataset.zarr&drop_dim=time=2023-01-01
105+
106+
# now
107+
https://.../0/0/0.png?url=dataset.zarr&sel=time=2023-01-01
108+
109+
# method
110+
https://.../0/0/0.png?url=dataset.zarr&sel=time=2023-01-02&sel_method=nearest
111+
112+
# Can use `slice` when providing 2 values
113+
https://.../0/0/0.png?url=dataset.zarr&sel=time=2023-01-01&time=2023-01-31
114+
```
115+
* add support for `bidx` parameter
116+
* remove `first` **time** dim selection **breaking change**
117+
* add support for 3D dataset
118+
* remove `drop_dim` option **breaking change**
119+
* remove `datetime` option **breaking change**
100120
* deprecate `VariablesExtension` extension
101121
* add `DatasetMetadataExtension` extension (`/dataset/keys`, `/dataset/` and `/dataset/dict` endpoints)
102122

‎docs/mkdocs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,7 @@ plugins:
161161
signature_crossrefs: true
162162
extensions:
163163
- griffe_inherited_docstrings
164-
import:
164+
inventories:
165165
- https://docs.python.org/3/objects.inv
166166
- https://numpy.org/doc/stable/objects.inv
167167
- https://rasterio.readthedocs.io/en/stable/objects.inv

‎docs/src/advanced/Extensions.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -33,32 +33,36 @@ class FactoryExtension(metaclass=abc.ABCMeta):
3333

3434
## Available extensions
3535

36-
#### cogValidateExtension
36+
#### titiler.extensions.cogValidateExtension
3737

3838
- Goal: adds a `/validate` endpoint which return the content of rio-cogeo `info` method
3939
- Additional requirements: `titiler.extensions["cogeo"]` (installs `rio-cogeo`)
4040

41-
#### cogViewerExtension
41+
#### titiler.extensions.cogViewerExtension
4242

4343
- Goal: adds a `/viewer` endpoint which return an HTML viewer for simple COGs
4444

45-
#### stacViewerExtension
45+
#### titiler.extensions.stacViewerExtension
4646

4747
- Goal: adds a `/viewer` endpoint which return an HTML viewer for STAC item
4848

49-
#### stacExtension
49+
#### titiler.extensions.stacExtension
5050

5151
- Goal: adds a `/stac` endpoint which return an HTML viewer for STAC item
5252
- Additional requirements: `titiler.extensions["stac"]` (installs `rio-stac`)
5353

54-
#### wmsExtension
54+
#### titiler.extensions.wmsExtension
5555

5656
- Goal: adds a `/wms` endpoint to support OGC WMS specification (`GetCapabilities` and `GetMap`)
5757

58-
#### stacRenderExtenstion
58+
#### titiler.extensions.stacRenderExtenstion
5959

6060
- Goal: adds `/render` and `/render/{render_id}` endpoints which return the contents of [STAC render extension](https://github.com/stac-extensions/render) and links to tileset.json and WMTS service
6161

62+
#### titiler.xarray.DatasetMetadataExtension
63+
64+
- Goal: adds `/dataset/`, `/dataset/keys` and `/datasets/dict` endpoints which return metadata about a multidimensional Dataset (not a DataArray)
65+
6266
## How To
6367

6468
### Use extensions
@@ -85,8 +89,6 @@ tiler = TilerFactory(
8589
app.include_router(tiler.router, prefix="/cog")
8690
```
8791

88-
See [titiler.application](../application) for a full example.
89-
9092
### Create your own
9193

9294
```python

‎docs/src/advanced/dependencies.md‎

Lines changed: 205 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ def preview(
3838

3939
Using `titiler.core.dependencies.DefaultDependency`, we can use `.as_dict(exclude_none=True/False)` method to `unpack` the object parameters. This can be useful if method or reader do not take the same parameters.
4040

41+
## titiler.core
42+
4143
#### AssetsParams
4244

4345
Define `assets`.
@@ -877,7 +879,7 @@ class StatisticsParams(DefaultDependency):
877879

878880
#### TileParams
879881

880-
Defile `buffer` and `padding` to apply at tile creation.
882+
Define `buffer` and `padding` to apply at tile creation.
881883

882884
| Name | Type | Required | Default
883885
| ------ | ----------|----------|--------------
@@ -952,3 +954,205 @@ def post_process(
952954

953955
</details>
954956

957+
## titiler.xarray
958+
959+
960+
#### XarrayIOParams
961+
962+
Define Xarray's `open_args` to `xarray.open_dataset`.
963+
964+
| Name | Type | Required | Default
965+
| ------ | ---------- |----------|--------------
966+
| **group** | Query (str) | No | None
967+
| **decode_times** | Query (bool)| No | None
968+
969+
<details>
970+
971+
```python
972+
@dataclass
973+
class XarrayIOParams(DefaultDependency):
974+
"""Dataset IO Options."""
975+
976+
group: Annotated[
977+
Optional[str],
978+
Query(
979+
description="Select a specific zarr group from a zarr hierarchy. Could be associated with a zoom level or dataset."
980+
),
981+
] = None
982+
983+
decode_times: Annotated[
984+
Optional[bool],
985+
Query(
986+
title="decode_times",
987+
description="Whether to decode times",
988+
),
989+
] = None
990+
```
991+
992+
</details>
993+
994+
#### XarrayDsParams
995+
996+
Define options to select a **variable** within a Xarray Dataset.
997+
998+
| Name | Type | Required | Default
999+
| ------ | ---------- |----------|--------------
1000+
| **variable** | Query (str) | Yes | None
1001+
| **sel** | Query (list of str) | No | None
1002+
| **method** | Query (str)| No | None
1003+
1004+
<details>
1005+
1006+
```python
1007+
@dataclass
1008+
class XarrayDsParams(DefaultDependency):
1009+
"""Xarray Dataset Options."""
1010+
1011+
variable: Annotated[str, Query(description="Xarray Variable name.")]
1012+
1013+
sel: Annotated[
1014+
Optional[List[SelDimStr]],
1015+
Query(
1016+
description="Xarray Indexing using dimension names `{dimension}={value}`.",
1017+
),
1018+
] = None
1019+
1020+
method: Annotated[
1021+
Optional[Literal["nearest", "pad", "ffill", "backfill", "bfill"]],
1022+
Query(
1023+
alias="sel_method",
1024+
description="Xarray indexing method to use for inexact matches.",
1025+
),
1026+
] = None
1027+
```
1028+
1029+
</details>
1030+
1031+
1032+
#### XarrayParams
1033+
1034+
Combination of `XarrayIOParams` and `XarrayDsParams`
1035+
1036+
| Name | Type | Required | Default
1037+
| ------ | ---------- |----------|--------------
1038+
| **group** | Query (str) | No | None
1039+
| **decode_times** | Query (bool)| No | None
1040+
| **variable** | Query (str) | Yes | None
1041+
| **sel** | Query (list of str) | No | None
1042+
| **method** | Query (str)| No | None
1043+
1044+
<details>
1045+
1046+
```python
1047+
@dataclass
1048+
class XarrayParams(XarrayIOParams, XarrayDsParams):
1049+
"""Xarray Reader dependency."""
1050+
1051+
pass
1052+
```
1053+
1054+
</details>
1055+
1056+
#### CompatXarrayParams
1057+
1058+
same as `XarrayParams` but with optional `variable` option.
1059+
1060+
| Name | Type | Required | Default
1061+
| ------ | ---------- |----------|--------------
1062+
| **group** | Query (str) | No | None
1063+
| **decode_times** | Query (bool)| No | None
1064+
| **variable** | Query (str) | No | None
1065+
| **sel** | Query (list of str) | No | None
1066+
| **method** | Query (str)| No | None
1067+
1068+
<details>
1069+
1070+
```python
1071+
@dataclass
1072+
class XarrayParams(XarrayIOParams, XarrayDsParams):
1073+
"""Xarray Reader dependency."""
1074+
1075+
pass
1076+
```
1077+
1078+
</details>
1079+
1080+
1081+
#### DatasetParams
1082+
1083+
Same as `titiler.core.dependencies.DatasetParams` but with only `nodata` and `reproject`
1084+
1085+
| Name | Type | Required | Default
1086+
| ------ | ----------|----------|--------------
1087+
| **nodata** | Query (str, int, float) | No | None
1088+
| **reproject** | Query (str) | No | 'nearest'
1089+
1090+
<details>
1091+
1092+
```python
1093+
@dataclass
1094+
class DatasetParams(DefaultDependency):
1095+
"""Low level WarpedVRT Optional parameters."""
1096+
1097+
nodata: Annotated[
1098+
Optional[Union[str, int, float]],
1099+
Query(
1100+
title="Nodata value",
1101+
description="Overwrite internal Nodata value",
1102+
),
1103+
] = None
1104+
reproject_method: Annotated[
1105+
Optional[WarpResampling],
1106+
Query(
1107+
alias="reproject",
1108+
description="WarpKernel resampling algorithm (only used when doing re-projection). Defaults to `nearest`.",
1109+
),
1110+
] = None
1111+
1112+
def __post_init__(self):
1113+
"""Post Init."""
1114+
if self.nodata is not None:
1115+
self.nodata = numpy.nan if self.nodata == "nan" else float(self.nodata)
1116+
```
1117+
1118+
</details>
1119+
1120+
1121+
#### DatasetParams
1122+
1123+
Same as `titiler.core.dependencies.PartFeatureParams` but with `resampling` option
1124+
1125+
| Name | Type | Required | Default
1126+
| ------ | ----------|----------|--------------
1127+
| **max_size** | Query (int) | No | None
1128+
| **height** | Query (int) | No | None
1129+
| **width** | Query (int) | No | None
1130+
| **resampling** | Query (str) | No | 'nearest'
1131+
1132+
1133+
<details>
1134+
1135+
```python
1136+
@dataclass
1137+
class PartFeatureParams(DefaultDependency):
1138+
"""Common parameters for bbox and feature."""
1139+
1140+
max_size: Annotated[Optional[int], "Maximum image size to read onto."] = None
1141+
height: Annotated[Optional[int], "Force output image height."] = None
1142+
width: Annotated[Optional[int], "Force output image width."] = None
1143+
resampling_method: Annotated[
1144+
Optional[RIOResampling],
1145+
Query(
1146+
alias="resampling",
1147+
description="RasterIO resampling algorithm. Defaults to `nearest`.",
1148+
),
1149+
] = None
1150+
1151+
def __post_init__(self):
1152+
"""Post Init."""
1153+
if self.width and self.height:
1154+
self.max_size = None
1155+
1156+
```
1157+
1158+
</details>

‎docs/src/advanced/endpoints_factories.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -343,7 +343,7 @@ class: `titiler.xarray.factory.TilerFactory`
343343
- **reader**: Dataset Reader **required**.
344344
- **path_dependency**: Dependency to use to define the dataset url. Defaults to `titiler.core.dependencies.DatasetPathParams`.
345345
- **reader_dependency**: Dependency to control options passed to the reader instance init. Defaults to `titiler.xarray.dependencies.XarrayParams`
346-
- **layer_dependency**: Dependency to define band indexes or expression. Defaults to `titiler.core.dependencies.DefaultDependency`.
346+
- **layer_dependency**: Dependency to define band indexes or expression. Defaults to `titiler.core.dependencies.BidxParams`.
347347
- **dataset_dependency**: Dependency to overwrite `nodata` value and change the `Warp` resamplings. Defaults to `titiler.xarray.dependencies.DatasetParams`.
348348
- **tile_dependency**: Dependency for tile creation options. Defaults to `titiler.core.dependencies.DefaultDependency`.
349349
- **stats_dependency**: Dependency to define options for *rio-tiler*'s statistics method used in `/statistics` endpoints. Defaults to `titiler.core.dependencies.StatisticsParams`.

‎docs/src/endpoints/cog.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ The `/cog` routes are based on `titiler.core.factory.TilerFactory` but with `cog
4040
- **x** (int): TMS tile's column.
4141
- **y** (int): TMS tile's row.
4242
- **scale** (int): Tile size scale, default is set to 1 (256x256). **Optional**
43-
- **format** (str): Output [image format](../output_format.md), default is set to None and will be either JPEG or PNG depending on masked value. **Optional**
43+
- **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**
4444

4545
- QueryParams:
4646
- **url** (str): Cloud Optimized GeoTIFF URL. **Required**
@@ -72,7 +72,7 @@ Example:
7272
`:endpoint:/cog/preview[.{format}]`
7373

7474
- PathParams:
75-
- **format** (str): Output [image format](../output_format.md), default is set to None and will be either JPEG or PNG depending on masked value. **Optional**
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**
7676

7777
- QueryParams:
7878
- **url** (str): Cloud Optimized GeoTIFF URL. **Required**
@@ -110,7 +110,7 @@ Example:
110110

111111
- PathParams:
112112
- **minx,miny,maxx,maxy** (str): Comma (',') delimited bounding box in WGS84.
113-
- **format** (str): Output [image format](../output_format.md).
113+
- **format** (str): Output [image format](../user_guide/output_format.md).
114114
- **height** (int): Force output image height.
115115
- **width** (int): Force output image width.
116116

@@ -150,7 +150,7 @@ Example:
150150
- PathParams:
151151
- **height** (int): Force output image height. **Optional**
152152
- **width** (int): Force output image width. **Optional**
153-
- **format** (str): Output [image format](../output_format.md), default is set to None and will be either JPEG or PNG depending on masked value. **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**
154154

155155
- QueryParams:
156156
- **url** (str): Cloud Optimized GeoTIFF URL. **Required**
@@ -213,7 +213,7 @@ Example:
213213

214214
- QueryParams:
215215
- **url** (str): Cloud Optimized GeoTIFF URL. **Required**
216-
- **tile_format** (str): Output [image format](../output_format.md), default is set to None and will be either JPEG or PNG depending on masked value.
216+
- **tile_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.
217217
- **tile_scale** (int): Tile size scale, default is set to 1 (256x256).
218218
- **minzoom** (int): Overwrite default minzoom.
219219
- **maxzoom** (int): Overwrite default maxzoom.
@@ -249,7 +249,7 @@ Example:
249249

250250
- QueryParams:
251251
- **url** (str): Cloud Optimized GeoTIFF URL. **Required**
252-
- **tile_format** (str): Output [image format](../output_format.md), default is set to None and will be either JPEG or PNG depending on masked value.
252+
- **tile_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.
253253
- **tile_scale** (int): Tile size scale, default is set to 1 (256x256).
254254
- **minzoom** (int): Overwrite default minzoom.
255255
- **maxzoom** (int): Overwrite default maxzoom.

0 commit comments

Comments
 (0)