Using Terragear

From FlightGear wiki
Revision as of 17:42, 18 March 2009 by Stuart (Talk | contribs)

Jump to: navigation, search
This article or section contains out-of-date information

Please help improve this article by updating it. There may be additional information on the talk page.

It has been suggested that this article or section be merged with Howto: Use Terragear on Windows.
It has been suggested that this article or section be merged with Using the Custom Scenery TerraGear Toolset.

See also TerraGear or Building terragear-cs in Ubuntu 64


The terrain used in FlightGear -- the land over which one flies, its texturing (by land usage type), the rivers and lakes and so forth -- are generated by software from a sister project called TerraGear. TerraGear is used to read in geographical data -- descriptions of ground elevations, land cover (usage) information, airport locations and layouts, and so forth -- and output terrain over which one can fly.

For a variety of reasons, you might want to build terrain yourself, rather than downloading it from the available scenery on FlightGear. For instance, if you use TaxiDraw to modify/improve information about an airport's taxiway/apron layout, you might wish to see how that modified airport would look in the scenery before deciding you're happy with the results. And normally to see and use the airport in the scenery, it's necessary to submit the changes to Robin Peel, have him sign off on the changes, have the changes appear in the next official apt.dat, and then wait for the next official FlightGear scenery build; if you can build terrain yourself, you can start using it right away. Maybe the official scenery is too detailed for your slow machine, and you'd like to build terrain using a digital elevation model (DEM) with poorer resolution, to decrease the number of polygons and thus improve your framerates. Or maybe you've got a fantastically fast machine, and you want to build your own terrain using higher-resultion vector data (vmap1, Tiger) to get better roads/streams. For all these reasons, learning how to use TerraGear is a good idea.

There's existing documentation for TerraGear in at least three places: in the source code tree when you fetch it, on the website, and in the CVS tree for the website. The latter is the most current, and really needs to replace the version on the website; but all three are out of date in various ways. When I tried to use the most current documentation to use TerraGear, I ran into all sorts of problems: some I figured out on my own, and others various people helped me with (thanks especially Ralf and Frederic). I'm writing this stuff to detail what I had to do to use TerraGear to build scenery. I am not trying to rewrite the documentation; this should be considered an adjunct/supplement to the TerraGear docs, something you read along with the TerraGear docs. The docs can steer you wrong, or miss something; this is my effort to address those issues.

So here I'll describe what you have to do to use TerraGear to build the terrain for a particular area. In writing this, I'm presuming that you've already downloaded and built the TerraGear source, and thus have a working copy of the TerraGear tools. Since that step was also challenging, similar adjunct documentation for Building Terragear exists.

A word of caution: I use Linux, so this description will be Linux-centric. I hope instructions for other OSes will be similar, but I really don't know. In particular, I don't have easy access to a Windows machine, so I don't know how what I say will differ for those on Windows. In fact, I don't even know if TerraGear can be used on Windows. Hopefully it'll work, under directions not too different from here. If not, hopefully someone else will edit this page to clarify how to do it (if it's possible).

Using TerraGear

TerraGear Process Flow Chart

Now that you've built TerraGear, it's time to build some scenery. The online documentation is out of date, but you need it anyway. I'll try to comment where it differs from reality. To get the most current docs on how to build scenery, from the TerraGear website's "CVS Resources" page, go to interactive CVS log browser, click on www, then docs, then scenery-tutorial, then fg-scenery-tutorial.html, then the version number of the one at the top. You can also try this link, but this link points to a specific version; if the docs are updated, you won't be seeing the updated version. The steps in the previous sentence should always get you the most recent version.

Before going any further, one general comment: the different programs that make up the TerraGear suite seem to sometimes have problems with the default optimization in the TerraGear Makefiles. On a couple of occasions, I had to rebuild part of the suite after editing a Makefile and changing an optimization option because of segfaults (e.g. genapts repeatedly segfaulted on one quite normal airport; I edited a suspect Makefile and removed optimization, and reran "make"; genapts then ran OK). So if you get weird failures, you might try ditching optimization in this fashion.

The docs tell you that the first thing you'll have to do is get the data files used to make the scenery. The first you'll have to get is the elevation data. The docs suggest three possible datasets you can use: 30-arcsec DEM data, 3-arcsec SRTM data, and 1-arcsec SRTM data. I've only used the 1-arcsec SRTM data, so I can't comment on any issues with using the other two. But as for the 1-arcsec SRTM data, the URL given in the docs for fetching the data is wrong. Instead, you want ; click on "What are these.pdf" to see the difference between Version 1 and Version 2 (you probably want Version 2); below each "version" directory can be found the SRTM3 / SRTM 1 / other datasets. As the docs note, you want files covering the region of interest.

