mirror of
https://github.com/maplibre/martin.git
synced 2024-12-20 21:31:49 +03:00
Adjust readme and martin book (#1253)
Fixes #1245 Large book and README refactoring, adding quick started section, list of available features to the README, and moving most of the content from README to the book. --------- Co-authored-by: Yuri Astrakhan <YuriAstrakhan@gmail.com>
This commit is contained in:
Lucas
GitHub
parent
81f4d4cd03
commit
a9cb0c972f
123
README.md
123
README.md
@ -8,116 +8,27 @@
|
||||
[](https://github.com/maplibre/martin/security)
|
||||
[](https://github.com/maplibre/martin/actions)
|
||||
|
||||
Martin is a tile server able to generate and serve [vector tiles](https://github.com/mapbox/vector-tile-spec) on the fly from large [PostGIS](https://github.com/postgis/postgis) databases, [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new) (local or remote), and [MBTile](https://github.com/mapbox/mbtiles-spec) files, allowing multiple tile sources to be dynamically combined into one. Martin optimizes for speed and heavy traffic, and is written in [Rust](https://github.com/rust-lang/rust).
|
||||
Martin is a tile server able to generate and serve [vector tiles](https://github.com/mapbox/vector-tile-spec) on the fly
|
||||
from large [PostGIS](https://github.com/postgis/postgis)
|
||||
databases, [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new) (local or remote),
|
||||
and [MBTile](https://github.com/mapbox/mbtiles-spec) files, allowing multiple tile sources to be dynamically combined
|
||||
into one. Martin optimizes for speed and heavy traffic, and is written in [Rust](https://github.com/rust-lang/rust).
|
||||
|
||||
Additionally, there are [several tools](https://maplibre.org/martin/tools.html) for generating tiles in bulk from any Martin-supported sources (similar to `tilelive-copy`), copying tiles between MBTiles files, creating deltas (patches) and applying them, and validating MBTiles files.
|
||||
### Features
|
||||
|
||||
See [Martin book](https://maplibre.org/martin/) for complete documentation.
|
||||
* Serve vector tiles from PostGIS, PMTile, and MBTile sources
|
||||
* [Combine](https://maplibre.org/martin/sources-composite.html) multiple tile sources
|
||||
* Generate [sprites](https://maplibre.org/martin/sources-sprites.html) and [font glyphs](https://maplibre.org/martin/sources-fonts.html)
|
||||
* Generate tiles in bulk from any Martin-supported sources into an `.mbtiles` file with [martin-cp](https://maplibre.org/martin/martin-cp.html) tool
|
||||
* Examine, copy, validate, compare, and apply diffs between `.mbtiles` files with [mbtiles](https://maplibre.org/martin/tools.html#mbtiles) tool
|
||||
|
||||
## Installation
|
||||
### Documentation
|
||||
|
||||
_See [installation instructions](https://maplibre.org/martin/installation.html) 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](https://github.com/maplibre/martin/releases).
|
||||
|
||||
| Platform | AMD-64 | ARM-64 |
|
||||
|----------|--------------------------------------------------------------------------------------------------|-------------------------------------|
|
||||
| Linux | [.tar.gz][rl-linux-x64] (gnu)<br>[.tar.gz][rl-linux-x64-musl] (musl)<br>[.deb][rl-linux-x64-deb] | [.tar.gz][rl-linux-a64-musl] (musl) |
|
||||
| macOS | [.tar.gz][rl-macos-x64] | [.tar.gz][rl-macos-a64] |
|
||||
| Windows | [.zip][rl-win64-zip] | |
|
||||
|
||||
[rl-linux-x64]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-unknown-linux-gnu.tar.gz
|
||||
[rl-linux-x64-musl]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-unknown-linux-musl.tar.gz
|
||||
[rl-linux-x64-deb]: https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb
|
||||
[rl-linux-a64-musl]: https://github.com/maplibre/martin/releases/latest/download/martin-aarch64-unknown-linux-musl.tar.gz
|
||||
[rl-macos-x64]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-apple-darwin.tar.gz
|
||||
[rl-macos-a64]: https://github.com/maplibre/martin/releases/latest/download/martin-aarch64-apple-darwin.tar.gz
|
||||
[rl-win64-zip]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-pc-windows-msvc.zip
|
||||
|
||||
If you are using macOS and [Homebrew](https://brew.sh/) you can install `martin` and `mbtiles` using Homebrew tap.
|
||||
|
||||
```shell
|
||||
brew tap maplibre/martin
|
||||
brew install martin
|
||||
```
|
||||
|
||||
## Running Martin Service
|
||||
|
||||
_See [running instructions](https://maplibre.org/martin/run.html) in the Martin book._
|
||||
|
||||
Martin supports any number of PostgreSQL/PostGIS database connections with [geospatial-enabled](https://postgis.net/docs/using_postgis_dbmanagement.html#geometry_columns) tables and tile-producing SQL functions, as well as [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new) and [MBTile](https://github.com/mapbox/mbtiles-spec) files as tile sources.
|
||||
|
||||
Martin can auto-discover tables and functions using a [connection string](https://maplibre.org/martin/pg-connections.html). A PG connection string can also be passed via the `DATABASE_URL` environment variable.
|
||||
|
||||
Each tile source will have a [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint.
|
||||
|
||||
#### Examples
|
||||
|
||||
```shell
|
||||
# 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](https://maplibre.org/martin/run-with-docker.html) in the Martin book._
|
||||
|
||||
Martin is also available as a [Docker image](https://ghcr.io/maplibre/martin). 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.
|
||||
|
||||
```shell
|
||||
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](https://maplibre.org/martin/using.html) 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) |
|
||||
| `/font/{font}/{start}-{end}` | Font source |
|
||||
| `/font/{font1},…,{fontN}/{start}-{end}` | Composite Font source |
|
||||
| `/health` | Martin server health check: returns 200 `OK` |
|
||||
|
||||
## Re-use Martin as a library
|
||||
|
||||
Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features:
|
||||
|
||||
* **postgres** - enable PostgreSQL/PostGIS tile sources
|
||||
* **pmtiles** - enable PMTile tile sources
|
||||
* **mbtiles** - enable MBTile tile sources
|
||||
* **fonts** - enable font sources
|
||||
* **sprites** - enable sprite sources
|
||||
|
||||
## Documentation
|
||||
|
||||
See [Martin book](https://maplibre.org/martin/) for complete documentation.
|
||||
* [Quick Start](https://maplibre.org/martin/quick-start.html)
|
||||
* [Installation](https://maplibre.org/martin/installation.html)
|
||||
* Running with [CLI](https://maplibre.org/martin/run-with-cli.html)
|
||||
or [configuration file](https://maplibre.org/martin/config-file.html)
|
||||
* [Usage and API](https://maplibre.org/martin/using.html)
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@ -1,5 +1,10 @@
|
||||
[Introduction](introduction.md)
|
||||
|
||||
- [Quick Start](quick-start.md)
|
||||
- [On Linux](quick-start-linux.md)
|
||||
- [On macOS](quick-start-macos.md)
|
||||
- [On Windows](quick-start-windows.md)
|
||||
- [View with QGIS](quick-start-qgis.md)
|
||||
- [Installation](installation.md)
|
||||
- [Running](run.md)
|
||||
- [Command Line Interface](run-with-cli.md)
|
||||
@ -32,3 +37,4 @@
|
||||
- [Diffing/Patching MBTiles](mbtiles-diff.md)
|
||||
- [Validating MBTiles](mbtiles-validation.md)
|
||||
- [Development](development.md)
|
||||
- [Martin as a library](martin-as-a-library.md)
|
||||
|
||||
@ -6,14 +6,14 @@ contain environment variables, which will be expanded before parsing. For exampl
|
||||
config file: `connection_string: ${MY_DATABASE_URL}`, or with a
|
||||
default `connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db}`
|
||||
|
||||
```shell
|
||||
```bash
|
||||
martin --config config.yaml
|
||||
```
|
||||
|
||||
You may wish to auto-generate a config file with `--save-config` argument. This will generate a config yaml file with
|
||||
all of your configuration, which you can edit to remove any sources you don't want to expose.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
martin ... ... ... --save-config config.yaml
|
||||
```
|
||||
|
||||
|
||||
@ -1,36 +1,39 @@
|
||||
# Development
|
||||
|
||||
Clone Martin, setting remote name to `upstream`. This way `main` branch will be updated automatically with the latest changes from the upstream repo.
|
||||
Clone Martin, setting remote name to `upstream`. This way `main` branch will be updated automatically with the latest
|
||||
changes from the upstream repo.
|
||||
|
||||
```shell, ignore
|
||||
```bash, ignore
|
||||
git clone https://github.com/maplibre/martin.git -o upstream
|
||||
cd martin
|
||||
```
|
||||
|
||||
Fork Martin repo into your own GitHub account, and add your fork as a remote
|
||||
|
||||
```shell, ignore
|
||||
```bash, ignore
|
||||
git remote add origin _URL_OF_YOUR_FORK_
|
||||
```
|
||||
|
||||
Install [docker](https://docs.docker.com/get-docker/) and [docker-compose](https://docs.docker.com/compose/)
|
||||
|
||||
```shell, ignore
|
||||
```bash, ignore
|
||||
# Ubuntu-based distros have an older version that might also work:
|
||||
sudo apt install -y docker.io docker-compose
|
||||
```
|
||||
|
||||
Install a few required libs and tools:
|
||||
|
||||
```shell, ignore
|
||||
```bash, ignore
|
||||
# For Ubuntu-based distros
|
||||
sudo apt install -y build-essential pkg-config jq file
|
||||
```
|
||||
|
||||
Install [Just](https://github.com/casey/just#readme) (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source:
|
||||
Install [Just](https://github.com/casey/just#readme) (improved makefile processor). Note that some Linux and Homebrew
|
||||
distros have outdated versions of Just, so you should install it from source:
|
||||
|
||||
```shell, ignore
|
||||
```bash, ignore
|
||||
cargo install just --locked
|
||||
```
|
||||
|
||||
When developing MBTiles SQL code, you may need to use `just prepare-sqlite` whenever SQL queries are modified. Run `just` to see all available commands.
|
||||
When developing MBTiles SQL code, you may need to use `just prepare-sqlite` whenever SQL queries are modified.
|
||||
Run `just` to see all available commands.
|
||||
|
||||
BIN
docs/src/images/qgis_add_to_layers.png
Normal file
BIN
docs/src/images/qgis_add_to_layers.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
BIN
docs/src/images/qgis_add_vector_tile.png
Normal file
BIN
docs/src/images/qgis_add_vector_tile.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 99 KiB |
BIN
docs/src/images/qgis_add_vector_tile_options.png
Normal file
BIN
docs/src/images/qgis_add_vector_tile_options.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
BIN
docs/src/images/qgis_shows_in_the_map.png
Normal file
BIN
docs/src/images/qgis_shows_in_the_map.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 173 KiB |
@ -1,48 +1,85 @@
|
||||
### Prerequisites
|
||||
|
||||
If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended.
|
||||
|
||||
### Binary Distributions
|
||||
|
||||
You can download martin from [GitHub releases page](https://github.com/maplibre/martin/releases).
|
||||
|
||||
| Platform | Downloads (latest) |
|
||||
|----------|------------------------|
|
||||
| Linux | [64-bit][rl-linux-tar] |
|
||||
| macOS | [64-bit][rl-macos-tar] |
|
||||
| Windows | [64-bit][rl-win64-zip] |
|
||||
|
||||
[rl-linux-tar]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-unknown-linux-gnu.tar.gz
|
||||
[rl-macos-tar]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-apple-darwin.tar.gz
|
||||
[rl-win64-zip]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-pc-windows-msvc.zip
|
||||
|
||||
### Building with Cargo
|
||||
|
||||
If you [install Rust](https://www.rust-lang.org/tools/install), you can build martin from source with Cargo:
|
||||
|
||||
```shell
|
||||
cargo install martin --locked
|
||||
martin --help
|
||||
```
|
||||
|
||||
### Homebrew
|
||||
|
||||
If you are using macOS and [Homebrew](https://brew.sh/) you can install martin using Homebrew tap.
|
||||
|
||||
```shell
|
||||
brew tap maplibre/martin
|
||||
brew install martin
|
||||
```
|
||||
If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended.
|
||||
|
||||
### Docker
|
||||
|
||||
Martin is also available as a [Docker image](https://ghcr.io/maplibre/martin). 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 or URLs to .pmtiles.
|
||||
Martin is also available as a [Docker image](https://ghcr.io/maplibre/martin). 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 or URLs to .pmtiles.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
### From Binary Distributions Manually
|
||||
|
||||
You can download martin from [GitHub releases page](https://github.com/maplibre/martin/releases).
|
||||
|
||||
| Platform | x64 | ARM-64 |
|
||||
|----------|--------------------------------------------------------------------------------------------------|-------------------------------------|
|
||||
| Linux | [.tar.gz][rl-linux-x64] (gnu)<br>[.tar.gz][rl-linux-x64-musl] (musl)<br>[.deb][rl-linux-x64-deb] | [.tar.gz][rl-linux-a64-musl] (musl) |
|
||||
| macOS | [.tar.gz][rl-macos-x64] | [.tar.gz][rl-macos-a64] |
|
||||
| Windows | [.zip][rl-win64-zip] | |
|
||||
|
||||
[rl-linux-x64]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-unknown-linux-gnu.tar.gz
|
||||
|
||||
[rl-linux-x64-musl]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-unknown-linux-musl.tar.gz
|
||||
|
||||
[rl-linux-x64-deb]: https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb
|
||||
|
||||
[rl-linux-a64-musl]: https://github.com/maplibre/martin/releases/latest/download/martin-aarch64-unknown-linux-musl.tar.gz
|
||||
|
||||
[rl-macos-x64]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-apple-darwin.tar.gz
|
||||
|
||||
[rl-macos-a64]: https://github.com/maplibre/martin/releases/latest/download/martin-aarch64-apple-darwin.tar.gz
|
||||
|
||||
[rl-win64-zip]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-pc-windows-msvc.zip
|
||||
|
||||
Rust users can install pre-built martin binary
|
||||
with [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) and `cargo`.
|
||||
|
||||
```bash
|
||||
cargo install cargo-binstall
|
||||
cargo binstall martin
|
||||
martin --help
|
||||
```
|
||||
|
||||
### From package
|
||||
|
||||
To install with apt source and others, We need your help
|
||||
to [improve packaging for various platforms](https://github.com/maplibre/martin/issues/578).
|
||||
|
||||
#### Homebrew
|
||||
|
||||
If you are using macOS and [Homebrew](https://brew.sh/) you can install martin using Homebrew tap.
|
||||
|
||||
```bash
|
||||
brew tap maplibre/martin
|
||||
brew install martin
|
||||
martin --help
|
||||
```
|
||||
|
||||
#### Debian Packages(x86_64) manually
|
||||
|
||||
```bash
|
||||
curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb
|
||||
sudo dpkg -i ./martin-Debian-x86_64.deb
|
||||
martin --help
|
||||
rm ./martin-Debian-x86_64.deb
|
||||
```
|
||||
|
||||
### Building From source
|
||||
|
||||
If you [install Rust](https://www.rust-lang.org/tools/install), you can build martin from source with Cargo:
|
||||
|
||||
```bash
|
||||
cargo install martin --locked
|
||||
martin --help
|
||||
```
|
||||
|
||||
9
docs/src/martin-as-a-library.md
Normal file
9
docs/src/martin-as-a-library.md
Normal file
@ -0,0 +1,9 @@
|
||||
# Martin as a library
|
||||
|
||||
Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features:
|
||||
|
||||
* **postgres** - enable PostgreSQL/PostGIS tile sources
|
||||
* **pmtiles** - enable PMTile tile sources
|
||||
* **mbtiles** - enable MBTile tile sources
|
||||
* **fonts** - enable font sources
|
||||
* **sprites** - enable sprite sources
|
||||
@ -1,14 +1,20 @@
|
||||
# Generating Tiles in Bulk
|
||||
|
||||
`martin-cp` is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. `martin-cp` can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. `martin-cp` supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources.
|
||||
`martin-cp` is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles
|
||||
into a new or an existing MBTiles file. `martin-cp` can be used to generate tiles for a large area or multiple areas (
|
||||
bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. `martin-cp` supports the
|
||||
same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources.
|
||||
|
||||
After copying, `martin-cp` will update the `agg_tiles_hash` metadata value unless `--skip-agg-tiles-hash` is specified. This allows the MBTiles file to be [validated](./mbtiles-validation.md#aggregate-content-validation) using `mbtiles validate` command.
|
||||
After copying, `martin-cp` will update the `agg_tiles_hash` metadata value unless `--skip-agg-tiles-hash` is specified.
|
||||
This allows the MBTiles file to be [validated](./mbtiles-validation.md#aggregate-content-validation)
|
||||
using `mbtiles validate` command.
|
||||
|
||||
## Usage
|
||||
|
||||
This copies tiles from a PostGIS table `my_table` into an MBTiles file `tileset.mbtiles` using [normalized](mbtiles-schema.md) schema, with zoom levels from 0 to 10, and bounds of the whole world.
|
||||
This copies tiles from a PostGIS table `my_table` into an MBTiles file `tileset.mbtiles`
|
||||
using [normalized](mbtiles-schema.md) schema, with zoom levels from 0 to 10, and bounds of the whole world.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
martin-cp --output-file tileset.mbtiles \
|
||||
--mbtiles-type normalized \
|
||||
"--bbox=-180,-90,180,90" \
|
||||
|
||||
@ -4,14 +4,14 @@
|
||||
|
||||
Copy command copies an mbtiles file, optionally filtering its content by zoom levels.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
mbtiles copy src_file.mbtiles dst_file.mbtiles \
|
||||
--min-zoom 0 --max-zoom 10
|
||||
```
|
||||
|
||||
This command can also be used to generate files of different [supported schema](mbtiles-schema.md).
|
||||
|
||||
```shell
|
||||
```bash
|
||||
mbtiles copy normalized.mbtiles dst.mbtiles \
|
||||
--dst-mbttype flat-with-hash
|
||||
```
|
||||
@ -20,7 +20,7 @@ mbtiles copy normalized.mbtiles dst.mbtiles \
|
||||
|
||||
This option is identical to using [`mbtiles diff ...`](mbtiles-diff.md). The following commands two are equivalent:
|
||||
|
||||
```shell
|
||||
```bash
|
||||
mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles
|
||||
|
||||
mbtiles copy file1.mbtiles diff.mbtiles \
|
||||
@ -29,9 +29,10 @@ mbtiles copy file1.mbtiles diff.mbtiles \
|
||||
|
||||
## `mbtiles copy --apply-patch`
|
||||
|
||||
Copy a source file to destination while also applying the diff file generated by `copy --diff-with-file` command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified.
|
||||
Copy a source file to destination while also applying the diff file generated by `copy --diff-with-file` command above
|
||||
to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
mbtiles copy src_file.mbtiles dst_file.mbtiles \
|
||||
--apply-patch diff.mbtiles
|
||||
```
|
||||
|
||||
@ -13,7 +13,7 @@ file to the original file, as the `agg_tiles_hash` value will be different after
|
||||
command will automatically rename the `agg_tiles_hash_after_apply` value back to `agg_tiles_hash` when applying the
|
||||
diff.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`.
|
||||
mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles
|
||||
|
||||
@ -41,7 +41,7 @@ Note that the `agg_tiles_hash_after_apply` metadata value will be renamed to `ag
|
||||
This is done to avoid confusion when applying the diff file to the original file, as the `agg_tiles_hash` value will be
|
||||
different after the diff is applied.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
mbtiles apply-patch src_file.mbtiles diff_file.mbtiles
|
||||
```
|
||||
|
||||
@ -53,7 +53,7 @@ from `diff_file.mbtiles` into `src_file.mbtiles`, where both files are of `flat`
|
||||
passed as a query parameter to the sqlite3 command line tool, and then used in the SQL statements. Note that this does
|
||||
not update the `agg_tiles_hash` metadata value, so it will be incorrect after the diff is applied.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
sqlite3 src_file.mbtiles \
|
||||
-bail \
|
||||
-cmd ".parameter set @diffDbFilename diff_file.mbtiles" \
|
||||
|
||||
@ -2,9 +2,11 @@
|
||||
|
||||
## summary
|
||||
|
||||
Use `mbtiles summary` to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level.
|
||||
Use `mbtiles summary` to get a summary of the contents of an MBTiles file. The command will print a table with the
|
||||
number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom
|
||||
level. The command will also print the bounding box of the covered area per zoom level.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles
|
||||
Schema: flat
|
||||
File size: 48.00KiB
|
||||
@ -24,24 +26,27 @@ Page count: 12
|
||||
|
||||
## meta-all
|
||||
|
||||
Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection.
|
||||
Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not
|
||||
stable, and should only be used for visual inspection.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
mbtiles meta-all my_file.mbtiles
|
||||
```
|
||||
|
||||
## meta-get
|
||||
|
||||
Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the `description` value from an mbtiles file:
|
||||
Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get
|
||||
the `description` value from an mbtiles file:
|
||||
|
||||
```shell
|
||||
```bash
|
||||
mbtiles meta-get my_file.mbtiles description
|
||||
```
|
||||
|
||||
## meta-set
|
||||
|
||||
Set metadata value by its name, or delete the key if no value is supplied. For example, to set the `description` value to `A vector tile dataset`:
|
||||
Set metadata value by its name, or delete the key if no value is supplied. For example, to set the `description` value
|
||||
to `A vector tile dataset`:
|
||||
|
||||
```shell
|
||||
```bash
|
||||
mbtiles meta-set my_file.mbtiles description "A vector tile dataset"
|
||||
```
|
||||
|
||||
@ -1,32 +1,47 @@
|
||||
# MBTiles Validation
|
||||
|
||||
The original [MBTiles specification](https://github.com/mapbox/mbtiles-spec#readme) does not provide any guarantees for the content of the tile data in MBTiles. `mbtiles validate` assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code.
|
||||
The original [MBTiles specification](https://github.com/mapbox/mbtiles-spec#readme) does not provide any guarantees for
|
||||
the content of the tile data in MBTiles. `mbtiles validate` assumes a few additional conventions and uses them to ensure
|
||||
that the content of the tile data is valid performing several validation steps. If the file is not valid, the command
|
||||
will print an error message and exit with a non-zero exit code.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
mbtiles validate src_file.mbtiles
|
||||
```
|
||||
|
||||
## SQLite Integrity check
|
||||
|
||||
The `validate` command will run `PRAGMA integrity_check` on the file, and will fail if the result is not `ok`. The `--integrity-check` flag can be used to disable this check, or to make it more thorough with `full` value. Default is `quick`.
|
||||
The `validate` command will run `PRAGMA integrity_check` on the file, and will fail if the result is not `ok`.
|
||||
The `--integrity-check` flag can be used to disable this check, or to make it more thorough with `full` value. Default
|
||||
is `quick`.
|
||||
|
||||
## Schema check
|
||||
|
||||
The `validate` command will verify that the `tiles` table/view exists, and that it has the expected columns and indexes. It will also verify that the `metadata` table/view exists, and that it has the expected columns and indexes.
|
||||
The `validate` command will verify that the `tiles` table/view exists, and that it has the expected columns and indexes.
|
||||
It will also verify that the `metadata` table/view exists, and that it has the expected columns and indexes.
|
||||
|
||||
## Per-tile validation
|
||||
|
||||
If the `.mbtiles` file uses [flat_with_hash](mbtiles-schema.md#flat-with-hash) or [normalized](mbtiles-schema.md#normalized) schema, the `validate` command will verify that the MD5 hash of the `tile_data` column matches the `tile_hash` or `tile_id` columns (depending on the schema).
|
||||
If the `.mbtiles` file uses [flat_with_hash](mbtiles-schema.md#flat-with-hash)
|
||||
or [normalized](mbtiles-schema.md#normalized) schema, the `validate` command will verify that the MD5 hash of
|
||||
the `tile_data` column matches the `tile_hash` or `tile_id` columns (depending on the schema).
|
||||
|
||||
A typical Normalized schema generated by tools like [tilelive-copy](https://github.com/mapbox/TileLive#bintilelive-copy) use MD5 hash in the `tile_id` column. The Martin's `mbtiles` tool can use this hash to verify the content of each tile. We also define a new [flat-with-hash](mbtiles-schema.md#flat-with-hash) schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout.
|
||||
A typical Normalized schema generated by tools like [tilelive-copy](https://github.com/mapbox/TileLive#bintilelive-copy)
|
||||
use MD5 hash in the `tile_id` column. The Martin's `mbtiles` tool can use this hash to verify the content of each tile.
|
||||
We also define a new [flat-with-hash](mbtiles-schema.md#flat-with-hash) schema that stores the hash and tile data in the
|
||||
same table, allowing per-tile validation without the multiple table layout.
|
||||
|
||||
Per-tile validation is not available for the `flat` schema, and will be skipped.
|
||||
|
||||
## Aggregate Content Validation
|
||||
|
||||
Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the `mbtiles` tool defines a new metadata value called `agg_tiles_hash`.
|
||||
Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as
|
||||
missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the `mbtiles` tool defines a
|
||||
new metadata value called `agg_tiles_hash`.
|
||||
|
||||
The value is computed by hashing the combined value for all rows in the `tiles` table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom `md5_concat_hex` function from [sqlite-hashes crate](https://crates.io/crates/sqlite-hashes):
|
||||
The value is computed by hashing the combined value for all rows in the `tiles` table/view, ordered by z,x,y. The value
|
||||
is computed using the following SQL expression, which uses a custom `md5_concat_hex` function
|
||||
from [sqlite-hashes crate](https://crates.io/crates/sqlite-hashes):
|
||||
|
||||
```sql, ignore
|
||||
md5_concat_hex(
|
||||
@ -36,6 +51,9 @@ md5_concat_hex(
|
||||
tile_data)
|
||||
```
|
||||
|
||||
In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if `tile_data` accidentally contains non-blob/text/null value, validation will fail.
|
||||
In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value
|
||||
type to be stored as in any column, so if `tile_data` accidentally contains non-blob/text/null value, validation will
|
||||
fail.
|
||||
|
||||
The `mbtiles` tool will compute `agg_tiles_hash` value when copying or validating mbtiles files. Use `--agg-hash update` to force the value to be updated, even if it is incorrect or does not exist.
|
||||
The `mbtiles` tool will compute `agg_tiles_hash` value when copying or validating mbtiles files. Use `--agg-hash update`
|
||||
to force the value to be updated, even if it is incorrect or does not exist.
|
||||
|
||||
24
docs/src/quick-start-linux.md
Normal file
24
docs/src/quick-start-linux.md
Normal file
@ -0,0 +1,24 @@
|
||||
## Quick start on Linux
|
||||
|
||||
```bash
|
||||
mkdir martin
|
||||
cd martin
|
||||
|
||||
# Download some sample data
|
||||
curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles
|
||||
|
||||
# Download the latest version of Martin binary, extract it, and make it executable
|
||||
curl -O https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-unknown-linux-gnu.tar.gz
|
||||
tar -xzf martin-x86_64-unknown-linux-gnu.tar.gz
|
||||
chmod +x ./martin
|
||||
|
||||
# Show Martin help screen
|
||||
./martin --help
|
||||
|
||||
# Run Martin with the sample data as the only tile source
|
||||
./martin world_cities.mbtiles
|
||||
```
|
||||
|
||||
### View the map
|
||||
|
||||
See [quick start with QGIS](quick-start-qgis.md) for instructions on how to view the map.
|
||||
27
docs/src/quick-start-macos.md
Normal file
27
docs/src/quick-start-macos.md
Normal file
@ -0,0 +1,27 @@
|
||||
## Quick start on macOS
|
||||
|
||||
1. Download some [demo tiles](https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles).
|
||||
|
||||
2. Download the latest version of Martin from
|
||||
the [release page](https://github.com/maplibre/martin/releases/latest/download).
|
||||
Use [about this Mac](https://support.apple.com/en-us/116943) to find your processors type.
|
||||
* Use [martin-x86_64-apple-darwin.tar.gz](https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-apple-darwin.tar.gz) for Intel
|
||||
* Use [martin-aarch64-apple-darwin.tar.gz](https://github.com/maplibre/martin/releases/latest/download/martin-aarch64-apple-darwin.tar.gz) for M1
|
||||
|
||||
3. Extract content of both files and place them in a same directory.
|
||||
|
||||
4. Open the command prompt and navigate to the directory where `martin` and `world_cities.mbtiles` are located.
|
||||
|
||||
5. Run the following command to start Martin with the demo data:
|
||||
|
||||
```bash
|
||||
# Show Martin help screen
|
||||
./martin --help
|
||||
|
||||
# Run Martin with the sample data as the only tile source
|
||||
./martin world_cities.mbtiles
|
||||
```
|
||||
|
||||
### View the map
|
||||
|
||||
See [quick start with QGIS](quick-start-qgis.md) for instructions on how to view the map.
|
||||
17
docs/src/quick-start-qgis.md
Normal file
17
docs/src/quick-start-qgis.md
Normal file
@ -0,0 +1,17 @@
|
||||
### View map with QGIS
|
||||
|
||||
1. Download, install, and run [QGIS](https://qgis.org/en/site/forusers/download.html) for your platform
|
||||
|
||||
2. Add a new `Vector Tiles` connection
|
||||
> 
|
||||
|
||||
3. In the `Vector Tile Connection` dialog, give it some name and the URL of the Martin server,
|
||||
e.g. `http://localhost:3000/martin/{z}/{x}/{y}.pbf` and click `OK`.
|
||||
> 
|
||||
|
||||
4. In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click
|
||||
on `Add Layer to Project`.
|
||||
> 
|
||||
|
||||
5. The map should now be visible in the QGIS map view.
|
||||
> 
|
||||
24
docs/src/quick-start-windows.md
Normal file
24
docs/src/quick-start-windows.md
Normal file
@ -0,0 +1,24 @@
|
||||
## Quick start on Windows
|
||||
|
||||
1. Download some [demo tiles](https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles).
|
||||
|
||||
2. Download the latest Windows version of Martin from
|
||||
the [release page](https://github.com/maplibre/martin/releases): []([martin-x86_64-pc-windows-msvc.zip](https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-pc-windows-msvc.zip)
|
||||
|
||||
3. Extract content of both files and place them in a same directory.
|
||||
|
||||
4. Open the command prompt and navigate to the directory where `martin` and `world_cities.mbtiles` are located.
|
||||
|
||||
5. Run the following command to start Martin with the demo data:
|
||||
|
||||
```bash
|
||||
# Show Martin help screen
|
||||
martin --help
|
||||
|
||||
# Run Martin with the sample data as the only tile source
|
||||
martin world_cities.mbtiles
|
||||
```
|
||||
|
||||
### View the map
|
||||
|
||||
See [quick start with QGIS](quick-start-qgis.md) for instructions on how to view the map.
|
||||
7
docs/src/quick-start.md
Normal file
7
docs/src/quick-start.md
Normal file
@ -0,0 +1,7 @@
|
||||
## Martin Quick Start Guide
|
||||
|
||||
Choose your operating system to get started with Martin tile server
|
||||
|
||||
* [Linux](quick-start-linux.md)
|
||||
* [macOS](quick-start-macos.md)
|
||||
* [Windows](quick-start-windows.md)
|
||||
@ -2,11 +2,15 @@
|
||||
|
||||
### Using with DigitalOcean PostgreSQL
|
||||
|
||||
You can use Martin with [Managed PostgreSQL from DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql/) with PostGIS extension
|
||||
You can use Martin
|
||||
with [Managed PostgreSQL from DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql/) with
|
||||
PostGIS extension
|
||||
|
||||
First, you need to download the CA certificate and get your cluster connection string from the [dashboard](https://cloud.digitalocean.com/databases). After that, you can use the connection string and the CA certificate to connect to the database
|
||||
First, you need to download the CA certificate and get your cluster connection string from
|
||||
the [dashboard](https://cloud.digitalocean.com/databases). After that, you can use the connection string and the CA
|
||||
certificate to connect to the database
|
||||
|
||||
```shell
|
||||
```bash
|
||||
martin --ca-root-file ./ca-certificate.crt \
|
||||
postgresql://user:password@host:port/db?sslmode=require
|
||||
```
|
||||
@ -15,13 +19,14 @@ martin --ca-root-file ./ca-certificate.crt \
|
||||
|
||||
You can use Martin with [Managed PostgreSQL from Heroku](https://www.heroku.com/postgres) with PostGIS extension
|
||||
|
||||
```shell
|
||||
```bash
|
||||
heroku pg:psql -a APP_NAME -c 'create extension postgis'
|
||||
```
|
||||
|
||||
Use the same environment variables as Heroku [suggests for psql](https://devcenter.heroku.com/articles/heroku-postgres-via-mtls#step-2-configure-environment-variables).
|
||||
Use the same environment variables as
|
||||
Heroku [suggests for psql](https://devcenter.heroku.com/articles/heroku-postgres-via-mtls#step-2-configure-environment-variables).
|
||||
|
||||
```shell
|
||||
```bash
|
||||
export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME)
|
||||
export PGSSLCERT=DIRECTORY/PREFIXpostgresql.crt
|
||||
export PGSSLKEY=DIRECTORY/PREFIXpostgresql.key
|
||||
@ -32,6 +37,6 @@ martin
|
||||
|
||||
You may also be able to validate SSL certificate with an explicit sslmode, e.g.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca"
|
||||
```
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
You can configure Martin using command-line interface. See `martin --help` or `cargo run -- --help` for more
|
||||
information.
|
||||
|
||||
```shell
|
||||
```text
|
||||
Usage: martin [OPTIONS] [CONNECTION]...
|
||||
|
||||
Arguments:
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
## Running with Docker Compose
|
||||
|
||||
You can use example [`docker-compose.yml`](https://raw.githubusercontent.com/maplibre/martin/main/docker-compose.yml) file as a reference
|
||||
You can use example [`docker-compose.yml`](https://raw.githubusercontent.com/maplibre/martin/main/docker-compose.yml)
|
||||
file as a reference
|
||||
|
||||
```yml
|
||||
services:
|
||||
@ -28,13 +29,13 @@ services:
|
||||
|
||||
First, you need to start `db` service
|
||||
|
||||
```shell
|
||||
```bash
|
||||
docker compose up -d db
|
||||
```
|
||||
|
||||
Then, after `db` service is ready to accept connections, you can start `martin`
|
||||
|
||||
```shell
|
||||
```bash
|
||||
docker compose up -d martin
|
||||
```
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@ You can use official Docker image [`ghcr.io/maplibre/martin`](https://ghcr.io/ma
|
||||
|
||||
### Using Non-Local PostgreSQL
|
||||
|
||||
```shell
|
||||
```bash
|
||||
docker run \
|
||||
-p 3000:3000 \
|
||||
-e DATABASE_URL=postgresql://postgres@postgres.example.org/db \
|
||||
@ -15,7 +15,7 @@ docker run \
|
||||
|
||||
You can expose local files to the Docker container using the `-v` flag.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
docker run \
|
||||
-p 3000:3000 \
|
||||
-v /path/to/local/files:/files \
|
||||
@ -24,11 +24,13 @@ docker run \
|
||||
|
||||
### Accessing Local PostgreSQL on Linux
|
||||
|
||||
If you are running PostgreSQL instance on `localhost`, you have to change network settings to allow the Docker container to access the `localhost` network.
|
||||
If you are running PostgreSQL instance on `localhost`, you have to change network settings to allow the Docker container
|
||||
to access the `localhost` network.
|
||||
|
||||
For Linux, add the `--net=host` flag to access the `localhost` PostgreSQL service. You would not need to export ports with `-p` because the container is already using the host network.
|
||||
For Linux, add the `--net=host` flag to access the `localhost` PostgreSQL service. You would not need to export ports
|
||||
with `-p` because the container is already using the host network.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
docker run \
|
||||
--net=host \
|
||||
-e DATABASE_URL=postgresql://postgres@localhost/db \
|
||||
@ -39,7 +41,7 @@ docker run \
|
||||
|
||||
For macOS, use `host.docker.internal` as hostname to access the `localhost` PostgreSQL service.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
docker run \
|
||||
-p 3000:3000 \
|
||||
-e DATABASE_URL=postgresql://postgres@host.docker.internal/db \
|
||||
@ -50,7 +52,7 @@ docker run \
|
||||
|
||||
For Windows, use `docker.for.win.localhost` as hostname to access the `localhost` PostgreSQL service.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
docker run \
|
||||
-p 3000:3000 \
|
||||
-e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \
|
||||
|
||||
@ -1,9 +1,12 @@
|
||||
# Usage
|
||||
|
||||
Martin requires at least one PostgreSQL [connection string](pg-connections.md) or a [tile source file](sources-files.md) as a command-line argument. A PG connection string can also be passed via the `DATABASE_URL` environment variable.
|
||||
Martin requires at least one PostgreSQL [connection string](pg-connections.md) or a [tile source file](sources-files.md)
|
||||
as a command-line argument. A PG connection string can also be passed via the `DATABASE_URL` environment variable.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
martin postgresql://postgres@localhost/db
|
||||
```
|
||||
|
||||
Martin provides [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint for each [geospatial-enabled](https://postgis.net/docs/using_postgis_dbmanagement.html#geometry_columns) table in your database.
|
||||
Martin provides [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint for
|
||||
each [geospatial-enabled](https://postgis.net/docs/using_postgis_dbmanagement.html#geometry_columns) table in your
|
||||
database.
|
||||
|
||||
@ -1,14 +1,16 @@
|
||||
## Composite Sources
|
||||
|
||||
Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma `{source1},...,{sourceN}`
|
||||
Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by
|
||||
comma `{source1},...,{sourceN}`
|
||||
|
||||
Each source in a composite source can be accessed with its `{source_name}` as a `source-layer` property.
|
||||
|
||||
Composite source [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint is available at `/{source1},...,{sourceN}`, and tiles are available at `/{source1},...,{sourceN}/{z}/{x}/{y}`.
|
||||
Composite source [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint is available
|
||||
at `/{source1},...,{sourceN}`, and tiles are available at `/{source1},...,{sourceN}/{z}/{x}/{y}`.
|
||||
|
||||
For example, composite source combining `points` and `lines` sources will be available at `/points,lines/{z}/{x}/{y}`
|
||||
|
||||
```shell
|
||||
```bash
|
||||
# TileJSON
|
||||
curl localhost:3000/points,lines
|
||||
|
||||
|
||||
@ -1,9 +1,12 @@
|
||||
## MBTiles and PMTiles File Sources
|
||||
|
||||
Martin can serve any type of tiles from [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new) and [MBTile](https://github.com/mapbox/mbtiles-spec) files. To serve a file from CLI, simply put the path to the file or the directory with `*.mbtiles` or `*.pmtiles` files. A path to PMTiles file may be a URL. For example:
|
||||
Martin can serve any type of tiles from [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new)
|
||||
and [MBTile](https://github.com/mapbox/mbtiles-spec) files. To serve a file from CLI, simply put the path to the file or
|
||||
the directory with `*.mbtiles` or `*.pmtiles` files. A path to PMTiles file may be a URL. For example:
|
||||
|
||||
```shell
|
||||
```bash
|
||||
martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles
|
||||
```
|
||||
|
||||
You may also want to generate a [config file](config-file.md) using the `--save-config my-config.yaml`, and later edit it and use it with `--config my-config.yaml` option.
|
||||
You may also want to generate a [config file](config-file.md) using the `--save-config my-config.yaml`, and later edit
|
||||
it and use it with `--config my-config.yaml` option.
|
||||
|
||||
@ -1,11 +1,14 @@
|
||||
## Font Sources
|
||||
|
||||
Martin can serve glyph ranges from `otf`, `ttf`, and `ttc` fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly.
|
||||
Martin can serve glyph ranges from `otf`, `ttf`, and `ttc` fonts as needed by MapLibre text rendering. Martin will
|
||||
generate them dynamically on the fly.
|
||||
The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation.
|
||||
|
||||
## API
|
||||
|
||||
Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces.
|
||||
Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are
|
||||
case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font
|
||||
names as they usually contain spaces.
|
||||
|
||||
| | Font Request |
|
||||
|---------|--------------------------------------|
|
||||
@ -14,7 +17,9 @@ Fonts ranges are available either for a single font, or a combination of multipl
|
||||
|
||||
### Composite Font Request
|
||||
|
||||
When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph.
|
||||
When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback
|
||||
to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the
|
||||
fonts contain the glyph.
|
||||
|
||||
| | Composite Font Request with fallbacks |
|
||||
|---------|--------------------------------------------------------------|
|
||||
@ -25,7 +30,7 @@ When combining multiple fonts, the glyph range will contain glyphs from the firs
|
||||
|
||||
Martin will show all available fonts at the `/catalog` endpoint.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
curl http://127.0.0.1:3000/catalog
|
||||
{
|
||||
"fonts": {
|
||||
@ -58,7 +63,7 @@ curl http://127.0.0.1:3000/catalog
|
||||
|
||||
A font file or directory can be configured from the [CLI](run-with-cli.md) with one or more `--font` parameters.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
martin --font /path/to/font/file.ttf --font /path/to/font_dir
|
||||
```
|
||||
|
||||
|
||||
@ -1,6 +1,11 @@
|
||||
## PostgreSQL Function Sources
|
||||
|
||||
Function Source is a database function which can be used to query [vector tiles](https://github.com/mapbox/vector-tile-spec). When started, Martin will look for the functions with a suitable signature. A function that takes `z integer` (or `zoom integer`), `x integer`, `y integer`, and an optional `query json` and returns `bytea`, can be used as a Function Source. Alternatively the function could return a record with a single `bytea` field, or a record with two fields of types `bytea` and `text`, where the `text` field is an etag key (i.e. md5 hash).
|
||||
Function Source is a database function which can be used to
|
||||
query [vector tiles](https://github.com/mapbox/vector-tile-spec). When started, Martin will look for the functions with
|
||||
a suitable signature. A function that takes `z integer` (or `zoom integer`), `x integer`, `y integer`, and an
|
||||
optional `query json` and returns `bytea`, can be used as a Function Source. Alternatively the function could return a
|
||||
record with a single `bytea` field, or a record with two fields of types `bytea` and `text`, where the `text` field is
|
||||
an etag key (i.e. md5 hash).
|
||||
|
||||
| Argument | Type | Description |
|
||||
|----------------------------|---------|-------------------------|
|
||||
@ -11,7 +16,8 @@ Function Source is a database function which can be used to query [vector tiles]
|
||||
|
||||
### Simple Function
|
||||
|
||||
For example, if you have a table `table_source` in WGS84 (`4326` SRID), then you can use this function as a Function Source:
|
||||
For example, if you have a table `table_source` in WGS84 (`4326` SRID), then you can use this function as a Function
|
||||
Source:
|
||||
|
||||
```sql, ignore
|
||||
CREATE OR REPLACE
|
||||
@ -63,15 +69,18 @@ END
|
||||
$$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
|
||||
```
|
||||
|
||||
The `query_params` argument is a JSON representation of the tile request query params. Query params could be passed as simple query values, e.g.
|
||||
The `query_params` argument is a JSON representation of the tile request query params. Query params could be passed as
|
||||
simple query values, e.g.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
curl localhost:3000/function_zxy_query/0/0/0?token=martin
|
||||
```
|
||||
|
||||
You can also use [urlencoded](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) params to encode complex values:
|
||||
You can also
|
||||
use [urlencoded](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)
|
||||
params to encode complex values:
|
||||
|
||||
```shell
|
||||
```bash
|
||||
curl \
|
||||
--data-urlencode 'arrayParam=[1, 2, 3]' \
|
||||
--data-urlencode 'numberParam=42' \
|
||||
@ -101,7 +110,11 @@ You can access this params using [json operators](https://www.postgresql.org/doc
|
||||
|
||||
### Modifying TileJSON
|
||||
|
||||
Martin will automatically generate a basic [TileJSON](https://github.com/mapbox/tilejson-spec) manifest for each function source that will contain the name and description of the function, plus optionally `minzoom`, `maxzoom`, and `bounds` (if they were specified via one of the configuration methods). For example, if there is a function `public.function_zxy_query_jsonb`, the default `TileJSON` might look like this (note that URL will be automatically adjusted to match the request host):
|
||||
Martin will automatically generate a basic [TileJSON](https://github.com/mapbox/tilejson-spec) manifest for each
|
||||
function source that will contain the name and description of the function, plus optionally `minzoom`, `maxzoom`,
|
||||
and `bounds` (if they were specified via one of the configuration methods). For example, if there is a
|
||||
function `public.function_zxy_query_jsonb`, the default `TileJSON` might look like this (note that URL will be
|
||||
automatically adjusted to match the request host):
|
||||
|
||||
```json
|
||||
{
|
||||
@ -116,9 +129,12 @@ Martin will automatically generate a basic [TileJSON](https://github.com/mapbox/
|
||||
|
||||
#### TileJSON in SQL Comments
|
||||
|
||||
To modify automatically generated `TileJSON`, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated `TileJSON` using [JSON Merge patch](https://www.rfc-editor.org/rfc/rfc7386). The following example adds `attribution` and `version` fields to the `TileJSON`.
|
||||
To modify automatically generated `TileJSON`, you can add a valid JSON as an SQL comment on the function. Martin will
|
||||
merge function comment into the generated `TileJSON` using [JSON Merge patch](https://www.rfc-editor.org/rfc/rfc7386).
|
||||
The following example adds `attribution` and `version` fields to the `TileJSON`.
|
||||
|
||||
**Note:** This example uses `EXECUTE` to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments.
|
||||
**Note:** This example uses `EXECUTE` to ensure that the comment is a valid JSON (or else PostgreSQL will throw an
|
||||
error). You can use other methods of creating SQL comments.
|
||||
|
||||
```sql
|
||||
DO $do$ BEGIN
|
||||
|
||||
@ -1,20 +1,28 @@
|
||||
## Sprite Sources
|
||||
|
||||
Given a directory with SVG images, Martin will generate a sprite -- a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. `icons/bicycle.svg` will be available as `icons/bicycle` sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation.
|
||||
Given a directory with SVG images, Martin will generate a sprite -- a JSON index and a PNG image, for both low and high
|
||||
resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched
|
||||
recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs,
|
||||
e.g. `icons/bicycle.svg` will be available as `icons/bicycle` sprite image. The sprite generation is not yet cached, and
|
||||
may require external reverse proxy or CDN for faster operation.
|
||||
|
||||
### API
|
||||
|
||||
Martin uses [MapLibre sprites API](https://maplibre.org/maplibre-style-spec/sprite/) specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately.
|
||||
Martin uses [MapLibre sprites API](https://maplibre.org/maplibre-style-spec/sprite/) specification to serve sprites via
|
||||
several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the
|
||||
changes will be reflected immediately.
|
||||
|
||||
##### Sprite PNG
|
||||
|
||||
|
||||
|
||||
`GET /sprite/<sprite_id>.png` endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at `GET /sprite/<sprite_id>@2x.png`.
|
||||
`GET /sprite/<sprite_id>.png` endpoint contains a single PNG sprite image that combines all sources images.
|
||||
Additionally, there is a high DPI version available at `GET /sprite/<sprite_id>@2x.png`.
|
||||
|
||||
##### Sprite index
|
||||
|
||||
`/sprite/<sprite_id>.json` metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at `/sprite/<sprite_id>@2x.json`.
|
||||
`/sprite/<sprite_id>.json` metadata index describing the position and size of each image inside the sprite. Just like
|
||||
the PNG, there is a high DPI version available at `/sprite/<sprite_id>@2x.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -31,19 +39,25 @@ Martin uses [MapLibre sprites API](https://maplibre.org/maplibre-style-spec/spri
|
||||
|
||||
#### Combining Multiple Sprites
|
||||
|
||||
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>`. No ID renaming is done, so identical sprite names will override one another.
|
||||
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>`. No ID renaming is done, so identical sprite names will
|
||||
override one another.
|
||||
|
||||
### Configuring from CLI
|
||||
|
||||
A sprite directory can be configured from the CLI with the `--sprite` flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory -- in the example below, the sprites will be available at `/sprite/sprite_a` and `/sprite/sprite_b`. Use `--save-config` to save the configuration to the config file.
|
||||
A sprite directory can be configured from the CLI with the `--sprite` flag. The flag can be used multiple times to
|
||||
configure multiple sprite directories. The name of the sprite will be the name of the directory -- in the example below,
|
||||
the sprites will be available at `/sprite/sprite_a` and `/sprite/sprite_b`. Use `--save-config` to save the
|
||||
configuration to the config file.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b
|
||||
```
|
||||
|
||||
### Configuring with Config File
|
||||
|
||||
A sprite directory can be configured from the config file with the `sprite` key, similar to how [MBTiles and PMTiles](config-file.md) are configured.
|
||||
A sprite directory can be configured from the config file with the `sprite` key, similar to
|
||||
how [MBTiles and PMTiles](config-file.md) are configured.
|
||||
|
||||
```yaml
|
||||
# Sprite configuration
|
||||
|
||||
@ -1,17 +1,20 @@
|
||||
## Troubleshooting
|
||||
|
||||
Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the `RUST_LOG` environment variable. The value of this environment variable is a comma-separated list of logging directives.
|
||||
Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is
|
||||
controlled via the `RUST_LOG` environment variable. The value of this environment variable is a comma-separated list of
|
||||
logging directives.
|
||||
|
||||
This will enable debug logging for all modules:
|
||||
|
||||
```shell
|
||||
```bash
|
||||
export RUST_LOG=debug
|
||||
martin postgresql://postgres@localhost/db
|
||||
```
|
||||
|
||||
While this will only enable verbose logging for the `actix_web` module and enable debug logging for the `martin` and `tokio_postgres` modules:
|
||||
While this will only enable verbose logging for the `actix_web` module and enable debug logging for the `martin`
|
||||
and `tokio_postgres` modules:
|
||||
|
||||
```shell
|
||||
```bash
|
||||
export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug
|
||||
martin postgresql://postgres@localhost/db
|
||||
```
|
||||
|
||||
@ -17,11 +17,14 @@ Martin data is available via the HTTP `GET` endpoints:
|
||||
|
||||
### Duplicate Source ID
|
||||
|
||||
In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as `/points`, `/points.1`, etc.
|
||||
In case there is more than one source that has the same name, e.g. a PG function is available in two
|
||||
schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such
|
||||
as `/points`, `/points.1`, etc.
|
||||
|
||||
### Reserved Source IDs
|
||||
|
||||
Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a `catalog` source will become `catalog.1`.
|
||||
Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID
|
||||
the same way as duplicate source IDs are handled, e.g. a `catalog` source will become `catalog.1`.
|
||||
|
||||
Some of the reserved IDs: `_`, `catalog`, `config`, `font`, `health`, `help`, `index`, `manifest`, `metrics`, `refresh`,
|
||||
`reload`, `sprite`, `status`.
|
||||
@ -30,7 +33,7 @@ Some of the reserved IDs: `_`, `catalog`, `config`, `font`, `health`, `help`, `i
|
||||
|
||||
A list of all available sources is available via catalogue endpoint:
|
||||
|
||||
```shell
|
||||
```bash
|
||||
curl localhost:3000/catalog | jq
|
||||
```
|
||||
|
||||
@ -73,9 +76,10 @@ curl localhost:3000/catalog | jq
|
||||
|
||||
All tile sources have a [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint available at the `/{SourceID}`.
|
||||
|
||||
For example, a `points` function or a table will be available as `/points`. Composite source combining `points` and `lines` sources will be available at `/points,lines` endpoint.
|
||||
For example, a `points` function or a table will be available as `/points`. Composite source combining `points`
|
||||
and `lines` sources will be available at `/points,lines` endpoint.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
curl localhost:3000/points | jq
|
||||
curl localhost:3000/points,lines | jq
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user