Martin Tile Server

Martin is a high-performance tile server written in Rust designed to serve vector tiles on the fly. It supports combining multiple tile sources into a single endpoint and can serve styles, sprites, and font glyphs.

Supported tile sources include:

• PostGIS: Automatic discovery of compatible tables and functions.
• PMTiles: Local files or remote files via HTTP.
• MBTiles: Local files.
• GeoJSON: Local files.

Additional capabilities:

• Bulk Generation: Use martin-cp to generate tiles in bulk into an MBTiles archive.
• MBTiles Management: Use the mbtiles tool to examine, copy, validate, compare, and apply diffs between MBTiles files.

The Martin Web UI provides several tools for interacting with tiles served by Martin:

• Tile Catalog: Browse and preview all available tile sources.
• Style Editor: Visual style editing with an integrated Maputnik editor.
• Font Catalog: View and manage font collections.
• Sprite Catalog: Browse and download sprite collections.
• Analytics: Real-time performance metrics and usage statistics.

The mbtiles tool extends the original MBTiles specification by supporting several different schema types for storing tile data. It can convert between these schemas, generate diffs between files of any schema, and merge multiple schema files.

All schemas include a metadata table containing key/value pairs like tileset name, format, and bounds.

Martin supports several data integration patterns depending on your source type:

PostgreSQL Integration

Martin connects via a connection string and uses a deadpool-postgres connection pool. It automatically discovers tables with geometry columns and functions that return MVT data by querying geometry_columns and pg_proc.

File Source Integration

Martin can serve tiles from local or remote files:

• MBTiles: SQLite-based format.
• PMTiles: Binary format (uses HTTP range requests for remote files).
• COG (Cloud Optimized GeoTIFF): Uses a TIFF parser and HTTP range requests for remote access.
• Cloud Storage: Supports S3, Azure, and GCP via the object_store crate.

GeoJSON Integration

GeoJSON files are loaded into memory, reprojected to Web Mercator, and indexed using a packed Hilbert R-tree for real-time MVT encoding on demand.

Martin is organized into four primary Rust crates, each serving a specific role in the tile serving ecosystem:

• martin: The main tile server binary. It provides the HTTP service layer (using Actix-Web), handles request routing, configuration parsing (CLI, env vars, config files), and manages runtime source reloading. It also serves the Web UI.
• martin-core: The library containing core abstractions. It implements tile source traits for PostgreSQL, MBTiles, PMTiles, and Cloud Optimized GeoTIFF (COG), and handles resource generation for sprites, fonts, and styles.
• mbtiles: A library and CLI tool dedicated to MBTiles. It supports SQLite-based reading/writing, metadata management, tile compression (gzip, brotli), and schema management.
• martin-tile-utils: Low-level utilities for tile coordinate conversions, encoding/decoding, and bounding box calculations.

Martin supports several types of tile sources depending on your data requirements for performance, flexibility, and scale:

• Tile Archives (MBTiles, PMTiles): Best for high performance and memory efficiency. Use these when you have pre-generated vector or raster tiles.
• GeoJSON Sources: Best for semi-static, relatively small datasets that do not justify the overhead of a tile archive.
• PostgreSQL Connections (Tables or Functions): Best for flexible data that may need to be updated in real-time.

Comparison Summary:

Martin can automatically publish PostgreSQL tables or views as vector tile sources. When a PostgreSQL connection string is provided, Martin identifies all tables with at least one geometry column and publishes them.

Key behaviors:

• Geometry Columns: If a geometry column has an SRID of 0, you must set a default SRID in the configuration, otherwise the table will be ignored.
• Properties: All non-geometry columns in the table are automatically published as vector tile feature tags (properties).
• Automatic Discovery: Martin uses database identifiers for the default name and description in the generated TileJSON.

SSL certificates can be provided to Martin in two ways:

1. Configuration file: Specify certificate paths within your Martin configuration.
2. Environment variables: Use environment variables (following standard psql conventions) to provide certificates. Environment variables apply to all PostgreSQL connections managed by Martin.

Composite Sources allow you to combine multiple data sources into a single endpoint. A composite source is defined by listing multiple source names separated by commas: {source1},{source2},...,{sourceN}.

When using a composite source:

• The TileJSON endpoint is available at /{source1},{source2},...,{sourceN}.
• Tiles are available at /{source1},{source2},...,{sourceN}/{z}/{x}/{y}.
• Individual sources within the composite can be accessed via their specific {source_name} using the source-layer property in your map client.