Howto:Complete TerraGear example using docker

From FlightGear wiki
Jump to navigation Jump to search

This article aims to serve as a quick starting point for people wanting to build scenery using the dockerized version of the TerraGear scenery toolchain. This will allow users to build scenery on all popular operating systems including Windows, macOS and Linux without the hassle of building the terragear toolchain themselves. This is in no way a comprehensive introduction, but should be enough to get one used to the scenery generation process.

Saint Helena island generated using the docker image for the TerraGear toolchain

Background

TerraGear requires three pieces of data for scenery generation:

  1. Elevation data: This data defines how high each point in the scenery or land is. One source for such data is http://viewfinderpanoramas.org/Coverage%20map%20viewfinderpanoramas_org3.htm.
  2. Landclass data: This data defines what kind of "land" is under each point in the scenery or land is. For example, some point might be "urban" class, or "forest" class. One source for such data is http://download.geofabrik.de/, which is derived from OSM.
  3. Airport data: This data defines the position of runways, taxiways and other assorted airport information. One source for such data is the XPlane gateway.

TerraGear consists of five tools:

  1. hgtchop - Processing elevation data
  2. terrafit - Processing elevation data
  3. genapts - Processing airport data
  4. ogr-decode - Processing landclass data
  5. tg-construct - Generating the final scenery.

Scenery location

We will build Saint Helena Island, an island in the Atlantic Ocean. Specifically, we will be building the island around Saint Helena Airport (ICAO: FHSH).

Its location is: DMS 15° 57′ 33″ S, 5° 38′ 45″ W, Decimal -5.645833 -15.959167

A good vantage point to see progress is to start FG with the following options: 

--lon=-5.62000000 --lat=-16.00000000 --altitude=4000 --heading=310

The bounds for our build will be:

  • Latitude: -6 to -5
  • Longitude: -17 to -15

Let $SCENERY_BUILD_DIR be the directory containing all of our working files for this project.

Getting docker running

The first step is to have docker installed and accessible through the command line. Run the following command to fetch the terragear toolchain: 

docker pull flightgear/terragear:ws20

Next, start a docker container to access the terragear tools: 

docker run -i -v $SCENERY_BUILD_DIR:/terragear-work/ -t flightgear/terragear:ws20 /bin/bash

Once this command runs successfully, the command line will now be a "window" into the docker container, allowing you to run the entire terragear toolchain. Because of the -v argument (bind mount), the container can see the contents of $SCENERY_BUILD_DIR will be visible at /terragear-work/ inside the container.

Process Elevation Data

