===So what is Carto ?===

Mapnik is a popular tool to render, that is to display, geographical information into images.

Mapnik's code instructs what features (roads, rivers, buildings) to display and what these features should look like (this is known as rendering), is in XML. This XML is very difficult to read. In 2009(ish?), cascadenik was made to help simplify this.

Then, Carto (also known as CartoCSS, but for the rest of this manual, it will be referred to as Carto) was set out to provide an easier way to write these instructions while taking full advantage of mapnik's rendering capabilities and superceded cascadenik.

It's like the CSS language (and less.js), it's used to style maps in the application, Tilemill and its successor, Mapbox-Studio

Before going any further, be sure that you have read these guides made by MapBox. https://www.mapbox.com/Tilemill/docs/guides and MapBox's carto documentation

If you're focused on performance or want to render large amount of data (like entire countries), go with postgis and SHP instead of geojson or CSV.

• If you are using shapefiles, you'll want run Shapeindex, a tool that improves performance for shapefiles in Tilemill, on each shapefile. Mac and Linux users already have Shapeindex installed through Mapnik but Windows users will need to download Shapeindex for Windows before continuing.

To run Shapeindex on Mac and Linux, go to the terminal, move to directory containing the shp file and run shapeindex like:

shapeindex land-polygons-split-3857.shp

PostgreSQL Queries:

If you're using a postgis DB, you want your layers to be as specific as possible. Just as using

select * FROM yourtablename

The syntax for the following SQL queries may be different because of the program that you use to generated your geographical data into Postgresql. If you are using Openstreetmap Data that was converted to Postgresql via osm2pgsql, these queries will be applicable. If you didn't, many changes will apply to these queries.

Here's a very simple query for a layer:

 (select shop,way from planet_osm_point where shop is not null) as points

(if you're importing data from osm2pgsql see http://wiki.openstreetmap.org/wiki/Osm2pgsql/schema for the names of tables)

Let's show what this means:

Shop is your column name, planet_osm_point is your table name and points is an arbitrary name at this time. You can name it whatever you want. If you used osm2pgsql to import your data, the column names in your postgis database are in most instances, the 'key' part of an OSM tag. (remember for osm tags, a tag is key=value ... e.g. highway=residential) One exception to this is the 'way' column. The way column represents all the geographic coordinates. You will want to include the way column every time in your query regardless if you are selecting points, linestrings, or polygons.

If you are interested in only selecting restaurants,bars, and pubs for a layer, then your layer should only include points that are restaurants, bars, and pubs!

This query would be:

(select way, name, amenity FROM planet_osm_point WHERE amenity IN ('restaurant','pub','bar')) AS grub

First things First Unwritten guidelines and things that I really wish knew when I started using Tilemill, you should know by now if you're reading this, and what inspired me to write this guide.

What data should go in each layer? Should I make one layer for all roads? One for railways? Labels?

This question really confused me as a newbie Tilemill user and it is difficult to answer because it depends on the map that you're making and the sources of your data.

If you're making a map that will feature distinct styling for bridges, tunnels and multiple types of highways, you'll likely have multiple layers there (one for bridges, one for highways, one for tunnels, etc). (And you're likely using postGIS data sources). Many popular stylesheets have 3 separate road stylesheets, one for lower zoom levels (like 10-13ish), medium (14-17ish), and more detailed (18+), plus separate ones for all tunnels and bridges.

One applicable rule that is applicable for nearly every Tilemill map is that you should have a layer solely dedicated to labels :)

Deciding whether to create a layer or specifying in your MSS file for your specfic feature is something that you'll learn more as you work with Tilemill. But: If you are unsure, just create its own layer for it.

What programs do I use to edit my stylesheets (.mss) and my project file (.mml)?

You can edit them within Tilemill itself. You can also use your own preferred text editor (sublime, notepad, vim, emacs). Editing them within your own preferred text editor is especially useful when you have many MSS files. If you edit and save your file in your text editor, Tilemill will automatically detect the changes, refresh, and display the changes.

For writing selectors like

highway='specifictypeofstreetforexample'

The order of the MSS files' tabs (from left to right) within Tilemill does not matter. Neither do the names of the MSS files; they do not have to match the name of your layers. Use whatever names that are easy for you to remember.

You can access Tilemill through your web browser. In the terminal, go to the directory where Tilemill install is located (/usr/share/Tilemill for ubuntu users). In this directory, type in:

./index.js --server=true

Inheritance

CSS saves you time by inheritance, so very basic:

 #place[type='neighbourhood'][zoom>=13][zoom<=20] {
  text-name:'[name]';
  text-face-name:@sans;
  text-placement:point;
  text-fill:@other_text;
  text-size:10;
  text-halo-fill:@other_halo;
  text-halo-radius:1;
  text-wrap-width: 30;
  text-min-distance: 100;
  text-avoid-edges: true;
  text-label-position-tolerance: 10;
   [zoom>=13] {
    text-min-distance: 50;
   }
   [zoom>=14] {
    text-size:11;
   }
 }   

