chiitiler 1.15.0 → 1.16.0

package/README.md

@@ -1,326 +1,314 @@
-# chiitiler - The Tiny MapLibre Server
+# chiitiler – Tiny MapLibre Server
 
 ![GitHub Release](https://img.shields.io/github/v/release/Kanahiro/chiitiler?label=ghcr.io/kanahiro/chiitiler)
-![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Kanahiro/chiitiler/test:unit.yml?label=unittest)
-![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Kanahiro/chiitiler/test:integration.yml?label=integrationtest)
+![Unit Tests](https://img.shields.io/github/actions/workflow/status/Kanahiro/chiitiler/test:unit.yml?label=unit%20tests)
+![Integration Tests](https://img.shields.io/github/actions/workflow/status/Kanahiro/chiitiler/test:integration.yml?label=integration)
 [![codecov](https://codecov.io/gh/Kanahiro/chiitiler/graph/badge.svg?token=9RVLAJG126)](https://codecov.io/gh/Kanahiro/chiitiler)
 
-![](./logo.webp)*generated by DALL-E*
+![chiitiler logo](./logo.webp)
 
-chii-tiler: "tiny" in Japanese is "chiisai", shorten into "chii"
+> Chiitiler is a tiny MapLibre server that renders raster tiles and map cut-outs from any MapLibre Style JSON, with built-in caching backends for source assets and a lightweight debug UI.
 
-## motivation
+## Overview
 
-- 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.
-- I want a server accept style.json-url and respond raster tile, inspired by [developmentseed/titiler](https://github.com/developmentseed/titiler)
+Chiitiler accepts remote or local `style.json` definitions and serves raster tiles or bounding-box images on demand. It was inspired by [`maptiler/tileserver-gl`](https://github.com/maptiler/tileserver-gl) and [`developmentseed/titiler`](https://github.com/developmentseed/titiler) but is intentionally minimal, scriptable, and easy to self-host.
 
-## usecases
+### Highlights
 
-- [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)
-- [dayjournal/qgis-amazonlocationservice-plugin](https://github.com/dayjournal/qgis-amazonlocationservice-plugin) - used in Maps feature
-- [Allmaps Latest - Bluesky](https://bsky.app/profile/latest.allmaps.org)
+- Zero-config startup: point Chiitiler at a style URL or POST a style object to receive tiles.
+- Optimized for ephemeral serverless runtimes such as AWS Lambda.
+- Multiple cache adapters (`memory`, `file`, `s3`, `gcs`) to cache shared source assets (MVT tiles, glyphs, sprites) and reduce redundant fetches.
+- Built-in `/debug` and `/editor` pages to preview styles during development.
 
-## features
+### In Production
 
-### /tiles
+- [MIERUNE/tiles](https://github.com/MIERUNE/tiles) – see the live example [map](https://mierune.github.io/tiles/color.html#11.62/43.064/141.3375).
+- [dayjournal/qgis-amazonlocationservice-plugin](https://github.com/dayjournal/qgis-amazonlocationservice-plugin) – powering QGIS integrations.
+- [PLATEAU VIEW](https://plateauview.mlit.go.jp/) – serving Cesium.js imagery through the `/tiles` endpoint.
+- [Allmaps Latest (Bluesky)](https://bsky.app/profile/latest.allmaps.org).
 
-chiitiler provides you with an endpoint `/tiles`. Once server launched, you can use the endpoint like this:
+## Supported Data Protocols
 
-```planetext
-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
-```
+Chiitiler can load tiles, sprites, glyphs, and assets via:
 
-### /clip.png|webp|jpg|jpeg
+- `http://` and `https://`
+- `s3://` (AWS S3 or compatible endpoints)
+- `gs://` (Google Cloud Storage)
+- `file://`
+- `mbtiles://`
+- `pmtiles://`
+- `cog://` (Cloud Optimized GeoTIFF, CRS must be `EPSG:3857`)
 
-chiitiler provides you with `/clip.png|webp|jpg|jpeg` endpoint. Once server launched, you can use like this:
+## Project Layout
 
-```planetext
-# 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
+```
+src/
+  main.ts           # CLI entry point and cluster bootstrap
+  cli.ts            # Commander-based CLI definition
+  server/           # Hono HTTP server & debug UI
+  render/           # Rasterization and Sharp pipelines
+  cache/            # Cache adapters (none/memory/file/s3/gcs)
+  source/           # Helpers for reading external sources
+tests/              # Vitest integration & benchmark suites
+localdata/          # Sample styles and tiles for demos
+cdk/                # AWS CDK deployment project
 ```
 
-#### POST endpoint
+## Quick Start
 
-Each endpoint also supports POST method. You can pass style.json as a body. (then, url parameter is not needed)
+### Requirements
 
-## architecture
+- Node.js 20.10.0 or newer (`.node-version` is provided).
+- System dependencies to support `sharp` (see [Dockerfile](./Dockerfile) for reference).
 
-```mermaid
-graph LR
-    subgraph sources
-        direction LR
-        A[style.json]
-        z/x/y.pbf
-        z/x/y.png/webp/jpg
-        sprite
-        glyphs
-    end
+### Run From Source
 
-    subgraph chiitiler
-        cache
-        render
-        server
-    end
+```bash
+git clone https://github.com/Kanahiro/chiitiler.git
+cd chiitiler
+npm install
+npx tsx src/main.ts tile-server --port 3000 --debug
+```
 
-sources --> cache --> render --> server --/tiles/z/x/y--> png/webp/jpg
+When the server starts you can request a tile:
 
-cache <--get/set--> memory/file/S3
+```
+http://localhost:3000/tiles/0/0/0.png?url=https://tile.openstreetmap.jp/styles/osm-bright/style.json
 ```
 
-## usage
+### Docker Image
 
-### Container Image
+```bash
+docker pull ghcr.io/kanahiro/chiitiler:latest
+docker run --rm -p 3000:3000 \
+  -e CHIITILER_CACHE_METHOD=memory \
+  -e CHIITILER_CACHE_TTL_SEC=600 \
+  ghcr.io/kanahiro/chiitiler:latest
+```
 
-```sh
-docker pull ghcr.io/kanahiro/chiitiler
-docker run -p 3000:3000 ghcr.io/kanahiro/chiitiler # -> tile-server
+The container entrypoint wraps `node /app/build/main.cjs tile-server`, so command-line options can be provided via env vars or by overriding the container CMD explicitly.
 
-# 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
-```
+#### docker-compose (local S3 + GCS emulation)
 
-#### 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`, `s3` or `gcs` |
-| 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      |
-| CHIITILER_GCS_CACHE_BUCKE          |          | gcs cache bucket name                          |
-| CHIITILER_GCS_CACHE_PREFIX         |          | gcs cache prefix                               |
-| CHIITILER_GCS_PROJECT_ID           |          | gcs project id                                 |
-| CHIITILER_GCS_KEY_FILENAME         |          | gcs key filename                               |
-| CHIITILER_GCS_API_ENDPOINT         |          | gcs api endpoint                               |
-
-### 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>
-
-## deployment
-
-### AWS CDK
-
-- you can deploy chiitiler with AWS CDK, check [cdk](./cdk)
-
-## supported protocols in style.json
-
-- `http://` or `https://` protocol are used in Style Specification
-- In addition, chiitiler supports following protocols:
-  - `s3://` for S3 bucket
-  - `gs://` for Google Cloud Storage 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](./localdata/style.json)
-
-```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
-    },
-    "gcs": {
-      "type": "vector",
-      "tiles": [
-        "gs://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": "pmtiles-s3",
-      "source": "pmtiles-s3",
-      "source-layer": "P2921",
-      "type": "circle",
-      "paint": {
-        "circle-radius": 3,
-        "circle-color": "purple"
-      }
-    },
-    {
-      "id": "gcs",
-      "source": "gcs",
-      "source-layer": "P2921",
-      "type": "circle",
-      "paint": {
-        "circle-radius": 3,
-        "circle-color": "purple"
-      }
-    },
-    {
-      "id": "cog",
-      "source": "cog",
-      "type": "raster",
-      "paint": {
-        "raster-opacity": 0.5
-      }
-    }
-  ]
-}
+The included [`docker-compose.yml`](./docker-compose.yml) spins up MinIO and `fake-gcs-server`:
+
+```bash
+docker compose up
 ```
 
-## Library Mode
+Volumes mount `localdata/` and `.cache/` so test assets and cached source data persist between runs.
+
+## HTTP API
 
-- chiitiler can be used as a library to render MapLibre Style.
-- methods to render MapLibre Style are exposed from `chiitiler` package.
+| Method | Path Pattern | Description |
+| ------ | ------------ | ----------- |
+| GET/POST | `/tiles/{z}/{x}/{y}.{ext}` | Render a raster tile (`png`, `jpeg`, `jpg`, `webp`). |
+| GET/POST | `/clip.{ext}` | Render a bounding box image (`png`, `jpeg`, `jpg`, `webp`). |
+| GET/POST | `/static/{lon},{lat},{zoom}[@{bearing}][,{pitch}]/{width}x{height}.{ext}` | Render a static image (`png`, `jpeg`, `jpg`, `webp`). |
+| GET | `/debug` | Style explorer UI (requires debug mode). |
+| GET | `/editor` | Lightweight style editor (requires debug mode). |
 
-### installation
+### Query Parameters
 
-```sh
-npm install chiitiler
+- `url` – Required when using GET. Points to a MapLibre Style JSON.
+- `tileSize` – Tile size in pixels (default `512`).
+- `quality` – JPEG/WebP quality (default `100`).
+- `margin` – Tile edge margin (default `0`).
+- `bbox` – Bounding box for `/clip` as `minLon,minLat,maxLon,maxLat`.
+- `size` – Longest edge of `/clip` output (default `1024`).
+
+POST requests accept the style object directly in the JSON body (`{ "style": { ... } }`).
+
+### Streaming Responses
+
+Enable streaming (Sharp pipeline without buffering) by setting `CHIITILER_STREAM_MODE=true` or passing `--stream`.
+
+## CLI Reference
+
+Chiitiler exposes a single command: `tile-server`.
+
+```bash
+npx tsx src/main.ts tile-server --help
+```
+
+| Option | Description | Environment Fallback | Default |
+| ------ | ----------- | -------------------- | ------- |
+| `--cache <none/memory/file/s3/gcs>` | Select cache backend. | `CHIITILER_CACHE_METHOD` | `none` |
+| `--cache-ttl <seconds>` | TTL for memory/file caches. | `CHIITILER_CACHE_TTL_SEC` | `3600` |
+| `--memory-cache-max-item-count <n>` | Max items in memory cache. | `CHIITILER_MEMORYCACHE_MAXITEMCOUNT` | `1000` |
+| `--file-cache-dir <dir>` | Disk cache directory. | `CHIITILER_FILECACHE_DIR` | `./.cache` |
+| `--s3-cache-bucket <name>` | S3 bucket for caching. | `CHIITILER_S3CACHE_BUCKET` | `""` |
+| `--s3-region <region>` | S3 region used for requests. | `CHIITILER_S3_REGION` | `us-east1` |
+| `--s3-endpoint <url>` | S3-compatible endpoint. | `CHIITILER_S3_ENDPOINT` | `""` |
+| `--s3-force-path-style` | Force path-style requests. | `CHIITILER_S3_FORCE_PATH_STYLE` (`true/false`) | `false` |
+| `--gcs-cache-bucket <name>` | GCS bucket for caching. | `CHIITILER_GCS_CACHE_BUCKET` | `""` |
+| `--gcs-project-id <id>` | GCP project ID. | `CHIITILER_GCS_PROJECT_ID` | `""` |
+| `--gcs-key-filename <path>` | Service account JSON. | `CHIITILER_GCS_KEY_FILENAME` | `""` |
+| `--gcs-cache-prefix <prefix>` | GCS object prefix. | `CHIITILER_GCS_CACHE_PREFIX` | `""` |
+| `--gcs-api-endpoint <url>` | Custom GCS endpoint. | `CHIITILER_GCS_API_ENDPOINT` | `""` |
+| `--port <number>` | HTTP listen port. | `CHIITILER_PORT` | `3000` |
+| `--stream` | Enable streaming mode. | `CHIITILER_STREAM_MODE` | `false` |
+| `--debug` | Enable debug UI routes. | `CHIITILER_DEBUG` | `false` |
+
+Set `CHIITILER_PROCESSES` to control clustering (`0` uses all CPUs). When `>1`, the primary process forks workers that all share the same cache adapter.
+
+## Environment Variables
+
+In addition to the CLI options above, the server respects:
+
+| Variable | Default | Notes |
+| -------- | ------- | ----- |
+| `CHIITILER_PROCESSES` | `1` | Number of worker processes; `0` = `availableParallelism()`. |
+| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | – | Used by the S3 cache adapter. |
+| `AWS_REGION` | – | Overrides SDK default region if set. |
+| `GOOGLE_APPLICATION_CREDENTIALS` | – | Path to a service account JSON used by the GCS adapter. |
+
+## Cache Backends
+
+Chiitiler caches the source material required for rendering (vector tiles, glyphs, sprites, spritesheets), not the final raster outputs. These cached assets are reused across requests to avoid refetching upstream sources.
+
+- **none** – No caching; every request renders from scratch.
+- **memory** – In-memory LRU cache with configurable TTL and max entries.
+- **file** – Stores fetched source assets under `CHIITILER_FILECACHE_DIR`.
+- **s3** – Uploads cached source assets to S3/MinIO; honors custom endpoint and path-style.
+- **gcs** – Uploads cached source assets to Google Cloud Storage or `fake-gcs-server`.
+
+Each adapter exposes the same `get`/`set` interface and can be reused when embedding Chiitiler as a library.
+
+## Debug Tools
+
+Run with `--debug` or `CHIITILER_DEBUG=true` to unlock:
+
+- `/debug` – Inspect styles, test queries, and view response metadata.
+- `/editor` – Lightweight MapLibre style editor with live preview.
+
+## Development & Testing
+
+```bash
+npm run dev               # Watch mode via tsx
+npm run build             # Bundle to build/main.cjs with esbuild
+npm run test:unit         # Vitest unit suite (src/**/*.test.ts)
+npm run test:integration  # End-to-end scenarios in tests/
+npm run test:coverage     # Unit coverage with V8 provider
+npm run test:benchmark    # Performance tests (see BENCHMARK.md)
 ```
 
-- chiitiler requires some dependencies in runtime, you can find them in [Dockerfile](./Dockerfile)
+Benchmark scenarios and recent measurements live in [BENCHMARK.md](./BENCHMARK.md).
+
+## Library Usage
 
-### Usage
+Chiitiler is also published as an npm library. Core helpers return Sharp instances or encoded buffers so you can integrate the renderer into other pipelines.
 
-```typescript
+```ts
+import { createWriteStream } from 'node:fs';
 import {
-    getRenderedBboxBuffer,
     getRenderedTileBuffer,
-    ChiitilerCache
+    getRenderedBboxBuffer,
+    getRenderedImageBuffer,
+    getRenderedTileStream,
+    getRenderedBboxStream,
+    getRenderedImageStream,
+    ChiitilerCache,
 } from 'chiitiler';
 
-const s3Cache = ChiitilerCache.s3Cache({
-    bucket: 'chiitiler',
-    region: 'ap-northeast-1',
-    endpoint: null,
+const cache = ChiitilerCache.fileCache({ dir: './.cache', ttl: 3600 });
+
+const tile = await getRenderedTileBuffer({
+    stylejson: 'https://tile.openstreetmap.jp/styles/osm-bright/style.json',
+    z: 5,
+    x: 27,
+    y: 12,
+    tileSize: 512,
+    margin: 0,
+    ext: 'webp',
+    quality: 100,
+    cache,
+});
+
+const clip = await getRenderedBboxBuffer({
+    stylejson: 'file://localdata/style.json',
+    bbox: [123.4, 34.5, 124.5, 35.6],
+    size: 1024,
+    ext: 'png',
+    quality: 95,
+    cache: ChiitilerCache.noneCache(),
 });
-// credentials are loaded from environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
 
-const gcsCache = ChiitilerCache.gcsCache({
-    bucket: 'chiitiler',
+const image = await getRenderedImageBuffer({
+    stylejson: 'file://localdata/style.json',
+    lat: 123.45,
+    lon: 67.89,
+    zoom: 10,
+    bearing: 180,
+    pitch: 60,
+    size: 1024,
+    ext: 'png',
+    quality: 95,
+    cache,
 });
-// credentials are loaded from environment variables: GOOGLE_APPLICATION_CREDENTIALS
 
-const tileBuf = await getRenderedTileBuffer({
-    stylejson: 'https://example.com/style.json', // or StyleSpecification object
-    z: 0,
-    x: 0,
-    y: 0,
+// you can get Sharp streams directly
+const tileStream = await getRenderedTileStream({
+    stylejson: 'https://tile.openstreetmap.jp/styles/osm-bright/style.json',
+    z: 5,
+    x: 27,
+    y: 12,
     tileSize: 512,
-    ext: 'webp', // png, webp, jpg
-    cache: s3Cache,
-    quality: 80,
     margin: 0,
+    ext: 'png',
+    quality: 90,
+    cache,
 });
 
-const bboxBuf = await getRenderedBboxBuffer({
-    stylejson: 'file://path/to/style.json', // or StyleSpecification object
+const bboxStream = await getRenderedBboxStream({
+    stylejson: 'file://localdata/style.json',
     bbox: [123.4, 34.5, 124.5, 35.6],
     size: 1024,
-    cache: s3Cache,
-    ext: 'webp',
-    quality: 80,
+    ext: 'jpeg',
+    quality: 85,
+    cache,
 });
 
-// return value is Buffer - binary of each image
+const imageStream = await getRenderedImageStream({
+    stylejson: 'file://localdata/style.json',
+    lat: 123.4,
+    lon: 34.5,
+    zoom: 10,
+    bearing: 180,
+    pitch: 60,
+    size: 1024,
+    ext: 'png',
+    quality: 95,
+    cache,
+})
 ```
 
-## development
+## Deployment
+
+- **AWS CDK** – The [`cdk/`](./cdk) directory contains an AWS CDK app for provisioning Chiitiler on ECS/Fargate. See `cdk/README.md` for stack details.
+- **Docker** – The provided `Dockerfile` installs runtime dependencies for `sharp` and exposes `tile-server` as the default entrypoint.
+- **Bench setups** – `docker-compose.yml` provisions MinIO, Fake GCS, and sample data for local smoke tests.
+
+## Architecture
+
+```mermaid
+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
 
-- To debug S3, run `docker compose up`
-- To debug GCS, change `CHIITILER_CACHE_METHOD` to `gcs` in `docker-compose.yml`, and then run `docker compose up`
+sources --> cache --> render --> server --/tiles/z/x/y--> png/webp/jpg
+
+cache <--get/set--> memory/file/S3
+```

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import { getRenderedBbox, getRenderedTile, GetRenderedBboxOptions, GetRenderedTileOptions } from './render/index.js';
+import { getRenderedBbox, getRenderedTile, getRenderedImage, GetRenderedBboxOptions, GetRenderedTileOptions, GetRenderedImageOptions } from './render/index.js';
 export declare function getRenderedBboxBuffer(options: GetRenderedBboxOptions): Promise<Buffer>;
 export { getRenderedBbox as getRenderedBboxStream };
+export declare function getRenderedImageBuffer(options: GetRenderedImageOptions): Promise<Buffer>;
+export { getRenderedImage as getRenderedImageStream };
 export declare function getRenderedTileBuffer(options: GetRenderedTileOptions): Promise<Buffer>;
 export { getRenderedTile as getRenderedTileStream };
 export * as ChiitilerCache from './cache/index.js';

package/dist/index.js

@@ -1,9 +1,14 @@
-import { getRenderedBbox, getRenderedTile, } from './render/index.js';
+import { getRenderedBbox, getRenderedTile, getRenderedImage, } from './render/index.js';
 export async function getRenderedBboxBuffer(options) {
     const sharp = await getRenderedBbox(options);
     return sharp.toBuffer();
 }
 export { getRenderedBbox as getRenderedBboxStream };
+export async function getRenderedImageBuffer(options) {
+    const sharp = await getRenderedImage(options);
+    return sharp.toBuffer();
+}
+export { getRenderedImage as getRenderedImageStream };
 export async function getRenderedTileBuffer(options) {
     const sharp = await getRenderedTile(options);
     return sharp.toBuffer();

package/dist/render/index.d.ts

@@ -23,4 +23,17 @@ type GetRenderedBboxOptions = {
     quality: number;
 };
 declare function getRenderedBbox({ stylejson, bbox, size, cache, ext, quality, }: GetRenderedBboxOptions): Promise<sharp.Sharp>;
-export { getRenderedTile, getRenderedBbox, type GetRenderedBboxOptions, type GetRenderedTileOptions, type SupportedFormat, };
+type GetRenderedImageOptions = {
+    stylejson: string | StyleSpecification;
+    cache: Cache;
+    ext: SupportedFormat;
+    quality: number;
+    bearing: number;
+    pitch: number;
+    zoom: number;
+    center: [number, number];
+    height: number;
+    width: number;
+};
+declare function getRenderedImage(options: GetRenderedImageOptions): Promise<sharp.Sharp>;
+export { getRenderedTile, getRenderedBbox, getRenderedImage, type GetRenderedBboxOptions, type GetRenderedTileOptions, type GetRenderedImageOptions, type SupportedFormat, };

package/dist/render/index.js

@@ -121,7 +121,7 @@ async function getRenderedBbox({ stylejson, bbox, size, cache, ext, quality, })
         height,
         center,
     }, cache, 'static');
-    let _sharp = sharp(pixels, {
+    const _sharp = sharp(pixels, {
         raw: {
             width,
             height,
@@ -138,4 +138,31 @@ async function getRenderedBbox({ stylejson, bbox, size, cache, ext, quality, })
             return _sharp.webp({ quality, effort: 0 });
     }
 }
-export { getRenderedTile, getRenderedBbox, };
+async function getRenderedImage(options) {
+    const style = await loadStyle(options.stylejson, options.cache);
+    const pixels = await render(style, {
+        center: options.center,
+        height: options.height,
+        width: options.width,
+        zoom: options.zoom,
+        bearing: options.bearing,
+        pitch: options.pitch,
+    }, options.cache, 'static');
+    const _sharp = sharp(pixels, {
+        raw: {
+            width: options.width,
+            height: options.height,
+            channels: 4,
+        },
+    });
+    switch (options.ext) {
+        case 'png':
+            return _sharp.png();
+        case 'jpeg':
+        case 'jpg':
+            return _sharp.jpeg({ quality: options.quality });
+        case 'webp':
+            return _sharp.webp({ quality: options.quality, effort: 0 });
+    }
+}
+export { getRenderedTile, getRenderedBbox, getRenderedImage, };