@carto/cartonik
v0.9.1
Published
Render maps with @carto/mapnik
Downloads
86
Maintainers
Keywords
Readme
Cartonik :earth_africa:
Render maps with @carto/mapnik
:rocket: 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
:package: Installation
Cartonik requires Node.js 12
npm install @carto/cartonik
:globe_with_meridians: 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)
:computer: Usage: rendererFactory(options)
const options = { ... }
const renderer = rendererFactory(options)
:triangular_ruler: 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' }
).
Raster renderer options (type
= raster
)
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.
Vector renderer options (type
= vector
)
gzip
:boolean
(defaulttrue
). Compression method used to encoding a vector tile.
:mag: 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 }
:fireworks: 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 }
}
})
:computer: Usage: preview(options)
const options = { ... }
const renderer = preview(options)
:triangular_ruler: 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
).
:1234: Versioning
We use SemVer for versioning. For the versions available, see the tags on this repository.
:busts_in_silhouette: Contributors
:page_with_curl: License
This project is licensed under the BSD 3-clause "New" or "Revised" License - see the LICENSE file for details.