chiitiler - The Tiny MapLibre Server

generated by DALL-E

chii-tiler: "tiny" in Japanese is "chiisai", shorten into "chii"

motivation

• In this type of server, there is a de-facto - maptiler/tileserver-gl, but this is too big for me.
• I want a server accept style.json-url and respond raster tile, inspired by developmentseed/titiler

features

/tiles

chiitiler provides you with an endpoint /tiles. Once server launched, you can use the endpoint like this:

http://localhost:3000/tiles/0/0/0.png?url=https://tile.openstreetmap.jp/styles/osm-bright/style.json
http://localhost:3000/tiles/0/0/0.webp?margin=100&url=https://tile.openstreetmap.jp/styles/maptiler-toner-en/style.json
http://localhost:3000/tiles/1/1/1.jpg?tileSize=256&quality=80&url=https://tile.openstreetmap.jp/styles/osm-bright/style.json

/clip.png|webp|jpg|jpeg

chiitiler provides you with /clip.png|webp|jpg|jpeg endpoint. Once server launched, you can use like this:

# default size is 1024, this is longer axis and shorter axis is calculated by aspect ratio
http://localhost:3000/clip.png?bbox=100,30,150,60&url=https://path/to/style.json
# specify size
http://localhost:3000/clip.png?bbox=100,30,150,6&size=512&url=https://path/to/style.json
# specify quality
http://localhost:3000/clip.png?bbox=100,30,150,6&size=512&quality=80&url=https://path/to/style.json

POST endpoint

Each endpoint also supports POST method. You can pass style.json as a body. (then, url parameter is not needed)

architecture

graph LR
    subgraph sources
        direction LR
        A[style.json]
        z/x/y.pbf
        z/x/y.png/webp/jpg
        sprite
        glyphs
    end

    subgraph chiitiler
        cache
        render
        server
    end

sources --> cache --> render --> server --/tiles/z/x/y--> png/webp/jpg

cache <--get/set--> memory/file/S3

Loading

usage

Container Image

docker pull ghcr.io/kanahiro/chiitiler
docker run -p 3000:3000 ghcr.io/kanahiro/chiitiler # -> tile-server

# recommended: you can use environment variables
docker run -p 3000:3000 -d \
-e CHIITILER_CACHE_METHOD=s3 \
-e CHIITILER_S3CACHE_BUCKET=bucketname \
-e CHIITILER_S3_REGION=ap-northeast-1 \
ghcr.io/kanahiro/chiitiler

# you also can pass options
docker run -p 8000:8000 ghcr.io/kanahiro/chiitiler tile-server -p 8000 -c s3 -s3b bucketname -s3r ap-northeast-1

Environment Variables

you can pass server options via environment variables

env var	default	description
CHIITILER_PORT	3000	port number
CHIITILER_PROCESSES	1	num of chiitiler processes. 0 means all-CPUs
CHIITILER_DEBUG	false	debug mode
CHIITILER_STREAM_MODE	false	stream mode
CHIITILER_CACHE_METHOD	none	cache method, none, memory, file or s3
CHIITILER_CACHE_TTL_SEC	3600	cache ttl, effect to memory and file
CHIITILER_MEMORYCACHE_MAXITEMCOUNT	1000	max items for memorycache
CHIITILER_FILECACHE_DIR	.cache	filecache directory
CHIITILER_S3CACHE_BUCKET		s3cache bucket name
CHIITILER_S3_REGION	us-east1	s3 bucket region for caching/fetching
CHIITILER_S3_ENDPOINT		s3 endpoint for caching/fetching
CHIITILER_S3_FORCE_PATH_STYLE	false	force path style for s3, needed for minio

CLI (deprecated)

• Node.js v18 or v20

npm install
npm run build
node dist/main.js tile-server
# running server: http://localhost:3000

# develop
npm run dev
# running server: http://localhost:3000
# debug page: http://localhost:3000/debug

options

node dist/main.js tile-server -p 8000 -c file -ctl 60 -fcd cachedir -D
# -p: port number
# -c: cache method
# -ctl: cache ttl
# -fcd: cache directory
# -D: debug mode

node dist/main.js tile-server -c memory -ctl 60 -mci 1000
# -mci: max cache items