The next possible pitfall: if you're using SRTM data, the docs tell you to use hgtchop to prepare the data. I had big problems with hgtchop. When I ran it, the status information that it put on the screen looked bizarre, and later phases of the TerraGear process (fgfs-tools-server/client) choked on the stuff hgtchop produced (see this email to terragear-devel for a description of what happened when I ran hgtchop, as well as what happened when I later tried to use fgfs-tools-server and fgfs-tools-client to build tiles; note the unprintable characters in the output to the screen). After struggling with this for a while, Ralf Gerlich posted a patch for SimGear's newbucket.hxx to flightgear-devel; this patch was meant to just take care of the bogus characters going to the screen, but oddly solved all my problems with hgtchop. To the best of my knowledge, this patch has not been committed to SimGear CVS. So if you get oddness out of hgtchop, and are unable to build tiles in the end, you might try applying the patch in the linked message above, then rebuilding SimGear and TerraGear. It worked for me.

Next pitfall: you're now supposed to run, which is a python script, from the top directory you're working in. It will attempt to run ../Terra/terra, which will not exist. The program in question can be found in the TerraGear source tree at source/src/Prep/Terra/terra; if you ran "make install" when you finished building TerraGear, it'll also be in /usr/local/bin or wherever you installed to. You can fix to point to one of these locations, or you can do the lazy thing (which I did), and create ../Terra/terra as a symbolic link to /usr/local/bin/terra.

Next comes genapts, the program that puts the airports into the scenery. There are two issues you can run into here. The first is that genapts needs access to the elevation info when it runs; without it, your airports will be on flat ground at sea level (and thus in deep pits in the ground), rather than at local ground level following the surface. So genapts goes looking for the elevation info that came out of your processing of DEM30 or SRTM 3" or SRTM 1" or whatever you used; in other words, if you're using SRTM data, genapts will want to see the files created by hgtchop. genapts has a list of directories it searches for ground elevation information; you can see this list by running "genapts --help". If you do so, you'll see that there are no SRTM 1-arcsecond directories listed. The TerraGear docs have you working through an example case with data from w080n40; it has you put the results into work/SRTM-United_States-1, a directory that genapts doesn't search. I got around this by simply creating SRTM2-North_America-3 as a symbolic link to SRTM-United_States-1. I'm also told that there's an undocumented command line option to tell genapts where to look; I haven't tried it so I don't know whether it works.

The second issue that can come up with genapts: the docs tell you to use command-line arguments like --min-lat, --max-lat, etc., to tell genapts what region to work in. Unfortunately, these command-line arguments are broken: they don't have any effect at all. Thus, genapts will try to work on every single airport in the apt.dat file that you point it to. If you're trying to build scenery for a small area, and you point genapts at the full apt.dat.gz file for FlightGear, you're in for trouble. First of all, genapts will take a very, very long time to go through all the airports in that file (many hours). Worse, it apparently builds a large data structure in memory as it goes, and processing the whole file takes a heck of a lot of memory. Furthermore, genapts appears to go berserk when it reaches NZSP, the "airport" at Amundsen-Scott Station, South Pole. It failed to handle that airport correctly, and memory use exploded until all available RAM and swap were taken and the kernel killed it. Ugh. The solution here is to create a new apt.dat file containing only the airports you need, and point genapts at that. If you're doing a full scenery build and you really do need all the airports, then maybe break the build into parts or something, to avoid having genapts work on the whole airport set, I dunno.

Next comes processing VMAP0 data. For me, this went pretty much as written in the docs, except for one big thing and one small thing. The big thing when you do :

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

You'll get an error:

Processing failed with VPF exception: Failed to open VPF table file 

This is because tgvpf is looking for f/j/fbr when the vmap0 stuff unpacks into f/J/fbr (note difference in case -- the capital J versus the little j). On Linux/Unix-ish machines, this matters, because the OS is case-sensitive. You'll have to go to vmaplv0/noamer/bnd/f and make a symbolic link from j to J (I chose not to rename the subdirectory from J to j because I didn't know if anything else would look for it as J). You're going to have to do this a bunch of times, which is annoying, but that's life.

The small thing: the docs tell you to use a command line argument of "--att=med:1" for freeways and "'--att=!med:1'" for roads. Note that set of single quotes in there -- that's because of the "!", which the shell would otherwise interpret before passing to the command, causing an error. Another option is to leave off the single quotes, but escape the "!" (i.e. "--att=\!med:1"), which I think is what I did.

Have Fun, and Good Luck!