Skip to content

CartoDB/cartonik

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Cartonik 🌍

CircleCI

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 (either raster or vector, default raster). 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 (default false). Enables mapnik strict mode.
  • 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.
  • poolSize: number (default os.cpus().length). Max number of preloaded maps available for rendering.
  • poolMaxWaitingClients: number (default 32). Max number of waiting clients to acquire one of the preloaded maps.
  • tileSize: number (default 256). Size of the tile in pixels.
  • limits: object.
    • render: number (default 0 = disabled). Time in milliseconds to wait for the renderer to return a tile.
  • metrics: boolean (default false). Configure @carto/mapnik to gather statistics about rendering performance.
  • variables: object. A key-value dictionary to customize map configuration at render-time. Placeholders defined in xml (e.g. <PolygonSymbolizer fill="@water"/>) will be replaced with the values defined here (e.g. { water: 'blue' }).

Raster renderer options (type = raster)

  • 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.
  • metatileCache: object.
    • timeout: number (default 1 minute). When the timeout fires, it removes the cached tiles.
    • deleteOnHit: boolean (default false). Removes the cached tile after delivered.
  • scale: number (default 1). Multiplier to scale up size-related properties of symbolizers.
  • resolution: number (default 4). When format = utf, the factor to scale down the tile size.

Vector renderer options (type = vector)

  • gzip: boolean (default true). 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 along dimensions option.
    • lng: number. Long coordinate.
    • lat: number. Latitude coordinate.
  • 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.
    • width: number.
    • heigth: number.
  • zoom: number default 0. The z cordinate, x and y will be calculated based on either bbox or center coordinates.
  • scale: number [1-4], default 1. Resolution (scale: 1 is 72dpi, scale: 4, is 288dpi).
  • format: string either png or jpg, default png.
  • 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.
  • limit: number default 19008. Max width or height of requested image in pixels. Default is 19008.
  • tileSize: number default 256. Size of tiles used in getTile function.
  • 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).

🔢 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.