rio_tiler.io.base

rio_tiler.io.base

rio_tiler.io.base: ABC class for rio-tiler readers.

BaseReader

Bases: SpatialMixin

Rio-tiler.io BaseReader.

Attributes:

• input (any) –

  Reader's input.

• tms (TileMatrixSet) –

  TileMatrixSet grid definition. Defaults to WebMercatorQuad.

__enter__

__enter__()

Support using with Context Managers.

__exit__

__exit__(exc_type, exc_value, traceback)

Support using with Context Managers.

feature abstractmethod

feature(shape: dict) -> ImageData

Read a Dataset for a GeoJSON feature.

Parameters:

• shape (dict) –

  Valid GeoJSON feature.

Returns:

• ImageData –

  rio_tiler.models.ImageData: ImageData instance with data, mask and input spatial info.

info abstractmethod

info() -> Info

Return Dataset's info.

Returns:

• Info –

  rio_tile.models.Info: Dataset info.

part abstractmethod

part(bbox: BBox) -> ImageData

Read a Part of a Dataset.

Parameters:

• bbox (tuple) –

  Output bounds (left, bottom, right, top) in target crs.

Returns:

• ImageData –

  rio_tiler.models.ImageData: ImageData instance with data, mask and input spatial info.

point abstractmethod

point(lon: float, lat: float) -> PointData

Read a value from a Dataset.

Parameters:

• lon (float) –

  Longitude.

• lat (float) –

  Latitude.

Returns:

• PointData –

  rio_tiler.models.PointData: PointData instance with data, mask and spatial info.

preview abstractmethod

preview() -> ImageData

Read a preview of a Dataset.

Returns:

• ImageData –

  rio_tiler.models.ImageData: ImageData instance with data, mask and input spatial info.

statistics abstractmethod

statistics() -> dict[str, BandStatistics]

Return bands statistics from a dataset.

Returns:

• dict[str, BandStatistics] –

  dict[str, rio_tiler.models.BandStatistics]: bands statistics.

tile abstractmethod

tile(tile_x: int, tile_y: int, tile_z: int) -> ImageData

Read a Map tile from the Dataset.

Parameters:

• tile_x (int) –

  Tile's horizontal index.

• tile_y (int) –

  Tile's vertical index.

• tile_z (int) –

  Tile's zoom level index.

Returns:

• ImageData –

  rio_tiler.models.ImageData: ImageData instance with data, mask and tile spatial info.

MultiBandReader

Bases: SpatialMixin

Multi Band Reader.

This Abstract Base Class Reader is suited for dataset that stores spectral bands as separate files (e.g. Sentinel 2).

Attributes:

• input (any) –

  input data.

• tms (TileMatrixSet) –

  TileMatrixSet grid definition. Defaults to WebMercatorQuad.

• minzoom (int) –

  Set dataset's minzoom.

• maxzoom (int) –

  Set dataset's maxzoom.

• reader_options ((dict, option)) –

  options to forward to the reader. Defaults to {}.

__enter__

__enter__()

Support using with Context Managers.

__exit__

__exit__(exc_type, exc_value, traceback)

Support using with Context Managers.

_get_band_url abstractmethod

_get_band_url(band: str) -> str

Validate band name and construct url.

feature

feature(shape: dict, bands: Sequence[str] | str | None = None, expression: str | None = None, **kwargs: Any) -> ImageData

Read and merge parts defined by geojson feature from multiple bands.

Parameters:

• shape (dict) –

  Valid GeoJSON feature.

• bands (sequence of str or str, default: None ) –

  bands to fetch info from.

• expression (str, default: None ) –

  rio-tiler expression for the band list (e.g. b1/b2+b3).

• kwargs (optional, default: {} ) –

  Options to forward to the self.reader.feature method.

Returns:

• ImageData –

  rio_tiler.models.ImageData: ImageData instance with data, mask and tile spatial info.

info

info(bands: Sequence[str] | str | None = None, **kwargs: Any) -> Info

Return metadata from multiple bands.

Parameters:

• bands (sequence of str or str, default: None ) –

  band names to fetch info from. Required keyword argument.

Returns:

• dict ( Info ) –

  Multiple bands info in form of {"band1": rio_tile.models.Info}.

parse_expression

parse_expression(expression: str) -> tuple

Parse rio-tiler band math expression.

part

part(bbox: BBox, bands: Sequence[str] | str | None = None, expression: str | None = None, **kwargs: Any) -> ImageData

