[mapnik-3] mapnik-reference

[rochoa]

• List backward incompatible changes between 2.3.x and 3.x versions.
• Prepare a migration path for those changes:
  • maximum-extent: default from none to -20037508.34, -20037508.34, 20037508.34, 20037508.34
  • polygon-clip: default from true to none
  • line-clip: default from true to none
  • marker-clip: default from true to none
  • shield-clip: default from true to none
  • line-pattern-clip: default from true to none
  • polygon-pattern-alignment: default from local to global
  • polygon-pattern-clip: default from true to none
  • text-label-position-tolerance: default from none to text-spacing/2.0
  • text-clip: default from true to none
  • building-fill: default from #FFFFFF/white to rgb(128,128,128)/gray

PR: #119

[dgaubert]

Changes between 2.3.x and 3.x

Api changes between v2.3 and v3.0 versions are summarized here. Below an exhaustive list of changes in mapnik-reference.

Marked as deprecated (2)

• marker-type
  • type: list
  • values: arrow, ellipse
  • default: ellipse
• text-min-distance
  • type: float
  • default: none

Marked as unstable (2)

• line-offset
  • type: float
  • default: none
• text-repeat-wrap-character
  • type: boolean
  • default: none

Marked as experimental (2)

• line-dash-offset
  • type: numbers
  • default: none
• text-largest-bbox-only
  • type: boolean
  • default: true

Added (32)

• marker-avoid-edges
  • type: boolean
  • default: none
• marker-simplify-algorithm
  • type: list
  • values: radial-distance, zhao-saalfeld, visvalingam-whyatt
  • default: none
• marker-offset
  • type: float
  • default: none
• marker-direction
  • type: list
  • values: auto, auto-down, left, right, left-only, right-only, up, down
  • default: right
• shield-margin
  • type: float
  • default: none
• shield-repeat-distance
  • type: float
  • default: none
• shield-label-position-tolerance
  • type: float
  • default: shield-spacing/2.0
• shield-halo-transform
  • type: functions
  • values: matrix,6, translate,2, scale,2, rotate,3, skewX,1, skewY,1
  • default: none
• shield-halo-comp-op
  • type: list
  • values: clear, src, dst, src-over, dst-over, src-in, dst-in, src-out, dst-out, src-atop, dst-atop, xor, plus, minus, multiply, screen, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference, exclusion, contrast, invert, invert-rgb, grain-merge, grain-extract, hue, saturation, color, value
  • default: src-over
• shield-halo-opacity
  • type: float
  • default: 1
• shield-simplify
  • type: float
  • default: none
• shield-simplify-algorithm
  • type: list
  • values: radial-distance, zhao-saalfeld, visvalingam-whyatt
  • default: radial-distance
• shield-smooth
  • type: float
  • values: 0-1
  • default: none
• line-pattern-opacity
  • type: float
  • default: 1
• text-repeat-wrap-character
  • type: boolean
  • default: none
• text-halo-opacity
  • type: float
  • default: 1
• text-halo-transform
  • type: functions
  • values: matrix,6, translate,2, scale,2, rotate,3, skewX,1, skewY,1
  • default: none
• text-margin
  • type: float
  • default: none
• text-repeat-distance
  • type: float
  • default: none
• text-rotate-displacement
  • type: boolean
  • default: none
• text-upright
  • type: list
  • values: auto, auto-down, left, right, left-only, right-only
  • default: auto
• text-simplify
  • type: float
  • default: none
• text-simplify-algorithm
  • type: list
  • values: radial-distance, zhao-saalfeld, visvalingam-whyatt
  • default: radial-distance
• text-smooth
  • type: float
  • values: 0-1
  • default: none
• text-halo-comp-op
  • type: list
  • values: clear, src, dst, src-over, dst-over, src-in, dst-in, src-out, dst-out, src-atop, dst-atop, xor, plus, minus, multiply, screen, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference, exclusion, contrast, invert, invert-rgb, grain-merge, grain-extract, hue, saturation, color, value
  • default: src-over
• text-font-feature-settings
  • type: string
  • default: none
• text-largest-bbox-only
  • type: boolean
  • default: true
• dot-fill
  • type: color
  • default: gray
• dot-opacity
  • type: float
  • default: 1
• dot-width
  • type: float
  • default: 1
• dot-height
  • type: float
  • default: 1
• dot-comp-op
  • type: list
  • values: clear, src, dst, src-over, dst-over, src-in, dst-in, src-out, dst-out, src-atop, dst-atop, xor, plus, minus, multiply, divide, screen, overlay, darken, lighten, color-dodge, color-burn, linear-dodge, linear-burn, hard-light, soft-light, difference, exclusion, contrast, invert, invert-rgb, grain-merge, grain-extract, hue, saturation, color, value
  • default: src-over

Changed (30)

• image-filters
  • add functions: color-blind-protanope, color-blind-deuteranope, color-blind-tritanope
• direct-image-filters
  • add functions: color-blind-protanope, color-blind-deuteranope, color-blind-tritanope
• comp-op
  • add values: divide, linear-dodge, linear-burn
• background-image
  • add accepted formats: svg, tiff, webp
• background-image-comp-op
  • add values: divide, linear-dodge, linear-burn
• maximum-extent
  • default from none to -20037508.34, -20037508.34, 20037508.34, 20037508.34
• polygon-clip
  • default from true to none
• polygon-comp-op
  • add values: divide, linear-dodge, linear-burn
• line-join
  • add values: miter-revert
• line-clip
  • default from true to none
• line-comp-op
  • add values: divide, linear-dodge, linear-burn
• marker-file
  • add accepted formats: svg, tiff, webp
• marker-placement
  • add values: vertex-first, vertex-last
• marker-clip
  • default from true to none
