Preparation [Builder]

Before osm2city related programs can be run to generate FlightGear scenery objects, the following steps need to be done:

  1. Creating a Directory Structure
  2. Getting OpenStreetMap Data
  3. Setting Minimal Parameters
  4. Generating elevation data

It is recommended to start with generating scenery objects for a small area around a smaller airport outside of big cities, such that manual errors are found fast. Once you are acquainted with all process steps, you can experiment with larger and denser areas.

Creating a Directory Structure

The following shows a directory structure, which one of the developers is using — feel free to use any other structure.

HOME/
    flightgear/
        fgfs_terrasync/
            Airports/
            Models/
            Objects/
            Terrain/
            terrasync-cache.xml
    development
        osm2city/
        osm2city-data/
        ...
    fg_customscenery/
        KBOS/
            Buildings/
                w080n40/
                    w071n42/
                        3105315.btg
                        w080n40_w071n42_1794312city00000.ac
                        ...
            Pylons/
                ...
            Roads/
                ...
        LSME/
            Buildings/
                ...
        projects/
            KBOS/
                params.py
            LSME/
                ...

The directory flightgear contains folder fgfs_terrasync. This is where you have your default FlightGear scenery. The FlightGear Wiki has extensive information about TerraSync and how to get data. You need this data in folder, as osm2city only enhances the scenery with e.g. additional buildings or power pylons.

The directory development contains the osm2city programs and data after installation as explained in Installation.

In the example directory structure above the directory fg_customscenery hosts the input and output information — here two sceneries for airports KBOS and LSME (however there is no need to structure sceneries by airports). The output of osm2city scenery generation goes into e.g. fg_customscenery/KBOS while the input to the scenery generation is situated in e.g. fg_customscenery/projects/KBOS (how to get the input files in this folder is discussed in the following chapters).

The directory structure in the output folders (e.g. fg_customscenery/KBOS) is created by osm2city related programs, i.e. you do not need to create it manually.

The directory .../fg_customscenery/projects will be called WORKING_DIRECTORY in the following. This is important because osm2city related programs will have assumptions about this.

Getting OpenStreetMap Data

The OpenStreetMap Wiki has comprehensive information about how to get OSM data. An easy way to start is using Geofabrik’s extracts (http://download.geofabrik.de/).

It is highly recommend to limit the area covered as much as possible: it leads to faster processing and it is easier to experiment with smaller areas until you found suitable parameters. If you use Osmosis to cut the area with --bounding-box, then you need to use completeWays=yes [1]. E.g. on Windows it could look as follows:

c:\> "C:\FlightGear\osmosis-latest\bin\osmosis.bat" --read-pbf file="C:\FlightGear\fg_customscenery\raw_data\switzerland-latest.osm.pbf"
     --bounding-box completeWays=yes top=46.7 left=9.75 bottom=46.4 right=10.0 --wx file="C:\FlightGear\fg_customscenery\projects\LSZS\lszs_wider.osm"

Setting a Minimal Set of Parameters

osm2city has a large amount of parameters, by which the generation of scenery objects based on OSM data can be influenced. Chapter Parameters has detailed information about the most important of these parameters[#]_. However to get started only a few parameters must be specified — actually it is generally recommended only to specify those parameters, which need to get a different value from the default values, so as to have a better understanding for which parameters you have taken an active decision.

Create a params.py file with your favorite text editor. In our example it would get stored in fg_customscenery/projects/LSZS and the minimal content could be as follows:

PREFIX = "LSZS"
PATH_TO_SCENERY = "/home/flightgear/fgfs_terrasync"
PATH_TO_OUTPUT = "/home/fg_customscenery/LSZS"
PATH_TO_OSM2CITY_DATA = "/home/user/osm2city-data"

NO_ELEV = False
FG_ELEV = '/home/pingu/bin/fgfs_git/next/install/flightgear/bin/fgelev'

DB_HOST = "localhost"
DB_PORT = 5433
DB_NAME = "osmgis"
DB_USER = "gisuser"
DB_USER_PASSWORD = "n/a"

A few comments on the parameters:

PREFIX
Needs to be the same as the specific folder below fg_customscenery/projects/. Do not use spaces in the name.
PATH_TO_SCENERY
Full path to the scenery folder without trailing slash. This is where we will probe elevation and check for overlap with static objects. Most likely you’ll want to use your TerraSync path here.
PATH_TO_OUTPUT
The generated scenery files (.stg, .ac) will be written to this path — specified without trailing slash. If empty then the correct location in PATH_TO_SCENERY is used. Note that if you use TerraSync for PATH_TO_SCENERY, you MUST choose a different path here. Otherwise, TerraSync will overwrite the generated scenery. Unless you know what you are doing, there is no reason not to specify a dedicated path here. While not absolutely needed, it is good practice to name the output folder the same as PREFIX.
NO_ELEV
Set this to False. The only reason to set this to True would be for builders to check generated scenery objects a bit faster not caring about the vertical position in the scenery.
FG_ELEV
Set parameter FG_ELEV to point to the full path of the fgelev executable. On Linux it could be something like FG_ELEV = '/home/pingu/bin/fgfs_git/next/install/flightgear/bin/fgelev'. On Windows you might have to put quotes around the path due to whitespace e.g. FG_ELEV = '"D:/Program Files/FlightGear/bin/Win64/fgelev.exe"' (yes, both single and double quotes).
DB_*
Connection settings for PostGIS: see database parameters.

Advanced Parameter Setting

The parameter files are just regular Python files, the content of which is merged with the default parameters. This actually allows for some scripting, if you know very basic Python programming.

The parameter AREA has been added with the sole purpose of helping you reuse some parameters, while having some saved for special areas. This saves the trouble of having different parameter files for different areas.

The following is an example of how that can be used, where the only change between two generations is that I have to update AREA to be either “HAWAII” or “SCOTLAND”. NB: “…” in the example below is just to tell that there would be other parameters - you must not have it in your file.

AREA = 'HAWAII'
...
OWBB_USE_EXTERNAL_LANDUSE_FOR_BUILDING_GENERATION = True
OWBB_LANDUSE_CACHE = True
...

if AREA == 'HAWAII':
    OWBB_GENERATE_BUILDINGS = True
    OWBB_USE_BTG_LANDUSE = True
    ...

elif AREA == 'SCOTLAND':
    OWBB_USE_EXTERNAL_LANDUSE_FOR_BUILDING_GENERATION = False
    ...

The drawback of this advanced parameter setting is, that you might get difficult to interpret error messages, if you do something wrong. Python knowledge helps in that case.

If you want to use your own variables, then make sure you prefix them with “_” (underscore) - otherwise the process will abort immediately because an unknown parameter was found.

Generating Elevation Data

osm2city uses scenery elevation data from the FlightGear sceneries (TerraSync) for two reasons:

  • No need to get additional data from elsewhere.
  • The elevation of the generated scenery objects need to be aligned with the underlying scenery data (otherwise houses could hover over the ground or be invisible because below ground level).

This comes at the cost that elevation data must be obtained by “flying” through the scenery, which can be a time consuming process for larger areas — especially if you need a good spatial resolution e.g. in mountain areas like Switzerland.

Please be aware that the scenery data needed for your area might not have been downloaded yet by TerraSync, e.g. if you have not yet “visited” a specific tile. An easy way to download large areas of data is by using TerraMaster. If you are exclusively using TerraMaster to download data, then make sure that you in TerraMaster also use button “Synchronise shared models”.

[1]Failing to do so might result in an exception, where the stack trace might contain something like KeyError: 1227981870.
[2]Many parameters are self-explanatory by their name. Otherwise have a look at the comments in parameters.py