Read and merge parts from multiple bands.

Parameters:

• bbox (tuple) –

  Output bounds (left, bottom, right, top) in target crs.

• bands (sequence of str or str, default: None ) –

  bands to fetch info from.

• expression (str, default: None ) –

  rio-tiler expression for the band list (e.g. b1/b2+b3).

• kwargs (optional, default: {} ) –

  Options to forward to the 'self.reader.part' method.

Returns:

• ImageData –

  rio_tiler.models.ImageData: ImageData instance with data, mask and tile spatial info.

point

point(lon: float, lat: float, bands: Sequence[str] | str | None = None, expression: str | None = None, **kwargs: Any) -> PointData

Read a pixel values from multiple bands.

Parameters:

• lon (float) –

  Longitude.

• lat (float) –

  Latitude.

• bands (sequence of str or str, default: None ) –

  bands to fetch info from.

• expression (str, default: None ) –

  rio-tiler expression for the band list (e.g. b1/b2+b3).

• kwargs (optional, default: {} ) –

  Options to forward to the self.reader.point method.

Returns:

• PointData –

  PointData

preview

preview(bands: Sequence[str] | str | None = None, expression: str | None = None, **kwargs: Any) -> ImageData

Read and merge previews from multiple bands.

Parameters:

• bands (sequence of str or str, default: None ) –

  bands to fetch info from.

• expression (str, default: None ) –

  rio-tiler expression for the band list (e.g. b1/b2+b3).

• kwargs (optional, default: {} ) –

  Options to forward to the self.reader.preview method.

Returns:

• ImageData –

  rio_tiler.models.ImageData: ImageData instance with data, mask and tile spatial info.

statistics

statistics(bands: Sequence[str] | str | None = None, expression: str | None = None, categorical: bool = False, categories: list[float] | None = None, percentiles: list[int] | None = None, hist_options: dict | None = None, max_size: int = 1024, **kwargs: Any) -> dict[str, BandStatistics]

Return array statistics for multiple assets.

Parameters:

• bands (sequence of str or str, default: None ) –

  bands to fetch info from. Required keyword argument.

• expression (str, default: None ) –

  rio-tiler expression for the band list (e.g. b1/b2+b3).

• categorical (bool, default: False ) –

  treat input data as categorical data. Defaults to False.

• categories (list of numbers, default: None ) –

  list of categories to return value for.

• percentiles (list of numbers, default: None ) –

  list of percentile values to calculate. Defaults to [2, 98].

• hist_options (dict, default: None ) –

  Options to forward to numpy.histogram function.

• max_size (int, default: 1024 ) –

  Limit the size of the longest dimension of the dataset read, respecting bounds X/Y aspect ratio. Defaults to 1024.

• kwargs (optional, default: {} ) –

  Options to forward to the self.preview method.

Returns:

• dict ( dict[str, BandStatistics] ) –

  Multiple assets statistics in form of {"{band}/{expression}": rio_tiler.models.BandStatistics, ...}.

tile

tile(tile_x: int, tile_y: int, tile_z: int, bands: Sequence[str] | str | None = None, expression: str | None = None, **kwargs: Any) -> ImageData

Read and merge Web Map tiles multiple bands.

Parameters:

• tile_x (int) –

  Tile's horizontal index.

• tile_y (int) –

  Tile's vertical index.

• tile_z (int) –

  Tile's zoom level index.

• bands (sequence of str or str, default: None ) –

  bands to fetch info from.

• expression (str, default: None ) –

  rio-tiler expression for the band list (e.g. b1/b2+b3).

• kwargs (optional, default: {} ) –

  Options to forward to the self.reader.tile method.

Returns:

• ImageData –

  rio_tiler.models.ImageData: ImageData instance with data, mask and tile spatial info.

MultiBaseReader

Bases: SpatialMixin

MultiBaseReader Reader.

This Abstract Base Class Reader is suited for dataset that are composed of multiple assets (e.g. STAC).

Attributes:

• input (any) –

  input data.

• tms (TileMatrixSet) –

  TileMatrixSet grid definition. Defaults to WebMercatorQuad.

• minzoom (int) –

  Set dataset's minzoom.

• maxzoom (int) –

  Set dataset's maxzoom.

• reader_options ((dict, option)) –

  options to forward to the reader. Defaults to {}.

__enter__

__enter__()

Support using with Context Managers.

__exit__

