River names that fit their line: abbreviate when short, spread when long, pick the straightest stretch, repeat on long rivers

Open
#2,265 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
rust
Domain
design

Research direction

Read the related issues #2259 and #2262, especially PR #2260, to understand the existing curved-label and stretch behavior. Then inspect the line-label placement code and tests for labels.placement; the proposal’s tests describe the expected cases, including unchanged behavior with fit off. Done means implementing and testing all five fit rules, including abbreviation, spacing, placement, and repeats.

Written by the indexing model from the issue text.

Description

Context: hand-lettered maps name streams by how much line there is for the name. Short creeks in steep country get an abbreviated name, close-set, on their straightest stretch. Long creeks get the full name with letters spread. Sinuous channels in flat land get a name spread along their general course. A main river is named more than once. RustGIS's line labels place the whole name at the line's middle, or repeated at a fixed repeat distance, with a fixed letter spacing. This proposal adds the rules that tie the label to the room its line gives. It builds on #2259 (PR #2260: a curved label anchored to a smoothed course, smoothing and allowed drift growing with the letter pitch) and on stretch from #2262.

Proposal

One new setting on labels.placement for line layers, "fit": "auto" (default "off", today's behaviour), which applies these rules in order to each line:

  1. Room: the longest stretch of the line, on screen, that a curved label can follow (#2259's checks), and the straightest stretch at least as long as the text. Straightness is the ratio of the stretch's end-to-end distance to its length along the line.
  2. Abbreviate when it doesn't fit: if the full name is longer than every stretch, the generic part is replaced by its abbreviation from a list, then tried again. An example list is Córrego → Cór., Ribeirão → Rib., Creek → Cr., River → R., Canyon → Cyn. It is given with "abbreviations": {"Creek": "Cr.", …}, matched as whole words, and a built-in list covers English, Portuguese and Spanish. If it still doesn't fit, the line isn't labelled, as today.
  3. Close-set on the straightest stretch: when the text takes more than about a third of the room, it is placed close-set (the class's own spacing) on the straightest stretch, beside the line as lineOffset says.
  4. Spread when there is room: when the room is more than about three times the text, the letters are spread to cover stretch of it (default 0.6), capped at about three letter widths between letters. The label is set on the line itself, along its smoothed course (#2259's rule: smoothing and drift grow with the letter pitch). Between these two thresholds, the spacing grows smoothly from one case to the other.
  5. Repeat on long lines: a line whose room is more than two spread labels long gets more than one, spaced as repeat says. The first is spread and the others are close-set near its ends, as a river is often named once along its valley and again near its mouth.

Text size by the stream's importance (a Strahler order or a class field) already works with label classes or labels.by "size". The proposal only documents it next to fit.

Example
labels.placement={"layer": "Rios", "position": "curved", "fit": "auto", "repeat": 400}
labels.style={"layer": "Rios", "italic": true, "stretch": 0.6}
labels.by={"layer": "Rios", "size": "6 + ordem"}
Tests
  • A short wiggly line with a long name gets the abbreviated name, close-set, on its straightest stretch.
  • A long smooth line gets the full name spread over about 60 % of it.
  • A very long line gets a spread label plus close-set repeats.
  • A line too short even for the abbreviation gets no label.
  • With fit off, every existing line-label test passes unchanged.
Choices in this proposal
  • One setting, not five: the rules only make sense together (abbreviating, spreading and the stretch chosen depend on the same room), so "fit": "auto" turns them on as a set. spacing, stretch, repeat and lineOffset keep their meaning, and fit reads them.
  • Thresholds from the text length, not fixed points: "a third" and "three times" the text's length scale with the label size and the map scale, so the same layer looks right at any zoom.
  • Abbreviation as a word list: predictable and editable per map. Truncating names automatically would be guessing.
  • Straightness for close-set labels, length for spread ones: a short name reads best on a straight piece; a spread name needs a long course, and the smoothing of #2259 deals with its bends.
  • Related: #2259, #2262 (stretch), #995 (placement candidates), #1187 (line labels along and off the line).
Dominant language
Rust
Stars
1.9k
Forks
268
Avg merge
11h 1m
Merged PRs (30d)
942

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from opengeos/RustGIS

All issues in opengeos/RustGIS

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.