Parameters [Builder]

Please consider the following:

  • Python does not recognize operating system environment variables, please use full paths in the parameters file (no $HOME etc).
  • These parameters determine how scenery objects are generated offline as described in chapter Scenery Generation.
  • All decimals need to be with “.” — i.e. local specific decimal separators like “,” are not accepted.
  • You do not have to specify all parameters in your params.ini file. Actually it is better only to specify those parameters, which you want to actively control — the rest just gets the defaults.

View a List of Parameters

The final truth about parameters is stored in — unfortunately the content in this chapter of the manual might be out of date (including default values).

It might be easiest to read directly. Python code is easy to read also for non-programmers. Otherwise you can run the following to see a listing:

/usr/bin/python3 /home/vanosten/develop_vcs/osm2city/ -d

If you want to see a listing of the actual parameters used during scenery generation (i.e. a combination of the defaults with the overridden values in your params.ini file, then you can run the following command:

/usr/bin/python3 --file /home/pingu/development/osm2city/ -f LSZS/params.ini

Detailed Description of Parameters

Minimal Set

See also Setting a Minimal Set of Parameters.

Parameter Type Default Description / Example
PREFIX String n/a Name of the scenery project. Do not use spaces in the name.
PATH_TO_SCENERY Path n/a 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_SCENERY_OPT List None Optional additional paths to scenery folders (e.g. for Project3000). Specified as a list of strings (e.g. [‘/foo/uno’, ‘/foo/due’]. Only used for overlap checking for buildings against static and shared objects.
PATH_TO_OUTPUT Path n/a The generated scenery (.stg, .ac, .xml) will be written to this path. 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.
PATH_TO_OSM2CITY_DATA Path n/a Full path to the folder with osm2city-data. See chapter Installation of osm2city (e.g. “/home/user/osm2city-data”).
FG_ELEV String n/a Points to the full path of the fgelev executable. On Linux it could be something like .../bin/fgfs_git/next/install/flightgear/bin/fgelev'. On Windows you might have to put quotes around the path due to whitespace e.g. '"D:/Program Files/FlightGear/bin/Win64/fgelev.exe"'.
PROBE_FOR_WATER Boolean False Checks the scenery in PATH_TO_SCENERY whether points are in the water or not. The FlightGear scenery’s water boundaries might be different from OSM. E.g. removes buildings if at least one corner is in the water. And removes or splits (parts of) roads/railways, if at least 1 point is in the water. Only possible with FGElev version after 9th of November 2016 / FG 2016.4.1.

Important Flags

Parameter Type Default Description / Example
FLAG_2018 Boolean False If True then then texture catalog and shader integration is for minimal version of FlightGear 2018.1.
BUILDING_USE_SHARED_WORSHIP Boolean False Use a shared model for worship buildings instead of OSM floor plan and heuristics. The shared models will try to respect the type of building (e.g. church vs. mosque) and will in size (not height) respect the convex hull of the building floor plan in OSM. If the building is composed of several parts as in OSM 3D buildings, then no shared models are used - as it is assumed that the 3D modeling is more realistic (e.g number and height of towers) than a generic model, although the facade texture is more dumb than a typical shared model texture.
NO_ELEV Boolean False The only reason to set this to True would be for scenery builders to check generated scenery objects a bit faster not caring about the vertical position in the scenery.

Level of Details of Buildings

The more buildings you have in LOD detailed, the less resources for rendering are used. However you might find it “irritating” the more buildings suddenly appear. Experiment with the settings in FlightGear, see also Adjusting Visibility of Scenery Objects.

Parameter Type Default Description / Example
LOD_ALWAYS_DETAIL_BELOW_AREA Integer 150 Below this area, buildings will always be LOD detailed
LOD_ALWAYS_ROUGH_ABOVE_AREA Integer 500 Above this area, buildings will always be LOD rough
LOD_ALWAYS_ROUGH_ABOVE_LEVELS Integer 6 Above this number of levels, buildings will always be LOD rough
LOD_ALWAYS_DETAIL_BELOW_LEVELS Integer 3 Below this number of levels, buildings will always be LOD detailed
LOD_PERCENTAGE_DETAIL Decimal 0.5 Of the remaining buildings, this percentage will be LOD detailed, the rest will be LOD rough.

European Style Inner Cities (Experimental)

Given the available textures in osm2city-data and the limited tagging of buildings in OSM as of fall 2017, European cities look wrong, because there are too many modern facades used and too many flat roofs.

The following parameters try to “fix” this by adding OSM-tags roof:colour=red and roof:shape=gabled to all those buildings, which do not have parents or pseudo-parents (i.e. nor relationships or parts in OSM), but which share node references with other buildings. So typically what is happening in blocks in inner cities in Europe.

Excluded from this are buildings tagged as building=house or building=terrace or building=detached.

Parameter Type Default Description / Example
BUILDING_FORCE_EUROPEAN_INNER_CITY_STYLE Boolean False If True then some OSM tags are enforced to better simulate European style buildings - especially in inner cities.
BUILDING_FORCE_EUROPEAN_MAX_LEVEL Integer 5 If the buildings is tagged with more levels than this parameter or the corresponding height of levels * BUILDING_CITY_LEVEL_HEIGHT_HIGH, then the OSM tags are not enforced.

Example of using the flag set to True in a part of Prague:


vs. setting it to False (default):


Roofs on Buildings

Below you will find quite a lot of parameters deciding what type of roofs should be generated on buildings. To understand the basic concepts, you should understand OSM Simple 3D buildings. With complex roof below all those roof types, which are not flat/horizontal are meant.

The following parameters decide whether a complex roof should be used on top of a building at all.

Parameter Type Default Description / Example
BUILDING_COMPLEX_ROOFS Bool True Set this to false if only flat roofs should be used. Good for performance, but not so nice for the eye. If this is set to False, all other parameters do not matter.
BUILDING_COMPLEX_ROOFS_MIN_LEVELS Integer 1 Don’t put complex roof on buildings smaller than the specified value unless there is an explicit roof:shape flag in OSM.
BUILDING_COMPLEX_ROOFS_MAX_LEVELS Integer 5 Don’t put complex roofs on buildings taller than the specified value unless there is an explicit roof:shape flag in OSM.
BUILDING_COMPLEX_ROOFS_MAX_AREA Integer 1600 Don’t put complex roofs on buildings larger than this.
BUILDING_COMPLEX_ROOFS_MIN_RATIO_AREA Integer 600 If a building is larger than this but smaller than ..._MAX_AREA, then it is compared whether the building tends to be small and long, because often one more square buildings, which at the same time are large, the roof tends to be flat.
BUILDING_SKEL_MAX_NODES Integer 10 The maximum number of nodes for which a complex roof is generated.

If the roof:shape tag is missing in OSM (which it most oftenly is), then the following parameters can help to make region specific decision on what roof types are to be applied randomly with a given ratio. Again — only if the roofs even may be somethine else than flat given the parameters above. Thes sum of the ratios should give 1.0.

Parameter Type Default

Finally the following parameters let you play around with how complex roofs are done.

Parameter Type Default Description / Example
BUILDING_SKEL_ROOFS_MIN_ANGLE Integer 10 The minimum angle of the roof
BUILDING_SKEL_ROOFS_MAX_ANGLE Integer 50 The max angle of the roof. Some randomness is applied between MIN and MAX.
No matter the MIN and MAX angles: a skillion will have at most this height difference.
Skip skeleton roofs (gabled, pyramidal, ..) if the roof height is larger than this value.
BUILDING_SKEL_ROOF_DEFAULT_HEIGHT Decimal 2.5 If the roof_height is not given in OSM this is what is used to calculate the real building height temporarily - until the real roof is constructed. Unless you know the code behind or see very odd effects, then you should probably not change this value.

Overlap Check for Buildings

Overlap checks try to omit overlap of buildings generated based on OSM data with static object as well as shared objects (depending on parameter OVERLAP_CHECK_CONSIDER_SHARED) in the default scenery (defined by PATH_TO_SCENERY).

If parameter PATH_TO_SCENERY_OPT is not None, then also object from that path are considered (e.g. for Project3000).

Parameter Type Default Description / Example
OVERLAP_CHECK_CONVEX_HULL Bool True Reads all points from static (not shared) objects and creates a convex hull around all points. This is a brute force algorithm only taking into account the firsts object’s vertices.
OVERLAP_CHECK_CH_BUFFER_STATIC Decimal 0.0 Buffer around static objects to extend the overlap area. In general convex hull is already a conservative approach, so using 0 (zero) should be fine.
OVERLAP_CHECK_CH_BUFFER_SHARED Decimal 0.0 Same as above but for shared objects.
OVERLAP_CHECK_CONSIDER_SHARED Bool True Whether only static objects (i.e. a unique representation of a real world thing) should be taken into account — or also shared objects (i.e. generic models reused in different places like a church model). For this to work PATH_TO_SCENERY must point to the TerraSync directory.
OVERLAP_CHECK_BRIDGE_MIN_REMAINING Integer 10 When a static bridge model intersect with a way, how much must at least be left so the way is kept after intersection.

Examples of overlap objects based on static objects at LSZS (light grey structures at bottom of buildings):

_images/lszs_hull_front.png _images/lszs_hull_back.png

Light Effects

Parameters for some light effects / shaders - has only effect if FLAG_2017_2 = False.

Parameter Type Default Description / Example
TRAFFIC_SHADER_ENABLE Boolean False If True then the traffic shader gets enabled, otherwise the light-map shader. These effects are only for roads, not railways. The traffic shader has moving cars, however it only works with the default renderer — ALS/Rembrandt must be off.
OBSTRUCTION_LIGHT_MIN_LEVELS Integer 15 Puts red obstruction lights on buildings >= the specified number levels. If you do not want this, then just set the value to 0.
LIGHTMAP_ENABLE Boolean True Creates simulated light effects on buildings from street lights.


Parameter Type Default Description / Example
ATLAS_SUFFIX String (empty) Add the the suffix to the texture atlas (also light-map) in osm2city-data including an underscore (e.g. ‘foo’ leads to atlas_facades_foo.png).
TEXTURES_ROOFS_NAME_EXCLUDE List [] List of roof file names to exclude, e.g. [“roof_red3.png”, “roof_orange.png”]. The file names must be relative paths to the tex.src directory within PATH_TO_OSM2CITY_DATA. Be aware the excluding roofs can lead to indirectly excluding facade textures, which might be depending on provided roof types. An empty list means that no filtering is done.
TEXTURES_FACADES_NAME_EXCLUDE List [] Same as TEXTURES_ROOFS_EXCLUDE but for facades — e.g. [“de/commercial/facade_modern_21x42m.jpg”].
TEXTURES_ROOFS_PROVIDE_EXCLUDE List [] List of provided features for roofs to exclude, e.g. [“colour:red”].
TEXTURES_REGIONS_EXPLICIT List [] Explicit list of regions to include. If list is empty, then all regions are accepted. There is also a special region “generic”, which corresponds to top directory structure. In many situations it might not make sense to include “generic”, as it provides a lot of colours etc. (which however could be filtered with the other parameters).
TEXTURES_EMPTY_LM_RGB_VALUE Integer 35 If a texture does not have an explicit light-map (i.e. same file name plus “_LM”, then a default light-map is constructed with RGB(VALUE, VALUE, VALUE).

Clipping Region

The boundary of a scenery as specified by the parameters boundary command line argument is not necessarily sharp. As described in Getting OpenStreetMap Data it is recommended to use completeWays=yes, when manipulating/getting OSM data - this happens also to be the case when using the OSM Extended API to retrieve data. However there are no parameters to influence the processing of OSM nodes and OSM ways depending on whether they are inside / outside the boundary or intersecting.

The processing is as follows:

  • if the first node is inside the boundary, then the whole building is processed — otherwise not
  • if not entirely inside then split at boundary, such that the first node is always inside and the last is either inside by default or the first node outside for splitting.
  • as above for piers
  • as above for platforms
    • storage tanks: if the centroid is inside the boundary, then the whole storage tank is processed — otherwise not
    • wind turbines and chimneys: no checking because the source data for OSM should already be extracted correctly
    • aerial ways: if the first node is inside the boundary, then the whole aerial way is processed — otherwise not (assuming that aerial ways are short)
    • power lines and railway overhead lines: as for roads. If the last node was split, then no shared model is placed assuming it is continued in another tile (i.e. optimized for batch processing across tiles)

Linear Objects (Roads, Railways)

Parameters for roads, railways and related bridges. One of the challenges to show specific textures based on OSM data is to fit the texture such that it drapes ok on top of the scenery. Therefore several parameters relate to enabling proper draping.

Parameter Type Default Description / Example
Discard short bridges and draw roads or railways instead.
MIN_ABOVE_GROUND_LEVEL Decimal 0.01 How much a highway / railway is at least hovering above ground
HIGHWAY_TYPE_MIN Integer 4 The lower the number, the smaller ways in the highway hierarchy are added. Currently the numbers are as follows (see -> HighwayType). motorway = 12 trunk = 11 primary = 10 secondary = 9 tertiary = 8 unclassified = 7 road = 6 residential = 5 living_street = 4 service = 3 pedestrian = 2 slow = 1 (cycle ways, tracks, footpaths etc).
POINTS_ON_LINE_DISTANCE_MAX Integer 1000 The maximum distance between two points on a line. If longer, then new points are added. This parameter might need to get set to a smaller value in order to have enough elevation probing along a road/highway. Together with parameter MIN_ABOVE_GROUND_LEVEL it makes sure that fewer residuals of ways are below the scenery ground. The more uneven a scenery ground is, the smaller this value should be chosen. The drawback of small values are that the number of faces gets bigger affecting frame rates.
MAX_SLOPE_ROAD, MAX_SLOPE_* Decimal 0.08 The maximum allowed slope. It is used for ramps to bridges, but it is also used for other ramps. Especially in mountainous areas you might want to set higher values (e.g. 0.15 for roads works fine in Switzeland). This leads to steeper ramps to bridges, but give much fewer residuals with embankments.
USE_TRAM_LINE Boolean False Often tram lines are on top of existing roads or between. This can lead to roads being (partially) hidden etc.

With residuals:


After adjusted MAX_SLOPE_* and POINTS_ON_LINE_DISTANCE_MAX parameters:


Detailed Features

The following parameters determine, whether specific features for procedures pylons respectively details will be generated at all.

Parameter Type Default Description / Example
C2P_PROCESS_POWERLINES Boolean True pylons: Generate electrical power lines (incl. cables)
C2P_PROCESS_WIND_TURBINES Boolean True pylons: wind turbines
C2P_PROCESS_STORAGE_TANKS Boolean True pylons: storage tanks either mapped as nodes or ways in OSM
C2P_PROCESS_CHIMNEYS Boolean True pylons: chimneys either mapped as nodes or ways in OSM
C2P_PROCESS_POWERLINES_MINOR Boolean False details: Only considered if C2P_PROCESS_POWERLINES is True
C2P_PROCESS_AERIALWAYS Boolean False details: Aerial ways is currently experimental and depends on local shared objects.
C2P_PROCESS_OVERHEAD_LINES Boolean False details: Railway overhead lines (pylons and cables)
C2P_PROCESS_STREETLAMPS Boolean False details: Only proof of concept. It will drain your resources in larger sceneries.
DETAILS_PROCESS_PIERS Boolean True details: Generate piers and boats
DETAILS_PROCESS_PLATFORMS Boolean True details: Generate railway platforms


OSM data is read from a PostGIS database. See also OSM Data in Database.

Parameter Type Default Description / Example
DB_HOST String n/a The host name of the computer running PostGIS (e.g. localhost).
DB_PORT Integer 5432 The port used to connect to the host (5433 for Postgres 9,x+)
DB_NAME String n/a The name of the database (e.g osmogis).
DB_USER String n/a The name of the user to be used to read from the database. Can be read-only.
DB_USER_PASSWORD String n/a The password for the DB_USER.

Skipping Specific Buildings and Roads/Railways

There might be situations, when you need to skip certain buildings or roads/railways, because e.g. the overlap checking does not work or the OSM features simply do not fit with the FlightGear scenery. Often it should be checked, whether the OSM data really is correct (if not, then please directly update the source in OSM) or the FlightGear scenery data is not correct (if not, then please check, whether source data can be improved, such that future versions of the scenery are more in line with reality and thereby with OSM data).

In order to temporarily exclude certain buildings or roads/railways, you can use parameter SKIP_LIST. For buildings you can either specify the OSM id or (if available) the value of the name tag. For roads/railways only the OSM id can be used.

E.g. SKIP_LIST = ['St. Leodegar im Hof (Hofkirche)', 87220999]

[1]The only exception to the rule is the possibility to adjust the Actual Distance of LOD Ranges.