FlightGear Scenery Tutorial

This tutorial provides step-by-step instructions for building the FlightGear w080n40 scenery tile, which includes (among other cities) New York, Boston, Toronto, Montreal, and Ottawa. At the end of the process, you will have a 10x10 deg scenery area built with airports, lakes, land-cover, roads, railroads, and rivers.

You can easily adapt this tutorial to build scenery anywhere in the world. All of the datasets mentioned here have world-wide coverage, and will work as well for Tibet or New Guinea as they will for Central Canada and the US Northeastern Seaboard.

In some cases, better (i.e. higher-resolution) datasets are available for the United States than for the rest of the world. This tutorial sticks with datasets that cover the whole world, but it occasionally notes where the higher-resolution US datasets are for people who want them.

2. Downloading the Datasets

TerraGear generates FlightGear scenery automatically from free, publicly-available geographical datasets: you do not have to (and are currently not able to) paint roads, rivers, and so forth by hand.

We will use two types of geographical datasets in this tutorial:

Raster data for elevation points. This data provides a two-dimensional grid of evenly-spaced points containing ground elevations. TerraGear will use this data to create hills, valleys, and rolling terrain; without it, the whole world would be at sea-level.
Vector data for polygons on the earth's surface. This data contains lines (such as roads and runways) or polygons (such as towns or lakes) that will be painted as textured polygons on top of the elevation grid; without it, the whole world would have exactly the same surface cover.

Here are the geographical data files you'll need to download:

30-arcsec DEM

ftp://edcftp.cr.usgs.gov/pub/data/gtopo30/global/w100n90.tar.gz (15MB).

This file contains all of the required elevation data for the scenery chunk (and many neighbouring ones as well).

If you are building scenery for a different region, go to http://edcdaac.usgs.gov/gtopo30/gtopo30.html and click on the appropriate rectangle on the world map to get your scenery.

These DEMs have approximately one point for every kilometer, so features [ridges, hills, valleys, etc.] smaller than 1km will not appear. Higher-resolution DEMs for the United States are available from http://edc.usgs.gov/geodata/.

Airport and Runway Data

$FG_ROOT/Airports/default.apt.gz

If you already have FlightGear installed on your computer, this file will appear in the Airports/ directory in your base package, so you don't need to download anything. If for some reason you don't have a copy of the FlightGear base package already installed, you can download one from http://rockfish.net/fg/ (a bit of overkill for just one file).

You will have to edit this file to add new airports or modify existing ones. For a description of the format, see docs-mini/AptNavFAQ.FlightGear.html in the FlightGear source distribution (not the base package).

vmap0

http://geoengine.nima.mil/ftpdir/archive/vpf_data/v0noa.tar.gz (245MB)

This dataset (formerly known as the Digital Chart of the World) contains non-airport vector data for all of North America, including landmass (shorelines), lakes, rivers, cities, towns, roads, railroads, rivers, landcover, and many other coverages that we are not using yet. After unpacking the file, you can burn it directly onto a CD-ROM and work from that, if you prefer. If you're building scenery outside North America, you can download one of the other three vmap0 CD-ROMs instead:

http://geoengine.nima.mil/ftpdir/archive/vpf_data/v0eur.tar.gz (Europe and North Asia, 251MB).
http://geoengine.nima.mil/ftpdir/archive/vpf_data/v0sas.tar.gz (South Asia and Oceania, 240MB).
http://geoengine.nima.mil/ftpdir/archive/vpf_data/v0soa.tar.gz (South America and Africa, 176MB).

There is other, higher-resolution vector data available for the United States, including the Digital Line Graphs (DLG) from http://edc.usgs.gov/geodata/. The http://www.soest.hawaii.edu/wessel/gshhs/gshhs.html has much more detailed ocean coastlines than vmap0, but its inline water bodies are highly inaccurate -- the shores of the Great Lakes, for example, are sometimes several kilometers off, stranding airports in the middle of the water.

vmap1, a much higher-resolution version of vmap0, is also available from http://geoengine.nima.mil/ for some regions in the United States. Unfortunately, at the time of writing, TerraGear and FlightGear cannot handle that level of extra detail, however tempting it may be.

3. Preparing the Datasets

