DOCSEARCHbyAlgolia
Submit Docs

Protomaps Basemaps

repository·main·Indexed 20 days ago

https://github.com/protomaps/basemaps

A toolset for building cartographic basemap PMTiles from OpenStreetMap and other data sources, including MapLibre GL styles for browser display. The project features a Planetiler build profile for generating tiles, a TypeScript package for multi-theme styles, and a single-page application for viewing and downloading basemap builds.

Tokens
9.6K
Snippets
33
Records
44
Agent score
69%

What's inside protomaps-basemaps

  1. Overview of Protomaps Basemaps

    main

    Protomaps Basemaps is a toolset for building cartographic 'basemap' PMTiles from OpenStreetMap and other data sources, along with MapLibre styles for browser-based display.

    The repository consists of three main components:

    • app: A single-page application for viewing and downloading basemap builds.
    • tiles/: A Planetiler build profile that generates planet.pmtiles from OpenStreetMap and Natural Earth.
    • styles/: A TypeScript package that generates MapLibre GL styles in multiple color themes, available via npm or as exported JSON.

    Note that assets like fonts and sprites are managed in a separate repository: protomaps/basemaps-assets.

  2. Licensing and Attribution Guidelines

    main

    When using Protomaps Basemaps, adhere to the following licensing rules:

    • Code: BSD-3 license. Retain all license notices in derived source code.
    • Map Design: CC0 (Public Domain). You can use the visual design without attribution, though it is appreciated.
    • Tilesets: ODbL. You must visibly attribute © OpenStreetMap (e.g., in the corner of the map display) if your map uses OpenStreetMap data.
    • Naming: If you distribute a modified 'fork' of these styles/tilesets or a tiles API based on them, you must name your product something different from 'Protomaps'.

    Example web map corner attribution:

    <a href="https://github.com/protomaps/basemaps">Protomaps</a> © <a href="https://openstreetmap.org">OpenStreetMap</a>

  3. Understand what is NOT versioned in Protomaps Basemaps

    main

    Certain changes in the map data do not trigger a version bump in the Protomaps Basemap API or Tilezen service. Developers should be aware of these to avoid unnecessary integration cycles.

    Individual Features

    Changes to specific features are not versioned. This includes:

    • Adding or removing a specific feature.
    • Changing a feature's name, geometry, or property values.
    • Changes to a feature's kind or min_zoom/max_zoom due to upstream data reclassification.

    Tip: You can investigate upstream changes by checking a feature's source and id properties.

    Languages

    While specific language keys are provided, the availability of additional localized names (as common-optional or optional) is not versioned.

    Political Geography

    Changes to political boundaries are not versioned. This includes:

    • Major changes: Additions/deletions of country names, borders, disputed territories, or capitals.
    • Minor corrections: Administrative geography corrections.

    Data Updates

    Data updates from primary sources (Natural Earth, OpenStreetMap, OpenStreetMapData) are handled via the Tilezen service versioning, not the Basemap schema versioning.

  4. Understand versioned vs non-versioned test artifacts

    main

    When interpreting test results, be aware of which components are versioned and which are environmental:

    Versioned Artifacts:

    • The tile archive.
    • Named style layers.

    Non-versioned components (affecting test runs):

    • The current examples.json configuration.
    • The smalltestregion.osm.pbf (affects covered areas and OSM snapshot date).
    • The maplibre-gl-js version.
    • Font glyphs and sprite assets used by the style.

  5. Identify Protomaps Basemap Schema Changes by Version Type

    main

    The Protomaps Basemap vector tile schema is categorized into three property/layer tiers: common, common-optional, and optional. Version increments are determined by how these tiers are modified.

    MAJOR Version Increments (Breaking Changes)

    Expect significant integration work if any of the following occur:

    • Removal or Renaming: Removing or changing names of common or common-optional layers or properties.
    • Property Removal: Removing common properties from all zooms, or removing common-optional/optional properties at zoom 14 or higher.
    • Kind Changes: Changing kind value names, removing kind values, or moving a kind from one layer to another.
    • Zoom/Font Changes: Significant changes to default min_zoom/max_zoom values or changing positioned glyph font versions.

    MINOR Version Increments (Backwards-Compatible Additions)

    Expect low integration effort for these additions:

    • Additions: Adding new common, common-optional, or optional layers/properties, or adding new kind values.
    • Simplification: Adding additional simplification to kind values at specific zoom levels (e.g., zooms $\le$ 13).
    • Zoom/Font Changes: Changing the maximum Tilezen zoom or adding new positioned glyph font scripts.

    PATCH Version Increments (Bug Fixes & Minor Adjustments)

    No integration effort should be required:

    • Optional Layer Changes: Adding, renaming, or removing optional layers.
    • Reassignment: Reassigning kind values when they are equivalent (e.g., fixing spelling) or minor reassignments of features.
    • Map Balance: Adjustments to overall map balance or correcting API regressions.

  7. Load local sprites in the basemaps viewer

    main

    To preview generated sprites in the basemaps viewer:

    1. Start the viewer by running npm run dev in the /app directory.
    2. In the viewer interface, check the "local sprites" checkbox. This instructs the application to load sprites from the /sprites/dist directory.

  9. Update expected test images

    main

    If the visual output of a test has changed intentionally and you need to update the baseline expected.png images, run the test command with the UPDATE=true environment variable. This instructs the runner to overwrite the existing expected.png files with the current actual.png outputs.

    UPDATE=true npm run test

  10. Build the spritegen binary

    main

    The spritegen tool is written in Rust. To build the binary, you must have a Rust compiler installed. Run the following command from the repository root to create the executable in the target/release directory.

    cargo build --release

  11. Run and view render test results

    main

    After running npm run test, a results.html file is generated. You can view these results by serving the current directory with a local web server:

    npx serve .

    In GitHub Actions, the results.html file is provided inside a zip container at the end of the run, allowing you to inspect the exact pixels generated in the CI environment.

  12. Understand Protomaps Basemap Semantic Versioning

    main

    Protomaps uses Semantic Versioning (SemVer) to communicate the level of effort required to integrate new basemap tiles. The version format is MAJOR.MINOR.PATCH (e.g., 1.0.0).

    Developer Effort by Version Type

    Version IncrementEffort LevelAction Required
    MAJOR (X.0.0)HighSignificant integration challenges; read the changelog closely.
    MINOR (0.Y.0)LowSome integration challenges; read the changelog.
    PATCH (0.0.Z)NoneSimply use the new tiles; skim or ignore the changelog.
    Pre-release (-POSTFIX)Low to HighVaries; read the changelog.

    Note: These rules apply after version 1.0.0 has been reached.