{"id":18673202,"url":"https://github.com/cartodb/cartonik","last_synced_at":"2025-04-12T01:31:24.877Z","repository":{"id":22766870,"uuid":"97263471","full_name":"CartoDB/cartonik","owner":"CartoDB","description":"Render maps with @carto/mapnik","archived":false,"fork":false,"pushed_at":"2022-12-30T17:18:47.000Z","size":4414,"stargazers_count":18,"open_issues_count":16,"forks_count":9,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-08T11:18:54.419Z","etag":null,"topics":["carto","map","mapnik","raster","render","tile","vector"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@carto/cartonik","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CartoDB.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-14T18:45:48.000Z","updated_at":"2023-01-25T15:26:06.000Z","dependencies_parsed_at":"2023-01-13T22:11:16.562Z","dependency_job_id":null,"html_url":"https://github.com/CartoDB/cartonik","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CartoDB%2Fcartonik","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CartoDB%2Fcartonik/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CartoDB%2Fcartonik/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CartoDB%2Fcartonik/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CartoDB","download_url":"https://codeload.github.com/CartoDB/cartonik/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248504248,"owners_count":21115139,"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","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":["carto","map","mapnik","raster","render","tile","vector"],"created_at":"2024-11-07T09:14:23.657Z","updated_at":"2025-04-12T01:31:24.310Z","avatar_url":"https://github.com/CartoDB.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cartonik :earth_africa:\n\n[![CircleCI](https://circleci.com/gh/CartoDB/cartonik.svg?style=svg)](https://circleci.com/gh/CartoDB/cartonik)\n\nRender maps with `@carto/mapnik`\n\n## :rocket: Features\n\n- Render tiles from a Mapnik XML\n- Support several formats: `png`, `jpeg`, `grid.json`, `mvt`, etc..\n- Support traditional mapnik datasources: `shape`, `postgis`, `gdal`, `ogr`, etc..\n- Render static images from tiles based on center (long, lat) or bounding box (east, south, west, north) coordinates.\n- Optimized for high-performance services\n\n## :package: Installation\n\nCartonik requires Node.js 12\n\n```sh\nnpm install @carto/cartonik\n```\n\n## :globe_with_meridians: Render tiles\n\n```js\nconst { rendererFactory } = require('@carto/cartonik')\n\nconst renderer = rendererFactory({ xml: '\u003cMap\u003e...\u003c/Map\u003e' })\nconst [ format, z, x, y ] = [ 'png', 0, 0, 0 ]\n\nconst tile = await renderer.getTile(format, z, x, y)\n```\n\n## :computer: Usage: `rendererFactory(options)`\n\n```js\nconst options = { ... }\nconst renderer = rendererFactory(options)\n```\n\n## :triangular_ruler: Renderer options\n\n- `type`: `string` (either `raster` or `vector`, default `raster`). Whether the renderer aims to render Mapnik Vector Tiles or traditional raster formats (`png`, `utf`).\n- `xml`: `string` (*required*). The [Mapnik XML](https://github.com/mapnik/mapnik/wiki/XMLConfigReference) configuration.\n- `base`: `string`. Path to the folder where the datasource files are (e.g. shapefiles).\n- `strict`: `boolean` (default `false`). Enables mapnik strict mode.\n- `bufferSize`: `number` (default `256`). Extra space, in pixels, surrounding the map size being rendered. This allows you to have text and symbols rendered correctly when they overlap the image boundary.\n- `poolSize`: `number` (default `os.cpus().length`). Max number of preloaded maps available for rendering.\n- `poolMaxWaitingClients`: `number` (default `32`). Max number of waiting clients to acquire one of the preloaded maps.\n- `tileSize`: `number` (default `256`). Size of the tile in pixels.\n- `limits`: `object`.\n  - `render`: `number` (default `0` = disabled). Time in milliseconds to wait for the renderer to return a tile.\n- `metrics`: `boolean` (default `false`). Configure `@carto/mapnik` to gather statistics about rendering performance.\n- `variables`: `object`. A key-value dictionary to customize map configuration at render-time. Placeholders defined in `xml` (e.g. `\u003cPolygonSymbolizer fill=\"@water\"/\u003e`) will be replaced with the values defined here (e.g. `{ water: 'blue' }`).\n\n### Raster renderer options (`type` = `raster`)\n\n- `metatile`: `number` (default `2`). The number of tiles included in a metatile. One metatile generates a group of images at once in batches before separating them into the final tiles - this improves efficiency in various ways.\n- `metatileCache`: `object`.\n  - `timeout`: `number` (default 1 minute). When the timeout fires, it removes the cached tiles.\n  - `deleteOnHit`: `boolean` (default `false`). Removes the cached tile after delivered.\n- `scale`: `number` (default `1`). Multiplier to scale up size-related properties of symbolizers.\n- `resolution`: `number` (default `4`). When `format` = `utf`, the factor to scale down the tile size.\n\n### Vector renderer options (`type` = `vector`)\n\n- `gzip`: `boolean` (default `true`). Compression method used to encoding a vector tile.\n\n## :mag: Get information about the renderer\n\n```js\nconst { rendererFactory } = require('@carto/cartonik')\n\nconst renderer = rendererFactory({ xml: '\u003cMap\u003e...\u003c/Map\u003e' })\n\nconst stats = renderer.getStats()\n\nconsole.log(stats)\n//  Map { 'cache.png' =\u003e 1, 'pool.count' =\u003e 2, 'pool.used' =\u003e 1, 'pool.unused' =\u003e 1, 'pool.waiting' =\u003e 0 }\n```\n\n## :fireworks: Static images (previews)\n\n```js\nconst { preview, rendererFactory } = require('@carto/cartonik')\n\nconst renderer = rendererFactory({ xml: '\u003cMap\u003e...\u003c/Map\u003e' })\n\nconst { image } = await preview({\n    center: {\n        lng: -3.68529754,\n        lat: 40.40197212\n    },\n    dimensions: {\n        width: 200,\n        height: 200\n    },\n    getTile: async function (format, x, y, z) {\n        const { buffer } = await renderer.getTile(format, z, x, y)\n        return { buffer }\n    }\n})\n```\n\n## :computer: Usage: `preview(options)`\n\n```js\nconst options = { ... }\nconst renderer = preview(options)\n```\n\n## :triangular_ruler: Preview options\n\n- `getTile`: `function` (*required*). Function to retrive the required tiles to build the preview image.\n- `bbox`: `object`. The bounding box for the west, south, east, and north coordinates of the requested area.\n  - `west`: `number`. Longitude coordinate.\n  - `south`: `number`. Latitude coordinate.\n  - `east`: `number`. Longitude coordinate.\n  - `north`: `number`. Latitude coordinate.\n- `center`: `object`. Point where the preview is centered. This option must be used along `dimensions` option.\n  - `lng`: `number`. Long coordinate.\n  - `lat`: `number`. Latitude coordinate.\n- `dimensions`: `object`. Preview's size in pixels. This options must be defined along `center` option and will be multiplied by scale to keep the resolution.\n  - `width`: `number`.\n  - `heigth`: `number`.\n- `zoom`: `number` default 0. The `z` cordinate, `x` and `y` will be calculated based on either `bbox` or `center` coordinates.\n- `scale`: `number` [`1-4`], default `1`. Resolution (scale: `1` is `72dpi`, scale: `4`, is `288dpi`).\n- `format`: `string` either `png` or `jpg`, default `png`.\n- `quality`: `number`. When used with `jpg` format, accepts `1-100` and defaults to `80`. When used with `png` format, accepts `2-256` (# of colors to reduce the image to) and defaults to `null`.\n- `limit`: `number` default `19008`. Max width or height of requested image in pixels. Default is 19008.\n- `tileSize`: `number` default `256`. Size of tiles used in `getTile` function.\n- `concurrency`: `number` default `32`. Number of concurrent calls to getTile. Useful to avoid map-pool exhaustion. Ideally, should match with `poolSize` (`os.cpus().length`) + `poolMaxWaitingClients` (`32`).\n\n## :1234: Versioning\n\nWe use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/cartodb/cartonik/tags).\n\n## :busts_in_silhouette: Contributors\n\n- [Daniel García Aubert](https://github.com/dgaubert)\n- [Raúl Marín](https://github.com/Algunenano)\n\n## :page_with_curl: License\n\nThis project is licensed under the BSD 3-clause \"New\" or \"Revised\" License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcartodb%2Fcartonik","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcartodb%2Fcartonik","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcartodb%2Fcartonik/lists"}