>=

==== Styling ===

ohh, ahh, so how do I Make stuff look purdy?

• Check out Mapbox's comp-op page if you haven't already
• Also check out the image filters (will add more on this)

===Reading the API===

So, the api can be difficult to read if you're not familiar with reading APIs.

For example, see The polygon-pattern-file,

#processed_p[zoom>=10] {
polygon-pattern-file:url('img/imagename.png'); 
}

This url path assumes that imagename.png is located in a subfolder of your project, named img.

Tip: For images, images that you use for polygon-pattern-file or map-background should be "seamless." They should be 256x256 or 512x512 in size. If they aren't seemless, you will notice where one tile ends and the other begins (add ugly example)

Attachments

When you see the :: being used, they're called attachments. These are pretty damn dope: they extend the capabilities of Tilemill, and wish I learned these earlier.

#layername[yourfilter-isthatwhatthisiscalled]::selector 
{ your code here. 
}

Also repeated in http://www.mapbox.com/Tilemill/docs/manual/carto/ (include?)

Note that newsymbol is not a special keyword but an arbitrary name chosen by the user. To help keep track of different symbolizers you can name additional symbolizers whatever makes sense for the situation. Some examples:

 #road::casing, #coastline::glow_inner, #building::shadow.  

To recap what was written there, the second rule will add a blue glow on top of the red line instead of replacing it:

 #layer {
   line-color: red;
   line-width: 4;
}

#layer::glow {
   line-color: blue;
   line-opacity: 0.5;
   line-width: 8;
}  

This glow is only possible because of the line-opacity rule. Try removing that and then click save. You'll now only see a blue line, as shown in the image below:

Important! Remember the painter's algorithm: One of the most important concepts that helped me understand Tilemill.

Let's explain how this works with attachments and the previous example. As you saw in the most recent example, you only saw a blue line.

but if we reverse the two colors, like the following :

#layer {
   line-color: red;
   line-width: 8;
}

#layer::glow {
   line-color: blue;
   line-width: 4;
}

In this case, you will see a blue line with a red outline or a red glow! Why? the red line with a width of 8, was drawn first, and then the blue line, with a width of 4, was drawn above the red line.

With attachments, the line is drawn over the previous object! This is the painter's algorithm!

However, if you do not use attachments you'll only end up with a blue line that is 4 pixels wide. Without attachments, the code in the second selector only will be used.

#countries {
   line-color: red;
   line-width: 8;
}

#countries {
   line-color: blue;
   line-width: 4;
} 

If you use attachments consecutively, like:

#layer::first {
   line-color: red;
   line-width: 4;
}
#layer::glow {
   line-color: blue;
   line-width: 2;
}

(http://www.mapbox.com/Tilemill/docs/guides/symbol-drawing-order/ explains pretty well, as well, wish this was there when I started)

And you already know, In addition to attachments, the painter's algorithm also applies to the entire mss file. Lines, points, and polygons that are written first in the MSS file will be drawn first. Any lines, polygons, and points that are written later in the file will be drawn over the earlier ones.

There's also one last affect on the drawing order of features in Tilemill which controlled by the order that the layers appear.

You can change the order of the layers, Drag the tiny icon that is to the left of each layers' name in the layers' window, that is located in the lower left hand corner of your screen. (credit Yohan Boniface) FIXME, add picture

Now, Attachment style:

there's no difference between:

 #layer {
  ::outline {
    line-width: 6;
    line-color: black;
  }
  ::inline {
    line-width: 2;
    line-color: white;
  }
}

#layer::outline {
    line-width: 6;
    line-color: black;
}
#layer::inline {
    line-width: 2;
    line-color: white;
}

