🧩 Virtual Mosaics

localtileserver supports creating virtual mosaics from multiple raster files, compositing them into a single seamless tile layer. This uses rio-tiler’s mosaic_reader and does not require the cogeo-mosaic package.

How It Works

The mosaic handler takes a list of raster file paths (or URLs) and serves tiles by reading from each file and compositing the results using a pixel selection method. The default method is “first valid pixel wins” – meaning the first file in the list that has valid data at a given pixel location provides the value.

Python Handler Functions

from localtileserver.tiler.mosaic import get_mosaic_tile, get_mosaic_preview

# List of raster files to mosaic
files = [
    'path/to/scene_north.tif',
    'path/to/scene_south.tif',
]

# Get a mosaic thumbnail
thumb = get_mosaic_preview(files, max_size=512)

# Get a mosaic tile at a specific location
tile = get_mosaic_tile(files, z=10, x=512, y=512)

You can specify band indexes:

# Single band mosaic with colormap
tile = get_mosaic_tile(files, z=10, x=512, y=512, indexes=[1])

Pixel Selection Methods

By default, the mosaic uses FirstMethod (first valid pixel wins). You can use any of rio-tiler’s built-in pixel selection methods:

from rio_tiler.mosaic.methods.defaults import (
    FirstMethod,
    HighestMethod,
    LowestMethod,
    MeanMethod,
    MedianMethod,
)

# Use the highest pixel value from overlapping areas
tile = get_mosaic_tile(files, z=10, x=512, y=512,
                       pixel_selection=HighestMethod)

# Use the mean of overlapping pixels
tile = get_mosaic_tile(files, z=10, x=512, y=512,
                       pixel_selection=MeanMethod)

REST API Endpoints

Mosaic endpoints are prefixed with /api/mosaic/:

# Get a mosaic tile (files via query parameter)
GET /api/mosaic/tiles/{z}/{x}/{y}.png?files=scene_north.tif,scene_south.tif

# Get a mosaic thumbnail
GET /api/mosaic/thumbnail.png?files=scene_north.tif,scene_south.tif&max_size=512

# With band selection
GET /api/mosaic/tiles/{z}/{x}/{y}.png?files=scene_north.tif,scene_south.tif&indexes=1,2,3

Parameters:

Parameter	Description
files	Comma-separated list of file paths or URLs (or register mosaic_assets in app state)
indexes	Comma-separated band indexes
max_size	Maximum thumbnail dimension (default: 512)

Server-Side Registration

For files that are cumbersome to pass as query parameters, you can register them in the application state:

from localtileserver.web import create_app

app = create_app()
app.state.mosaic_assets = [
    'path/to/scene_north.tif',
    'path/to/scene_south.tif',
]

Then access the mosaic endpoints without the files parameter:

GET /api/mosaic/tiles/{z}/{x}/{y}.png
GET /api/mosaic/thumbnail.png