Installation & Usage¶

Installation¶

If you are using a map design application like Kosmtik, Mapbox Studio Classic or Tilemill you already have CartoCSS installed and might be more interested in the language reference.

Else you can install the carto binary with NPM by running:

npm install -g carto

You should consider using a Node.js version manager like NVM.

Optionally you may also want to install millstone which is required for resolving data in the same way as Mapbox Studio Classic does:

npm install -g millstone

Having millstone installed specifically enables support for localizing external resources (URLs and local files) referenced in your MML file, and detecting projections (using node-srs).

Usage from the command line¶

Now that Carto is installed you should have a carto command line tool available that can be run on a CartoCSS project:

carto project.mml > mapnik.xml

The following command line options are available:

-a / –api VERSION: Specify Mapnik API version (e.g. –api 3.0.10) (default: latest Mapnik API version)
-b / –benchmark: Outputs total compile time
-f / –file: Outputs to the specified file instead of stdout
-h / –help: Display help message
-l / –localize: Use millstone to localize resources when loading an MML (default: off)
-n / –nosymlink: Use absolute paths instead of symlinking files
-o / –output: Specify output format, possible values are mapnik and json (default: mapnik)
-ppi RESOLUTION: Pixels per inch used to convert m, mm, cm, in, pt, pc to pixels (default: 90.714)
-q / –quiet: Do not output any warnings (default: off)
-v / –version: Display version information

Usage from JavaScript (Carto API)¶

Alternatively, Carto can be used from JavaScript. While you theoretically could instantiate almost all of the classes the main outward facing stable interfaces are the Renderer and the MML interface. We start with an example and describe the details afterwards:

// defined variables:
// - input (the name or identifier of the file being parsed)
var carto = require('carto');

try {
    var data = fs.readFileSync(input, 'utf-8');
    var mml = new carto.MML({});
    mml.load(path.dirname(input), data, function (err, data) {
        var output = {};

        if (!err) {
            output = new carto.Renderer({
                filename: input
            }).render(data);
        }

        if (output.msg) {
            output.msg.forEach(function (v) {
                if (v.type === 'error') {
                    console.error(carto.Util.getMessageToPrint(v));
                }
                else if (v.type === 'warning') {
                    console.warn(carto.Util.getMessageToPrint(v));
                }
            });
        }

        // output content (if no errors)
        if (output.data) {
            console.log(output.data);
        }
    });
} catch (err) {
    // program failures
    ...
}

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.

Note

If you want to use Carto within the browser you should not use MML loading via carto.MML.load. Instead you should supply the JSON of the MML including the Stylesheet strings directly to carto.Renderer.render.

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
}

Note

datasources is not yet used by carto for validation.

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
}

Caution

Adherence to the specification is not assessed in-depth because that would be too resource intensive. If you don’t adhere to the specification it is quite likely that you hit runtime errors.