Magnacarto

# Magnacarto

## Create Map Stylings for MapServer and Mapnik

---

# About me

### Oliver Tonnhofer

* Omniscale, Oldenburg, Germany
  * Open Source development (Client/Server)
  * MapProxy and Imposm development and support

---

# maps.omniscale.com

---

# Custom map services

---

# Custom map services

---

# Magnacarto

---

# What is Magnacarto?

---

# Magnacarto
## is a style processor

---

# It's similar to TileMill and Carto (the tool)

---

<div style="position: absolute; top: 2em">
<pre style="font-size: 0.5em; padding: 2em; color: grey; background-color: white;">
    [feature = 'highway_residential'],
    [feature = 'highway_unclassified'] {
      [zoom >= 13] {
        line-color: @residential-casing;
        line-width: @residential-width-z13;
        [zoom >= 14] { line-width: @residential-width-z14; }
        [zoom >= 15] { line-width: @residential-width-z15; }
        [zoom >= 16] { line-width: @residential-width-z16; }
        [zoom >= 17] { line-width: @residential-width-z17; }
        [zoom >= 18] { line-width: @residential-width-z18; }
        [zoom >= 19] { line-width: @residential-width-z19; }
        .roads-casing {
          line-join: round;
          line-cap: round;
        }
        .tunnels-casing {
          line-dasharray: 4,2;
        }
        .bridges-casing {
          [zoom >= 14] {
            line-color: @bridge-casing;
            line-join: round;
          }
        }
      }
    }

[feature = 'highway_road'] {
      [zoom >= 14] {
        line-color: @road-casing;
        line-width: @road-width-z14;
        [zoom >= 16] { line-width: @road-width-z16; }
        [zoom >= 17] { line-width: @road-width-z17; }
        [zoom >= 18] { line-width: @road-width-z18; }
        [zoom >= 19] { line-width: @road-width-z19; }
        .roads-casing {
          line-join: round;
          line-cap: round;
        }
        .tunnels-casing {
          line-dasharray: 4,2;
        }
        .bridges-casing {
          line-color: @bridge-casing;
          line-join: round;
        }
      }
    }
</pre>

</div>

<div style="position: relative;">
<h1>Reads CartoCSS</h1>
</div>

---

<div style="position: absolute; top: 2em">
<pre style="font-size: 0.5em; padding: 2em; color: grey; background-color: white;">
    &lt;Rule&gt;
      &lt;!--Zoom{&gt;=13}--&gt;
      &lt;MaxScaleDenominator&gt;100000&lt;/MaxScaleDenominator&gt;
      &lt;Filter&gt;([feature] = 'highway_residential')&lt;/Filter&gt;
      &lt;LineSymbolizer stroke="#bbbbbb" stroke-dasharray="4, 2" stroke-width="2.5"&gt;&lt;/LineSymbolizer&gt;
    &lt;/Rule&gt;
    &lt;Rule&gt;
      &lt;!--Zoom{&gt;=13}--&gt;
      &lt;MaxScaleDenominator&gt;100000&lt;/MaxScaleDenominator&gt;
      &lt;Filter&gt;([feature] = 'highway_tertiary')&lt;/Filter&gt;
      &lt;LineSymbolizer stroke="#8f8f8f" stroke-dasharray="4, 2" stroke-width="4"&gt;&lt;/LineSymbolizer&gt;
    &lt;/Rule&gt;
    &lt;Rule&gt;
      &lt;!--Zoom{&gt;=13}--&gt;
      &lt;MaxScaleDenominator&gt;100000&lt;/MaxScaleDenominator&gt;
      &lt;Filter&gt;([feature] = 'highway_secondary')&lt;/Filter&gt;
      &lt;LineSymbolizer stroke="#707d05" stroke-dasharray="4, 2" stroke-width="5"&gt;&lt;/LineSymbolizer&gt;
    &lt;/Rule&gt;
    &lt;Rule&gt;
      &lt;!--Zoom{&gt;=13}--&gt;
      &lt;MaxScaleDenominator&gt;100000&lt;/MaxScaleDenominator&gt;
      &lt;Filter&gt;([feature] = 'highway_primary')&lt;/Filter&gt;
      &lt;LineSymbolizer stroke="#a06b00" stroke-dasharray="4, 2" stroke-width="5"&gt;&lt;/LineSymbolizer&gt;
    &lt;/Rule&gt;
    &lt;Rule&gt;
      &lt;!--Zoom{&gt;=13}--&gt;
      &lt;MaxScaleDenominator&gt;100000&lt;/MaxScaleDenominator&gt;
      &lt;Filter&gt;([feature] = 'highway_trunk')&lt;/Filter&gt;
      &lt;LineSymbolizer stroke="#c84e2f" stroke-dasharray="4, 2" stroke-width="6"&gt;&lt;/LineSymbolizer&gt;
    &lt;/Rule&gt;
    &lt;Rule&gt;
      &lt;!--Zoom{&gt;=13}--&gt;
      &lt;MaxScaleDenominator&gt;100000&lt;/MaxScaleDenominator&gt;
      &lt;Filter&gt;([feature] = 'highway_motorway')&lt;/Filter&gt;
      &lt;LineSymbolizer stroke="#dc2a67" stroke-dasharray="4, 2" stroke-width="6"&gt;&lt;/LineSymbolizer&gt;
    &lt;/Rule&gt;
    &lt;Rule&gt;
      &lt;!--Zoom{&gt;=12}--&gt;
      &lt;MaxScaleDenominator&gt;200000&lt;/MaxScaleDenominator&gt;
      &lt;Filter&gt;([feature] = 'highway_tertiary')&lt;/Filter&gt;
      &lt;LineSymbolizer stroke="#8f8f8f" stroke-dasharray="4, 2" stroke-width="2.5"&gt;&lt;/LineSymbolizer&gt;
    &lt;/Rule&gt;
    &lt;Rule&gt;
      &lt;!--Zoom{&gt;=12}--&gt;
      &lt;MaxScaleDenominator&gt;200000&lt;/MaxScaleDenominator&gt;
      &lt;Filter&gt;([feature] = 'highway_secondary')&lt;/Filter&gt;
      &lt;LineSymbolizer stroke="#9eae23" stroke-dasharray="4, 2" stroke-width="3.5"&gt;&lt;/LineSymbolizer&gt;
    &lt;/Rule&gt;
