Repository navigation
Description
Status (updated 2026-11-12, main fbc5bab)
This issue proposed automatic placement of layout.publication's surrounds (locator, north arrow, legend, scale bar). Most of it is now merged. This text lists what is done and what is left, and keeps the original proposal at the end.
Done
| Proposal | Where |
|---|---|
Arrangements with a favourite: classic, mirrored, legendRight, legendTop, or corner by corner; layout.arrangement {"favourite": …}; "arrangement": "best" | "favourite" | <name> |
#1392 (ARRANGEMENTS, crates/engine/src/cmd/layout.rs) |
| A surround stays home unless it leaks (more than 0.5 % of what the map draws, or a taken corner) | #1392 (LEAK) |
| A leaking surround searches the whole frame on a 1 mm step: coverage cost, distance from home, a pull toward alignment guides (frame margins, centre, edges of placed surrounds), and a 2 mm gap from the others | #1392 (free_spot) |
| A finer coverage grid (384 cells on the long side) with a summed-area table | #1392 |
| Grid label bands kept out of the search area (the "safe area") | #1392 (the frame's room per labelled edge) |
The answer names the arrangement and what moved ("arrangement", "moved") |
#1392 |
| A legend in up to three columns, chosen from the largest free rectangle | #1494 |
| Point symbols in the legend drawn as the map draws them | #1442 (jgregoriorincon) |
"colorbar": "none", with no empty room left in the legend box |
#1682 |
When no shape of the legend fits: the map moves aside (mapShift), one-colour context counts as free, and what lies outside the extent is veiled with the surrounds grouped there ("veil") |
#1725 |
| A tile layer's attribution kept clear of the grid labels | #1797 |
Open and related: #1758 lists a classified raster's classes in the legend, in place of a colorbar of class codes.
Left to do
- A scale bar box the size of its bar. The box is still
(fw * 0.3).max(25.0)wide (layout.rs, whereswis set), so on an A4 sheet it takes 30 % of the frame's width and leaves the bar in a wide empty box. Size it to the bar and its labels, plus the padding. - Several saved arrangements by name.
layout.arrangementkeeps one favourite, which can be a custom corner-by-corner arrangement. The proposal also asked for saving more than one under a name and picking it by that name, as with the built-in ones. - The coverage image on request.
"coverage": "path.png"was proposed: drawn cells dark, free cells white, grid label bands tinted, the placed surrounds outlined. It is not there yet, and it is the quickest way to see why a surround moved. - The footer's right column aligned with the legend when the legend sits on the right (between 45 % and 70 % of the frame's width). I find no such alignment in
layout.rs.
Smaller steps, from comparing the output with published cartographic guidance (Ordnance Survey):
- Context layers out of the legend. A one-colour context layer ("Other states") is already recognised as context for placement (feat(layout): when no shape of the legend fits, move the map aside, then veil what lies outside the extent (#1379) #1725). It could also be left out of the legend by default.
- No north arrow at continental scale when a graticule is drawn. The graticule already gives north.
- No white box behind the legend over truly free space. Keep the box over the veil or over data, where it is needed for reading.
- When the map moves aside, prefer the side that keeps it closest to the page's visual centre. The move stays a fallback for when the legend doesn't fit, not a rule.
Choices in this proposal
- Items 1 to 4 first, in one PR each. They finish the original proposal. Items 5 to 8 change what every publication layout looks like, so each needs a maintainer's view before it is coded.
- Item 1 keeps the bar's length rule. Only the box changes, so the bar's scale and divisions stay the same.
- Item 3 writes the grid the search uses, not a re-render. What the image shows is then exactly what the placement saw.
The original proposal (2026-11-03)
Before you start
- I searched the existing issues and the roadmap and did not find a duplicate request.
What problem does this solve?
layout.publication already keeps surrounds off what the map draws. It renders the frame into a 96-cell coverage grid (frame_coverage) and tries every assignment of the locator, north arrow, legend and scale bar to the frame's four corners, up to 256 picks. The cost is the data covered, plus a small cost for leaving a surround's own corner and a large one for overlaps. When every corner is busy, it warns "move by hand what matters".
That last case is common. The free space is often not in a corner: an ocean beside a continent, the empty side of a municipality, a wide gap between a coast and the frame edge. With v0.5.0, the sample's countries in EPSG:8858 over South America (extent [-82, -56.5, -34.5, 13]) come out as follows:
a4-portrait: the legend sits over Chile and Argentina, and the north arrow over Central America. The Pacific beside Peru and Chile and the South Atlantic are empty.figure-1col: the legend covers Brazil's coast, and the scale bar the Caribbean islands. The Pacific, left of Peru, is empty.
Three smaller gaps add to it:
- the surrounds can cover grid labels (a measured grid's
9470000along the left edge, a graticule's30°S); - nothing aligns one surround with another, so the scale bar and the locator have unrelated left edges, and the legend and the footer columns too;
- there is no way to say "I prefer the locator at the top right" and still get the automatic fallback.
I built this as a prototype in Python on our layout generator, and it closes all four gaps. Tested on three maps (a municipality on a Sentinel-2 image in UTM, South America at A4 and at one column, a relief map), none of its surrounds covers the map's data, grid labels or each other. The hand-placed layouts had the north arrow over 17 % land in the one-column figure, and two surrounds over grid labels in the UTM map.
Proposed solution
Extend layout.publication's placement, keeping its corner search as the first step.
-
Arrangements (presets), with a favourite. An arrangement gives each surround a home: a corner and an offset, counted from the frame's safe area, which is the frame minus the bands where grid labels are drawn. The built-in arrangements:
arrangementnorth arrow legend locator scale bar classictop right bottom right top left bottom left mirroredtop left bottom left top right bottom right righttop right bottom right top right, under the arrow bottom left lefttop right bottom left top left bottom right "arrangement": "best"is the default. It tries the favourite first, then the others, and keeps the one that moves the fewest surrounds; ties go to the favourite."arrangement": "favourite"always uses the favourite. The favourite is a user setting,layout.arrangement {"favourite": "classic"}, kept with the other preferences. Users can save their own arrangements by name, in the same shape. -
A surround stays home unless it leaks. It leaks when, at home, it covers more than 0.5 % of what the map draws, overlaps another surround (with a 1 mm gap), or covers a grid label band. Only leaking surrounds move.
-
A leaking surround searches the whole frame, not only the corners. Candidates are every position on a 1 mm step inside the safe area, plus the positions where one of its edges or its centre falls on an alignment guide. It cannot overlap a placed surround. Each candidate costs:
- 1000 × the share of drawn cells it covers;
-
- 100 × the share of a grid label band it covers;
-
- 0.05 × its distance in mm from home;
-
- 0.25 × its distance in mm, up to 4 per axis, from the nearest alignment guide. The guides are the frame margins, the frame's centre, the footer's right column, and the edges of surrounds already placed.
The lowest cost wins, and ties go to the first in scan order, so the same map always gives the same layout. The 0.25 term is what puts the scale bar under the locator's left edge and the legend on the scale bar's baseline.
-
A finer coverage grid, from 96 cells to about 0.5 mm per cell: about 400 × 450 cells on A4. The search keeps a summed-area table of the grid, so a rectangle's coverage is four lookups. With a 1 mm step, the whole frame is about 40,000 candidates per surround, and the four surrounds of an A4 sheet place in a few milliseconds.
-
The footer's right column aligned with the legend when the legend sits on the right, between 45 % and 70 % of the frame's width.
-
The coverage image on request.
"coverage": "path.png"writes the grid as an image: drawn cells dark, free cells white, grid label bands tinted and the placed surrounds outlined. The command's answer names the arrangement chosen and the surrounds it moved, for examplearrangement 'classic'; moved: scale bar.
Choices in this proposal
- The coverage stays the rendered map, as today, not a vector of the layers' geometries. It is what the reader sees, labels and halos included, and
frame_coveragealready computes it. - Arrangements are homes, not fixed slots. Fixed slots fail in exactly the maps where free space isn't in a corner.
bestby fewest moved surrounds, favourite on ties, rather than by the lowest total cost. A user's preferred look should win unless another arrangement is clearly better.- Grid label bands are part of the safe area. Measured grids (feat(layouts): measured grids, eastings and northings in a projected system, beside the graticule #1012) draw their labels inside the frame, and covering them was the most frequent defect in the hand-placed layouts.
- No change without
layout.publication. Hand-made layouts (layout.addElement) keep their positions.
Estimated scope
Medium: about 300 lines in crates/engine/src/cmd/layout.rs (arrangements, the full-frame search, guides), a setting, and tests on synthetic coverage grids (a continent with free ocean beside it, an all-covered relief frame, a measured-grid frame). A Python prototype with the same costs, and its comparisons against hand-placed layouts, is ready to share.
Alternatives considered
- Keep the corners and only warn, as today. The warning leaves the user to move surrounds by hand, which is what the command is meant to save.
- Let the user give a
lonlatper surround. It is what we did by hand, and it has to be redone for each page size.
Activity
feat(layout): arrangements for publication layouts, a favourite, and …
fix(layout): review round on legend columns (opengeos#1379)
elpidioassinaturas commentedon Nov 6, 2026
When no shape of the legend fits: move the map, then veil what lies outside the extent
This is a proposal for a follow-up to #1494, which lays a publication legend in up to three columns. I have a working prototype, so the figures below are real output, but it isn't pushed, and I'd like a maintainer's view before opening a PR. It changes what
layout.publicationdraws and returns by default, whichdocs/maintaining.mdputs with the changes that need two maintainers.The problem
#1494 picks the fewest columns that fit the largest free rectangle. On a map with no such rectangle, the legend still lands on the data, however many columns it takes. Three cases from a geology map of Minas Gerais (18 to 25 classes, IBGE BDiA), A4, in an Albers projection centred on the state:
What I propose
These run only when no shape of the legend fits. A map where one fits comes out as it does today.
mapShift."veiled": trueand"arrangement": "veil".Results
A two-column figure of Brazil, which has room for its legend, comes out with the same columns, scale and arrangement as with #1494.
Continuous extent, with #1494
Continuous extent, with this proposal
18 classes, with #1494
18 classes, with this proposal
Filled neighbours, with #1494
Filled neighbours, with this proposal
Choices in this proposal
"veil": falsefor anyone who wants the map untouched. The prototype doesn't have that parameter yet.Any of these can change if you prefer otherwise.
Known limits
"exclude"removes it by hand.It isn't tried in a real window yet, only through
rustgis-cliand tests.🤖 Generated with Claude Code
fix(layout): a legend given columns says what its box loses (opengeos…
fix(layout): one column draws as before; a legend in columns says mor…
fix(layout): a legend with no rows has nothing to lose in its box (op…
feat(layout): a legend in up to three columns, and publication layout…
fix(layout): one drawing per scale in the map's search, the legend's …
fix(layout): a map moved in its frame is said, and a scale whose lege…
fix(layout): a move keeps the extent inside each side's own margin; p…
fix(layout): the veil stops at the graticule's labels; one-colour con…
fix(layout): "moved" names the surrounds in the veil's band; the sear…
docs(layout): say when a map counts as continuous for the veil (openg…
fix(layout): a moved frame places the extent at its own centre's grou…
test(layout): moved frames read every streamed feature they draw; doc…
22 remaining items
feat(layout): a publication's scale bar box the size of its bar (#1379)…
feat(layout): publication arrangements saved by name (#1379) (#1829)
feat(layout): a sheet's footer lined up with a legend at the right (#…
fix(layout): one measure for a scale box's automatic width; its bar i…
test(layout): a save with nothing passed over says nothing of dropping (
fix(layout): review round 1 on context out of the legend (opengeos#1379)
test(layout): the footer test keeps the sample's lakes in its legend (o…
fix(layout): a veiled group with neither locator nor arrow keeps no g…
fix(layout): a moved frame drawn on its own gives the legend its own …
fix(layout): a moved frame whose legend can't be measured is said, no…
feat(layout): context layers out of a publication's legend, and no no…
fix(layout): review round 1 for the plain legend box and the least mo…
fix(layout): the plain-paper probe reads the background the map draws…
feat(layout): no legend box over plain paper, and a moved map kept ne…