13,212
edits
Using TerraGear: Difference between revisions
Jump to navigation
Jump to search
copyedit; caution, note and tip templates
m (→Troubleshooting: apt.dat.gt must be unzipped!) |
(copyedit; caution, note and tip templates) |
||
| Line 14: | Line 14: | ||
*# Download the latest TerraGear build from [http://flightgear.simpits.org:8080/job/TerraGear-Win-Cmake/lastSuccessfulBuild/artifact/*zip*/archive.zip the FlightGear Build Server]. | *# Download the latest TerraGear build from [http://flightgear.simpits.org:8080/job/TerraGear-Win-Cmake/lastSuccessfulBuild/artifact/*zip*/archive.zip the FlightGear Build Server]. | ||
*# Create or choose a directory to hold the TerraGear tools. | *# Create or choose a directory to hold the TerraGear tools. | ||
*# Unzip the package and move the files from < | *# Unzip the package and move the files from <code>archive/install/msvc100/TerraGear/bin</code> into a sub-directory named <code>Terragear/</code> in the base directory. | ||
* '''Option 2 - Compile TerraGear from source code''' as explained in [[Building TerraGear|this article]]. | * '''Option 2 - Compile TerraGear from source code''' as explained in [[Building TerraGear|this article]]. | ||
{{note|1=You might need <code>default_priorities.txt</code> from the [https://gitorious.org/fg/terragear/blobs/raw/master/src/BuildTiles/Clipper/default_priorities.txt Git repository] or from the archive downloaded from the build server (in the <code>archive/install/msvc100/TerraGear/share</code> subdirectory). See [http://forum.flightgear.org/viewtopic.php?f=5&p=77950 this forum thread] for details.}} | |||
=== GUI tool === | === GUI tool === | ||
| Line 25: | Line 25: | ||
First, choose the boundaries for the area of scenery you want to build, in terms of latitude and longitude. The smaller the area of scenery you generate, the smaller the amount of data you will need, and the less CPU time it will take. For example, if you are just interested in generating a new airport layout at 12.3W 34.4N, then simply generating the scenery between 12W 34N and 13W 35N would be sufficient. | First, choose the boundaries for the area of scenery you want to build, in terms of latitude and longitude. The smaller the area of scenery you generate, the smaller the amount of data you will need, and the less CPU time it will take. For example, if you are just interested in generating a new airport layout at 12.3W 34.4N, then simply generating the scenery between 12W 34N and 13W 35N would be sufficient. | ||
Write down the bounding box (minimum and maximum longitude and latitude) for the scenery you want to generate. Remember that West and South are negative - | Write down the bounding box (minimum and maximum longitude and latitude) for the scenery you want to generate. Remember that West and South are negative - in essence 4W 10S would be -4, -10. Try not to get mixed up, otherwise you'll end up generating scenery or airports on the other side of the planet! | ||
You'll be dealing with multiple different types of data in various formats. Create a new directory for your scenery work. Within that directory, create the following sub-directories: | You'll be dealing with multiple different types of data in various formats. Create a new directory for your scenery work. Within that directory, create the following sub-directories: | ||
; <code>data/</code>: For raw and pre-processed data (eg elevation files) | |||
; <code>output/</code>: For the scenery files you will create | |||
; <code>work/</code>: For data that has been processed (eg by shape-decode) and is ready to be munged into scenery | |||
=== Obtaining and processing data === | === Obtaining and processing data === | ||
TerraGear uses three different kinds of information to generate scenery: | |||
# The elevation of the land (provided by SRTM) | # The elevation of the land (provided by SRTM) | ||
| Line 42: | Line 42: | ||
This article describes how obtain and process each of these types of data in order, and bring it together for use by FlightGear. The order of these steps is important. For example, the airport data step needs the elevation data to determine the elevation of the airports and thus you should start with preparing elevation data. | This article describes how obtain and process each of these types of data in order, and bring it together for use by FlightGear. The order of these steps is important. For example, the airport data step needs the elevation data to determine the elevation of the airports and thus you should start with preparing elevation data. | ||
{{caution|For inclusion in the official FlightGear scenery, all data '''must''' come from [[GNU GPL]] compatible sources!}} | |||
==== Elevation data ==== | ==== Elevation data ==== | ||
| Line 50: | Line 50: | ||
From now on, we'll assume you are using SRTM-3 data. Unless otherwise noted, the process for SRTM-1 is identical. | From now on, we'll assume you are using SRTM-3 data. Unless otherwise noted, the process for SRTM-1 is identical. | ||
You can download the appropriate data from http://dds.cr.usgs.gov/srtm/version2_1/. You want all .hgt.zip files covering your region of interest. Depending on the size of your scenery, there may be quite a few. Download them to < | You can download the appropriate data from http://dds.cr.usgs.gov/srtm/version2_1/. You want all .hgt.zip files covering your region of interest. Depending on the size of your scenery, there may be quite a few. Download them to <code>data/SRTM-1/</code>(or SRTM-3/SRTM-30 depending on the type you downloaded) in your base directory. (Genapts looks for a few known, hardcoded elevation data directories in its working directory. SRTM-30 is one of them and this is the least confusing in that list. Note: W.E.F. 31st July 2010, the genapts tool now also looks for SRTM-1/SRTM-3 directories. If you are using an older version, please supply the directories using --dem-path). | ||
Now we've got the data, we need to convert it into something of use to TerraGear. First, you need to unzip each of the .hgt files. After that, open the commandline (Windows: | Now we've got the data, we need to convert it into something of use to TerraGear. First, you need to unzip each of the .hgt files. After that, open the commandline (Windows: Start > Run > <code>cmd.exe</code>) and change into the base directory (<code>cd .../.../TerraGear</code>). | ||
{{note|According to [[TerraGear_Documentation]], hgtchop is superseded by gdalchop.}} | |||
{{note|For SRTM-1 data, replace the <code>3</code> by a <code>1</code> in the first argument to hgtchop}} | |||
{{tip|If you want to create a batch-file, replace <code>%f</code> with <code>%%f</code>, see [http://technet.microsoft.com/en-us/library/bb490909.aspx]}} | |||
For Windows: | For Windows: | ||
| Line 67: | Line 67: | ||
Now you will get a lot of .arr.gz files in your work/SRTM-3/ directory. We need to convert these to the .fit.gz format. Run the commandline again with | Now you will get a lot of .arr.gz files in your work/SRTM-3/ directory. We need to convert these to the .fit.gz format. Run the commandline again with | ||
{{note|The space and dot at the and are important!}} | |||
For Windows: | For Windows: | ||
| Line 76: | Line 77: | ||
==== Airport data ==== | ==== Airport data ==== | ||
Now we've got elevation data, we can generate our airports. First, create a < | Now we've got elevation data, we can generate our airports. First, create a <code>data/airports/</code> directory and copy in your apt.dat file. This may be direct from your FlightGear data package (though you'll need to unzip it), or it may be one that you've modified with [[WorldEditor]]. | ||
The command to create airports is "genapts850". Run it without any arguments to see the various command-line options. | The command to create airports is "genapts850". Run it without any arguments to see the various command-line options. | ||
| Line 82: | Line 83: | ||
If it is simply run with a specified apt.dat and work directory, it will generate airport layouts for every airport in the file, which can take a long time. | If it is simply run with a specified apt.dat and work directory, it will generate airport layouts for every airport in the file, which can take a long time. | ||
If you are just creating a single airport and you know the ICAO ID ( | If you are just creating a single airport and you know the ICAO ID (for example [[KSFO]], EGPH or EG32), use is as follows from your root scenery directory (in essence the directory above your data, work and output directories). If you use an apt.dat file with one single airport in it you should omit the <code>--airport</code> parameter. | ||
genapts850 --input=data/airports/apt.dat --work=./work --airport=<AIRPORT_ID> | genapts850 --input=data/airports/apt.dat --work=./work --airport=<AIRPORT_ID> | ||
| Line 89: | Line 90: | ||
Genapts will create two sub-directories in your work directory: | Genapts will create two sub-directories in your work directory: | ||
* < | |||
* < | * <code>AirportArea/</code> | ||
* <code>AirportObj/</code> | |||
These contain the definitions of the airport layout and any objects present (e.g. windsocks and beacons). | These contain the definitions of the airport layout and any objects present (e.g. windsocks and beacons). | ||
| Line 97: | Line 100: | ||
The landuse data can be split into a number of different types: | The landuse data can be split into a number of different types: | ||
; Landmass: Separates the land from the sea. It can be used as a mask for all other data. The most commonly used is the VMAP0 Landmass, but GSHHS can also be used. When running tg-construct with <code>--ignore-landmass</code>, all input shapefiles will be taken into consideration, so no landmass mask is required then. | |||
; Land use data: Defines whether a piece of land is forest, urban, sand, lava, glacier etc. These are usually VMAP0 data, defined as polygons. | |||
; Line data: Includes railroads, streams, roads. Typically VMAP0, but also Open Street Map for roads. | |||
; Point data: Is currently only used for defining towns. | |||
By far the easiest way to get this data is to download shapefiles from the wonderful [http://mapserver.flightgear.org MapServer]. The MapServer lets you download the shapefiles for any selected scenery area. Click on the "Download Shapefiles" link (or go direct: http://mapserver.flightgear.org/download.psp). Enter in the bounding box of the scenery you want to generate, select the type of shapefile data you want, and click download. | By far the easiest way to get this data is to download shapefiles from the wonderful [http://mapserver.flightgear.org MapServer]. The MapServer lets you download the shapefiles for any selected scenery area. Click on the "Download Shapefiles" link (or go direct: http://mapserver.flightgear.org/download.psp). Enter in the bounding box of the scenery you want to generate, select the type of shapefile data you want, and click download. | ||
==== Layers ==== | |||
; <code>v0</code>: Global coverage, low detail. This is "the last resort", but unfortunately it is the only layer that covers the entire world. | |||
; <code>cs</code>: It is v0 with some contributions someone did in the past. Get this instead of v0. | |||
; <code>v1</code>: Only parts of some countries available, higher detail than v0. | |||
; <code>clc06</code>: European '''only'''. Very high detail, this is the preferred choice for an European country. | |||
; <code>osm</code>: Global coverage, high resolution but very low detail. | |||
: This means: if you are interested in an area out of Europe and forests are defined in OpenStreetMaps for your area, this is going to be the best data source. If forests are not defined, you will get a dull, neverending DEFAULT landclass. OSM provides the best coastline and I encourage you to use this coastline even in Europe. [http://forum.flightgear.org/viewtopic.php?f=5&t=25549&sid=d501cb651ef9e34ca9dc8fae429d51ab&p=234002#p234002] | |||
{{caution|Make sure each shape file is in its own directory whether you download shape files or create your own otherwise the ogrDecode step will fail.}} | {{caution|Make sure each shape file is in its own directory whether you download shape files or create your own otherwise the ogrDecode step will fail.}} | ||
Download each shapefile into a seperate (!) < | Download each shapefile into a seperate (!) <code>data/shapefiles/...</code> directory. So, for v0_landmass, you would end up with <code>data/shapefiles/v0_landmass/v0_landmass.shp</code> etc. | ||
You can load these shapefiles into a GIS editor such as [[QGIS]] or GRASS to view and edit. This is a good idea to verify you have the correct files! Later on, you can experiment with replacing various shapefiles with other versions (GSHHS for coastline, OSM for roads etc.). | You can load these shapefiles into a GIS editor such as [[QGIS]] or GRASS to view and edit. This is a good idea to verify you have the correct files! Later on, you can experiment with replacing various shapefiles with other versions (GSHHS for coastline, OSM for roads etc.). | ||
| Line 124: | Line 129: | ||
* the material type | * the material type | ||
Each shape-file corresponds with one of the material types defined in the materials.xml files. The mapping is pretty obvious. For example, v0_mixedcroppasturecover maps to MixedCropPastureCover. Note that the material types are case-sensitive, so it is a good idea to refer to the < | Each shape-file corresponds with one of the material types defined in the materials.xml files. The mapping is pretty obvious. For example, <code>v0_mixedcroppasturecover</code> maps to <code>MixedCropPastureCover</code>. Note that the material types are case-sensitive, so it is a good idea to refer to the <code>[[$FG_ROOT]]/Materials/default/materials.xml</code> file (<code>[[$FG ROOT]]/materials.xml</code> in FlightGear 2.6.0 and older) to hand so you can check. The exception is landmass, which - when used - MUST be mapped onto the type Default. | ||
Additionally, there are a number of optional arguments, to indicate the width of line data (for roads, streams, railways), how large to make point data (for towns) and how long the longest straight line is allowed to be. | Additionally, there are a number of optional arguments, to indicate the width of line data (for roads, streams, railways), how large to make point data (for towns) and how long the longest straight line is allowed to be. | ||
For example, to decode the v0_landmass shapefile, you use the following command: | For example, to decode the <code>v0_landmass</code> shapefile, you use the following command: | ||
ogr-decode --max-segment 500 --area-type Default work/Default data/shapefiles/v0_landmass | ogr-decode --max-segment 500 --area-type Default work/Default data/shapefiles/v0_landmass | ||
| Line 173: | Line 178: | ||
We need to define: | We need to define: | ||
* The work (--work-dir) and output (--output-dir | * The work (<code>--work-dir</code>) and output (<code>--output-dir</code>) directories. | ||
* The center of the scenery we want to generate (<code>--lat</code> and <code>--lon</code>). | |||
* The center of the scenery we want to generate (--lat | * The radius (<code>--xdist</code> and <code>--ydist</code>) from which to generate. | ||
* The radius (--xdist | |||
* All the work directories to include in the scenery. | * All the work directories to include in the scenery. | ||
{{note|The output directory must point to a <code>Terrain/</code> directory, else recent FlightGear versions will be unable to load the terrain.}} | |||
For example: | For example: | ||
{{Pre2|<nowiki>tg-construct --work-dir=./work --output-dir=./output/Terrain --min-lon=55 --max-lon=57 --min-lat=60 --max-lat=62 AirportArea SRTM-3 AirportObj Default Stream Bog IrrCropPastureCover Town Lake Urban Railroad DryCropPastureCover Road EvergreenBroadCover Marsh Sand MixedCropPastureCover ScrubCover GrassCover MixedForestCover</nowiki> }} | {{Pre2|<nowiki>tg-construct --work-dir=./work --output-dir=./output/Terrain --min-lon=55 --max-lon=57 --min-lat=60 --max-lat=62 AirportArea SRTM-3 AirportObj Default Stream Bog IrrCropPastureCover Town Lake Urban Railroad DryCropPastureCover Road EvergreenBroadCover Marsh Sand MixedCropPastureCover ScrubCover GrassCover MixedForestCover</nowiki> }} | ||
When this finishes, the output directory will contain a scenery sub-tree. Point to it by setting either [[$FG_SCENERY]] or by using the --fg-scenery command-line option to fgfs, and give your new scenery a try! | When this finishes, the output directory will contain a scenery sub-tree. Point to it by setting either [[$FG_SCENERY]] or by using the <code>--fg-scenery</code> command-line option to fgfs, and give your new scenery a try! | ||
== Troubleshooting == | == Troubleshooting == | ||
Below is a list of common problems and solutions. If in doubt - Google it. Many problems (particularly when compiling TerraGear) have been hit before: | Below is a list of common problems and solutions. If in doubt - Google it. Many problems (particularly when compiling TerraGear) have been hit before: | ||
* Crashes in genapts. Sometimes genapts will crash when dealing with a particular airport. In that case, try running it again with the --start-id argument to start at the airport it failed on, and the --nudge argument which tries to nudge the calculations in the right direction. | * Crashes in genapts. Sometimes genapts will crash when dealing with a particular airport. In that case, try running it again with the <code>--start-id</code> argument to start at the airport it failed on, and the <code>--nudge</code> argument which tries to nudge the calculations in the right direction. | ||
* tg-construct | * tg-construct killed. The tg-construct process may kill itself if it is using too many system resources. Increasing the values for <code>setrlimit</code> in <code>src/BuildTiles/Main/main.cxx</code> is the best solution. | ||
* tg-construct silently stops immediately without an error and nothing goes to the "output" directory: make sure that lon/lat values correspond to tiles boundaries. See [[ | * tg-construct silently stops immediately without an error and nothing goes to the "output" directory: make sure that lon/lat values correspond to tiles boundaries. See [[Tile Index Scheme]] | ||
* Airports appear in the bottom of holes, or there are spaces between the airports and the scenery. This typically happens when genapts is unable to find the correct elevation data, or the elevation data changed between running genapts and shape-decode. Try generating a single airport in your scenery area using genapts, and look at the output. In particular, make sure there is a work/SRTM-3 directory. | * Airports appear in the bottom of holes, or there are spaces between the airports and the scenery. This typically happens when genapts is unable to find the correct elevation data, or the elevation data changed between running genapts and shape-decode. Try generating a single airport in your scenery area using genapts, and look at the output. In particular, make sure there is a work/SRTM-3 directory. | ||
* Only the airports appear in the scenery. There are three typical causes for this: | * Only the airports appear in the scenery. There are three typical causes for this: | ||
** You didn't download the correct shapefiles for the area. | ** You didn't download the correct shapefiles for the area. | ||
** You haven't run shape-decode on the v0_landmass shapefile as Default | ** You haven't run shape-decode on the <code>v0_landmass</code> shapefile as Default | ||
** You didn't include the correct directories in tg-construct. | ** You didn't include the correct directories in tg-construct. | ||
* Generate scenery includes data removed from the shapefiles. If you are editing shapefiles, you need to delete the appropriate work subdirectory before running shape-decode. Otherwise your changes will be in addition to those already present. | * Generate scenery includes data removed from the shapefiles. If you are editing shapefiles, you need to delete the appropriate work subdirectory before running shape-decode. Otherwise your changes will be in addition to those already present. | ||
* All the scenery is flat and at sea-level. Typically this is because you didn't include any elevation data in your tg-construct command. Make sure there's a STRM-3 directory included in the command-line. | * All the scenery is flat and at sea-level. Typically this is because you didn't include any elevation data in your tg-construct command. Make sure there's a STRM-3 directory included in the command-line. | ||
* All terrain copies the material of a certain shapefile. You have probably forgotten to put each of the downloaded shapefiles in a seperate directory inside the Data/shapefiles directory. | * All terrain copies the material of a certain shapefile. You have probably forgotten to put each of the downloaded shapefiles in a seperate directory inside the Data/shapefiles directory. | ||
* genapts850 never passes the stage "Adding airport <ICAO> to parse list": did you unzip apt.dat.gz? | * genapts850 never passes the stage "Adding airport <ICAO> to parse list": did you unzip <code>apt.dat.gz</code>? | ||
== General comments from forum discussion == | == General comments from forum discussion == | ||