• marker-comp-op
  • add values: divide, linear-dodge, linear-burn
• shield-clip
  • default from true to none
• shield-comp-op
  • add values: divide, linear-dodge, linear-burn
• line-pattern-clip
  • default from true to none
• line-pattern-comp-op
  • add values: divide, linear-dodge, linear-burn
• polygon-pattern-alignment
  • default from local to global
• polygon-pattern-clip
  • default from true to none
• polygon-pattern-comp-op
  • add values: divide, linear-dodge, linear-burn
• raster-comp-op
  • add values: divide, linear-dodge, linear-burn
• point-comp-op
  • add values: divide, linear-dodge, linear-burn
• text-label-position-tolerance
  • default from none to text-spacing/2.0
• text-transform
  • add values: reverse
• text-horizontal-alignment
  • add values: adjust
• text-clip
  • default from true to none
• text-comp-op
  • add values: divide, linear-dodge, linear-burn
• building-fill
  • default from #FFFFFF/white to rgb(128,128,128)/gray

Removed (0)

N/A

[dgaubert]

For the record: I've just found Notes for cartographers.

[dgaubert]

Ready for CR in #119

[dgaubert]

About maximum-extent. I'm skipped to set the default value because in grainstore we are setting datasources's extent param:

<Parameter name="extent">
   <![CDATA[-20037508.3,-20037508.3,20037508.3,20037508.3]]>
</Parameter>

Should we take care of it? or can we skip setting maximum-extent default?

cc/ @rochoa

[dgaubert]

I've been researching TextSymbolizer changes between mapnik v2.3.x and v3.x, i.e:

Mapnik 2.3.x

Mapnik 3.x

Playing with properties of TextSymbolizer nothing seems to work to mitigate differences between versions. In mapnik's wiki I've found two mentions about how text-symbolizer could behave different:

• TextSymbolizer line wrapping behavior has now changed: previously line wrapping only happened on ascii whitespace (if wrap-character was not provided) but now it happens on any valid wrapping characters as determined by the default locale and the behavior of the ICU::BreakIterator [..]
• wrap-character property for TextSymbolizer should behave similarly as 2.3 but the code to support it was completely re-written so there may be slight differences in render: Status of wrap-character option at 3.x mapnik/mapnik#2333

Both points are related with the differences that we can see in our test. But I've found one more using the simplest style to render text, i.e:

#layer {
 text-name:"[name]";
 text-face-name:"DejaVu Sans Book";
}

Mapnik 3.x

Mapnik 2.3.x

Both of them are slightly different, it seems that in Mapnik v3.x char-spacing is higher than v2.3.x.

Not sure if we should mitigate those differences in order to be 100% backwards compatible or accept them and be aware of that. If I'm not mistaken, these changes are intended to improve text placement and so on.

@rochoa, what do you think?

[dgaubert]

Also we have different behaviours regarding marker-allow-overlap. i.e:

Given the following style:

#layer {
  marker-fill:hsl(100, 50%, 50%);
  marker-max-error:0.226367927783;
  marker-allow-overlap:false;
  marker-line-opacity:0.849622918895;
  marker-type:ellipse;
  marker-line-color:#ff7;
  marker-placement:interior;
  marker-spacing:19.0;
  marker-width:14.0;
  marker-height:15.0;
  marker-opacity:0.495065045968;
  marker-line-width:4.0;
}

and query:

SELECT
    row_number() OVER (ORDER BY x DESC) AS scale,
    'my really long name here' as name,
    st_transform(st_setsrid(st_makepoint(10*x,10*x),4326),3857) as the_geom_webmercator
FROM generate_series(-6,6) x

It should render 13 point with big ellipse markers, obviously they overlaps and some of them are hidden:

Mapnik 3.x

Mapnik 2.3.x

The way to calculate which points are show/hidden is totally different. I've tried to dig into it, many things, such as mapnik/mapnik#1361, mapnik/mapnik#952, mapnik/mapnik#1754 seems to be related but I couldn't see the main reason of this change in the behaviour.

By the way, setting allaw-overlap to true, all markers are rendered:

Mapnik 3.x

Mapnik 2.3.x

[dgaubert]

Even though we all are aware of line-dasharray issue, just for the record:

For this style:

#layer {
  marker-fill:green;
  marker-max-error:0.308437912944;
  marker-line-opacity:0.209584404812;
  marker-allow-overlap:false;
  polygon-fill:#FF6600;
  marker-spacing:8.0;
  marker-width:20.0;
  marker-height:6.0;
  marker-opacity:0.031267288851;
  line-color:hsl(100, 50%, 50%);
  line-gamma:0.805214581926;
  line-cap:square;
  polygon-opacity:0.921278888075;
  marker-type:ellipse;
  polygon-gamma:0.316572349064;
  line-dasharray:22,44;
  line-join:miter;
  marker-placement:line;
  line-width:10.0;
  marker-line-color:#ff7;
  line-opacity:0.55735836368;
  marker-line-width:2.0;
}

and the given query:

SELECT
    'my polygon name here' as name,
   st_envelope(st_buffer(st_transform(st_setsrid(st_makepoint(-1.26462144913,68.6705865302),4326),3857),10000000)) as the_geom_webmercator
FROM generate_series(-6,6) x
UNION ALL
SELECT
    'my marker name here' as name,
    st_transform(st_setsrid(st_makepoint(-172.851435136,-40.078291601),4326),3857) as the_geom_webmercator
FROM generate_series(-6,6) x

Mapnik 3.x

Mapnik 2.3.x

The behaviour of how line-dash is rendered has changed. Seems that in Mapnik 2.3.x to draw the dashed line starts from the last point and ends at the first one, whereas in Mapnik 3.x starts from the first point and ends in the last one.