Repository files navigation

CartoCSS (short: Carto) is a language for map design. It is similar in syntax to CSS, but builds upon it with specific abilities to filter map data and by providing things like variables.It targets theMapnik renderer and is able to generate Mapnik XML and a JSON variant of Mapnik XML.It can run from the command line or in the browser.

Carto is an evolution of theCascadenik idea and language, with an emphasis on speed and flexibility.

The best place to start is to review theCartoCSS documentation.

Tutorials like theMapbox Getting started with CartoCSS guide are a great place to start to learn the basics of CartoCSS.

For more advanced topics see theStudio style quickstart guide andStudio style manual. The links below reference the Tilemill application, which preceded Mapbox Studio Classic, but still contain useful and relevant information.

• Details on Filtering data with CartoCSS
• How order works in rendering
• How to style labels
• How to style lines
• How to style polygons
• See also theStyling Concepts for explanations of advanced features.

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

Else you can install thecarto binary with NPM by running:

npm install -g carto

You should consider using a Node.js version manager likeNVM.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

Havingmillstone installed specifically enable support for localizing external resources (URLs and local files) referenced in your mml file, and detecting projections (usingnode-srs)

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

carto project.mml > mapnik.xml

Available parameters:

• -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 aremapnik andjson (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

Alternatively, Carto can be used from JavaScript.TheRenderer 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)varcarto=require('carto');try{vardata=fs.readFileSync(input,'utf-8');varmml=newcarto.MML({});mml.load(path.dirname(input),data,function(err,data){varoutput={};if(!err){output=newcarto.Renderer({filename:input}).render(data);}if(output.msg){output.msg.forEach(function(v){if(v.type==='error'){console.error(carto.Util.getMessageToPrint(v));}elseif(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    ...}

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

To install, download or clone this repository, then copy thevim-cartodirectory located atbuild/vim-carto to your~/.vim directory.

cp build/vim-carto/* ~/.vim -R

CartoCSS is based onless.js, a CSS compiler written by Alexis Sellier.

See also alist of dependencies.

• Magnacarto (Go implementation of CartoCSS for Mapnik and Mapserver)

• Tom MacWright (tmcw)
• Konstantin Käfer (kkaefer)
• AJ Ashton (ajashton)
• Dane Springmeyer (springmeyer)
• Michael Glanznig (nebulon42)