{"id":14611245,"url":"https://github.com/Kanahiro/chiitiler","last_synced_at":"2025-09-06T03:32:24.149Z","repository":{"id":193885962,"uuid":"689648474","full_name":"Kanahiro/chiitiler","owner":"Kanahiro","description":"Lightweight Raster Tile Server for MapLibre Style Specification","archived":false,"fork":false,"pushed_at":"2025-06-15T02:15:38.000Z","size":19454,"stargazers_count":74,"open_issues_count":6,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-15T03:22:33.329Z","etag":null,"topics":["foss4g","maplibre","nodejs","raster-tiles","serverless","typescript","vector-tiles"],"latest_commit_sha":null,"homepage":"https://spatialty-io.github.io/chiitiler-demo","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kanahiro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["Kanahiro"]}},"created_at":"2023-09-10T13:33:11.000Z","updated_at":"2025-06-15T02:15:41.000Z","dependencies_parsed_at":"2024-05-23T09:40:33.311Z","dependency_job_id":"bc0f8755-be39-4601-9cc5-13091c1ea204","html_url":"https://github.com/Kanahiro/chiitiler","commit_stats":null,"previous_names":["kanahiro/chiitiler"],"tags_count":53,"template":false,"template_full_name":null,"purl":"pkg:github/Kanahiro/chiitiler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanahiro%2Fchiitiler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanahiro%2Fchiitiler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanahiro%2Fchiitiler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanahiro%2Fchiitiler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kanahiro","download_url":"https://codeload.github.com/Kanahiro/chiitiler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanahiro%2Fchiitiler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273853214,"owners_count":25179803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["foss4g","maplibre","nodejs","raster-tiles","serverless","typescript","vector-tiles"],"created_at":"2024-09-09T02:00:33.740Z","updated_at":"2025-09-06T03:32:24.140Z","avatar_url":"https://github.com/Kanahiro.png","language":"TypeScript","funding_links":["https://github.com/sponsors/Kanahiro"],"categories":["Tile Servers"],"sub_categories":["JavaScript"],"readme":"# chiitiler - The Tiny MapLibre Server\n\n![GitHub Release](https://img.shields.io/github/v/release/Kanahiro/chiitiler?label=ghcr.io/kanahiro/chiitiler)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Kanahiro/chiitiler/test:unit.yml?label=unittest)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Kanahiro/chiitiler/test:integration.yml?label=integrationtest)\n[![codecov](https://codecov.io/gh/Kanahiro/chiitiler/graph/badge.svg?token=9RVLAJG126)](https://codecov.io/gh/Kanahiro/chiitiler)\n\n![](./logo.webp)*generated by DALL-E*\n\nchii-tiler: \"tiny\" in Japanese is \"chiisai\", shorten into \"chii\"\n\n## motivation\n\n- In this type of server, there is a de-facto - [maptiler/tileserver-gl](https://github.com/maptiler/tileserver-gl), but this is too big for me.\n- I want a server accept style.json-url and respond raster tile, inspired by [developmentseed/titiler](https://github.com/developmentseed/titiler)\n\n## usecases\n\n- [MIERUNE/tiles](https://github.com/MIERUNE/tiles) - You can find example [here](https://mierune.github.io/tiles/color.html#11.62/43.064/141.3375)\n- [dayjournal/qgis-amazonlocationservice-plugin](https://github.com/dayjournal/qgis-amazonlocationservice-plugin) - used in Maps feature\n- [Allmaps Latest - Bluesky](https://bsky.app/profile/latest.allmaps.org)\n- [PLATEAU VIEW](https://plateauview.mlit.go.jp/) - `/tiles` endpoint is used with Cesium.js based WebGIS.\n\n## features\n\n### /tiles\n\nchiitiler provides you with an endpoint `/tiles`. Once server launched, you can use the endpoint like this:\n\n```planetext\nhttp://localhost:3000/tiles/0/0/0.png?url=https://tile.openstreetmap.jp/styles/osm-bright/style.json\nhttp://localhost:3000/tiles/0/0/0.webp?margin=100\u0026url=https://tile.openstreetmap.jp/styles/maptiler-toner-en/style.json\nhttp://localhost:3000/tiles/1/1/1.jpg?tileSize=256\u0026quality=80\u0026url=https://tile.openstreetmap.jp/styles/osm-bright/style.json\n```\n\n### /clip.png|webp|jpg|jpeg\n\nchiitiler provides you with `/clip.png|webp|jpg|jpeg` endpoint. Once server launched, you can use like this:\n\n```planetext\n# default size is 1024, this is longer axis and shorter axis is calculated by aspect ratio\nhttp://localhost:3000/clip.png?bbox=100,30,150,60\u0026url=https://path/to/style.json\n# specify size\nhttp://localhost:3000/clip.png?bbox=100,30,150,6\u0026size=512\u0026url=https://path/to/style.json\n# specify quality\nhttp://localhost:3000/clip.png?bbox=100,30,150,6\u0026size=512\u0026quality=80\u0026url=https://path/to/style.json\n```\n\n#### POST endpoint\n\nEach endpoint also supports POST method. You can pass style.json as a body. (then, url parameter is not needed)\n\n## architecture\n\n```mermaid\ngraph LR\n    subgraph sources\n        direction LR\n        A[style.json]\n        z/x/y.pbf\n        z/x/y.png/webp/jpg\n        sprite\n        glyphs\n    end\n\n    subgraph chiitiler\n        cache\n        render\n        server\n    end\n\nsources --\u003e cache --\u003e render --\u003e server --/tiles/z/x/y--\u003e png/webp/jpg\n\ncache \u003c--get/set--\u003e memory/file/S3\n```\n\n## usage\n\n### Container Image\n\n```sh\ndocker pull ghcr.io/kanahiro/chiitiler\ndocker run -p 3000:3000 ghcr.io/kanahiro/chiitiler # -\u003e tile-server\n\n# recommended: you can use environment variables\ndocker run -p 3000:3000 -d \\\n-e CHIITILER_CACHE_METHOD=s3 \\\n-e CHIITILER_S3CACHE_BUCKET=bucketname \\\n-e CHIITILER_S3_REGION=ap-northeast-1 \\\nghcr.io/kanahiro/chiitiler\n```\n\n#### Environment Variables\n\nyou can pass server options via environment variables\n\n| env var                            | default  | description                                    |\n| ---------------------------------- | -------- | ---------------------------------------------- |\n| CHIITILER_PORT                     | 3000     | port number                                    |\n| CHIITILER_PROCESSES                | 1        | num of chiitiler processes. 0 means all-CPUs   |\n| CHIITILER_DEBUG                    | false    | debug mode                                     |\n| CHIITILER_STREAM_MODE              | false    | stream mode                                    |\n| CHIITILER_CACHE_METHOD             | none     | cache method, `none`, `memory`, `file`, `s3` or `gcs` |\n| CHIITILER_CACHE_TTL_SEC            | 3600     | cache ttl, effect to `memory` and `file`       |\n| CHIITILER_MEMORYCACHE_MAXITEMCOUNT | 1000     | max items for memorycache                      |\n| CHIITILER_FILECACHE_DIR            | .cache   | filecache directory                            |\n| CHIITILER_S3CACHE_BUCKET           |          | s3cache bucket name                            |\n| CHIITILER_S3_REGION                | us-east1 | s3 bucket region for caching/fetching          |\n| CHIITILER_S3_ENDPOINT              |          | s3 endpoint for caching/fetching               |\n| CHIITILER_S3_FORCE_PATH_STYLE      | false    | force path style for s3, needed for minio      |\n| CHIITILER_GCS_CACHE_BUCKET         |          | gcs cache bucket name                          |\n| CHIITILER_GCS_CACHE_PREFIX         |          | gcs cache prefix                               |\n| CHIITILER_GCS_PROJECT_ID           |          | gcs project id                                 |\n| CHIITILER_GCS_KEY_FILENAME         |          | gcs key filename                               |\n| CHIITILER_GCS_API_ENDPOINT         |          | gcs api endpoint                               |\n\n### debug page\n\n- in debug mode, you can access:\n  - debug page: \u003chttp://localhost:3000/debug\u003e\n    - You can pass style.json url: \u003chttp://localhost:3000/debug?url=https://tile.openstreetmap.jp/styles/osm-bright/style.json\u003e\n  - editor page: \u003chttp://localhost:3000/editor\u003e\n\n## deployment\n\n### AWS CDK\n\n- you can deploy chiitiler with AWS CDK, check [cdk](./cdk)\n\n## supported protocols in style.json\n\n- `http://` or `https://` protocol are used in Style Specification\n- In addition, chiitiler supports following protocols:\n  - `s3://` for S3 bucket\n  - `gs://` for Google Cloud Storage bucket\n  - `file://` for file system\n  - `mbtiles://` for MBTIles files\n  - `pmtiles://` for PMTiles, remote or local or s3\n  - `cog://` experimental, for Cloud Optimized GeoTIFF. CRS must be EPSG:3857.\n- Only when `http://` and `https://` chiitiler cache them with a method you specified.\n\n### example\n\n[./localdata/style.json](./localdata/style.json)\n\n```json\n{\n  \"version\": \"8\",\n  \"sources\": {\n    \"dir\": {\n      \"type\": \"vector\",\n      \"tiles\": [\n        \"file://localdata/tiles/{z}/{x}/{y}.pbf\"\n      ],\n      \"maxzoom\": 6\n    },\n    \"mbtiles\": {\n      \"type\": \"vector\",\n      \"tiles\": [\n        \"mbtiles://localdata/school.mbtiles/{z}/{x}/{y}\"\n      ],\n      \"maxzoom\": 10\n    },\n    \"pmtiles\": {\n      \"type\": \"vector\",\n      \"tiles\": [\n        \"pmtiles://localdata/school.pmtiles/{z}/{x}/{y}\"\n      ],\n      \"maxzoom\": 10\n    },\n    \"s3\": {\n      \"type\": \"vector\",\n      \"tiles\": [\n        \"s3://tiles/{z}/{x}/{y}.pbf\"\n      ],\n      \"maxzoom\": 6\n    },\n    \"gcs\": {\n      \"type\": \"vector\",\n      \"tiles\": [\n        \"gs://tiles/{z}/{x}/{y}.pbf\"\n      ],\n      \"maxzoom\": 6\n    },\n    \"cog\": {\n      \"type\": \"raster\",\n      \"tiles\": [\n        \"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}\"\n      ],\n      \"tileSize\": 256\n    }\n  },\n  \"layers\": [\n    {\n      \"id\": \"dir\",\n      \"source\": \"dir\",\n      \"source-layer\": \"P2921\",\n      \"type\": \"circle\",\n      \"paint\": {\n        \"circle-radius\": 10,\n        \"circle-color\": \"red\"\n      }\n    },\n    {\n      \"id\": \"mbtiles\",\n      \"source\": \"mbtiles\",\n      \"source-layer\": \"P2921\",\n      \"type\": \"circle\",\n      \"paint\": {\n        \"circle-radius\": 7,\n        \"circle-color\": \"blue\"\n      }\n    },\n    {\n      \"id\": \"pmtiles\",\n      \"source\": \"pmtiles\",\n      \"source-layer\": \"P2921\",\n      \"type\": \"circle\",\n      \"paint\": {\n        \"circle-radius\": 5,\n        \"circle-color\": \"yellow\"\n      }\n    },\n    {\n      \"id\": \"s3\",\n      \"source\": \"s3\",\n      \"source-layer\": \"P2921\",\n      \"type\": \"circle\",\n      \"paint\": {\n        \"circle-radius\": 3,\n        \"circle-color\": \"green\"\n      }\n    },\n    {\n      \"id\": \"pmtiles-s3\",\n      \"source\": \"pmtiles-s3\",\n      \"source-layer\": \"P2921\",\n      \"type\": \"circle\",\n      \"paint\": {\n        \"circle-radius\": 3,\n        \"circle-color\": \"purple\"\n      }\n    },\n    {\n      \"id\": \"gcs\",\n      \"source\": \"gcs\",\n      \"source-layer\": \"P2921\",\n      \"type\": \"circle\",\n      \"paint\": {\n        \"circle-radius\": 3,\n        \"circle-color\": \"purple\"\n      }\n    },\n    {\n      \"id\": \"cog\",\n      \"source\": \"cog\",\n      \"type\": \"raster\",\n      \"paint\": {\n        \"raster-opacity\": 0.5\n      }\n    }\n  ]\n}\n```\n\n## Library Mode\n\n- chiitiler can be used as a library to render MapLibre Style.\n- methods to render MapLibre Style are exposed from `chiitiler` package.\n\n### installation\n\n```sh\nnpm install chiitiler\n```\n\n- chiitiler requires some dependencies on runtime, you can find them in [Dockerfile](./Dockerfile)\n\n### Usage\n\n```typescript\nimport {\n    getRenderedBboxBuffer,\n    getRenderedTileBuffer,\n    ChiitilerCache\n} from 'chiitiler';\n\n// File Cache\nconst fileCache = ChiitilerCache.fileCache({\n    dir: './.cache', // default is .cache\n    ttlSec: 3600, // default is 3600 seconds\n});\n\n// Amazon S3\nconst s3Cache = ChiitilerCache.s3Cache({\n    bucket: 'chiitiler',\n    region: 'ap-northeast-1',\n    endpoint: null,\n    // credentials are loaded from environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY\n});\n\n// Google Cloud Storage\nconst gcsCache = ChiitilerCache.gcsCache({\n    bucket: 'chiitiler',\n    // credentials are loaded from environment variables: GOOGLE_APPLICATION_CREDENTIALS\n});\n\nconst tileBuf = await getRenderedTileBuffer({\n    stylejson: 'https://example.com/style.json', // or StyleSpecification object\n    z: 0,\n    x: 0,\n    y: 0,\n    tileSize: 512,\n    ext: 'webp', // png, webp, jpg\n    cache: fileCache,\n    quality: 80,\n    margin: 0,\n});\n\nconst bboxBuf = await getRenderedBboxBuffer({\n    stylejson: 'file://path/to/style.json', // or StyleSpecification object\n    bbox: [123.4, 34.5, 124.5, 35.6],\n    size: 1024,\n    cache: s3Cache,\n    ext: 'webp',\n    quality: 80,\n});\n\n// nits: stream\n// it may be usefull to avoid buffering encoded image\nconst stream = await getRenderedTileStream({\n    stylejson: 'https://example.com/style.json',\n    z: 0,\n    x: 0,\n    y: 0,\n    tileSize: 512,\n    ext: 'webp',\n    cache: ChiitilerCache.noneCache(),\n    margin: 0,\n    quality: 100,\n}); // returns sharp.Sharp instance\nconst buffer = await stream.toBuffer();\n```\n\n## development\n\n- To debug S3, run `docker compose up`\n- To debug GCS, change `CHIITILER_CACHE_METHOD` to `gcs` in `docker-compose.yml`, and then run `docker compose up`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKanahiro%2Fchiitiler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKanahiro%2Fchiitiler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKanahiro%2Fchiitiler/lists"}