</pre>

</div>

<div style="position: relative;">
<h1>Writes Mapnik XML</h1>
</div>

---

<div style="position: absolute; top: 2em">
<pre style="font-size: 0.5em; padding: 2em; color: grey; background-color: white;">
   CLASS
      # Zoom{>=13}
      MAXSCALEDENOM 100000
      EXPRESSION ('[feature]' = 'highway_residential')
      STYLE
        WIDTH 2.5
        PATTERN
          4
          2
        END
        COLOR "#bbbbbb"
        LINECAP BUTT
        LINEJOIN MITER
      END
    END
    CLASS
      # Zoom{>=13}
      MAXSCALEDENOM 100000
      EXPRESSION ('[feature]' = 'highway_tertiary')
      STYLE
        WIDTH 4
        PATTERN
          4
          2
        END
        COLOR "#8f8f8f"
        LINECAP BUTT
        LINEJOIN MITER
      END
    END
    CLASS
      # Zoom{>=13}
      MAXSCALEDENOM 100000
      EXPRESSION ('[feature]' = 'highway_secondary')
      STYLE
        WIDTH 5
        PATTERN
          4
          2
        END
        COLOR "#707d05"
        LINECAP BUTT
        LINEJOIN MITER
      END
    END
</pre>

</div>

<div style="position: relative;">
<h1>Writes MapServer map files</h1>
</div>

---

# Command line tool

```
magnacarto -mml mystyle.mml -builder mapserver -out mystyle.map

```

```
magnacarto -mml mystyle.mml -builder mapnik3 -out mystyle.xml

```

---

# Web client

- Multiple interactive maps
- Automatic reloading
- Edit layers
  - Create
  - Modify
  - Activate/deactivate
  - Reorder

---

# It's not point & click

]

---

# It's BYOE

## Bring Your Own Editor

]

---

# CartoCSS

- Very powerful
- Steep learning curve
--

- Not the right tool for simple maps!
  - Post codes, admin districts
  - POI, routes, etc.
--

---

---

---

# OpenStreetMap Carto

- ~7.000 lines CartoCSS
- ~35.000 lines Mapnik XML

*Disclaimer: The OpenStreetMap project officially builds the Mapnik XML with Carto, but some contributors use Magnacarto for styling.*

---

# Magnacarto is fast

- simple stylings <10ms
- complex stylings ~1s

### Essential for rapid iterations!