AJ Ashton - I don't really have a preference and will do either or both depending on the project and the data. But for OSM-Carto I think the no-repeat approach is a good fit, and it's good to have that kind of consistency on a collaborative project.

(What's the diff between:

#place::small[type='neighbourhood'][zoom>=13][zoom<=20] 
and 
#place [type='neighbourhood'][zoom>=13][zoom<=20] ::small  

As shown in the examples, attachments are useful to style features (roads, land, etc). multiple textures, casings for lines (if you want a road to be outside with a different color than what the inside of it is...), and so much more can be done with attachments..

Like this example for a railroad.

#rail [zoom>=12][zoom<=21]::perpendicular-dashes  {

line-cap: butt;
line-color: black;
[zoom>=12] { line-width: 5.25;
    line-dasharray: 0.45,10; }
[zoom>=14] { line-width: 5.75; 
    line-dasharray: 0.75,15;}
[zoom>=16] { line-width: 6.75; 
    line-dasharray: 1.25,20; }
[zoom>=18] { line-width: 7;
     line-dasharray: 1.5,25; }
[zoom>=20] { line-width: 7;
     line-dasharray: 1.75,35; }
}
#rail [zoom>=12][zoom<=21]::base-line {
 line-cap: butt;
line-color: black;
[zoom>=12] { line-width: 1; }
[zoom>=14] { line-width: 1.25; }
[zoom>=16] { line-width: 1.75; }
[zoom>=18] { line-width: 2; }
[zoom>=20] { line-width: 2.25; }
}

In the above rail instance, the perpendicular-dashes are drawn first, then the base-line are drawn. (ADD IMAGE)

Selections/selectors within the Layer:

There are times when even if you filter the objects that you want in your layer, you want to customize styling based on certain properties within your layer.

- Adding a comma starts a whole new selector - meaning aspects of your previous selector (like the layer and zoom level) are not considered. So you need to repeat yourself a bit.

For example, if you want to add a style to display for only 2 types of parks at only level 10, and you want the style to apply to either park, you would repeat the zoom level and the park_type twice.

Like the following:

	#parkpoint[zoom=10][park_type = 'National Park'],
    #parkpoint[zoom=10][park_type = 'National Park & Preserve'] {
    } 

As you notice, I started a new line following the first parkpoint in the example and it's helps yourself to be consistent and organized by using a new line after a comma.

ajashton: is there a way to perform boolean ops between filters? so instead of #layer [field=foo][field=bar] we could do [field1=foo] AND [field2=bar]? #layer[field1=foo][field2=bar] is an AND operation #layer[field1=foo], #layer[field2=bar] is an OR operation you can also use nesting, like

#layer { [field1=foo],[field2=bar] { /* style */ } }

one more, for complex expressions can you use parens to separate the logic: #layer {[field3=baa],( [field1=foo][field2=bar]) bFlood, no parens. Everything between commas is totally separate down side is that

x AND (y OR z)

(x AND Y) OR (x AND z)

!=

[display_designation != 'National Park'][display_designation != 'National Park & Preserve']

SELECT way, railway, CASE WHEN railway in ('spur','siding') THEN 'yard' WHEN railway='disused' THEN 'disused' WHEN railway='rail' THEN 'main' ELSE 'other' END AS type FROM planet_osm_line WHERE railway IS NOT NULL ORDER BY z_order) as rail",

#railway[type='yard']
{
  your rules for yard
}
#railway[type='main']
{
  your rules for main
}

SELECT way, tunnel, bridge, railway, service, CASE WHEN railway in ('spur','siding') or (railway='rail' and service in ('spur','siding','yard')) THEN 'yard' WHEN railway='disused' THEN 'disused' WHEN railway='rail' THEN 'main' ELSE 'other' END AS type FROM planet_osm_line WHERE railway IS NOT NULL AND railway!='abandoned' ORDER BY z_order) as rail",

(e.g. /Documents/MapBox/project/mycooldakarmap.tm2/)

 Map { 
  font-directory: url('fonts/');  

 @streetsfont:  "Avenir Next LT Pro Regular"; 

@secondary_line:    #9FA9A8;
@secondary_fill:    lighten(@secondary_line,10%);
@secondary_case:    @secondary_line * 0.9;

@land: url('img/land.png');

  #countries { 
  polygon-pattern-file: @land; 
  }

#foo[bar=1] { opacity: 0.2 }
#foo[bar=2] { opacity: 0.8 }

#mapbox on freenode (irc)

./index.js