Skip to content

Commit 97343ed

Browse files
vincentsaragovincentsarago
committed
add migration guides
1 parent 2821a9b commit 97343ed

2 files changed

Lines changed: 285 additions & 0 deletions

File tree

‎docs/mkdocs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,9 @@ nav:
139139
- k8s / Helm Deployment: "deployment/k8s.md"
140140
- Azure: "deployment/azure.md"
141141

142+
- Migrations:
143+
- From titiler 0.26.x to 1.x: "migrations/v1_migration.md"
144+
142145
- External links: "external_links.md"
143146
- Development - Contributing: "contributing.md"
144147
- Release Notes: "release-notes.md"

‎docs/src/migrations/v1_migration.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
# Migration Guide: TiTiler 0.26 to 1.0
2+
3+
This guide covers the breaking changes and new features when upgrading from TiTiler 0.26 to 1.0.
4+
5+
## Breaking Changes
6+
7+
### Data Type Changes
8+
9+
#### UINT8 Output for JPEG/PNG
10+
11+
**Impact:** High - Affects all automatic image format outputs
12+
13+
When no output format is explicitly specified, TiTiler now returns `UINT8` datatype for JPEG and PNG formats.
14+
15+
```python
16+
# If your data needs specific datatypes, explicitly specify the format
17+
# Example: Request with explicit format control
18+
# In this case, if the input data is in uint16, the ouput png will be in UINT16
19+
response = requests.get("/tiles/1/2/3.png?url=data_in_uint16.tif")
20+
```
21+
22+
**Action Required:** Review your endpoints that rely on automatic format detection. If you need specific data type handling, consider explicitly specifying the output format and rescaling parameters.
23+
24+
### WMTS Changes
25+
26+
#### WMTS Endpoint Restructuring
27+
28+
**Impact:** High - Affects all WMTS usage
29+
30+
The `/{tileMatrixSetId}/WMTSCapabilities.xml` endpoints have been removed from the default factories. WMTS functionality is now provided through a dedicated extension.
31+
32+
```python
33+
# Before (0.26)
34+
# WMTS available at: /{tileMatrixSetId}/WMTSCapabilities.xml
35+
36+
# Now (1.0)
37+
from titiler.extensions import wmtsExtension
38+
39+
# Add extension to factory
40+
factory = TilerFactory(
41+
router_prefix="/cog",
42+
extensions=[wmtsExtension()]
43+
)
44+
45+
# WMTS now available at: /WMTSCapabilities.xml
46+
```
47+
48+
Additionally, the WMTS response now supports all TileMatrixSets as separate layers.
49+
50+
**Action Required:**
51+
1. Add `wmtsExtension` to your factory configurations
52+
2. Update client applications to use the new `/WMTSCapabilities.xml` endpoint path
53+
3. Update any code that expects a single layer to handle multiple TileMatrixSets
54+
55+
### titiler.core Changes
56+
57+
#### Point Endpoint Response Model
58+
59+
**Impact:** Medium - Affects `/point` endpoint consumers
60+
61+
The `/point` endpoint now includes a `band_description` attribute in its response model.
62+
63+
```python
64+
# Before (0.26)
65+
class Point(BaseModel):
66+
coordinates: List[float]
67+
values: List[Optional[float]]
68+
# ... other fields
69+
70+
# Now (1.0)
71+
class Point(BaseModel):
72+
coordinates: List[float]
73+
values: List[Optional[float]]
74+
band_description: List[str] | None # New field
75+
# ... other fields
76+
```
77+
78+
**Action Required:** Update client code that parses `/point` responses to handle the new `band_description` field.
79+
80+
### titiler.mosaic Changes
81+
82+
#### Point Endpoint Response Restructuring
83+
84+
**Impact:** High - Affects mosaic `/point` endpoint consumers
85+
86+
The response model for the mosaic `/point` endpoint has been completely restructured for better clarity.
87+
88+
```python
89+
# Before (0.26)
90+
class Point(BaseModel):
91+
coordinates: List[float]
92+
values: List[Tuple[str, List[Optional[float]], List[str]]]
93+
94+
# Now (1.0)
95+
class AssetPoint(BaseModel):
96+
name: str
97+
values: list[float | None]
98+
band_names: list[str]
99+
band_descriptions: list[str] | None = None
100+
101+
class Point(BaseModel):
102+
coordinates: list[float]
103+
assets: list[AssetPoint]
104+
```
105+
106+
**Migration Example:**
107+
```python
108+
# Before (0.26)
109+
response = {
110+
"coordinates": [-122.5, 37.5],
111+
"values": [
112+
("asset1", [100.0, 200.0], ["B1", "B2"]),
113+
("asset2", [150.0, 250.0], ["B1", "B2"])
114+
]
115+
}
116+
117+
# Now (1.0)
118+
response = {
119+
"coordinates": [-122.5, 37.5],
120+
"assets": [
121+
{
122+
"name": "asset1",
123+
"values": [100.0, 200.0],
124+
"band_names": ["B1", "B2"],
125+
"band_descriptions": None
126+
},
127+
{
128+
"name": "asset2",
129+
"values": [150.0, 250.0],
130+
"band_names": ["B1", "B2"],
131+
"band_descriptions": None
132+
}
133+
]
134+
}
135+
```
136+
137+
**Action Required:** Update all client code that parses mosaic `/point` responses to use the new structure.
138+
139+
#### MosaicJSON Dependency Now Optional
140+
141+
**Impact:** Medium - Affects installations and imports
142+
143+
The `cogeo-mosaic` package is now an optional dependency.
144+
145+
```bash
146+
# Before (0.26)
147+
pip install titiler.mosaic
148+
149+
# Now (1.0) - Install with MosaicJSON support
150+
pip install "titiler.mosaic[mosaicjson]"
151+
```
152+
153+
**Action Required:** Update your installation commands if you use MosaicJSON functionality.
154+
155+
#### Backend Attribute No Longer Has Default
156+
157+
**Impact:** High - Affects custom mosaic implementations
158+
159+
The `MosaicTilerFactory.backend` attribute no longer has a default value and must be explicitly specified.
160+
161+
```python
162+
# Before (0.26)
163+
# Backend had a default value
164+
factory = MosaicTilerFactory()
165+
166+
# Now (1.0)
167+
# Must explicitly set backend
168+
from titiler.mosaic.backends import MosaicBackend
169+
170+
factory = MosaicTilerFactory(
171+
backend=MosaicBackend
172+
)
173+
```
174+
175+
**Action Required:** Explicitly set the `backend` attribute when creating `MosaicTilerFactory` instances.
176+
177+
#### MosaicJSON Endpoints Moved to Extension
178+
179+
**Impact:** Medium - Affects mosaic endpoint structure
180+
181+
The `/` and `/validate` endpoints are now provided by the `MosaicJSONExtension` instead of being included by default.
182+
183+
```python
184+
# Before (0.26)
185+
# Endpoints available by default
186+
factory = MosaicTilerFactory()
187+
188+
# Now (1.0)
189+
from titiler.mosaic.extensions import MosaicJSONExtension
190+
191+
factory = MosaicTilerFactory(
192+
extensions=[MosaicJSONExtension()]
193+
)
194+
```
195+
196+
**Action Required:** Add `MosaicJSONExtension` to your factory if you need the `/` and `/validate` endpoints.
197+
198+
### titiler.extensions Changes
199+
200+
#### rio-cogeo Version Update
201+
202+
**Impact:** Low - Dependency version change
203+
204+
The `rio-cogeo` requirement has been updated to `7.0,<8.0`.
205+
206+
**Action Required:** Review the [rio-cogeo changelog](https://github.com/cogeotiff/rio-cogeo/blob/main/CHANGES.md) for any breaking changes that might affect your usage.
207+
208+
## New Features
209+
210+
### titiler.mosaic
211+
212+
#### New Optional Endpoints
213+
214+
Three new optional endpoints are available for mosaic operations:
215+
216+
- `/feature` - Feature-based queries
217+
- `/bbox` - Bounding box queries
218+
- `/statistics` - Statistical analysis
219+
220+
```python
221+
# Enable in your factory
222+
factory = MosaicTilerFactory(
223+
add_feature=True, # Enables /feature endpoint
224+
add_bbox=True, # Enables /bbox endpoint
225+
add_statistics=True # Enables /statistics endpoint
226+
)
227+
```
228+
229+
#### WMTS Extension for Mosaics
230+
231+
A dedicated WMTS extension is now available for mosaic factories:
232+
233+
```python
234+
from titiler.mosaic.extensions import wmtsExtension
235+
236+
factory = MosaicTilerFactory(
237+
extensions=[wmtsExtension()]
238+
)
239+
```
240+
241+
#### OGC Maps API Support
242+
243+
Optional OGC Maps API `/map` endpoint is now available:
244+
245+
```python
246+
factory = MosaicTilerFactory(
247+
add_map=True # Enables /map endpoint
248+
)
249+
```
250+
251+
## Dependency Updates
252+
253+
### Core Dependencies
254+
255+
- `rio-tiler`: Updated to `>=8.0,<9.0`
256+
- `rio-cogeo`: Updated to `7.0,<8.0`
257+
258+
**Action Required:** Test your application with the new versions and review their respective changelogs for any behavioral changes.
259+
260+
## Migration Checklist
261+
262+
Use this checklist to ensure a smooth migration:
263+
264+
- [ ] Update WMTS usage to use the new `wmtsExtension`
265+
- [ ] Update client code parsing `/point` responses (both core and mosaic)
266+
- [ ] Explicitly set `backend` attribute for `MosaicTilerFactory`
267+
- [ ] Add `MosaicJSONExtension` if using MosaicJSON endpoints
268+
- [ ] Update installation to include `[mosaicjson]` extra if needed
269+
- [ ] Review and test automatic image format outputs (UINT8 behavior)
270+
- [ ] Update dependency versions: `rio-tiler` and `rio-cogeo`
271+
- [ ] Test with new Python 3.11+ requirement (from 0.25)
272+
- [ ] Update any hardcoded WMTS endpoint paths in client applications
273+
- [ ] Consider adopting new optional endpoints (`/feature`, `/bbox`, `/statistics`)
274+
- [ ] Review OGC Maps API support for your use cases
275+
276+
## Getting Help
277+
278+
If you encounter issues during migration:
279+
280+
1. Check the [GitHub Issues](https://github.com/developmentseed/titiler/issues)
281+
2. Review the [full CHANGELOG](https://github.com/developmentseed/titiler/blob/main/CHANGES.md)
282+
3. Join the discussions in the [TiTiler repository](https://github.com/developmentseed/titiler)

0 commit comments

Comments
 (0)