???
Carto needs >7 seconds

---

# How to get started?

- magnacarto.org
- Open source (Apache 2 license)
- Written in Go
- Binaries for Linux, Mac OS X and Windows
  - `magnacarto` CLI tool
  - `magnaserv` web client
--

### Web client requires either

- `mapserv` binary for MapServer
- `magnacarto-mapnik` for Mapnik .small[(no binaries at the moment)]

---

# How to create map stylings?

---

# Step 1

## Define layers

---

# Define layers

## MML file (JSON or YAML)

```
Layer:
*- name: "roads"
*  geometry: "linestring"
   id: "roads"
   Datasource:
*   type: "postgis"
    host: "localhost"
    port: 5432
    dbname: "magnacarto"
    extent: "-20037508.34 -20037508.34 20037508.34 20037508.34"
    geometry_field: "geometry"
    srid: "3857"
*   table: "(SELECT * FROM roads WHERE type IN ('motorway', 'primary')) AS data"
```

---

# Define layers

## from web client

---

---

# Step 2

## Style layers

---
class: middle

# Style layers

## Write one or more MSS files

---

# Basic MSS file

```
#layername {
  style-option: 10;
  another-option: value;
}
```
---

# Available style options

<pre style="white-space: pre-wrap; font-size: 0.6em">
background-color building-fill building-fill-opacity building-height dot-fill dot-opacity dot-width dot-height dot-comp-op line-cap line-clip line-color line-dasharray line-dash-offset line-gamma line-gamma-method line-join line-miterlimit line-offset line-opacity line-rasterizer line-simplify line-simplify-algorithm line-smooth line-width line-comp-op line-geometry-transform line-pattern-file line-pattern-clip line-pattern-opacity line-pattern-simplify line-pattern-simplify-algorithm line-pattern-smooth line-pattern-offset line-pattern-geometry-transform line-pattern-comp-op marker-allow-overlap marker-file marker-fill marker-fill-opacity marker-height marker-line-color marker-line-width marker-line-opacity marker-opacity marker-placement marker-spacing marker-transform marker-type marker-width marker-multi-policy marker-avoid-edges marker-ignore-placement marker-max-error marker-clip marker-simplify marker-simplify-algorithm marker-smooth marker-geometry-transform marker-offset marker-comp-op marker-direction point-file point-allow-overlap point-opacity point-transform point-ignore-placement point-placement point-comp-op polygon-fill polygon-gamma polygon-gamma-method polygon-opacity polygon-clip polygon-simplify polygon-simplify-algorithm polygon-smooth polygon-geometry-transform polygon-comp-op polygon-pattern-alignment polygon-pattern-file polygon-pattern-gamma polygon-pattern-opacity polygon-pattern-clip polygon-pattern-simplify polygon-pattern-simplify-algorithm polygon-pattern-smooth polygon-pattern-geometry-transform polygon-pattern-comp-op shield-allow-overlap shield-avoid-edges shield-character-spacing shield-clip shield-dx shield-dy shield-face-name shield-file shield-fill shield-halo-fill shield-halo-radius shield-halo-rasterizer shield-halo-transform shield-halo-comp-op shield-halo-opacity shield-line-spacing shield-min-distance shield-min-padding shield-name shield-opacity shield-placement shield-placement-type shield-placements shield-transform shield-simplify shield-simplify-algorithm shield-smooth shield-comp-op shield-size shield-spacing shield-text-dx shield-text-dy shield-text-opacity shield-text-transform shield-wrap-before shield-wrap-character shield-wrap-width shield-unlock-image shield-margin shield-repeat-distance shield-label-position-tolerance shield-horizontal-alignment shield-vertical-alignment shield-justify-alignment text-allow-overlap text-avoid-edges text-character-spacing text-clip text-dx text-dy text-face-name text-font-feature-settings text-fill text-halo-fill text-halo-radius text-halo-opacity text-halo-rasterizer text-halo-transform text-halo-comp-op text-line-spacing text-min-distance text-min-padding text-name text-opacity text-orientation text-placement text-placement-type text-placements text-size text-spacing text-transform text-wrap-before text-wrap-character text-wrap-width text-repeat-wrap-characater text-ratio text-label-position-tolerance text-max-char-angle-delta text-vertical-alignment text-horizontal-alignment text-justify-alignment text-margin text-repeat-distance text-min-path-length text-rotate-displacement text-upgright text-simplify text-simplify-algorithm text-smooth text-comp-op text-largest-bbox-only raster-opacity raster-scaling raster-colorizer-default-mode raster-colorizer-default-color raster-colorizer-stops raster-comp-op raster-filter-factor raster-mesh-size raster-colorizer-epsilon
</pre>

