Building TerraGear: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
No edit summary
 
(Merged usefull info into TerraGear, replaced text by REDIRECT)
 
(17 intermediate revisions by 8 users not shown)
Line 1: Line 1:
== Intro ==
#REDIRECT [[TerraGear#Compilation]]
 
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 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 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:
 
* GPC. The instructions for what to do are in source/README.gpc. That file says the current version is 3.21; in fact, it's 3.22. Don't forget that editing step described in the README. When you run the makefile, it'll create a library called libgenpolyclip.a; make install will put it in /usr/local/lib/ or wherever else you want it to go.
* GTS. I didn't build this -- I use Debian and got it by installing the Debian packages (libgts-0.7-1 and libgts-dev, both version 0.7.3-2 at this writing). So I can't comment on the instructions in source/README.gts.
* newmat. This is a bunch of matrix manipulation utilities, it looks like. The file source/README.newmat tells you what to do, except for the fact that it sends you to the wrong webpage (an info page) to download the file you need. Once on that info page, to actually find the file you want to download, click on "to home page" near the top, then on the link for downloading files. You'll see links for newmat downloads (I downloaded the current newmat11). Once you've got it, just follow the step by step instructions in the source/README.newmat file.
 
Once you have all of the above installed, you can proceed with configuring the TerraGear build, and building TerraGear. The TerraGear CVS Resources page that told you how to check out a copy of the source code tells you what to do to build it: run autogen.sh, then run configure, then make, then make install. However, first, autogen.sh comes out of CVS not-executable. So you'll need to make it executable first with chmod +x autogen.sh
 
Next, when you run configure, it takes arguments telling it where to find the libraries you need. I don't know what those arguments default to, but just for show, if they're all in /usr/local/lib, you could run configure like this: configure w/ args
   
$ ./configure --with-gts=/usr/local/lib/ --with-gpc=/usr/local/lib/
--with-newmat=/usr/local/lib/ --with-plib=/usr/local/lib/
--with-simgear=/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).
 
At that point, you're ready to run "make", then "make install". Unless you gave an option to configure telling it that TerraGear should be installed somewhere other than /usr/local, you'll probably need to be root to do "make install" successfully.
 
I ran into no problems with the above -- everything built and installed OK. This was the most pain-free part of the whole experience.
 
== 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 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 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 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 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 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
/home/cmetzler/Projects/TGSandbox/data/vmap0/v0noa/vmaplv0/noamer/bnd/f/j/fbr
 
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!'''

Latest revision as of 21:39, 3 June 2011