node dist/main.js tile-server -c s3 -s3b chiitiler -s3r ap-northeast-1
# -s3b: S3 bucket name for cache
# -s3r: S3 bucket region
# caution: TTL is not supported in S3 cache, please utilize S3 lifecycle policy

debug page

• in debug mode, you can access:
  • debug page: http://localhost:3000/debug
    • You can pass style.json url: http://localhost:3000/debug?url=https://tile.openstreetmap.jp/styles/osm-bright/style.json
  • editor page: http://localhost:3000/editor

supported protocols in style.json

• http:// or https:// protocol are used in Style Specification
• In addition, chiitiler supports following protocols:
  • s3:// for S3 bucket
  • file:// for file system
  • mbtiles:// for MBTIles files
  • pmtiles:// for PMTiles, remote or local or s3
  • cog:// experimental, for Cloud Optimized GeoTIFF. CRS must be EPSG:3857.
• Only when http:// and https:// chiitiler cache them with a method you specified.

example

./localdata/style.json

{
  "version": "8",
  "sources": {
    "dir": {
      "type": "vector",
      "tiles": [
        "file://localdata/tiles/{z}/{x}/{y}.pbf"
      ],
      "maxzoom": 6
    },
    "mbtiles": {
      "type": "vector",
      "tiles": [
        "mbtiles://localdata/school.mbtiles/{z}/{x}/{y}"
      ],
      "maxzoom": 10
    },
    "pmtiles": {
      "type": "vector",
      "tiles": [
        "pmtiles://localdata/school.pmtiles/{z}/{x}/{y}"
      ],
      "maxzoom": 10
    },
    "s3": {
      "type": "vector",
      "tiles": [
        "s3://tiles/{z}/{x}/{y}.pbf"
      ],
      "maxzoom": 6
    },
    "cog": {
      "type": "raster",
      "tiles": [
        "cog://https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/54/T/WN/2024/9/S2A_54TWN_20240908_0_L2A/TCI.tif/{z}/{x}/{y}"
      ],
      "tileSize": 256
    }
  },
  "layers": [
    {
      "id": "dir",
      "source": "dir",
      "source-layer": "P2921",
      "type": "circle",
      "paint": {
        "circle-radius": 10,
        "circle-color": "red"
      }
    },
    {
      "id": "mbtiles",
      "source": "mbtiles",
      "source-layer": "P2921",
      "type": "circle",
      "paint": {
        "circle-radius": 7,
        "circle-color": "blue"
      }
    },
    {
      "id": "pmtiles",
      "source": "pmtiles",
      "source-layer": "P2921",
      "type": "circle",
      "paint": {
        "circle-radius": 5,
        "circle-color": "yellow"
      }
    },
    {
      "id": "s3",
      "source": "s3",
      "source-layer": "P2921",
      "type": "circle",
      "paint": {
        "circle-radius": 3,
        "circle-color": "green"
      }
    },
    {
      "id": "cog",
      "source": "cog",
      "type": "raster",
      "paint": {
        "raster-opacity": 0.5
      }
    }
  ]
}

Library Mode

• chiitiler can be used as a library to render MapLibre Style.
• methods to render MapLibre Style are exposed from chiitiler package.

installation

npm install chiitiler

• chiitiler requires some dependencies in runtime, you can find them in Dockerfile

Usage

import {
    getRenderedBboxBuffer,
    getRenderedTileBuffer,
    ChiitilerCache
} from 'chiitiler';

const s3Cache = ChiitilerCache.s3Cache({
    bucket: 'chiitiler',
    region: 'ap-northeast-1',
    endpoint: null,
});
// credentials are loaded from environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY

const tileBuf = await getRenderedTileBuffer({
    stylejson: 'https://example.com/style.json', // or StyleSpecification object
    z: 0,
    x: 0,
    y: 0,
    tileSize: 512,
    ext: 'webp', // png, webp, jpg
    cache: s3Cache,
    quality: 80,
    margin: 0,
});

const bboxBuf = await getRenderedBboxBuffer({
    stylejson: 'file://path/to/style.json', // or StyleSpecification object
    bbox: [123.4, 34.5, 124.5, 35.6],
    size: 1024,
    cache: s3Cache,
    ext: 'webp',
    quality: 80,
});

// return value is Buffer - binary of each image

development

• run docker compose up