After following the instructions in the previous section, you should have the following three data files downloaded onto your computer:

w100n90.tar.gz (approx. 15MB)
default.apt.gz (approx. 1MB)
v0noa.tar.gz (approx. 145MB)

Before you go any further, you need to create a root directory for scenery building. Personally, I use /usr/local/src/Scenery/, but you can set things up any way you like. Inside your root scenery directory, create two subdirectories, ./work/ and ./data/:

$ cd /usr/local/src/Scenery/
$ mkdir work
$ mkdir data

3.1. Preparing the Elevation Data

Change into the data directory, and create a dem30 subdirectory to hold the DEM data, then change to the dem30 subdirectory and unpack the :

$ cd data
$ mkdir dem30
$ cd dem30
$ tar xvzf ../../w100n90.tar.gz

You should end up something like this:

-rw-r--r--    1 david    david    57600000 Jan 21  1997 W100N90.DEM
-rw-r--r--    1 david    david         222 Jan 21  1997 W100N90.DMW
-rw-r--r--    1 david    david      114634 Jan 22  1997 W100N90.GIF
-rw-r--r--    1 david    david         327 Jan 23  1997 W100N90.HDR
-rw-r--r--    1 david    david         648 Jan 21  1997 W100N90.PRJ
-rw-r--r--    1 david    david         326 Jan 23  1997 W100N90.SCH
-rw-r--r--    1 david    david    28800000 Jan 21  1997 W100N90.SRC
-rw-r--r--    1 david    david          28 Jan 21  1997 W100N90.STX

First, we need to convert the DEM from the current binary format to an ASCII format that TerraGear can handle, using TerraGear's raw2ascii command (we'll put the output in an ascii subdirectory). You can skip this step if you're using the US 3arcsec DEMs, since they're already in ASCII format:

$ mkdir ascii
$ raw2ascii W100N90 ascii

Ouch! The command runs for a while and ends up creating 2,000 files in the ascii/ subdirectory, using up over 200MB of disk space; the good news is that you'll be able to delete these soon. In fact, you can already delete the original 57MB DEM files, since you won't be needing them anymore (you might want to back up the original tarball somewhere, though):

$ rm -v W100N90*

Now, if you know for certain (really for certain) that you're not going to build any scenery outside of the w080n40 chunk, you can also delete all of the extra DEM files that you won't be needing. For w080n40, you need w071n40.dem to w080n49.dem inclusive:

