# Data provenance and attribution

This document defines operational attribution and provenance requirements. The source-by-source commercial license review is maintained separately in [Data licensing policy and verification](licensing.md).

## Approved pilot sources

- ICGC 0.5 m Terrain Elevation Model, CC BY 4.0.
- ICGC Model d'Elevacions del Terreny de Catalunya 5 × 5 m v1.0, CC BY 4.0, for the Catalunya baseline.
- IGN/CNIG PNOA MDT05 first coverage, under the reuse license established by Orden FOM/2807/2015 and identified by CNIG as compatible with CC BY 4.0, for four bounded Catalunya gap fills.
- Current definitive ICGC Territorial Orthophoto, conditionally approved under CC BY 4.0 pending verification of the exact downloaded product metadata.
- ICGC Territorial Topography 3D is downloaded for evaluation but is not yet approved; exact product license metadata and attribution must be archived and reviewed first.
- OpenStreetMap planet extracts, ODbL 1.0.
- Copernicus DEM GLO-30 as a global fallback under the Copernicus WorldDEM-30 license.

FABDEM is excluded from production because its CC BY-NC-SA 4.0 license does not permit commercial use.

## Application attribution

When OSM-derived trails or features are visible, show this readable attribution in or adjacent to the map:

```text
© OpenStreetMap contributors
```

Link it to `https://www.openstreetmap.org/copyright`. The Data licenses panel must also identify ODbL 1.0.

For the Catalunya terrain composite:

```text
Derived from ICGC MET5, used under CC BY 4.0, with IGN/CNIG PNOA MDT05 sheets 0118B, 0448, 0473, and 0547 used under its CC BY 4.0-compatible reuse license.
```

For ICGC-derived imagery:

```text
Derived from the Orthophoto of Catalonia of the Institut Cartogràfic i Geològic de Catalunya (ICGC), used under CC BY 4.0.
```

