mirror of https://github.com/maplibre/martin.git synced 2024-12-19 04:41:46 +03:00

Dynamically create image sprites for MapLibre rendering, given a
directory with images.

### TODO
* [x] Work with @flother to merge these PRs
  * [x] https://github.com/flother/spreet/pull/59  (must have)
  * [x] https://github.com/flother/spreet/pull/57
  * [x] https://github.com/flother/spreet/pull/56
* [ ] https://github.com/flother/spreet/pull/62 (not required but nice
to have, can upgrade later without any code changes)
* [x] Add docs to the book
* [x] Add CLI param, e.g. `--sprite <dir_path>`
* [x] Don't output `.sprites` in auto-genned config when not in use

### API
Per [MapLibre sprites
API](https://maplibre.org/maplibre-style-spec/sprite/), we need to
support the following:
* `/sprite/<sprite_id>.json` metadata about the sprite file - all coming
from a single directory
* `/sprite/<sprite_id>.png` all images combined into a single PNG
* `/sprite/<sprite_id>@2x.json` same but for high DPI devices
* `/sprite/<sprite_id>@2x.png`

Multiple sprite_id values can be combined into one sprite with the same
pattern as for tile joining:
`/sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>[.json|.png|@2x.json|@2x.png]`.
No ID renaming is done, so identical names will override one another.

### Configuration
[Config file](https://maplibre.org/martin/config-file.html) and possibly
CLI should have a simple option to serve sprites. The configuration may
look similar to how mbtiles and pmtiles are configured:

```yaml
# Publish sprite images
sprites:
  paths:
    # scan this whole dir, matching all image files, and publishing it as "my_images" sprite source
    - /path/to/my_images
  sources:
    # named source matching source name to a directory
    my_sprites: /path/to/some_dir
```

Implement #705

2023-06-16 08:19:47 -04:00

5.5 KiB

Executable File

Raw Blame History

Martin

Martin is a tile server able to generate and serve vector tiles on the fly from large PostGIS databases, PMTile, and MBTile files, allowing multiple tile sources to be dynamically combined into one. Martin optimizes for speed and heavy traffic, and is written in Rust.

See Martin book for complete documentation.

Installation

See installation instructions in the Martin book.

Prerequisites: If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended.

You can download martin from GitHub releases page.

Platform	Downloads (latest)
Linux	64-bit
macOS	64-bit
Windows	64-bit

If you are using macOS and Homebrew you can install martin using Homebrew tap.

brew tap maplibre/martin https://github.com/maplibre/martin.git
brew install maplibre/martin/martin

Running Martin Service

See running instructions in the Martin book.

Martin supports any number of PostgreSQL/PostGIS database connections with geospatial-enabled tables and tile-producing SQL functions, as well as PMTile and MBTile files as tile sources.

Martin can auto-discover tables and functions using a connection string. A PG connection string can also be passed via the DATABASE_URL environment variable.

Each tile source will have a TileJSON endpoint.

Examples

# publish all tables and functions from a single database
export DATABASE_URL="postgresql://user:password@host:port/database"
martin

# same as above, but passing connection string via CLI, together with a directory of .mbtiles/.pmtiles files  
martin postgresql://user:password@host:port/database path/to/dir

# publish all discovered tables/funcs from two DBs
# and generate config file with all detected sources
martin postgres://... postgres://...  --save-config config.yaml

# use configuration file instead of auto-discovery
martin --config config.yaml

Docker Example

See Docker instructions in the Martin book.

Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files.

export PGPASSWORD=postgres  # secret!
docker run -p 3000:3000 \
           -e PGPASSWORD \
           -e DATABASE_URL=postgresql://user@host:port/db \
           -v /path/to/config/dir:/config \
           ghcr.io/maplibre/martin --config /config/config.yaml

API

See API documentation in the Martin book.

Martin data is available via the HTTP GET endpoints:

URL	Description
`/`	Status text, that will eventually show web UI
`/catalog`	List of all sources
`/{sourceID}`	Source TileJSON
`/{sourceID}/{z}/{x}/{y}`	Map Tiles
`/{source1},...,{sourceN}`	Composite Source TileJSON
`/{source1},...,{sourceN}/{z}/{x}/{y}`	Composite Source Tiles
`/sprite/{spriteID}[@2x].{json,png}`	Sprites (low and high DPI, index/png)
`/health`	Martin server health check: returns 200 `OK`

Documentation