DOCSEARCHbyAlgolia
Submit Docs

t-rex vector tile server

repository·master·Indexed 20 days ago

https://github.com/t-rex-tileserver/t-rex

A vector tile server specialized in publishing Mapbox Vector Tiles (MVT) from PostGIS databases or GDAL vector formats. It supports automatic layer detection, custom tile grids, and automatic reprojection. Features include a CLI for serving tiles, configuration via TOML, and support for local file or S3 caching. Note: t-rex is no longer maintained and has been replaced by bbox-tile-server.

Tokens
13.7K
Snippets
56
Records
72
Agent score
69%

What's inside t-rex

  1. Quick start: Serve vector tiles from a PostGIS database

    master

    To start serving vector tiles immediately from a PostgreSQL/PostGIS database, use the serve command with the --dbconn flag.

    Tiles are served at the following URL pattern: http://localhost:6767/{layer}/{z}/{x}/{y}.pbf

    You can view a list of all detected layers at http://localhost:6767/.

    t_rex serve --dbconn postgresql://user:pass@localhost/osm2vectortiles

  4. Understand MVT Command and Parameter encoding

    master

    MVT encoding relies on two specific integer types to represent geometry instructions and their coordinates:

    1. CommandInteger: Encodes a command ID and the number of subsequent parameters. The command ID is stored in the lower 3 bits, and the count is shifted left by 3 bits.

      • MoveTo (ID: 1)
      • LineTo (ID: 2)
      • ClosePath (ID: 7)

    2. ParameterInteger: Encodes the actual coordinate deltas. These are ZigZag encoded to allow for efficient representation of signed integers (deltas) within an unsigned 32-bit integer format.

    When building a CommandSequence manually, you must push a CommandInteger followed by the required number of ParameterInteger values.

  5. Manage multiple datasources via the Datasources collection

    master

    The Datasources struct manages a collection of named Datasource instances. You can define multiple datasources in your application configuration.

    • Naming: Each datasource can have an optional name. If no name is provided, it defaults to <noname>.
    • Default Datasource: You can designate one datasource as the default by setting default = true in its configuration. If no default is specified, the first datasource in the collection is used as the default.
    • Accessing Datasources: You can retrieve a specific datasource by its name or fall back to the default datasource.
    [[datasource]]
name = "primary"
dbconn = "postgresql://localhost/db"
default = true

[[datasource]]
name = "secondary"
path = "/data/map.gpkg"

  6. Use zoom-level specific queries in a Layer

    master

    To optimize performance, you can provide a list of LayerQuery objects for a single layer. Each query is valid for a specific zoom range (minzoom to maxzoom). When a tile is requested at a specific zoom level, t-rex will select the most specific query that matches that level.

    Each LayerQuery can define:

    • minzoom: The starting zoom level.
    • maxzoom: The ending zoom level.
    • simplify: A boolean to enable/disable simplification for this zoom range.
    • tolerance: A specific simplification tolerance for this zoom range.
    • sql: A custom SQL string to fetch data for this zoom range.
    [[tileset.layer.query]]
minzoom = 0
maxzoom = 10
sql = "SELECT name, wkb_geometry FROM mytable WHERE complex_logic = true"

[[tileset.layer.query]]
minzoom = 11
maxzoom = 22
sql = "SELECT name, wkb_geometry FROM mytable"

  7. How GDAL layers are detected

    master

    When t-rex connects to a GDAL datasource, it scans the dataset for layers. For every geometry field found within a GDAL layer, a new t-rex layer is created.

    If a GDAL layer contains multiple geometry fields, they are assigned unique table names in the format {original_layer_name}_{index} (e.g., layer_0, layer_1) to allow them to be treated as distinct layers in the tileserver.

  9. Use PostGIS query parameters in SQL templates

    master

    When writing custom SQL queries for a PostGIS datasource in t-rex, you can use special placeholders that the server will automatically replace with appropriate PostGIS functions and parameters. This allows for dynamic spatial filtering and zoom-dependent logic.

    Supported placeholders:

    • !bbox!: Replaced with a spatial envelope (e.g., ST_MakeEnvelope(...)) to filter features within the requested tile extent.
    • !zoom!: Replaced with the current zoom level as a numeric parameter (e.g., $n).
    • !pixel_width!: Replaced with the pixel width of the tile, cast to FLOAT8 (e.g., $n::FLOAT8).
    • !scale_denominator!: Replaced with the scale denominator, cast to FLOAT8 (e.g., $n::FLOAT8).

    Note that !bbox! is handled specially by being replaced with an envelope expression, while the others are replaced with positional SQL parameters (like $1, $2) to prevent SQL injection.

    -- Example of a custom query using placeholders
SELECT id, name, geom 
FROM my_table 
WHERE geom && !bbox! 
AND ST_Area(geom) > !pixel_width! * 0.1;
-- The server will transform this into a parameterized query using ST_MakeEnvelope and numeric parameters.

  10. Use MvtService for Mapbox Vector Tile serving

    master

    The MvtService is the core component for serving Mapbox Vector Tiles (MVT). It manages datasources, tilesets, and a tile cache. Developers can use it to retrieve tiles directly or seed a tile cache for high-performance serving.

    Key lifecycle steps for using MvtService:

    1. Initialize: Create the service from an ApplicationCfg using from_config.
    2. Connect: Call .connect() to establish connections to all configured datasources (required for PostGIS).
    3. Prepare: Call .prepare_feature_queries() to prepare datasource queries before requesting tiles.
    4. Serve: Use .tile_cached() to fetch tiles with cache support or .tile() for raw tile generation.
    // Example conceptual workflow
let mut service = MvtService::from_config(&app_cfg).map_err(|e| e)?;
service.connect();
service.prepare_feature_queries();

// Fetch a cached tile
let tile_data = service.tile_cached("my_tileset", x, y, zoom, true, None);

  11. Configure t-rex via a configuration file

    master

    You can initialize the t-rex webserver using a configuration file by providing the --config argument. When a configuration file is used, other direct connection arguments like --dbconn, --datasource, or --qgs are ignored. The server will attempt to read the file and exit with an error if it cannot be parsed or read.

    # Example of running with a config file
t-rex --config /path/to/your/config.toml

  12. Run S3 tests

    master

    Unit tests requiring an S3 connection are skipped by default. To run them:

    1. Start a local S3 instance using MinIO via Docker:
      docker run -d --rm -p 9000:9000 -e MINIO_REGION_NAME=my-region -e MINIO_ACCESS_KEY=miniostorage -e MINIO_SECRET_KEY=miniostorage minio/minio server /data && sleep 5 && mc config host add local-docker http://localhost:9000 miniostorage miniostorage && mc mb local-docker/trex && mc policy set download local-docker/trex
    2. Set the S3TEST environment variable to true:
      export S3TEST=true
    3. Run the tests with all features enabled:
      cargo test --all-features --all -- --ignored