Installation & Usage¶

MML¶

The MML interface loads and processes a MML file (see MML File Structure for details). You instantiate the class with carto.MML. The constructor takes a options object with the following possible attributes:

• localize boolean (same as -l / –localize on the command line) - this uses millstone to localize stylesheet resources

• nosymlink boolean (same as -n / –nosymlink on the command line) - for millstone, tells it to use unmodified paths instead of symlinking files

By calling load(basedir, data, callback) the MML file is loaded and processed. This method does not perform reading from a file, so you have to read the contents of the file yourself and provide it as string to the method via the data parameter to the load function. The basedir parameter is used to resolve stylesheet references. When the processing is finished the specified callback function is called, which has the following signature:

function (err, data) {}

If an error occurred you find the message within err and data is null. When successful you find the processed MML data structure in data and err is null. The structure within data is excpected by the Renderer interface’s render method.

Renderer¶

The Renderer interface performs the parsing and transformation for rendering from a MML file string (either self loaded or loaded through the MML interface) or from a MSS file string (without layers). You instantiate the class with carto.Renderer. The constructor takes a options object with the following possible attributes:

• benchmark boolean (similar to -b / –benchmark on the command line) - specifies if carto should run in benchmarking mode

• effects array - a container for side-effects limited to FontSets

• filename string - name of the input file, used to format errors and warnings

• outputFormat string [mapnik|json] (similar to -o / –output on the command line) - specifies which format the output should have, either Mapnik XML or JSON similar to Mapnik XML

• ppi float (similar to -ppi on the command line) - Pixels per inch used to convert m, mm, cm, in, pt, pc to pixels

• quiet boolean (similar to -q / –quiet on the command line) - if carto should output warnings or not

• reference class - carto uses a reference to validate input. You can specify your own which has to adhere to the specification. (see Using a custom reference)

• validationData object

  • fonts array - a list of fonts that carto should use to validate if used fonts are valid/present

• version string (semver) (similar to -a / –api on the command line) - specify which Mapnik API version carto should use

carto.Renderer offers two methods for actual rendering. You can either use render(data) or renderMSS(data). Both accept a string of either a processed MML file or a MSS style fragment. The render method produces a full-featured style output while the renderMSS outputs only a style fragment. Both return the following object:

{
  msg: [],
  data: ''
}

If errors or warnings occurred during rendering you will find them in msg and data will be null (in case of errors). The actual output is found in data if no errors occurred.

Util¶

Carto provides a Util class to assist you with e.g. message formatting. Like in the example you can call getMessageToPrint with a received message object to output it nicely formatted as string.

Using a custom reference¶

Carto uses a reference to validate input. This reference specifies which rules and functions are valid and which types a rule can take. It also describes how rules are transformed for the output. By default carto uses mapnik-reference as reference, but you can also use your own. It has to adhere to the following specification:

{
  versions: [], // array of versions (semver) as strings
  latest: '', // latest version (semver) as strings
  load: function (version) {} // return data structure for specified version
}

The data structure returned by load has to look like this:

{
  version: '', // version (semver) as string
  style: {}, // rules that apply to the style as a whole
  layer: {}, // rules that apply to a layer as a whole
  symbolizers: {}, // rules that apply to different elements of the renderer, this elements make up the map
  colors: {}, // color names and their mapping to RGB values
  datasources: {} // possible data sources for the rendering library and their parameters
}

All entries that contain rules are objects where there attributes are named after a color, symbolizer or rule. style and layer have the same inner structure. Here is an example:

{
  'filter-mode': {
    type: {},
    doc: '',
    'default-value': '',
    'default-meaning': ''
  }
  ...
}

symbolizer first contains the possible symbolizers and then their rules:

{
  polygon: {
    fill: {},
    'fill-opacity': {}
    ...
  }
  ...
}

colors maps color names to their RGB values:

{
  aliceblue: [ 240, 248, 255 ],
  antiquewhite: [ 250, 235, 215 ]
  ...
}

datasources is similar to symbolizers and contains first the possible data sources and then their possible parameters:

{
  csv: {
    file: {},
    base: {}
    ...
  }
}

Rules (all the parts that where specified with {} with a little preview at filter-mode) can have several attributes that are evaluated:

name: {
    css: '', // rule name which is used in CartoCSS
    default-meaning: '', // meaning of the default value
    default-value: '', // default value of the rule
    doc: '', // documentation about the rule
    expression: bool, // whether this rule is a expression or not
    functions: [], // array of arrays that contain function name and # of params e.g. ["matrix", 6]
    range: '', // range of values that are allowed e.g. 0-1
    required: bool, // if this rule is required
    status: '[unstable|experimental|deprecated]', // if omitted it means stable
    type: '[bbox|boolean|color|float|functions|numbers|string|uri]', // type can also be an array of keywords
}