Layers and Targets¶

Layer configuration files define layer definitions (reusable data source + processing config) and build targets (what to produce). They reference source IDs from source config files.

Concepts¶

Layers (definitions)¶

Layer definitions describe what data to use and how to process it. They are reusable and have no output file or exporter — they are purely definitions.

Targets (build instructions)¶

Build targets describe what to produce. Each target specifies an output file, an exporter, and an ordered list of layer entries. A target can reference defined layers (by ref) or define layers inline.

Single-layer targets are the simplest case — one layer entry producing one file. Composite targets combine multiple layer entries, blended bottom-to-top using alpha compositing (painter's algorithm).

File structure¶

A typical layer config file has three sections:

includes:
  - ../sources/swisstopo.yaml

# Default bounding box for all layers/targets in this file
bounds:
  west: 5.96
  east: 10.49
  south: 45.82
  north: 47.81

# Layer definitions (reusable, no output)
layers:
  my_basemap:
    name: "My Basemap"
    format: wmts
    source:
      ref: my_wmts
      layer: ch.swisstopo.pixelkarte-farbe
    zoom_levels: [8, 9, 11, 12, 13, 14, 15, 16]

  my_overlay:
    name: "My Overlay"
    format: wmts
    source:
      ref: my_wmts
      layer: ch.swisstopo.skiroutes
      extension: png
    zoom_levels: [11, 12, 13, 14, 15, 16]

# Build targets (what to produce, with output files)
targets:
  my_map:
    name: "My Map"
    output: my_map.img
    zoom_levels: [8, 9, 11, 12, 13, 14, 15, 16]
    layers:
      - ref: my_basemap
      - ref: my_overlay
        opacity: 0.6
        zoom_levels: [13, 14, 15, 16]

Includes¶

The includes directive loads other config files (typically source definitions). Paths are relative to the current file. Includes are processed depth-first with last-file-wins merge semantics.

File-level bounds¶

A top-level bounds key sets default bounds for all layers and targets in the file. Individual layers and targets can override this.

There are two formats for bounds:

Anonymous bounds (file-level default, backward compatible):

bounds:
  west: 5.96
  east: 10.49
  south: 45.82
  north: 47.81

Named bounds (reusable, slug-referenced):

bounds:
  switzerland:
    west: 5.96
    east: 10.49
    south: 45.82
    north: 47.81
  bern:
    west: 7.31
    east: 7.57
    south: 46.88
    north: 47.06

The loader auto-detects the format: if all keys are in {west, east, south, north}, it's anonymous; otherwise it's named bounds.

Layers and targets can reference named bounds by slug:

layers:
  my_layer:
    name: "My Layer"
    source: my_source
    zoom_levels: [10, 12]
    bounds: switzerland   # references the named bounds above

Or use inline coordinates:

targets:
  my_target:
    output: out.img
    layers: [...]
    bounds:               # inline coordinates
      west: 7.0
      east: 8.0
      south: 46.5
      north: 47.0

Named bounds are merged across includes with last-file-wins semantics.

Layer definitions¶

Each entry under layers: is a named, reusable definition:

layers:
  ch_basemap:
    name: "Switzerland Basemap"
    description: "Swisstopo national map"
    format: wmts
    source:
      ref: swisstopo_wmts
      layer: ch.swisstopo.pixelkarte-farbe
    zoom_levels: [8, 9, 11, 12, 13, 14, 15, 16]

Layer fields¶

Source reference¶

The source field can be a string (source ID) or a dict with a ref key plus variable overrides:

# String form
source: my_wmts

# Dict form (with variable overrides)
source:
  ref: my_wmts
  layer: ch.swisstopo.pixelkarte-farbe
  extension: png

When using the dict form, all keys except ref become source_args — these override source defaults for template variable resolution.

Format field¶

The format field determines how the data is processed:

Backward compat fields¶

• wmts_layer — maps to source_args.layer
• extension — maps to source_args.extension

If both a shorthand field and source_args are provided, source_args takes precedence.

Build targets¶

Each entry under targets: defines what to build:

targets:
  my_map:
    name: "My Map"
    output: my_map.img
    zoom_levels: [8, 9, 11, 12, 13, 14, 15, 16]
    layers:
      - ref: my_basemap

Target fields¶

Zoom levels and bounds inheritance¶

Targets can omit zoom_levels and bounds. When omitted:

• zoom_levels: Resolved from the union of all referenced layer definitions' zoom levels
• bounds: Resolved from the enclosing bounding box of all referenced layer definitions' bounds

This keeps targets DRY — the data source definitions own the zoom/bounds, and the target just says "build them all."

Layer entries¶

Each item in a target's layers: list is either a ref entry or an inline entry:

Ref entry¶

References a top-level layer definition. Optional overrides for zoom_levels and opacity:

- ref: my_basemap
  zoom_levels: [8, 9, 11]
  opacity: 0.8

Inline entry¶

Defines a layer directly in the target (no top-level layer definition needed):

- name: "Overlay"
  format: wmts
  source:
    ref: my_wmts
    layer: ch.swisstopo.skiroutes
    extension: png
  zoom_levels: [13, 14, 15, 16]
  opacity: 0.6

Entry fields¶

An entry must have either ref or source, but not both.

Opacity¶

Opacity controls how transparent a layer entry appears in composite targets:

• Uniform: a float between 0.0 (fully transparent) and 1.0 (fully opaque)
• Per-zoom: a mapping from zoom level to opacity value

opacity: 0.6                    # uniform
opacity: {12: 0.3, 14: 0.8}    # per-zoom

Tile fallback¶

When a layer entry declares a zoom level but a specific tile is unavailable (404 from server), the system automatically falls back to the closest lower zoom level in the entry's zoom_levels list and upscales that tile. If no lower-zoom fallback exists, the entry is skipped for that tile position.

Fallback only applies when the zoom level is declared but the tile is missing. Zoom levels intentionally omitted from zoom_levels are not subject to fallback.

Products¶

A products section defines product catalogs for server-side use (e.g., pricing, download tokens). This section is optional and ignored by the CLI pipeline — it exists for the server to consume.

products:
  outdoor-summer:
    name: "Outdoor Summer"
    price: 25.0
    currency: CHF
    targets: [ch_outdoor_summer]
    token_max_downloads: 10
    token_expiry_days: 60
    sort_order: 1

Product fields¶

All product target references are validated — a product referencing a nonexistent target slug will raise an error at config load time. Products are merged across includes with last-file-wins semantics.

Complete example¶

includes:
  - ../sources/swisstopo.yaml

bounds:
  west: 5.96
  east: 10.49
  south: 45.82
  north: 47.81

layers:
  basemap:
    name: "Switzerland Basemap"
    format: wmts
    source:
      ref: swisstopo_wmts
      layer: ch.swisstopo.pixelkarte-farbe
    zoom_levels: [8, 9, 11, 12, 13, 14, 15, 16]

  hiking:
    name: "Hiking Trails"
    format: wmts
    source:
      ref: swisstopo_wmts
      layer: ch.swisstopo.swisstlm3d-wanderwege
      extension: png
    zoom_levels: [11, 12, 13, 14, 15, 16]

  skiroutes:
    name: "Skiroutes"
    format: wmts
    source:
      ref: swisstopo_wmts
      layer: ch.swisstopo-karto.skitouren
      extension: png
    zoom_levels: [11, 12, 13, 14, 15, 16]

targets:
  winter_map:
    name: "Switzerland Winter Outdoor"
    output: ch_winter.img
    zoom_levels: [8, 9, 11, 12, 13, 14, 15, 16]
    layers:
      - ref: basemap
      - ref: hiking
        opacity: {13: 0.4, 14: 0.6, 15: 0.7, 16: 0.7}
        zoom_levels: [13, 14, 15, 16]
      - ref: skiroutes
        opacity: {13: 0.5, 14: 0.6, 15: 0.7, 16: 0.7}
        zoom_levels: [13, 14, 15, 16]

  simple_basemap:
    output: ch_basemap.img
    layers:
      - ref: basemap

Note how simple_basemap omits zoom_levels and bounds — they are inherited from the referenced basemap layer definition.