The elevation data can be obtained from ViewFinderPanoramas, specifically, the SD30 and [SE30 http://viewfinderpanoramas.org/dem3/SE30.zip] tiles cover this island.

Extract and add to $SCENERY_BUILD_DIR/data/SRTM-3/*.hgt. Run the following commands in the docker container: 

cd  /terragear-work/
for f in data/SRTM-3/*.hgt; do hgtchop 3 "${f}" "work/SRTM-3"; done
terrafit work/SRTM-3 -m 50 -x 22500 -e 1

Process Airport Data

FHSH is not available in FlightGear's apt.dat, so the airport information has to be fetched from elsewhere. The XPlane gateway is one possible source. For this sample project, we can use the following data from https://github.com/accek/fg-nav-fixups: 

1   1023 1 0 FHSH St Helena
100 45.00 2 0 0.00 1 2 1 02 -15.96694276 -005.64575428  100    0 2 9 0 2 20 -15.94934298 -005.64615237  300    0 2 9 0 2
110 1 0.00 358.7100 New Taxiway 4
111 -15.96166211 -005.64927678
111 -15.96340503 -005.64926307
111 -15.96340434 -005.64836151
111 -15.96290056 -005.64836043
111 -15.96284142 -005.64854134
111 -15.96265507 -005.64854103
113 -15.96155909 -005.64854086
110 2 0.00 358.7100 New Taxiway 3
111 -15.94934844 -005.64635879 3 102
111 -15.94935248 -005.64663563 3 102
111 -15.94995561 -005.64662024 3 102
113 -15.95019415 -005.64634336
110 2 0.00 358.7100 New Taxiway 2
111 -15.96693818 -005.64554618 3 102
111 -15.96693596 -005.64524600 3 102
111 -15.96628657 -005.64526997 3 102
113 -15.96603006 -005.64556883
110 2 0.00 358.7100 New Taxiway 1
111 -15.96305635 -005.64765837 3 102
111 -15.96240410 -005.64767341 3 102
112 -15.96226078 -005.64761762 -15.96220044 -005.64756860 3 102
111 -15.96219925 -005.64745814 3 102
111 -15.96219005 -005.64624609 3 102
112 -15.96223439 -005.64613746 -15.96227201 -005.64609544 3 102
111 -15.96236947 -005.64606567
111 -15.96184016 -005.64607709 3 102
112 -15.96195708 -005.64616687 -15.96199469 -005.64621034 3 102
111 -15.96199881 -005.64627387 3 102
111 -15.96200448 -005.64744540 3 102
112 -15.96197248 -005.64759953 -15.96193665 -005.64765444 3 102
111 -15.96183543 -005.64768917 3 102
111 -15.96154350 -005.64769949 3 102
111 -15.96155909 -005.64854086
111 -15.96265507 -005.64854103
111 -15.96265481 -005.64818499
113 -15.96306600 -005.64818480 3 102
130 Airport Boundary
111 -15.95876878 -005.64712051
111 -15.96005216 -005.64729370
111 -15.96043831 -005.64731000
111 -15.96048880 -005.64864132
111 -15.96154716 -005.64921198
111 -15.96159626 -005.65014384
111 -15.96388391 -005.64953797
111 -15.96430513 -005.64699927
111 -15.96882642 -005.64692255
111 -15.96885682 -005.64412109
111 -15.94564642 -005.64456651
113 -15.94563863 -005.64716916
120 Hold
111 -15.96200516 -005.64660225 4 103
115 -15.96218383 -005.64660129
120 Linear Feature 5
111 -15.96210864 -005.64767019 1 101
112 -15.96206007 -005.64782922 -15.96201482 -005.64792776 1 101
115 -15.96188449 -005.64810582
120 Linear Feature 4
111 -15.96210864 -005.64767019 1 101
112 -15.96213878 -005.64782592 -15.96215760 -005.64789051 1 101
115 -15.96229199 -005.64808544
120 Linear Feature 3
111 -15.96156820 -005.64813668 20
111 -15.96263721 -005.64810368 20
111 -15.96263233 -005.64792345 20
115 -15.96304480 -005.64791075
120 Linear Feature 2
111 -15.96210864 -005.64767019 1 101
111 -15.96210128 -005.64660525 1 105
115 -15.96209919 -005.64630388
120 Linear Feature 1
111 -15.96154408 -005.64588717 1 105
111 -15.96184445 -005.64588139 1 105
112 -15.96204503 -005.64596036 -15.96210198 -005.64604073 1 105
111 -15.96209919 -005.64630388 1 105
112 -15.96217524 -005.64595582 -15.96225060 -005.64588070 1 105
111 -15.96236918 -005.64587174 1 105
115 -15.96269552 -005.64586403
21 -15.95361317 -005.64657631 3 180.0000 3.0 Papi
21 -15.95359638 -005.64551140 2 180.0000 3.0 Papi
21 -15.96347774 -005.64645343 2 -1.2600 3.0 Papi
20 -15.96192491 -005.64660719 90.0000 0 3 {@R}20-02{@@}{@Y}APRON
20 -15.96225995 -005.64660719 90.0000 0 3 {@R}20-02{@@}{@Y}APRON
14 -15.96312208 -005.64867411  82.02 0 Tower Viewpoint
15 -15.96179344 -005.64822577 -50.36 Ramp Start 1
1300 -15.96238032 -005.64819725 -129.45 gate jets Ramp Start 2
15 -15.96285880 -005.64779046 -181.04 Ramp Start 3
19 -15.95196179 -005.64670036 0 New Windsock 2
19 -15.96603475 -005.64630065 0 New Windsock 1

Copy and paste the above into $SCENERY_BUILD_DIR/data/airports/FHSH.dat. We can now run genapts: 

genapts850 --input=data/airports/FHSH.dat --work=./work --dem-path=SRTM-3 --min-lon=-6 --max-lon=-5 --min-lat=-17 --max-lat=-15
genapts850 --input=data/airports/FHSH.dat --work=./work --dem-path=SRTM-3 --airport=FHSH

Process Landclass Data

We can download landclass data from GeoFabrik, specifically from http://download.geofabrik.de/africa/saint-helena-ascension-and-tristan-da-cunha.html. Download the *.shp files and extract them into $SCENERY_BUILD_DATA/data/shapefiles. Each type of file should go into its own folder. For example, copy all gis_osm_places_a_free_1.* files into $SCENERY_BUILD_DATA/data/shapefiles/gis_osm_places_a_free_1/*, as this is the format that TerraGear expects the files to be in. Usually, we would use a landmass (See Notes below) shapefile as our Default, but to simplify things for this tutorial, we can use the gis_osm_places_a_free_1.shp file, as the landmass file and this file are identical for this particular island. We are now ready to run ogr-decode: 

ogr-decode --max-segment 500 --area-type Default work/Default data/shapefiles/gis_osm_places_a_free_1/

We have to run ogr-decode for every land class (so urban, forest, lakes, roads etc). At each time, we need to specify the shapefile (the last argument in the above command) and the corresponding area material type that FlightGear recognizes ("Default") in the above command. For this tutorial, we will run the command just once to get the construct the entire island as a "Default" landclass.

Bringing it all together

We can finally run tg-construct to bring everything together 

tg-construct --priorities=/usr/local/share/TerraGear/default_priorities.txt --work-dir=./work --output-dir=./output/Terrain --min-lon=-6 --max-lon=-5 --min-lat=-17 --max-lat=-15 AirportArea AirportObj Default SRTM-3

The $SCENERY_BUILD_DIR/output will now contain the built scenery. Point your FG instance to this path using --fg-scenery and take a look at the built scenery!

Notes

  • There are two docker images, flightgear/terragear:ws20 and flightgear/terragear:latest. The former corresponds to the 2.0 world scenery build, while the later points to the latest code. The latest container has several improvements and GDAL tools which can be used to manipulate shapefiles, but also unfortunately has bugs in the hgtchop and terrafit tools for SRTM-3 data. The best way is to use flightgear/terragear:ws20 for elevation data processing, and flightgear/terragear:latest for everything else.
  • The OSM coastlines data is a good source for the landmass ("Default") terrain, but is a single file for the entire world.
  • You can use the following command (found in the latest terragear docker image) to "crop" the shapefile to an area of interest:
ogr2ogr -clipsrc -6 -17 -5 -15 cut_landmass.shp land_polygons.shp
  • As mentioned in the introduction, this tutorial is just a starting point. Have a look at the other TerraGear wiki articles. A good resource is also provided on the forum, which uses TerraGear GUI. You can use the concepts learned from there and run the commands in the docker image.
Retrieved from "https://wiki.flightgear.org/w/index.php?title=Howto:Complete_TerraGear_example_using_docker&oldid=134543"