---

# Polygon style options

<pre style="white-space: pre-wrap; font-size: 1em">
polygon-fill polygon-gamma polygon-gamma-method polygon-opacity polygon-clip polygon-simplify polygon-simplify-algorithm polygon-smooth polygon-geometry-transform polygon-comp-op
</pre>

---

# Common polygon style options

<pre style="white-space: pre-wrap; font-size: 1em">
polygon-fill polygon-gamma polygon-opacity
</pre>

### Remember, there is a learning curve.

---

# How to style polygons?

```css
#areas {
  polygon-fill: #008000;
}
```

```xml
  <Style name="areas" filter-mode="first">
    <Rule>
      <PolygonSymbolizer fill="#008000"></PolygonSymbolizer>
    </Rule>
  </Style>
```
--

```
    CLASS
      STYLE
        COLOR "#008000"
      END
    END
```

---

# How to style polygons?

```css
#areas {
  polygon-fill: #008000;
}
```

---

# How to style lines?

```css
#roads {
  line-width: 1;
  line-color: black;
}
```

--
.center[<img src="examples/map/mapnik-roads-line.png" style="width: 60%;"/>]

---

# Filters

```css
*#roads[type='motorway'] {
  line-width: 3;
  line-color: red;
}

*#roads[type='primary'] {
  line-width: 2;
  line-color: blue;
}
```

```
    CLASS
      EXPRESSION ('[type]' = 'primary')
      STYLE
        WIDTH 2
        COLOR "#0000ff"
      END
    END
    CLASS
      EXPRESSION ('[type]' = 'motorway')
      STYLE
        WIDTH 3
        COLOR "#ff0000"
      END
    END
```

---

# Filters

```css
*#roads[type='motorway'] {
  line-width: 3;
  line-color: red;
}

*#roads[type='primary'] {
  line-width: 2;
  line-color: blue;
}
```

---

# Styles for different map scales?

```css
#roads[zoom>=12][zoom<=14] {
  line-color: black;
  line-width: 3;
}
```

```
    CLASS
*     # Zoom{12 13 14}
*     MAXSCALEDENOM 200000
*     MINSCALEDENOM 25000
      STYLE
        WIDTH 3
        COLOR "#000000"
      END
    END
```

---

# Combine Filters

# And

```css
*#roads[type='motorway'][tunnel=1] {
  line-width: 3;
  line-color: black;
}
```

--
```
      EXPRESSION (([tunnel] = 1) AND ('[type]' = 'motorway'))
```

---

# Combine Filters

# Or

```css
*#roads[type='motorway'],
*#roads[type='primary'] {
  line-width: 3;
  line-color: black;
}
```

---

# Nesting

```css
#roads {
  line-cap: round;
  line-join: round;
  line-width: 4;
  line-color: blue;

[type='motorway'] { line-width: 10; }
  [type='primary']  { line-color: red; }
}
```

---

# Variables

```css

@road_color: rgb(240, 230, 220);
@road_width: 1;

#roads {
  line-width: @road_width;
  line-color: @road_color;
}
```

---

# Arithmetic

```css

#roads {
  line-width: @road_width;
  [type='motorway'] {
*    line-width: @road_width + 1;
  }
}
```

---

# Color Functions

```css

#roads[tunnel=1] {
  line-color: lighten(@road_color, 50%);
}
```

- lighten, darken
- saturate, desaturate,
- fadein, fadeout
- spin, mix, multiply

---

# Color Functions

```css
@grass: green;

#areas {
  [type='park'] { polygon-fill: @grass; }
  [type='forest'] { polygon-fill: darken(@grass, 15%); }
  [type='cemetery'] { polygon-fill: lighten(@grass, 15%); }
}
```

.center[
<img src="examples/map/mapnik-polygon-color-functions.png" style="width: 40%;"/>
<img src="examples/map/mapnik-polygon-colorp-functions.png" style="width: 40%; opacity: 0;"/>
]

---

# Perceptual Color Functions

```css
@grass: green;

#areas {
  [type='park'] { polygon-fill: @grass; }
  [type='forest'] { polygon-fill: darkenp(@grass, 15%); }
  [type='cemetery'] { polygon-fill: lightenp(@grass, 15%); }
}
```

