Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Forest-cover world data

Settlement-scale forest cover comes from the Copernicus Land Monitoring Service High Resolution Layer Tree Cover and Forests, using the 2018 Tree Cover Density (TCD) and Dominant Leaf Type (DLT) products. This is modern data, used as a plausibility input for the game's 1544 setting rather than as a claim about the exact historical tree cover around a settlement.

Initialize the default playable-area coverage with:

just plan-forest-cover
just init-forest-cover
just verify-forest-cover

scripts/init_forest_cover.py reads COPERNICUS_CLIENT_ID and COPERNICUS_CLIENT_SECRET from the environment or the Git-ignored repository .env, without displaying either value. These are Sentinel Hub OAuth client credentials. They do not authorize direct CDSE OData or S3 object downloads; the initializer instead uses the official Sentinel Hub Process API and its public CLMS BYOC collections.

The authoritative playable bounds are 8.965-11.110 degrees east and 50.877-52.211 degrees north. The default integer EPSG:4326 source envelope is therefore 8-12 degrees east and 50-53 degrees north: the smallest 12 one-degree tiles that cover the playable area. Override them with --west, --south, --east, and --north. Each request is independently restartable in a staging directory. The existing source directory is replaced only after all 24 output rasters verify; the previous directory is retained below target/world-data-backups/. When an existing installation already contains valid cells from the requested envelope, preparation reuses them in staging instead of downloading them again. This makes narrowing an older broad installation cheap and preserves the broad set in the normal recoverable backup.

The prepared source inventory records the exact byte size and SHA-256 of every consumed TCD/DLT tile. A source-separated world-data bundle therefore pins the installed result even though a later invocation of the upstream processing service could produce revised bytes. The legacy release verifier still reports this source as release-blocked because it cannot independently pin the upstream Process API result before acquisition; the local prepared result is nevertheless exact and repeatably verifiable after download.

Prepared tile contract

The initializer requests the official 2018 100 m Tree Cover Density collection (edd3c5f5-da8e-463f-8c9a-712aa451d37e) directly. It derives leaf type from the official 100 m Broadleaved Cover Density (a06a42ae-f899-4a07-a5cd-fb7fd920d6c1) and Coniferous Cover Density (a0edd575-c763-4c4a-a910-631df3df4506) collections. Those density products are themselves the official aggregation of the 10 m DLT pixels. A cell is broadleaf or conifer when that type is at least 75% of its classified tree pixels, mixed otherwise, and 255 when no leaf type applies.

The resulting rasters are 1000-by-1000-pixel one-degree, EPSG:4326, RasterPixelIsArea, single-band UInt8 GeoTIFFs. This fixed 0.001-degree grid is approximately 100 m at European latitudes and makes the prepared format deterministic. They live in the Git-ignored target/world-data-sources/raw/forest-cover/ directory. A locally prepared directory contains forest-cover-manifest.json with this version marker:

{"format":"adventuresim-copernicus-forest-2018-v1"}

The pinned, externally inventoried world-data release uses the reviewed adventuresim-copernicus-forest-2018-v2 marker. V2 changes the distribution identity, not the raster interpretation: both accepted markers require the same source year, resolution, aggregation rule, class mapping, filenames, and strict GeoTIFF validation described here. Other markers and unknown manifest fields remain rejected. The local initializer continues to emit v1 and verify its separate source-inventory.json; pinned-release v2 integrity is supplied by the release descriptor and per-file bundle inventory.

Each used degree tile requires a pair named for its southwest corner:

The marker itself is not a content inventory. Local v1 preparation uses source-inventory.json; pinned v2 installation is bound by the verified world-data release inventory. Both pin every TCD/DLT tile by checked size and SHA-256 outside the marker.

  • TCD_N48_E002.tif
  • DLT_N48_E002.tif

Southern and western coordinates use S and W. Both rasters in a pair must be 1000 by 1000, have identical transforms, and span exactly one degree. TCD values are canopy percentages from 0 through 100. DLT emits 1 for at least 75% broadleaf, 2 for at least 75% coniferous, and 3 for a mixture where neither type reaches 75%. Use 255 where no leaf type applies or either source is nodata. This code 3 is part of the preparation contract; it is derived from the two official density products rather than asserted to be a raw DLT class.

The importer groups settlements by degree tile and reads only tile pairs that contain settlements. A source density of zero becomes ForestCover::Open. Positive density becomes ForestCover::Wooded(Woodland), whose bounded CanopyDensity makes zero-density woodland unrepresentable and whose required DominantLeafType is broadleaf, coniferous, or mixed. There is no unknown variant.

If density is nodata, the importer creates a deterministic plausible density from HYDE 3.5 natural/seminatural land use; cells with less than 5% natural land become open. If only leaf type is missing, elevation supplies a deterministic broadleaf/mixed/conifer fallback. The build report counts every settlement where either fallback was used. Malformed GeoTIFF structure, unsupported raster encodings, mismatched paired transforms, and missing required tiles are not silently accepted. Reserved or unclassified cell values take the documented plausible fallback path and are counted.

The settlement Map presentation may additionally generalize any installed TCD/DLT tile pairs into one naturalized forest mask at 20 percent canopy cover. It retains the exact bounded percentage in its offline inputs rather than turning presentation data into sparse/deep classes. Hilly forest is rendered dark green while flat forest is green. Production raster generation first classifies one canonical 0.001-degree canopy mask, then constructs every lower level of detail by area-averaging 2-by-2 child cells. Rendering uses bilinear sampling within a level and blends adjacent mip levels, so zooming changes the amount of retained detail without switching to a separately sampled or procedurally distorted forest mask. This is explicitly partial-coverage presentation data: absent tiles stay absent, tile coverage is recorded in the map package, and no missing regional forest is inferred from a settlement sample.

Published map and terrain packs retain the Copernicus source, modification, and no-endorsement statements in STRATEGIC_MAP_DATA_LICENSE.md, which the offline compiler writes beside every output directory. That notice must remain with redistributed bundles or be available through an equivalent prominent link.

Forest cover is stored on settlements because it describes the immediate area and can drive timber and foraging products, scene vegetation density, visibility, encounters, and fuel availability. Continuous route or canonical regional forest data still belongs in later spatial products rather than being inferred from one settlement sample; the generalized raster layer is not such a canonical world product.