migration to 0.4

[vincentsarago]

This Document references main changes from 0.3 to 0.4

Install

Current version on pypi is 0.4.0

python -m pip install titiler.core==0.4.0 titiler.mosaic==0.4.0 titiler.application==0.4.0

Bands and Assets

In previous titiler version, we were requesting bands or assets options to be set for MultiBase and MultiBands readers info and statistics method. With TiTiler 0.4.0, we changed this and will now defaults to all available bands/assets if not provided.

# before 
{endpoint}/info?url=data.json&assets=data&assets=image

# now
{endpoint}/info?url=data.json

tradeoff: This means that you don't have to call the /assets or /bands endpoint to get a list of available assets/bands but this means that rio-tiler will also open all dataset (bands or assets) to get the info.

QueryParameters

• list parameters

Instead of requesting coma (,) delimited value (e.g bidx=1,2,3), in 0.4 we now use List directly (e.g bidx=1&bidx=2&bidx=3)

Parameters accepting list:
- bidx
- bands
- assets
- asset_bidx
- asset_expression
- rescale
- c (categories in /statistics endpoints)
- p (percentiles in /statistics endpoints)

• object/dict

Some endpoints in MultiBaseTilerFactory needs dict (object) parameter. Sadly there is no standard way (for GET request) to define Object in Query Parameter so we had to make a custom way using pipe (|) as param={key}|{value} which will then be converted to param = {"key": value} in the application.

asset_bidx=data|1,2,3 -> asset_bidx = {"data": [1, 2, 3]}

• alias

In FastAPI we can use alias for Query parameter. This help for using nice QueryParameter name in the API but keep direct compatibility with the backend code.

parameter in API	parameter name rio-tiler	example
bidx	indexes	{endpoint}/preview?url=data.tif&bidx=1&bidx=2&bdix=3
asset_bidx	asset_indexes	{endpoint}/preview?url=data.json&asset_bidx=data|1,2,3
return_mask	add_mask	{endpoint}/preview.tif?url=data.tif&return_mask=False
rescale	in_range	{endpoint}/preview?url=data.tif&rescale=0,1000
resampling	resampling_method	{endpoint}/preview?url=data.tif&resampling=cubic

Summary of changes

• resampling_method -> resampling
• bidx=1,2,3 -> bidx=1&bidx=2&bidx=3
• assets=b1,b2 -> assets=b1&assets=b2 (for MultiBaseTilerFactory)
• bands=b1,b2 -> bands=b1&bands=b2 (for MultiBandsTilerFactory)
• new asset_bidx=image|1,2,3
• new asset_expression=image|b1+b2

Dependencies

• titiler.core.dependencies.DefaultDependency

#before
from dataclasses import dataclass, field
from titiler.core.dependencies import DefaultDependency

@dataclass
class a(DefaultDependency):

    v: int = field(default=1)

    def __post_init__(self):
        """Post Init."""
        if self.v is not None:
            self.kwargs["v"] = self.v

#now
@dataclass
class a(DefaultDependency):

    v: int = field(default=1)

Before 0.4, we were using the kwargs attribute to pass values to the function

with self.reader(src_path) as src_dst:
    data = src_dst.tile(**params.kwargs)

now we can unpack directly the values to the function

with self.reader(src_path) as src_dst:
    data = src_dst.tile(**params)

• titiler.core.dependencies.RenderParams

In 0.4 we split the RenderParams to PostProcessParams and ImageRenderingParams and added process_dependency attribute in the TileFactory (defaults to PostProcessParams)

@dataclass
class ImageRenderingParams(DefaultDependency):
    """Image Rendering options."""

    add_mask: bool = Query(
        True, alias="return_mask", description="Add mask to the output data."
    )


@dataclass
class PostProcessParams(DefaultDependency):
    """Data Post-Processing options."""

    in_range: Optional[List[str]] = Query(
        None,
        alias="rescale",
        title="Min/Max data Rescaling",
        description="comma (',') delimited Min,Max range. Can set multiple time for multiple bands.",
        example=["0,2000", "0,1000", "0,10000"],  # band 1  # band 2  # band 3
    )
    color_formula: Optional[str] = Query(
        None,
        title="Color Formula",
        description="rio-color formula (info: https://github.com/mapbox/rio-color)",
    )

    def __post_init__(self):
        """Post Init."""
        if self.in_range:
            self.in_range = [  # type: ignore
                tuple(map(float, r.replace(" ", "").split(","))) for r in self.in_range
            ]

Output Models

Precise pydantic Models have been added to all endpoint returning JSON or GeoJSON response. OpenAPI documentation should give a good preview of the expected responses.

Changes

• dataset key has been removed from the /info responses (to match rio-tiler.models.Info` model)
• minzoom, maxzoom, bounds are kept in the /info responses

Endpoints

• /metadata: deleted and replaced by /statistics

• /statistics: Statistics endpoints are now added by defaults (only preview and part are optional)