Configuration Reference¶

PASSAGE is configured through config/config.yaml. The shipped file is the configuration that built PASSAGE v1.0. This page documents every key, in the order of the generation workflow.

How generate Reads This File¶

The key generation.dataset_version selects the generator that built PASSAGE v1.0 (the release generator). Keep the value shipped in config/config.yaml: another value stops passage generate with an error, and without the key passage generate runs another generation path, which the v1.0 release does not use.

The release generator also checks three rules before it starts:

• exactly three solvers, with unique names and the objectives elevation, energy and slope_uphill;
• diagonal_movement: always for every solver;
• obstacles.impassable: true.

Some keys stay in the file but are not read by the v1.0 release generator:

solvers[].diagonal_movement is read only to check that it is always.

Resolutions¶

resolutions:
  - 64
  - 128
  - 256
  - 512
  - 1024
  - 2048
  - 4096

List of crop sizes to generate. A resolution \(R\) produces scenes of \(R \times R\) cells. With 30 m cells, the nominal side is \(R \times 30\) m; the actual ground spacing varies with latitude.

A source tile holds 3600 × 3600 cells. A crop is cut wherever it falls, so it can span two tiles per axis; a 4096 crop, wider than one tile, can span three.

Sample Counts¶

num_samples:
  64: 1000000
  128: 1000000
  256: 1000000
  512: 1000000
  1024: 250000
  2048: 100000
  4096: 50000

Number of scenes to generate per resolution: 4,400,000 in total. The value can be a single integer (applied to every resolution) or a per-resolution mapping.

Splits¶

splits:
  enabled: true
  ratios:
    train: 0.9
    calibration: 0.02
    validation: 0.04
    test: 0.04
  seed: 42

See Splits for the geographic rules.

Hold-Out Region¶

hold_out:
  enabled: true
  mask_path: assets/hold_out_mask.png

The mask is a 181 × 361 pixel PNG with one pixel per degree: row 0 is latitude +90°, column 0 is longitude −180°. Non-zero pixels mark hold-out tiles. Tiles inside the mask belong to the test split only, and every test scene comes from them. Supply an authorised mask at the configured path; it is not included in every source distribution. For the legacy generator, use a 1-bit, grayscale, RGB or RGBA PNG; RGB channels must agree. When hold-out filtering is enabled, a missing, unreadable or invalid mask stops generation.

The public PASSAGE v1.0 hold-out mask is available separately from the dataset repository. To obtain it manually at the default path and verify its bytes before generation:

mkdir -p assets
test ! -e assets/hold_out_mask.png && test ! -L assets/hold_out_mask.png || { echo "Mask path already exists; verify it separately"; exit 1; }
curl --fail --location --output assets/hold_out_mask.png \
  https://huggingface.co/datasets/thalesgroup/passage/resolve/v1.0/assets/hold_out_mask.png
printf '%s  %s\n' \
  d53526b04dfa23767b8558126a4372cf7ab96c593079e149a63c497df633715d \
  assets/hold_out_mask.png | sha256sum --check

Do not proceed if the download or hash check fails. The mask is a geographic control, not a test scene; obtaining it does not read the test split. Review the dataset terms and datasheet for the applicable use conditions. Generation does not download the mask automatically.

Generation¶

generation:
  dataset_version: passage-successor-v1
  seed: 42
  max_scene_attempts: 100
  max_reference_expansions: null
  geographic_policy:
    block_degrees: 5
    buffer_tiles: 1
  preview_images:
    enabled: true
    resolutions: [64, 128, 256, 512, 1024, 2048, 4096]
    num_samples_per_split: 64

Solvers¶

solvers:
  - name: astar_elevation
    backend: grid
    diagonal_movement: always
    max_marker_retries: 10
    solver: astar
    cost_model: elevation
    weight: 62.4
    heuristic: euclidean
  - name: astar_energy
    backend: grid
    diagonal_movement: always
    max_marker_retries: 10
    solver: astar
    cost_model: energy
    weight: 1125.3
    heuristic: euclidean
  - name: astar_slope
    backend: grid
    diagonal_movement: always
    max_marker_retries: 10
    solver: astar
    cost_model: slope_uphill
    weight: 8886.2
    heuristic: euclidean

Each entry of the list defines one objective:

Every label comes from an exact A* reference that computes in float64. See Cost Models for the formulas and Solvers & Heuristics for the solvers.

Obstacles¶

obstacles:
  enabled: true
  ratio_max: 0.30
  shape:
    size:
      min_ratio: 0.02
      max_ratio: 0.25
    n:
      min: 1.0
      max: 80.0
      distribution:
        type: log_uniform
  generation:
    max_attempts: 50
    candidates_per_mask: 200
  impassable: true
  obstacle_penalty: 1e8

Obstacles never cover the start or the goal. See Obstacle Generation for the superellipse math.

Export¶

export:
  default: 1024x1024_samples
  sample:
    num_samples: 64
  compression_level: 12
  chunk_size:
    64: 20000
    128: 10000
    256: 2500
    512: 1500
    1024: 250
    2048: 75
    4096: 25

Full Example¶

resolutions: [64, 128, 256, 512, 1024, 2048, 4096]

export:
  default: 1024x1024_samples
  sample:
    num_samples: 64
  compression_level: 12
  chunk_size:
    64: 20000
    128: 10000
    256: 2500
    512: 1500
    1024: 250
    2048: 75
    4096: 25

num_samples:
  64: 1000000
  128: 1000000
  256: 1000000
  512: 1000000
  1024: 250000
  2048: 100000
  4096: 50000

splits:
  enabled: true
  ratios:
    train: 0.9
    calibration: 0.02
    validation: 0.04
    test: 0.04
  seed: 42

generation:
  dataset_version: passage-successor-v1
  seed: 42
  max_scene_attempts: 100
  max_reference_expansions: null
  geographic_policy:
    block_degrees: 5
    buffer_tiles: 1
  preview_images:
    enabled: true
    resolutions: [64, 128, 256, 512, 1024, 2048, 4096]
    num_samples_per_split: 64

hold_out:
  enabled: true
  mask_path: assets/hold_out_mask.png

solvers:
  - name: astar_elevation
    backend: grid
    diagonal_movement: always
    max_marker_retries: 10
    solver: astar
    cost_model: elevation
    weight: 62.4
    heuristic: euclidean
  - name: astar_energy
    backend: grid
    diagonal_movement: always
    max_marker_retries: 10
    solver: astar
    cost_model: energy
    weight: 1125.3
    heuristic: euclidean
  - name: astar_slope
    backend: grid
    diagonal_movement: always
    max_marker_retries: 10
    solver: astar
    cost_model: slope_uphill
    weight: 8886.2
    heuristic: euclidean

obstacles:
  enabled: true
  ratio_max: 0.30
  shape:
    size:
      min_ratio: 0.02
      max_ratio: 0.25
    n:
      min: 1.0
      max: 80.0
      distribution:
        type: log_uniform
  generation:
    max_attempts: 50
    candidates_per_mask: 200
  impassable: true
  obstacle_penalty: 1e8