.center[
<img src="examples/map/mapnik-polygon-color-functions.png" style="width: 40%;"/>
<img src="examples/map/mapnik-polygon-colorp-functions.png" style="width: 40%;"/>
]

---

# Easy map variations

#### `palette.mss`
```css
*@grass: brown;
```

#### `areas.mss`
```css
#areas {
  [type='park'] { polygon-fill: @grass; }
  [type='forest'] { polygon-fill: darkenp(@grass, 15%); }
  [type='cemetery'] { polygon-fill: lightenp(@grass, 15%); }
}
```

.center[
<img src="examples/map/mapnik-polygon-brown-color-functions.png" style="width: 40%;"/>
<img src="examples/map/mapnik-polygon-brown-colorp-functions.png" style="width: 40%;"/>
]

---

# Combine Styles

```css
#areas {
  polygon-fill: green;
  line-width: 2;
  line-color: black;
}
```

---

# Multiple Styles

```css
#areas[type='danger'] {
  base/polygon-fill: rgba(255, 0, 0, 0.2);
  base/line-width: 10;
  base/line-color: #d00000;

dash/line-width: 5;
  dash/line-dasharray: 20, 10;
  dash/line-color: rgba(255, 255, 255, 0.9);
}
```

---

# Multiple Styles

```css
#roads {
  outline/line-width: 10;
  outline/line-color: black;
  inline/line-width: 7;
  inline/line-color: white;
}
```

---

# Attachments

## Render same layer multiple times

```css
#layer::first_time {
  ...
}

#layer::second_time {
  ...
}
```

---

# Attachments

```css
#roads::outline {
  line-width: 10;
  line-color: black;
}

#roads::inline {
  line-width: 7;
  line-color: white;
}
```

---

# Classes

```css
*.labels {
  text-name: [name];
  text-size: 10;
  text-fill: black;
  text-face-name: "DejaVu Sans";
}

#place_labels {
  [type='city'] {
    text-size: 12;
  }
}

#road_labels {
  text-placement: line;
}
```

---

## *and with a **little** bit more work...*

---

---

# Pixel prefect match

- for lines
- for polygons

### Text labels are different, but equal in quality

---

# Differences between Mapserver and Mapnik

- Font sizes based on 72 and 91 DPI
- Halo size as radius or width

## Magnacarto compensates differences

- Mapnik is the reference
- Sizes in MapServer map files are adapted

---

# Other differences

---

# Unsupported
## MapServer: Label leaders

---

# Unsupported
## MapServer: Dynamic symbols

---

# Unsupported
## Data-driven styles

```css
#roads {
  line-width: [width];
}
```

- Take `line-width` from `width` column.
- Support for nearly all parameters since Mapnik 3

---

# Future

- Display Mapnik/MapServer errors in web client
- Official release
- Documentation
  - Available style options
  - Differences between Mapnik and MapServer
--

- More output builder
  - GeoServer (SLD)
  - QGIS
  - OpenLayers JSON Styling
  - MapBox GL

---

# More output builder

To the developers in this room: The hardest part is already solved!

- Parses CartoCSS
- Resolves variables
- Evaluates expressions
- Flattens nested stylings
--

- **Creates a set of simplified rules**

---

# New output builder

- Iterate over layers
- Iterate over sorted set of filters and rules

- MapServer ~1000 LOC
- Mapnik ~1200 LOC

```
  style := NewBlock("LABEL")
  style.AddNonNil("Color", fmtColor(r.Properties.GetColor("text-fill")))
  style.AddNonNil("Text", fmtFieldString(r.Properties.GetFieldList("text-name")))
  style.AddNonNil("Force", fmtBool(r.Properties.GetBool("text-allow-overlap")))
```

---

# Summary

* CartoCSS is a powerful markup language
* Magnacarto is a tool to work with CartoCSS
* Works with MapServer and Mapnik
* It's fast and extensible

---

# Fin

* https://talks.omniscale.de/2016/foss4g/magnacarto/
]

* `magnacarto.org`
* `github.com/omniscale/magnacarto`
]

* Oliver Tonnhofer, <img src="imgs/omniscale_logo_4c_cymk.png" alt="Omniscale" style="display:inline; height: 1.0em;"/>
* `tonnhofer@omniscale.de`
* `@oltonn`
]