Grid placement

[talaj]

Introduces new placements grid and alternating-grid for labeling polygons with density controlled by grid-cell-width and grid-cell-height parameters.

Every single placement of the grid is individual subject of collision resolution. In order not to waste best placements inside a polygon, the grid is iterated from polygon's interior in a spiral, to occupy best places first.

Here are some use cases:

Text in regular grid

<TextSymbolizer
    placement="grid"
    face-name="DejaVu Sans Book"
    grid-cell-width="50"
    grid-cell-height="30"
    size="15">
    "Text"
</TextSymbolizer>

Text in alternating grid

<TextSymbolizer
    placement="alternating-grid"
    face-name="DejaVu Sans Book"
    grid-cell-width="50"
    grid-cell-height="30"
    size="15">
    "Text"
</TextSymbolizer>

Shields in a grid

<ShieldSymbolizer
    file="../../data/svg/octocat.svg"
    transform="scale(0.1)"
    placement="alternating-grid"
    face-name="DejaVu Sans Book"
    grid-cell-width="50"
    grid-cell-height="40"
    size="15">
</ShieldSymbolizer>

Grid reduced by negative offset to the polygon

<ShieldSymbolizer
    offset="-30"
    file="../../data/svg/octocat.svg"
    transform="scale(0.1)"
    placement="alternating-grid"
    face-name="DejaVu Sans Book"
    grid-cell-width="50"
    grid-cell-height="40"
    size="15">
</ShieldSymbolizer>

Finding single placement inside a polygon

Since grid can iterate many possible placements, it can be helpful as a single placement finder thanks to repeat-distance parameter.

The interior placement is occupied by another label but grid placement can generate possible placements around:

repeat-distance set to a large value will leave only the first grid placement visible:

<TextSymbolizer
    placement="interior"
    face-name="DejaVu Sans Book"
    fill="blue"
    size="15">
    "Interior\nplacement"
</TextSymbolizer>
<TextSymbolizer
    repeat-distance="10000"
    placement="grid"
    offset="-50"
    face-name="DejaVu Sans Book"
    grid-cell-width="20"
    grid-cell-height="20"
    size="15">
    "Grid\nplacement"
</TextSymbolizer>

Insert area to the collision detector

<TextSymbolizer
    opacity="0"
    placement="grid"
    face-name="DejaVu Sans Book"
    grid-cell-width="20"
    grid-cell-height="20"
    size="20">
    "X"
</TextSymbolizer>

cc @kocio-pl

[codecov]

Codecov Report

Merging #3847 into master will increase coverage by 0.07%.
The diff coverage is 94.57%.

@@            Coverage Diff             @@
##           master    #3847      +/-   ##
==========================================
+ Coverage   68.48%   68.56%   +0.07%     
==========================================
  Files         441      442       +1     
  Lines       23037    23150     +113     
==========================================
+ Hits        15777    15872      +95     
- Misses       7260     7278      +18

Impacted Files	Coverage Δ
include/mapnik/text/text_properties.hpp	0% <ø> (ø)	⬆️
include/mapnik/text/symbolizer_helpers.hpp	0% <ø> (ø)	⬆️
src/symbolizer_enumerations.cpp	100% <ø> (ø)	⬆️
src/load_map.cpp	86.24% <100%> (+0.03%)	⬆️
src/text/text_properties.cpp	91.5% <80%> (-1.14%)	⬇️
src/text/symbolizer_helpers.cpp	95.72% <95.34%> (-0.41%)	⬇️
include/mapnik/grid_vertex_converter.hpp	95.94% <95.94%> (ø)
...clude/mapnik/geometry/polygon_vertex_processor.hpp	0% <0%> (-100%)	⬇️
... and 1 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d4826ee...1adebaa. Read the comment docs.

[artemp]

great concept 💯

[kocio-pl]

As I wrote recently, I'm interested in this feature very much, but without package deployment on OSMF servers, osm-carto is not able to use this in practice. Do you plan to port it to v3.0.x branch or maybe release v3.1.0 any time soon?

[talaj]

@kocio-pl - Yes, I do plan to make a port to v3.0.x, but haven't had time yet.