__exit__(exc_type, exc_value, traceback)

Support using with Context Managers.

_get_asset_info abstractmethod

_get_asset_info(asset: str) -> AssetInfo

Validate asset name and construct url.

_get_reader

_get_reader(asset_info: AssetInfo) -> tuple[type[BaseReader], dict]

Get Asset Reader and options.

_update_statistics

_update_statistics(img: ImageData, indexes: Indexes | None = None, statistics: Sequence[tuple[float, float]] | None = None)

Update ImageData Statistics from AssetInfo.

feature

feature(shape: dict, assets: Sequence[str] | str | None = None, expression: str | None = None, asset_indexes: dict[str, Indexes] | None = None, asset_as_band: bool = False, **kwargs: Any) -> ImageData

Read and merge parts defined by geojson feature from multiple assets.

Parameters:

• shape (dict) –

  Valid GeoJSON feature.

• assets (sequence of str or str, default: None ) –

  assets to fetch info from.

• expression (str, default: None ) –

  rio-tiler expression for the asset list (e.g. asset1/asset2+asset3).

• asset_indexes (dict, default: None ) –

  Band indexes for each asset (e.g {"asset1": 1, "asset2": (1, 2,)}).

• kwargs (optional, default: {} ) –

  Options to forward to the self.reader.feature method.

Returns:

• ImageData –

  rio_tiler.models.ImageData: ImageData instance with data, mask and tile spatial info.

info

info(assets: Sequence[str] | str | None = None, **kwargs: Any) -> dict[str, Info]

Return metadata from multiple assets.

Parameters:

• assets (sequence of str or str, default: None ) –

  assets to fetch info from. Required keyword argument.

Returns:

• dict ( dict[str, Info] ) –

  Multiple assets info in form of {"asset1": rio_tile.models.Info}.

merged_statistics

merged_statistics(assets: Sequence[str] | str | None = None, expression: str | None = None, asset_indexes: dict[str, Indexes] | None = None, categorical: bool = False, categories: list[float] | None = None, percentiles: list[int] | None = None, hist_options: dict | None = None, max_size: int = 1024, **kwargs: Any) -> dict[str, BandStatistics]

Return array statistics for multiple assets.

Parameters:

• assets (sequence of str or str, default: None ) –

  assets to fetch info from.

• expression (str, default: None ) –

  rio-tiler expression for the asset list (e.g. asset1/asset2+asset3).

• asset_indexes (dict, default: None ) –

  Band indexes for each asset (e.g {"asset1": 1, "asset2": (1, 2,)}).

• categorical (bool, default: False ) –

  treat input data as categorical data. Defaults to False.

• categories (list of numbers, default: None ) –

  list of categories to return value for.

• percentiles (list of numbers, default: None ) –

  list of percentile values to calculate. Defaults to [2, 98].

• hist_options (dict, default: None ) –

  Options to forward to numpy.histogram function.

• max_size (int, default: 1024 ) –

  Limit the size of the longest dimension of the dataset read, respecting bounds X/Y aspect ratio. Defaults to 1024.

• kwargs (optional, default: {} ) –

  Options to forward to the self.preview method.

Returns:

• dict[str, BandStatistics] –

  Dict[str, rio_tiler.models.BandStatistics]: bands statistics.

parse_expression

parse_expression(expression: str, asset_as_band: bool = False) -> tuple

Parse rio-tiler band math expression.

part

part(bbox: BBox, assets: Sequence[str] | str | None = None, expression: str | None = None, asset_indexes: dict[str, Indexes] | None = None, asset_as_band: bool = False, **kwargs: Any) -> ImageData

Read and merge parts from multiple assets.

Parameters:

• bbox (tuple) –

  Output bounds (left, bottom, right, top) in target crs.

• assets (sequence of str or str, default: None ) –

  assets to fetch info from.

• expression (str, default: None ) –

  rio-tiler expression for the asset list (e.g. asset1/asset2+asset3).

• asset_indexes (dict, default: None ) –

  Band indexes for each asset (e.g {"asset1": 1, "asset2": (1, 2,)}).

• kwargs (optional, default: {} ) –

  Options to forward to the self.reader.part method.

Returns:

• ImageData –

  rio_tiler.models.ImageData: ImageData instance with data, mask and tile spatial info.

point

point(lon: float, lat: float, assets: Sequence[str] | str | None = None, expression: str | None = None, asset_indexes: dict[str, Indexes] | None = None, asset_as_band: bool = False, **kwargs: Any) -> PointData

