.. SPDX-FileCopyrightText: 2026 Stuart Buchanan
.. SPDX-License-Identifier: GPL-2.0-or-later

genVPB.py
=========

genVPB.py is a command-line tool for generating FlightGear WS3.0 scenery from a landclass raster.

As part of the generation process it can also perform a number of useful pre-processing steps on
the landclass raster, and incorporate OSM data directly into the scenery.

Specifically, its features include:

* Downloading Sentinel-2 data directly
* Re-mapping landclass information
* Clipping rasters to OSM coastline data (which is typically more accurate than other sources)
* Generating high resolution water rasters from OSM data (which again is typically more accurate than other sources)
* Generating FlightGear-native road and railway data

Command-line Arguments
----------------------

GenVPB.py has a wide variety of command-line arguments.
The only mandatory arguments are :option:`genVPB.py --bbox` and either :option:`genVPB.py --raster` or :option:`genVPB.py --sentinel`.

Functional command-line arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These command-line argument fundamentally affect the scenery generation process.

.. program:: genVPB.py

.. option:: --bbox <lat0> <lon0> <lat1> <lon1>

    The scenery area to generate, as a box with SW corner lat0/lon and NE corner lat1/lon1.  Mandatory.

.. option:: --raster <file>

    Landclass raster to use.  Must be a geoTIFF.  Required unless setting :option:`genVPB.py --sentinel`

.. option:: --sentinel

    Use Sentinel2 landclass tiles

.. option:: --download-sentinel

    Download Sentinel2 tiles if required

.. option:: --reclass <file>

    Reclassification to use to reclassify raster.  Requires for Sentinel-2.  See fgmeta/ws30/mappings/

.. option:: --coastline <file>

    Clip against coastline against OSM land polygon (.osm)

.. option:: --shrink-water <pixels>

    Shrink water bodies (landclasses 40, 41) by <pixels> pixels

.. option:: --generate-water-raster

    Generate water raster from OSM data

.. option:: --generate-line-features

    Generate line features (roads, railways, tramlines) from OSM data

.. option:: --debug

    Run in debug mode.  Will generate additional logging and output intermediate landclass raster files

NASADEM command-line arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If :option:`genVPB.py --nasadem-user` and :option:`genVPB.py --nasadem-password` are set, then NASADEM .hgt files will be downloaded
to the :option:`genVPB.py --hgt-dir` directory if they do not already exist.  Create an account at https://ers.cr.usgs.gov/

.. option:: --nasadem-user <user>

    Set the NASA Earthdata username for downloading NASADEM data

.. option:: --nasadem-password <password>

    Set the NASA Earthdata password for downloading NASADEM data

.. option:: --nasadem-server <server>

    Set server to download NASADEM data from. Default https://e4ftl01.cr.usgs.gov/MEASURES/NASADEM_HGT.001/2000.02.11/

Directory command-line arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Specific directories can be configured.  The defaults are set to map easily via the docker image.

.. option:: --hgt-dir <dir>

    Directory for .hgt DEM files.  Defaults to /home/flightgear/data/NASADEM

.. option:: --sentinel-dir <dir>

    Directory for Sentinel-2 landclass rasters.  Defaults to /home/flightgear/data/Sentinel-2

.. option:: --cache-dir <dir>

    Directory for caching OSM data. Defaults to /home/flightgear/cache/

.. option:: --output-dir <dir>

    Directory to output scenery data to Defaults to /home/flightgear/output

Examples
--------

To generate some simple scenery using Sentinel-2 landclass raster for a 1x1 degree tile in Scotland,
reclassifying to match the standard landclass mappings.

``genVPB.py --bbox 55 -4 56 -3 --sentinel --download-sentinel --reclassify ./scripts/mappings/sentinel-2.txt``

Generate scenery from a CORINE landclass raster, that has already been remapped

``genVPB.py --bbox 55 -4 56 -3 --raster ./data/corine.tiff``


Generate scenery including a water raster and line features from OSM data.
We shrink the water areas of the raster as the detailed water raster provides more detail.

``genVPB.py --bbox 55 -4 56 -3 --raster ./data/corine.tiff --shrink-water 2 --generate-water-raster --generate-line-features``


Generate scenery, clipping the raster with OSM coastline information.

``genVPB.py --bbox 55 -4 56 -3 --coastline land_polygon.osm``