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

Difference between revisions of "Building TerraGear"

From FlightGear wiki
Jump to: navigation, search
(Using TerraGear)
Line 1: Line 1:
== Intro ==
+
== Introduction ==
  
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.  
+
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 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.  
+
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 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.  
+
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).  
 
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).  
Line 11: Line 11:
 
== Building TerraGear ==
 
== 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.  
+
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:  
 
Some comments on the other stuff you need:  
Line 26: Line 26:
 
  --with-newmat=/usr/local/lib/ --with-plib=/usr/local/lib/  
 
  --with-newmat=/usr/local/lib/ --with-plib=/usr/local/lib/  
 
  --with-simgear=/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).  
 
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).  
  
Line 35: Line 35:
 
== Using TerraGear ==
 
== 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.  
+
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. 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.  
+
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 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.  
+
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 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.  
+
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.
 
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.
Line 54: Line 54:
 
  $ cd work  
 
  $ cd work  
 
  $ tgvpf --chunk=w080n40 --work-dir=LandMass --material=Default /cdrom/vmaplv0 noamer bnd polbnda  
 
  $ tgvpf --chunk=w080n40 --work-dir=LandMass --material=Default /cdrom/vmaplv0 noamer bnd polbnda  
+
 
 
You'll get an error:  
 
You'll get an error:  
 
  Processing failed with VPF exception: Failed to open VPF table file  
 
  Processing failed with VPF exception: Failed to open VPF table file  

Revision as of 00:10, 31 May 2006

Introduction

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!