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¶

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
-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
-ppi RESOLUTION: Pixels per inch used to convert m, mm, cm, in, pt, pc to pixels (default: 90.714)
-v / –version: Display version information

Alternatively, Carto can be used from JavaScript. The Renderer interface is the main API for developers, and it takes an MML file as a string as input.

// 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) {
        if (err) throw err;
        var output = new carto.Renderer({
            filename: input,
            local_data_dir: path.dirname(input),
        }).render(data);
        console.log(output);
    });
} catch(err) {
    if (Array.isArray(err)) {
        err.forEach(function(e) {
            carto.writeError(e, options);
        });
    } else { throw err; }
}

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.