$ # Are you SURE you want to do this?
$ rm ascii/*n[5678]*
$ rm ascii/w06*
$ rm ascii/w070*
$ rm ascii/w08[1-9]*
$ rm ascii/w09*
$ rm ascii/w10*

Now, instead of 2,000 files using over 200MB, we have only 100 files using a little over 10MB. Note again that you shouldn't do this if you're planning on building scenery for the surrounding tiles as well.

OK, now it's time to chop up the DEM files into segments for TerraGear. Change back to the root of your scenery source tree (such as /usr/local/src/Scenery/, then create a work/DEM-30/ directory for the predigested DEM data to live in (US 3-arcsec DEM data, if you're using it instead, should go to work/DEM-3):

$ mkdir work/DEM-30

Now, the next part is even more OS-dependent than usual. You need to run the command demchop on each of the *.dem files in data/dem30/ascii separately. With the bash shell, I use the following (again, from the root of the scenery source tree):

$ for file in data/dem30/ascii/*.dem; do
> demchop $file work/DEM-30
> done

After the code churns away for a couple of minutes, you should find a w080n40/ directory in work/DEM-30/, containing 100 subdirectories named w071n40 to w080n49, using about 12MB of disk space.

You are now done preparing the elevation data. To build scenery, TerraGear needs only the files and directories under the work/DEM-30/; if you are tight for space, you can delete all of your working files under data/ now, before going any further (if you have a lot of space, it doesn't hurt to keep them around).

3.2. Preparing the Airport Data

Note that you must prepare the elevation data before your prepare the airport data, and that data must be in a directory named DEM-30 or DEM-3; otherwise, all airports will be created at sea level and will live in giant holes in your scenery.

Even if you already have a copy of default.apt.gz on your hard-drive in the FlightGear base package, it is probably a good idea to make a separate copy for scenery building -- that way, you can make local modifications without breaking anything in the file you need to run FlightGear.

From the root of your scenery source tree, change to the data/ directory and create a new airports/ subdirectory, then copy default.apt.gz (or default.apt) into it:

$ cd data
$ mkdir airports
$ cp $FG_ROOT/Airports/default.apt.gz airports

Change to the airport directory, then create all of your airport data with a single instance of the TerraGear genapts command:

$ cd airports
$ genapts --input=default.apt.gz --work=../../work/ --min-lon=-80 --max-lon=-70 --min-lat=40 --max-lat=50

When the command finishes, you should see two new directories inside work/: AirportArea and AirportObject; together they take up a little less than 9MB (possibly more for filesystems with large, fixed block sizes). That's all that's required to build the airports.

If you ever need to replace an airport, the easiest approach is to delete all of the airports for that chunk and start over. For example, if you modified the entries for KBOS (Boston), you would do

$ rm -rf work/AirportArea/w080n40/
$ rm -rf work/AirportObj/w080n40/

And then repeat the above instructions. It is possible to replace individual files, but it gets fairly tricky and is not a good idea for new users.

3.3. Preparing the vmap0 Data

By now, you should already have unpacked the v0noa.tar.gz into a directory somewhere on your hard drive, or even burned it onto a CD-ROM. If you have not yet done so, then consider placing it in a data/vmap0/ directory. Wherever the data is, find the directory vmaplv0 containing the files dht and lat -- this is your vmap0 root that you'll need to reference throughout this section. All of the examples will use /cdrom/vmaplv0/, so you'll have to substitute your own location.

The TerraGear tgvpf program extracts data from vmap0 and places it in working directories for scenery building. You run the program once for each kind of data you require; depending on the amount of data, each run can take several minutes to finish.

We'll start by extracting the basic landmass (i.e. everything that isn't ocean):

NOTE: This and all of the following examples assume that you are building scenery for w080n40 from the noamer vmap0 CD. If that is not the case, substitute eurnasia, sasaus, or soamafr for noamer in every example (look inside the vmaplv0/ directory to see which one applies), and subsitute your scenery chunk for w080n40.

$ cd work
$ tgvpf --chunk=w080n40 --work-dir=LandMass --area=Default /cdrom/vmaplv0 noamer bnd polbnda

This command creates a LandMass/ subdirectory containing polygons for all non-ocean areas, to ensure that at least some land appears even when specific land-cover is not available.

If you are impatient to see if this is working, you can skip ahead to the next section now and try building the scenery -- note, though, that you'll have only ocean, forested landmass, and airports.

Next, we'll add inland lakes and large rivers, to break up the landmass a little:

$ tgvpf --chunk=w080n40 --work-dir=Lakes --area=Lake /cdrom/vmaplv0 noamer hydro inwatera

These polygons go into a separate directory, named Lakes/. We could put all of the vmap0 polygons into the same directory, but by separating them we're able easily to regenerate one type without having to regenerate the others.

Next, we'll generate some narrower rivers and streams. Since vmap0 uses only lines for these, we'll have to make up a standard width; for now, 100m should do:

$ tgvpf --chunk=w080n40 --work-dir=Rivers --area=Stream --width=100 /cdrom/vmaplv0 noamer hydro watrcrsl

This command adds polygons for cities and large towns:

$ tgvpf --chunk=w080n40 --work-dir=Cities --area=Urban /cdrom/vmaplv0 noamer pop builtupa

vmap0 stores small towns only as points, so we'll use the default 1x1km squares for them:

$ tgvpf --chunk=w080n40 --work-dir=Towns --area=Town /cdrom/vmaplv0 noamer pop mispopp

The next two commands add basic forests and farmland:

$ tgvpf --chunk=w080n40 --work-dir=Forest --area=MixedForestCover /cdrom/vmaplv0 noamer veg treesa
$ tgvpf --chunk=w080n40 --work-dir=Crops --area=MixedCropPastureCover /cdrom/vmaplv0 noamer veg cropa

The final few commands use vmap0 line data to add freeways (50m wide), regular roads (20m wide), and railroads (10m wide):

$ tgvpf --chunk=w080n40 --width=50m --work-dir=Freeways --area=Freeway --att=med:1 /cdrom/vmaplv0 noamer trans roadl
$ tgvpf --chunk=w080n40 --width=20m --work-dir=Roads --area=Road '--att=!med:1' /cdrom/vmaplv0 noamer trans roadl
$ tgvpf --chunk=w080n40 --width=10m --work-dir=Railroads --area=Railroad /cdrom/vmaplv0 noamer trans railrdl

This is just a start. There is actually much more information available in vmap0, and once you're comfortable with scenery building, you can distinguish different kinds of rivers, farmland, forests, and so on, as well as adding new coverages like marshes, tundra, and polar ice. When you're ready, take a look at http://www.terragear.org/docs/vmap0/ for full documentation on the tgvpf command, and at http://www.terragear.org/docs/vmap0/coverage.html for details on vmap0 coverages and attributes.

For now, though, let's go on and build our FlightGear scenery.

4. Generating the Scenery

After generating your working files for elevation, airports, and scenery cover, you should have the following subdirectories in your scenery work/ directory:

AirportArea
AirportObj
Cities
Crops
DEM-30
Forest
Freeways
Lakes
LandMass
Railroads
Rivers
Roads
Towns

(On my system, they use about 265MB of disk space; if you use a filesystem that has large, fixed block sizes, then the space used might be several times higher because of all the small files.)

When you build your actual scenery, you can decide to include or exclude each of these directories separately; for now, we'll use all of them.

Before you start the scenery building, you will have to change to your work directory and create a Status/ subdirectory, then touch a MASTER_ON file inside it:

$ cd work
$ mkdir Status
$ touch Status/MASTER_ON

Now we're ready to build the w080n40 scenery in earnest. We'll use two TerraGear programs for scenery building: fgfs-tools-server, which controls the overall build process, and fgfs-tools-client, which does the actual tile building. First, from inside the working directory, start fgfs-tools-server:

$ fgfs-tools-server . . w080n40

When the program starts, it will print out some information:

Work base: .
Output base: .
Area width: 10 degrees
Area height: 10 degrees
lons = w080 lats = n40
start_lon = -80  start_lat = 40
socket is connected to port = 33933

The last line is the important one -- you need to know what port the server is listening on before you can start any clients (the port will be different every time).

Now, in a separate terminal window, start a copy of fgfs-tools-client to build the scenery tiles (for "33933", substitute the port fgfs-tools-server is actually listening on):

$ fgfs-tools-client --rude --min-angle=0 --output-dir=. --work-dir=. --port=33933 DEM-30 LandMass AirportArea AirportObj Cities Crops Forest Freeways Lakes Railroads Rivers Roads Towns

If you are running on a multiprocessor machine, you can start additional instances of fgfs-tools-client in separate windows using the same command line; fgfs-tools-server will divide up the work among them.

It will take a while for TerraGear to build the scenery -- possibly an hour or two, depending on system load, processor speed, and disk speed. Go take a break until it's finished.

OK, it's finally done. fgfs-tools-server will still be running (you have to kill it manually), but fgfs-tools-client will have finished. Inside Scenery/, you should find a w080n40/ subdirectory containing your new scenery. Let's give it a try, using magic-carpet mode at KSYR (Syracuse, NY), staying in your work/ directory:

$ FG_SCENERY=./Scenery fgfs --fdm=magic --disable-panel --airport-id=KSYR

Note that you will start slightly underground, but as soon as you rise a few feet, you'll see the scenery properly. Here's the view from over the runway:

And here's a more interesting view a bit to the left, with Interstate 90 running south of the airport and a river running in the background:

If you're seeing similar scenery, then you have succeeded. Here are a few other larger airports you can start at in w080n40:

KJFK (New York, NY)
KLGA (New York, NY)
KEWR (Newark, NJ)
KBOS (Boston, MA)
KBUF (Buffalo, NY)
KROC (Rochester, NY)
KPIT (Pittsburg, PA)
CYUL (Montreal, PQ)
CYMX (Montreal, PQ)
CYQB (Quebec, PQ)
CYYZ (Toronto, ON)
CYOW (Ottawa, ON)