TileCloud-chain
TileCloud Chain is a comprehensive toolset for generating, serving, and managing map tiles. It supports WMS and Mapnik sources, multiple cloud and local storage backends, distributed master/slave generation with configurable queue backends, and a built-in WMTS tile server with an administrative web interface.
Sources
- Web Map Service (WMS)
- Mapnik rendering engine (legacy)
Destination Formats and Storage
- Web Map Tile Service (WMTS) layout
- Amazon S3 storage
- Azure Blob storage
- Local filesystem
- SQLite (MBTiles) support (legacy)
- Berkeley DB integration (legacy)
Key Features
- Tile generation in three modes:
local(single machine),master(prepares jobs for a queue),slave(consumes jobs from the queue) - Distributed generation with configurable queue backends: Redis, Amazon SQS, or PostgreSQL
- Daemon mode for continuous slave operation
- Zoom separation via
min_resolution_seed: pre-generate low zooms, serve high zooms dynamically through the internal MapCache - Geometry-based filtering using PostGIS SQL queries or GDAL datasources (e.g. Shapefile) — only generate tiles that intersect your areas of interest
- Bounding box filtering to restrict tile generation to a geographic extent
- Multi-grid support: multiple grids per layer with TileMatrixSetLimits in WMTS capabilities
- Layer dimensions: multi-variant tilesets (e.g. time, date) with WMTS dimension support
- MetaTiles: efficient generation by fetching multiple tiles in a single WMS request, with configurable size and border buffer
- Empty tile detection via SHA-1 hashing at both metatile and tile level
- Tile post-processing: run external tools (optipng, jpegoptim, pngquant) and configure Pillow save options
- Legend image generation: per-layer, per-zoom legend images with SHA-1 deduplication
- WMTS GetCapabilities: automatic XML generation with TileMatrixSetLimits, legend URLs, and ResourceURLs for GetFeatureInfo
- GetFeatureInfo (interrogation): WMS feature info proxy, available via REST and KVP interfaces
- WMTS tile server: built-in FastAPI server serving tiles via RESTful URLs and KVP interface, with caching, CORS, CSP, GZip compression, and configurable cache expiration
- Internal MapCache: Redis-based dynamic tile cache with locking for concurrent generation, WMS fallback for cache misses, and geometry-based redirect
- Administration web interface: job status monitoring, PostgreSQL job lifecycle (create/cancel/retry), command execution with ACL validation, OAuth2 GitHub authentication, and configuration validation
- OpenLayers demo page: interactive map with WMTS layers, dimension selectors, GetFeatureInfo on click, and state persistence in the URL
- Multi-tenant mode: host-based configuration resolution for serving multiple projects from a single deployment
- Monitoring: Prometheus metrics (
tilecloud_chain_*counters) and Sentry error reporting - Empty tile detection via hashing
- Geographic filtering (bbox and geometry-based)
Legacy Support
The following features are maintained for backward compatibility:
- Mapnik rendering
- Mapnik UTFGrid (interactive tile grids)
- Berkeley DB integration
- SQLite (MBTiles) support
- Error file generation and tile retry (
--tiles)
Visual Preview
The admin interface with PostgreSQL queue integration:
The test page:
Demo.
Getting Started
Create a configuration file at tilegeneration/config.yaml.
Reference the example configuration.
Commands
| Command | Description |
|---|---|
generate-tiles |
Generate tiles from WMS or Mapnik sources. Supports local, master, and slave roles, and --get-hash for computing empty tile hashes |
generate-controller |
Generate WMTS capabilities, legend images, display queue status, or dump the effective configuration |
Generation Pipeline
The generate-tiles command supports four execution modes:
local: generate tiles directly and store them in the target cache.master: prepare metatile jobs and push them to the queue store.slave: read jobs from the queue store, generate tiles, and store them.--get-hash: switch to hash mode to print metatile/tile hashes.
flowchart TD
A["generate-tiles CLI"] --> B{"Mode"}
B -->|local| L1["Build metatile stream"]
B -->|master| M1["Build metatile stream"]
B -->|slave| S1["Read metatiles from queue"]
B -->|hash via --get-hash| H1["Build tile or metatile selection"]
L1 --> L2["Apply geometry filter"]
L2 --> C["Fetch source tile data"]
M1 --> M2["Apply geometry filter"]
M2 --> O3["Push metatile jobs to queue (Redis, SQS, PostgreSQL)"]
S1 --> C
H1 --> C
C --> D["Split metatiles into tiles"]
D --> E{"Hash handling"}
E -->|hash mode| H2["Print hash values"]
E -->|normal modes| F["Drop empty tiles/metatiles with configured hashes"]
F --> G["Run post-process chain"]
G --> I{"Mode output"}
I -->|local| O1["Store tiles to cache (S3, local, etc.)"]
I -->|slave| O2["Store tiles to cache and delete processed queue items"]
I -->|hash| O4["Console output only"]
Server
TileCloud Chain includes a built-in WMTS tile server powered by FastAPI:
- WMTS REST API: tile serving with and without dimensions
- KVP interface: supports GetCapabilities, GetTile, and GetFeatureInfo via query parameters
- Internal MapCache: Redis-based dynamic tile cache with locking for concurrent generation and WMS fallback on cache miss
- GetFeatureInfo: proxies feature info requests to the configured WMS backend
- Cache headers: configurable
ExpiresandCache-Control - CORS: configurable origins, methods, headers, and credentials
- CSP: Content Security Policy with nonce-based scripts
- Prometheus metrics: request counters and resource usage
- Sentry: error reporting integration
- Multi-tenant: host-based configuration resolution
- Tile-Backend header: reports whether a tile came from cache, Redis, or WMS generation
Admin Interface
The web admin interface provides:
- Job status: per-job counters (to generate, pending, error) with PostgreSQL, or queue counters with Redis/SQS
- PostgreSQL job management: create, cancel, and retry jobs (retry only errored metatiles)
- Command execution: run
generate-tilesandgenerate-controllerwith validated arguments - Configuration validation: schema validation errors and deprecation warnings
- Predefined commands: quick-run buttons for common operations
- OAuth2 authentication: GitHub OAuth2 with configurable access control
- Test page: OpenLayers map with WMTS layers, dimension selectors, GetFeatureInfo, and URL-based state persistence
Development
Building
make build
Quality Assurance
make prospector
Testing
make tests
Documentation
Contributing
Set up pre-commit hooks:
pip install pre-commit
pre-commit install --allow-missing-config
2 maintainers
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
tilecloud_chain-2.0.2.tar.gz
(441.3 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file tilecloud_chain-2.0.2.tar.gz.
File metadata
- Download URL: tilecloud_chain-2.0.2.tar.gz
- Upload date:
- Size: 441.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.2.0 CPython/3.12.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
523e61a77ffc025c1d4cdce44489bc41f4418aee3ccdb2894cbc6f6d5ba9e14f
|
|
| MD5 |
ec4eba259e412493d49de76ad72a31e9
|
|
| BLAKE2b-256 |
31c8686767c52e988c1b66197f9ec4455fb770947d90cd1911ff15eebdf6c8a8
|
File details
Details for the file tilecloud_chain-2.0.2-py3-none-any.whl.
File metadata
- Download URL: tilecloud_chain-2.0.2-py3-none-any.whl
- Upload date:
- Size: 480.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.2.0 CPython/3.12.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8a905eef3232f9f3b73ef8ef2eeca90814e12f3d23e13b3e83d100a6068ac950
|
|
| MD5 |
f958447104b7f6ff78c2b1c39ff71adc
|
|
| BLAKE2b-256 |
09dcc24dce3f06e65661a9c29e8f224834ff6cb5ecd808593d13df4d3ff8c117
|