Each notice must link to its source and license and state the actual modifications performed. Copernicus fallback terrain requires the longer source and liability notices recorded in [`licensing.md`](licensing.md#4-copernicus-dem-glo-30).

Each high-resolution walking-area build displays the ICGC notice in the page footer. Regular La Mola and Montserrat builds create exact crops from the unified VRT, derive L0–L3 terrain quadtrees and 4096² slope-normal textures, and convert geometry to tile-local coordinates. The optional unified sparse build first applies the public dissolved coverage mask, derives a quantized sparse terrain quadtree, and derives one lossless 512² normal tile for every terrain key. Runtime performs mesh generation, streamed normal-page selection, lighting, and elevation/slope coloring. Machine-readable runtime records live in each registered area directory, including [`static/assets/la-mola/terrain.json`](../static/assets/la-mola/terrain.json) and [`static/assets/montserrat/terrain.json`](../static/assets/montserrat/terrain.json).

The Catalunya baseline preserves all provider archives, nested CRC validation, SHA-256, per-sheet ISO XML, normalized COGs, VRT, coverage database, and inventories outside Git. An audit against the official ICGC 1:5,000 administrative boundary found land gaps caused by unavailable or ambiguous ICGC sheet variants. Original IGN/CNIG PNOA MDT05 sheets `0118B`, `0448`, `0473`, and `0547` are preserved with checksums; `0118B` is reprojected from EPSG:25830 to EPSG:25831 and all four enter a source-specific-nodata VRT after ICGC MET5. A 100 m coverage audit leaves approximately 2.01 km² split among 172 tiny components, none larger than 0.05 km². At runtime-tile resolution, every official-boundary tile except one 37.6 m² boundary sliver has terrain coverage.

Runtime assets are bilinearly sampled into sparse 1,024 m L9 leaves, reconciled at shared edges, quantized to little-endian UInt16 at 0.1 m precision with a -100 m offset, paired with per-sample validity bitsets, gzip-compressed, and aggregated through L5 parents. Candidate selection uses the official ICGC boundary plus a 1,024 m terrain buffer; the buffer avoids an artificial vertical wall at the administrative line while excluding unrelated source-sheet coverage. Exact source `-8888` values are treated as secondary nodata; nearest-valid heights are retained only as reconstruction values beneath masks and are not rendered as source coverage. The 43,477-tile manifest records both providers, licenses, boundary source and scale, vertical-reference note, bounds, encoding, and transformations.

The Catalunya renderer composes registered 0.5 m-source terrain, slope-normal, and OSM assets in the national terrain frame. The committed fallback translates separate La Mola and Montserrat assets; the optional unified sparse asset replaces them when installed. Valid resident high-resolution fragments write scene depth before a slightly depth-biased national pass, so the national surface fills invalid or unavailable sparse samples rather than being removed by approximate rectangles. ICGC terrain and OSM feature assets retain their manifests, licenses, and attribution independently.

The optional Catalunya terrain-context apron is a separate Copernicus DEM GLO-30 derivative. It samples the public 2021 AWS COG distribution into independent low-detail EPSG:25831 terrain tiles, clips them to a configured buffer outside the ICGC/IGN Catalunya surface, and preserves the mandatory Copernicus attribution and liability notices in its manifest. At runtime, the separate ODbL coastline mask clips both national and apron geometry to the same OSM shoreline, preventing coarse Copernicus coastal elevations from protruding into the rendered sea. The apron does not alter or replace the national ICGC/IGN terrain asset.

The optional ground-material set is a separate ODbL derivative database and Produced Work assembled from the local Catalunya OSM extract. The builder selects noninteractive ground polygons; projects them to EPSG:25831; rasterizes a terrain-root-aligned L3–L5 pyramid with a pinned L3 base and 4-pixel neighbor-rendered gutters; and encodes RGBA WebP with exact alpha. Its manifest retains a generation identity, page and source checksums, source feature counts, transformation description, ODbL URI, and OpenStreetMap attribution. Roads, trails, waterways, boundaries, buildings, POIs, labels, routes, and picking remain separate runtime layers.

The Catalunya coastline is a separate ODbL runtime database derived from `natural=coastline` in the local `planet-260803` OSM snapshot. `osmium tags-filter` creates a coastline-only PBF from the Catalunya extract; `scripts/build_osm_coastline_mask.py` assembles directed ways using OSM's land-on-left convention, transforms them to EPSG:25831, closes the mainland chain outside the Catalunya extraction against the terrain root, and writes machine-readable land polygons plus a sparse terrain-aligned bitset pyramid. The L9 masks sample terrain vertex positions at approximately 4 m, then reconcile shared edges and derive L2–L8 parents from even child samples. The overview-enabled runtime contains 1,290 mixed masks and 159 explicit sea markers; 42,100 terrain tiles use an implicit all-land mask. Source and filtered-extract SHA-256 values, generation identity, commands, transformations, ODbL URI, and attribution are retained in the external provenance record and runtime manifest under `osm/processed/catalunya-coastline/`. The browser combines this OSM mask with DEM validity at render time, so the OSM derivative remains separable from ICGC/IGN terrain.

```bash
osmium tags-filter -O -o coastline.osm.pbf catalunya.osm.pbf w/natural=coastline
python3 scripts/build_osm_coastline_mask.py coastline.osm.pbf \
  static/assets/catalunya/terrain.json runtime --source-snapshot planet-260803
```

The La Mola, Montserrat, and optional unified public high-resolution trail and POI overlays were extracted from local snapshot `planet-260803.osm.pbf`, clipped to their configured terrain extents, transformed to EPSG:25831 tile-local coordinates, and vertically draped over the corresponding masked ICGC DEM. Trail ribbons preserve style IDs, cumulative distance, surface, track grade, access, bridge, and tunnel state. POIs preserve their OSM node or way identity, source coordinates, source tag, relevant hiking/access tags, OSM elevation, and sampled DEM elevation. Parking ways use polygon centroids and are included only when `access=yes` and a name or capacity is present. The OSM overlays remain separate static assets under ODbL 1.0; they are not merged into ICGC terrain. Runtime provenance and POI inclusion rules are recorded in each walking area's `osm/overlay.json` manifest.

The OSM road layers convert drivable highway centerlines into terrain-draped style ribbons. They preserve highway, surface, access, service, bridge, tunnel, and layer tags; runtime WGSL derives scale-dependent casing and fill widths. They remain separate ODbL assets with runtime provenance in each walking area's `osm/roads/roads.json`.

Roads, trails, buildings, labels, and POI symbols use an adaptation of OpenStreetMap Carto `v6.0.0`, pinned to commit `7d2926a85acd07c0a4051f3d444ebe2b59c0676e`. OpenStreetMap Carto's software, associated documentation, and cartographic design are CC0 1.0. The vendored, unmodified SVG subset and upstream notice are recorded in [`static/assets/osm-carto-v6/`](../static/assets/osm-carto-v6/). CC0 governs the style and symbols only; the styled OSM-derived feature data remains under ODbL 1.0.

The OSM building layers are also separate ODbL assets. They convert closed building ways to terrain-aligned wall and roof triangles. Heights use explicit `height`, then `building:levels × 3 m`, then documented type defaults because almost all local footprints lack height tags. Runtime provenance and complete per-feature height sources are recorded in each walking area's `buildings/osm/buildings.json`. Do not merge these assets with a future ICGC building asset; retain independent source layers and provide source selection/comparison in the application.

## Provenance record

For every downloaded source and generated release, record:

- provider and exact product name/version;
- source URL and retrieval timestamp;
- coverage and acquisition date;
- checksum;
- license identifier, URL, attribution, and legal notices;
- horizontal CRS and vertical reference;
- nodata semantics and resolution;
- complete transformation history;
- generated release identifier.

Do not publish an asset whose exact source metadata has not been archived.

## Local data policy

Raw downloaded geodata and generated tiles can be large. Keep them out of git by default.

Repository paths such as `data/raw/` and `data/processed/` are suitable only for small metadata, recipes, and examples. Large local source data lives under:

```text
/media/ominiverdi/usb4t/muntanya/
```

The ICGC 0.5 m terrain collection uses one product-wide inventory rather than place-named source directories. Original pieces remain separate and are exposed as one logical VRT mosaic, with footprints in `coverage.gpkg` and provenance in `inventory.json`. Named areas are requested/target polygons, not containers for source files. See [ICGC local source inventory](icgc-local-data.md).

Never commit private GPS-test bounds or other data that reveals a home location.