Hi fellow wiki editors!

To help newly registered users get more familiar with the wiki (and maybe older users too) there is now a {{Welcome to the wiki}} template. Have a look at it and feel free to add it to new users discussion pages (and perhaps your own).

I have tried to keep the template short, but meaningful. /Johan G


Jump to: navigation, search

Building TerraGear

848 bytes added, 04:10, 31 May 2006
no edit summary
== Intro Introduction ==
The terrain used in [http://flightgear.org 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 [http://terragear.org 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 [http://taxidraw.sourceforge.net/ 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 [http://www.x-plane.org/home/robinp/#Updates submit the changes to Robin Peel], have him sign off on the changes, have the changes appear in the next [http://www.x-plane.org/home/robinp/ official apt.dat], and then wait for the next [http://www.flightgear.org/Downloads/scenery.html 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 [http://cvs.terragear.org/cgi-bin/viewcvs/viewcvs.cgi/*checkout*/www/docs/scenery-tutorial/fg-scenery-tutorial.html?rev=1.3&cvsroot=TerraGear-0.0 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 get TerraGear up and running, and then use it to build the terrain for a particular area. A word of caution, however: 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 built/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).
== Building TerraGear ==
Go to the [http://www.terragear.org/ TerraGear website], select "CVS Resources", and check out a copy of the current sourcecode from CVS using the instructions at the top of the page. Once you've done that, you can try to build the source code. First, though, TerraGear depends on some other libraries you'll need. If you look in source/, you'll see a bunch of README files. Read them. In particular, note the ones with names like "README.somesoftwarename"; those describe software you'll need to be able to build and run TerraGear. Cygwin I ignored because that's for Windows and I'm not running Windows. plib and SimGear I already had from their CVS repositories, because I track FlightGear CVS; but it's a good idea to go ahead and update those two to current CVS, just in case the current TerraGear CVS depends on something that's been checked into plib or SimGear since the last time you updated them (yes, that means you'll have to update and rebuild FlightGear as well, sorry). If you don't track CVS for any of these things, you can still try to build TerraGear against whatever copies of SimGear and plib you have installed; but if you run into problems (unresolved symbols or whatever), that'd be the first place I'd look.
Some comments on the other stuff you need:
--with-newmat=/usr/local/lib/ --with-plib=/usr/local/lib/
Next comes running make to build all the executables. The instructions in source/README tell you that you want to "compile the /Libs/TriangleJRS code without optimization (-O2)". However, that's not the path to those files. Go to source/src/Lib/TriangleJRS. There, edit Makefile -- remove "-O2" from the two locations it appears (CFLAGS and CXXFLAGS).
== Using TerraGear ==
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 [http://cvs.terragear.org/cgi-bin/viewcvs/viewcvs.cgi/*checkout*/www/docs/scenery-tutorial/fg-scenery-tutorial.html?rev=1.3&cvsroot=TerraGear-0.0 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. [http://mail.flightgear.org/pipermail/terragear-devel/2006-March/001347.html 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 ftp://e0srp01u.ecs.nasa.gov/srtm ; 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 .hgt.zip 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 [http://mail.flightgear.org/pipermail/terragear-devel/2006-April/001359.html 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 [http://sourceforge.net/mailarchive/message.php?msg_id=15392092 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 terrafit.py, 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 terragear.py 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 [http://mail.flightgear.org/pipermail/terragear-devel/2006-May/001371.html 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.
$ 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

Navigation menu