🌍
Cartonik
Render maps with @carto/mapnik
🚀 Features
- Render tiles from a Mapnik XML
- Support several formats:
png
,jpeg
,grid.json
,mvt
, etc.. - Support traditional mapnik datasources:
shape
,postgis
,gdal
,ogr
, etc.. - Render static images from tiles based on center (long, lat) or bounding box (east, south, west, north) coordinates.
- Optimized for high-performance services
📦 Installation
Cartonik requires Node.js 12
npm install @carto/cartonik
🌐 Render tiles
const { rendererFactory } = require('@carto/cartonik')
const renderer = rendererFactory({ xml: '<Map>...</Map>' })
const [ format, z, x, y ] = [ 'png', 0, 0, 0 ]
const tile = await renderer.getTile(format, z, x, y)
💻 Usage: rendererFactory(options)
const options = { ... }
const renderer = rendererFactory(options)
📐 Renderer options
-
type
:string
(eitherraster
orvector
, defaultraster
). Whether the renderer aims to render Mapnik Vector Tiles or traditional raster formats (png
,utf
). -
xml
:string
(required). The Mapnik XML configuration. -
base
:string
. Path to the folder where the datasource files are (e.g. shapefiles). -
strict
:boolean
(defaultfalse
). Enables mapnik strict mode. -
bufferSize
:number
(default256
). 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. -
poolSize
:number
(defaultos.cpus().length
). Max number of preloaded maps available for rendering. -
poolMaxWaitingClients
:number
(default32
). Max number of waiting clients to acquire one of the preloaded maps. -
tileSize
:number
(default256
). Size of the tile in pixels. -
limits
:object
.-
render
:number
(default0
= disabled). Time in milliseconds to wait for the renderer to return a tile.
-
-
metrics
:boolean
(defaultfalse
). Configure@carto/mapnik
to gather statistics about rendering performance. -
variables
:object
. A key-value dictionary to customize map configuration at render-time. Placeholders defined inxml
(e.g.<PolygonSymbolizer fill="@water"/>
) will be replaced with the values defined here (e.g.{ water: 'blue' }
).
type
= raster
)
Raster renderer options (-
metatile
:number
(default2
). 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. -
metatileCache
:object
.-
timeout
:number
(default 1 minute). When the timeout fires, it removes the cached tiles. -
deleteOnHit
:boolean
(defaultfalse
). Removes the cached tile after delivered.
-
-
scale
:number
(default1
). Multiplier to scale up size-related properties of symbolizers. -
resolution
:number
(default4
). Whenformat
=utf
, the factor to scale down the tile size.
type
= vector
)
Vector renderer options (-
gzip
:boolean
(defaulttrue
). Compression method used to encoding a vector tile.
🔍 Get information about the renderer
const { rendererFactory } = require('@carto/cartonik')
const renderer = rendererFactory({ xml: '<Map>...</Map>' })
const stats = renderer.getStats()
console.log(stats)
// Map { 'cache.png' => 1, 'pool.count' => 2, 'pool.used' => 1, 'pool.unused' => 1, 'pool.waiting' => 0 }
🎆 Static images (previews)
const { preview, rendererFactory } = require('@carto/cartonik')
const renderer = rendererFactory({ xml: '<Map>...</Map>' })
const { image } = await preview({
center: {
lng: -3.68529754,
lat: 40.40197212
},
dimensions: {
width: 200,
height: 200
},
getTile: async function (format, x, y, z) {
const { buffer } = await renderer.getTile(format, z, x, y)
return { buffer }
}
})
💻 Usage: preview(options)
const options = { ... }
const renderer = preview(options)
📐 Preview options
-
getTile
:function
(required). Function to retrive the required tiles to build the preview image. -
bbox
:object
. The bounding box for the west, south, east, and north coordinates of the requested area.-
west
:number
. Longitude coordinate. -
south
:number
. Latitude coordinate. -
east
:number
. Longitude coordinate. -
north
:number
. Latitude coordinate.
-
-
center
:object
. Point where the preview is centered. This option must be used alongdimensions
option.-
lng
:number
. Long coordinate. -
lat
:number
. Latitude coordinate.
-
-
dimensions
:object
. Preview's size in pixels. This options must be defined alongcenter
option and will be multiplied by scale to keep the resolution.-
width
:number
. -
heigth
:number
.
-
-
zoom
:number
default 0. Thez
cordinate,x
andy
will be calculated based on eitherbbox
orcenter
coordinates. -
scale
:number
[1-4
], default1
. Resolution (scale:1
is72dpi
, scale:4
, is288dpi
). -
format
:string
eitherpng
orjpg
, defaultpng
. -
quality
:number
. When used withjpg
format, accepts1-100
and defaults to80
. When used withpng
format, accepts2-256
(# of colors to reduce the image to) and defaults tonull
. -
limit
:number
default19008
. Max width or height of requested image in pixels. Default is 19008. -
tileSize
:number
default256
. Size of tiles used ingetTile
function. -
concurrency
:number
default32
. Number of concurrent calls to getTile. Useful to avoid map-pool exhaustion. Ideally, should match withpoolSize
(os.cpus().length
) +poolMaxWaitingClients
(32
).
🔢 Versioning
We use SemVer for versioning. For the versions available, see the tags on this repository.
👥 Contributors
📃 License
This project is licensed under the BSD 3-clause "New" or "Revised" License - see the LICENSE file for details.