Skip to content

Commit 60153a3

Browse files
bdonbdon
authored
add docs for region localization/shields (#125)
* add icons for basic US and NL shields * add docs on generating custom spritesheets * add docs on roads layer network and shield_text values
1 parent 8775ccb commit 60153a3

File tree

3 files changed

+54
-13
lines changed

3 files changed

+54
-13
lines changed

‎basemaps/flavors.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,3 +57,28 @@ Use [ES6 spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/
5757
import { namedFlavor } from "@protomaps/basemaps"
5858
let flavor = {...namedFlavor("light"),buildings:"red"}
5959
```
60+
61+
## Sprites
62+
63+
Each of the five default Flavors has an associated spritesheet. Sprites are necessary for displaying:
64+
65+
* Townspots - circles for cities and named places at low zoom levels.
66+
* Highway shields - Shields are localized for different countries and road classes. See [shields](layers#shields).
67+
* Points of interest - used for the `light` and `dark` flavors only.
68+
69+
Spritesheets are designed according to the [MapLibre Sprite specification](https://maplibre.org/maplibre-style-spec/sprite/). Because these sprites are stored in a static PNG image, the colors are pre-rendered to match the associated basemap Flavor.
70+
71+
A spritesheet can be generated by building the program in [basemaps/sprites](https://github.com/protomaps/basemaps/tree/main/sprites):
72+
73+
```sh
74+
cargo build # creates the binary target/release/spritegen
75+
make # builds all 5 default flavor spritesheets in dist/
76+
# Create a new JSON in flavors/custom.json and customize the colors...
77+
./target/release/spritegen refill.svg flavors/custom.json dist/custom
78+
```
79+
80+
A custom spritesheet (`custom.json`, `custom.png`, `custom@2x.json`, `custom@2x.png`) can be referenced from a [MapLibre JSON style](maplibre):
81+
82+
```js
83+
sprite: "https://example.com/assets/custom"
84+
```

‎basemaps/layers.md‎

Lines changed: 29 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -349,18 +349,19 @@ railways and piers from OpenStreetMap. This layer represents built infrastructur
349349

350350
<MaplibreMap highlightLayer="roads" :zoom=13 :showZoom="true" :lat="35.68" :lng="139.76"/>
351351

352-
| Key | Values | Description |
353-
| -------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ----------: |
354-
| `kind` | See kinds below | |
355-
| `kind_detail` | `motorway`, `motorway_link`, `trunk`, `trunk_link`, `primary`, `primary_link`, `secondary`, `secondary_link`, `tertiary`, `tertiary_link`, `residential`, `service`, `unclassified`, `road`, `raceway`, `pedestrian`, `track`, `path`, `cycleway`, `bridleway`, `steps`, `corridor`, `sidewalk`, `crossing`, `driveway`, `parking_aisle`, `alley`, `drive-through`, `emergency_access`, `utility`, `irrigation`, `slipway`, `cable_car`, `pier`, `runway`, `taxiway`, `disused`, `funicular`, `light_rail`, `miniature`, `monorail`, `narrow_gauge`, `preserved`, `subway`, `tram` | |
356-
| `ref` | string | |
357-
| `shield_text_length` | int | |
358-
| `network` | string | |
359-
| `oneway` | string | |
360-
| `service` | `siding`, `crossover`, `yard` | |
361-
| `is_link` | boolean | |
362-
| `is_tunnel` | boolean | |
363-
| `is_bridge` | boolean | |
352+
| Key | Values | Description |
353+
| ------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -----------------------: |
354+
| `kind` | See kinds below | |
355+
| `kind_detail` | `motorway`, `motorway_link`, `trunk`, `trunk_link`, `primary`, `primary_link`, `secondary`, `secondary_link`, `tertiary`, `tertiary_link`, `residential`, `service`, `unclassified`, `road`, `raceway`, `pedestrian`, `track`, `path`, `cycleway`, `bridleway`, `steps`, `corridor`, `sidewalk`, `crossing`, `driveway`, `parking_aisle`, `alley`, `drive-through`, `emergency_access`, `utility`, `irrigation`, `slipway`, `cable_car`, `pier`, `runway`, `taxiway`, `disused`, `funicular`, `light_rail`, `miniature`, `monorail`, `narrow_gauge`, `preserved`, `subway`, `tram` | |
356+
| `ref` | string | |
357+
| `shield_text` | string | see [shields](#shields) |
358+
| `network` | string | see [shields](#shields) |
359+
| `oneway` | string | |
360+
| `service` | `siding`, `crossover`, `yard` | |
361+
| `is_link` | boolean | |
362+
| `is_tunnel` | boolean | |
363+
| `is_bridge` | boolean | |
364+
364365

365366
### Kinds
366367

@@ -376,6 +377,22 @@ railways and piers from OpenStreetMap. This layer represents built infrastructur
376377
| `rail` |
377378
| `aeroway` |
378379

380+
### Shields
381+
382+
The `network` and `shield_text` are designed for displaying localized highway shields. The values are derived from the OpenStreetMap `ref` tag, and a spatial join with administrative boundaries.
383+
384+
Example `network` values:
385+
386+
| Value | Sprite | Description |
387+
| ----------- | :-------------------------------------------------: | ------------------------------------------------------------------------------------------------------------ |
388+
| `US` | | United States [Numbered Highway System](https://en.wikipedia.org/wiki/United_States_Numbered_Highway_System) |
389+
| `US:I` | <Icon kind="US:I-1char" :sprites="sprites"/> | United States [Interstate Highway System](https://en.wikipedia.org/wiki/Interstate_Highway_System) |
390+
| `NL:S-road` | <Icon kind="NL:S-road-1char" :sprites="sprites"/> | Dutch S-road network |
391+
|
392+
|
393+
394+
For example, an [OpenStreetMap way](https://www.openstreetmap.org/way/584348895) with the tag `ref=S100` where the way is contained within the Netherlands polygon as defined by [ideditor.codes](https://ideditor.codes) will gain the tags `network=NL:S-road`, `shield_text=S100`.
395+
379396
## transit
380397

381398
Lines representing scheduled passenger services suitable for rendering on the map, even at lower zoom levels. For physical infrastructure, like highways and railways, see the [roads](#roads) layer.

‎basemaps/localization.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -297,4 +297,3 @@ For example, to localize a map to Dutch (nl) and French (fr), one can use the fo
297297
["coalesce", "name:nl", "name:fr"],
298298
]
299299
```
300-

0 commit comments

Comments
 (0)