Read pixel value from multiple assets.

Parameters:

• lon (float) –

  Longitude.

• lat (float) –

  Latitude.

• assets (sequence of str or str, default: None ) –

  assets to fetch info from.

• expression (str, default: None ) –

  rio-tiler expression for the asset list (e.g. asset1/asset2+asset3).

• asset_indexes (dict, default: None ) –

  Band indexes for each asset (e.g {"asset1": 1, "asset2": (1, 2,)}).

• kwargs (optional, default: {} ) –

  Options to forward to the self.reader.point method.

Returns:

• PointData –

  PointData

preview

preview(assets: Sequence[str] | str | None = None, expression: str | None = None, asset_indexes: dict[str, Indexes] | None = None, asset_as_band: bool = False, **kwargs: Any) -> ImageData

Read and merge previews from multiple assets.

Parameters:

• assets (sequence of str or str, default: None ) –

  assets to fetch info from.

• expression (str, default: None ) –

  rio-tiler expression for the asset list (e.g. asset1/asset2+asset3).

• asset_indexes (dict, default: None ) –

  Band indexes for each asset (e.g {"asset1": 1, "asset2": (1, 2,)}).

• kwargs (optional, default: {} ) –

  Options to forward to the self.reader.preview method.

Returns:

• ImageData –

  rio_tiler.models.ImageData: ImageData instance with data, mask and tile spatial info.

statistics

statistics(assets: Sequence[str] | str | None = None, asset_indexes: dict[str, Indexes] | None = None, asset_expression: dict[str, str] | None = None, **kwargs: Any) -> dict[str, dict[str, BandStatistics]]

Return array statistics for multiple assets.

Parameters:

• assets (sequence of str or str, default: None ) –

  assets to fetch info from.

• asset_indexes (dict, default: None ) –

  Band indexes for each asset (e.g {"asset1": 1, "asset2": (1, 2,)}).

• asset_expression (dict, default: None ) –

  rio-tiler expression for each asset (e.g. {"asset1": "b1/b2+b3", "asset2": ...}).

• kwargs (optional, default: {} ) –

  Options to forward to the self.reader.statistics method.

Returns:

• dict ( dict[str, dict[str, BandStatistics]] ) –

  Multiple assets statistics in form of {"asset1": {"1": rio_tiler.models.BandStatistics, ...}}.

tile

tile(tile_x: int, tile_y: int, tile_z: int, assets: Sequence[str] | str | None = None, expression: str | None = None, asset_indexes: dict[str, Indexes] | None = None, asset_as_band: bool = False, **kwargs: Any) -> ImageData

Read and merge Wep Map tiles from multiple assets.

Parameters:

• tile_x (int) –

  Tile's horizontal index.

• tile_y (int) –

  Tile's vertical index.

• tile_z (int) –

  Tile's zoom level index.

• assets (sequence of str or str, default: None ) –

  assets to fetch info from.

• expression (str, default: None ) –

  rio-tiler expression for the asset list (e.g. asset1/asset2+asset3).

• asset_indexes (dict, default: None ) –

  Band indexes for each asset (e.g {"asset1": 1, "asset2": (1, 2,)}).

• kwargs (optional, default: {} ) –

  Options to forward to the self.reader.tile method.

Returns:

• ImageData –

  rio_tiler.models.ImageData: ImageData instance with data, mask and tile spatial info.

SpatialMixin

Spatial Info Mixin.

Attributes:

• tms (TileMatrixSet) –

  TileMatrixSet grid definition. Defaults to WebMercatorQuad.

_dst_geom_in_tms_crs cached property

_dst_geom_in_tms_crs

Return dataset geom info in TMS projection.

_maxzoom cached property

_maxzoom: int

Calculate dataset maximum zoom level.

_minzoom cached property

_minzoom: int

Calculate dataset minimum zoom level.

get_geographic_bounds

get_geographic_bounds(crs: CRS) -> BBox

Return Geographic Bounds for a Geographic CRS.

tile_exists

tile_exists(tile_x: int, tile_y: int, tile_z: int) -> bool

Check if a tile intersects the dataset bounds.

Parameters:

• tile_x (int) –

  Tile's horizontal index.

• tile_y (int) –

  Tile's vertical index.

• tile_z (int) –

  Tile's zoom level index.

Returns:

• bool ( bool ) –

  True if the tile intersects the dataset bounds.