TerraGear GUI: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(Rewriting the manual for the TerraGear GUI)
 
mNo edit summary
Line 5: Line 5:
| initialrelease        = March 24, 2009
| initialrelease        = March 24, 2009
}}
}}
Since March 2009 a GUI Tool for [[TerraGear]] is available at [http://www.flightgear.org/forums/viewtopic.php?p=30238#p30238 the forum]. This tool makes the use of commandlines redundant, through which it's easy to use for everyone not known with commandlines.
Since March 2009 a '''GUI''' tool for '''[[TerraGear]]''' is available at [http://www.flightgear.org/forums/viewtopic.php?p=30238#p30238 the forum]. This tool makes the use of commandlines redundant, through which it's easy to use for everyone not known with commandlines.


=Manual=
=Manual=
Create a <tt>TerraGearWork/</tt> folder and inside that folder create three more named:
Create a <tt>TerraGearWork/</tt> folder somewhere on your computer and create the following three folders inside that one:
* '''Data''': used to collect the raw unprocessed data we need to feed the tools.
* '''Data/''': used to collect the raw unprocessed data we need to feed the tools.
* '''Output''': used at the very end and is where your newly processed scenery is finally stored.
* '''Output/''': used at the very end and is where your newly processed scenery is finally stored.
* '''Work''': we will keep the files and folders here we will be generating with the TerraGear Tools.
* '''Work/''': we will keep the files and folders here we will be generating with the TerraGear Tools.


==Obtaining data==
==Obtaining data==
Line 18: Line 18:
*'''SRTM-1''': Highly accurate 1-arcsecond resolution data, for the USA.
*'''SRTM-1''': Highly accurate 1-arcsecond resolution data, for the USA.
*'''SRTM-3''': Less accurate 3-arcsecond data, for the rest of the world.
*'''SRTM-3''': Less accurate 3-arcsecond data, for the rest of the world.
From now on, we’ll assume you are using SRTM-3 data. Unless otherwise noted, the process for SRTM-1 is identical. You can get download appropriate data at ftp://e0srp01u.ecs.nasa.gov/srtm. You want all .hgt.zip files covering your region of interest. Depending on the size of your scenery, there may be quite a few. Make sure you download ALL the ones which cover your area of interest. Create a new folder in your <tt>TerraGearWork/Data/</tt> folder called <tt>SRTM-30/</tt>. Download the .hgt.zip files there. The reason why the directories are called SRTM-30 is because genapts will look for a few known, hardcoded directories in it’s working directory. SRTM-30 is one of them and this is the least confusing in that list.
From now on, we will assume that you are using SRTM-3 data. Unless otherwise noted, the process for SRTM-1 is identical.  


Unzip all of the .hgt.zip files.
Create a new folder in your <tt>TerraGearWork/Data/</tt> folder called <tt>SRTM-30/</tt>. Now download appropriate data from ftp://e0srp01u.ecs.nasa.gov/srtm. You want ALL .hgt.zip files covering the area you want to create. Depending on the size of your scenery, there may be quite a few. The reason why the directories are called SRTM-30 is because genapts (a tool we will meet further on) will look for a few known, hardcoded directories in it’s working directory. SRTM-30 is one of them and this is the least confusing in that list.
 
Unzip all of the .hgt.zip files using your favorite software.


===Land use data===
===Land use data===
The final piece of data we need to generate is the land-use data. In general, this is taken from the VMAP0 dataset as shapefiles from the scenery database mapserver, but other sources can be used. The landuse data can be split into a number of different types:  
The final piece of data we need to download is the land-use data. In general, this is taken from the VMAP0 dataset, but other sources can be used as well. The landuse data can be split into a number of different types:  
*'''Landmass''': separates the land from the sea. It is used as a mask for all other data. The most common used is the VMAP0 Landmass, but GSHHS can be used as well.  
*'''Landmass''': separates the land from the sea. It is used as a mask for all other data. The most common used is the VMAP0 Landmass, but GSHHS can be used as well.  
*'''Land use data''': defines whether a piece of land is forest, urban, sand, lava, glacier etc. These are usually VMAP0 data, defined as polygons.
*'''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 [http://www.openstreetmap.org Open Street Map] for roads.
*'''Line data''': includes railroads, streams, roads. Typically VMAP0, but also [http://www.openstreetmap.org Open Street Map] for roads.
*'''Point data''': currently only used for defining towns.
*'''Point data''': currently only used for defining towns.
By far the easiest way to get this data is to download shapefiles from the [http://mapserver.flightgear.org FlightGear Mapserver]. This provides access to a database of information, and allows you to download the specific shapefiles for your scenery area. Click on the Download Shapefiles link, enter in the bounding box of the scenery you want to generate, select the shapefiles you want, and click download. For your first scenery generation, you want all of the ones listed under VMap0 (with prefix v0_). Download each of them into a seperate Data/Shapefiles directory. The v0_landmass shapefiles goes into a <tt>Data/Shapefiles/v0_landmass/</tt> directory for example and v0_urban should be downloaded into <tt>Data/Shapefiles/v0_urban/</tt>.
By far the easiest way to get this data is to download shapefiles from the [http://mapserver.flightgear.org FlightGear Mapserver]. This webpage provides access to a database, and allows you to download the specific shapefiles for your scenery area. Click on the Download Shapefiles link, enter in the bounding box of the scenery you want to generate, select the shapefiles you want, and click download. For your first scenery generation, you want all of the ones listed under VMap0 (with prefix v0_). Download each of them into a seperate Data/Shapefiles directory. The v0_landmass shapefiles goes into a <tt>Data/Shapefiles/v0_landmass/</tt> directory for example and v0_urban should be downloaded into <tt>Data/Shapefiles/v0_urban/</tt>.


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! There is a Fantastic Tutorial by John Holden which shows you how to create your own shapefiles here.http://stattosoftware.com/flightgear/tutorial/index.html 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! There is [http://stattosoftware.com/flightgear/tutorial/index.html a tutorial available] written by John Holden which shows you how to create your own shapefiles. Later on, you can experiment with replacing various shapefiles with other versions (GSHHS for coastline, OSM for roads etc.).


==Using the GUI==
==Using the GUI==
As you can see, if you click on the Tools button the list of available tools is shown. They are in order of use if we were to start from the beginning of the process, so are they in this manual.
Now we can finally launch the <tt>TerraGear Toolset GUI.exe</tt>. If you click on the Tools button the list of available tools will be shown. The first tool will be needed first, then the seconds and so on. This manual follows the same steps.


===HGTchop===
===HGTchop===
The HGTchop tool uses the .hgt.zip files you have and converts it into a form that FlightGear can read. We need to first create another folder, this time under the <tt>Work/</tt> directory call <tt>SRTM-30/</tt>. This is where the processed data will be output to.
The HGTchop tool uses the .hgt.zip files you have downloaded earlier on and converts it into a form that FlightGear can read. First we need to create yet another folder, this time it's <tt>Work/SRTM-30/</tt>. The processed data will be output to this folder, if you set the correct Output path.  


A command box will open and you will see the tool working away. It will produce numerous .arr.gz files which is quite rough data and requires more refinement with Terrafit.
Select the first .hgt.zip file and click the Start button. A command box will open and you will see the tool working away. It will produce numerous .arr.gz files which is quite rough data and requires more refinement with Terrafit (see below). At the moment you need to repeat this step for every file in your <tt>Data/SRTM-30/</tt> folder.  


At the moment you need to repeat this step for all the files in your <tt>Data/SRTM-30/</tt> folder. Once completed we can move onto the next tool.
Once completed we can move onto the next tool.


===Terrafit===
===Terrafit===
The Terrafit tool is used to process the .arr.gz files into a more refined data. The data collected so far would show flat land and requires more work, so lets use Terrafit to enhance our data.
The Terrafit tool is used to process the .arr.gz files that you just created into a more refined data. The data collected so far would show flat land and requires more work, so lets use Terrafit to enhance our data.


The three boxes Min Points, Max Points and Max Error can be left blank, unless you are an advanced user. The tool currently uses the default setting for these figures which are sufficient for use in FlightGear. with this tool simply use the browse button to point the tool at the <tt>Work/SRTM-30/</tt> folder where the .aar.gz files are stored. Terrafit will extract .fit files which has converted all our data to the correct elevation data required.
The three boxes Min Points, Max Points and Max Error can be left blank, unless you are an advanced user. The tool currently uses the default setting for these figures which are sufficient for use in FlightGear. Now simply use the browse button to point the tool to the <tt>Work/SRTM-30/</tt> folder where the .aar.gz files are stored. Press the Start button and Terrafit will converte all our data to the correct elevation data required, leaving .fit files in the <tt>Work/SRTM-30/</tt> folder.


===Genapt===
===Genapt===
First create a folder in <tt>Data/</tt> called <tt>Airports/</tt>. Locate FlightGears apt.dat file which is usually in <tt>[[$FG_ROOT]]/Airports/</tt>.
What is scenery without airport in a flight simulator? If your tile does not contain any airports, you can skip this part of the manual on continue with [[#ogr-decode|ogr-decode]].
Copy this file to your newly created Airport folder (you will need to unzip it) Once you have completed this we can use the Genapts Tool.
 
First create the <tt>Data/Airports/</tt> directory. Then locate FlightGears <tt>apt.dat.gz</tt> file, which is usually in <tt>[[$FG_ROOT]]/Airports/</tt>.
Copy this file to your newly created <tt>Airports/</tt> folder. Unzip the file before you continue.
 
Use the upper browse button to locate your, just unzipped, apt.dat file. In the second box, use the browse button to locate your <tt>Work/</tt> folder.
If you only want to create the scenery for a specific airport you can enter the ICAO name into the relevant field. If you want to create a larger piece of scenery you can also enter min/max lat and lon co-ordinates. If you do not enter any information in any of the boxes, the tool will run through the entire apt.dat file, which can take a long time.
 
Click the Start button. Genapts will create two sub-directories in your <tt>Work/</tt> directory, namely AirportArea and AirportObj. These define the definitions of the airport layout and any objects present (e.g. windsocks and beacons). Right, that’s the airports sorted out.


===ogr-decode===
===ogr-decode===
Line 61: Line 70:


So this is what we need to begin. A shapefiles directory in your <tt>Data/</tt> folder. Then for each of the different shapefiles you are going to create a folder with that name in the <tt>Work/</tt> directory. see the image below for example.
So this is what we need to begin. A shapefiles directory in your <tt>Data/</tt> folder. Then for each of the different shapefiles you are going to create a folder with that name in the <tt>Work/</tt> directory. see the image below for example.
===fgfs-construct===
The fgfs-construct tool brings all your gathered data together, throws it in a washing machine and spits it out the otherside in format ready for use with FlightGear.
Using the Browse button, select the <tt>Work/</tt> directory. Then select the <tt>Output/</tt> directory we created at the start of the manual. The next two fields are for the centre of the area you have chosen. The next two fields are the outward distance from the centre in degrees. If you click on the Get Folders button it will populate the empty field with all the folders in your <tt>Work/</tt> directory. Highlite them all, holding Shift and clicking the first and last items in the list.
Press Create Scenery to fianlly generate your scenery. This may take a long time depending on the size of the area you are creating the scenery for and the level of detail in your shapefiles. Simple and small sceneries will take a couple of minutes, where larger, more detailed areas can take over an hour! So trying new things on small areas first will save you a lot of time.
The folders and files in the <tt>Output/</tt> directory are ready to use scenery. You can set the scenery path of FlightGear to this directory to check if the scenery is generated correctly.


[[Category:Scenery enhancement]]
[[Category:Scenery enhancement]]

Revision as of 20:00, 15 September 2009

TerraGear GUI
TerraGearGUI.jpg
Developed by Alex Park
Initial release March 24, 2009

Since March 2009 a GUI tool for TerraGear is available at the forum. This tool makes the use of commandlines redundant, through which it's easy to use for everyone not known with commandlines.

Manual

Create a TerraGearWork/ folder somewhere on your computer and create the following three folders inside that one:

  • Data/: used to collect the raw unprocessed data we need to feed the tools.
  • Output/: used at the very end and is where your newly processed scenery is finally stored.
  • Work/: we will keep the files and folders here we will be generating with the TerraGear Tools.

Obtaining data

Elevation data

The best elevation data currently available is from the Shuttle Radar Topography Mission (SRTM). There are two types of SRTM data:

  • SRTM-1: Highly accurate 1-arcsecond resolution data, for the USA.
  • SRTM-3: Less accurate 3-arcsecond data, for the rest of the world.

From now on, we will assume that you are using SRTM-3 data. Unless otherwise noted, the process for SRTM-1 is identical.

Create a new folder in your TerraGearWork/Data/ folder called SRTM-30/. Now download appropriate data from ftp://e0srp01u.ecs.nasa.gov/srtm. You want ALL .hgt.zip files covering the area you want to create. Depending on the size of your scenery, there may be quite a few. The reason why the directories are called SRTM-30 is because genapts (a tool we will meet further on) will look for a few known, hardcoded directories in it’s working directory. SRTM-30 is one of them and this is the least confusing in that list.

Unzip all of the .hgt.zip files using your favorite software.

Land use data

The final piece of data we need to download is the land-use data. In general, this is taken from the VMAP0 dataset, but other sources can be used as well. The landuse data can be split into a number of different types:

  • Landmass: separates the land from the sea. It is used as a mask for all other data. The most common used is the VMAP0 Landmass, but GSHHS can be used as well.
  • 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: currently only used for defining towns.

By far the easiest way to get this data is to download shapefiles from the FlightGear Mapserver. This webpage provides access to a database, and allows you to download the specific shapefiles for your scenery area. Click on the Download Shapefiles link, enter in the bounding box of the scenery you want to generate, select the shapefiles you want, and click download. For your first scenery generation, you want all of the ones listed under VMap0 (with prefix v0_). Download each of them into a seperate Data/Shapefiles directory. The v0_landmass shapefiles goes into a Data/Shapefiles/v0_landmass/ directory for example and v0_urban should be downloaded into Data/Shapefiles/v0_urban/.

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! There is a tutorial available written by John Holden which shows you how to create your own shapefiles. Later on, you can experiment with replacing various shapefiles with other versions (GSHHS for coastline, OSM for roads etc.).

Using the GUI

Now we can finally launch the TerraGear Toolset GUI.exe. If you click on the Tools button the list of available tools will be shown. The first tool will be needed first, then the seconds and so on. This manual follows the same steps.

HGTchop

The HGTchop tool uses the .hgt.zip files you have downloaded earlier on and converts it into a form that FlightGear can read. First we need to create yet another folder, this time it's Work/SRTM-30/. The processed data will be output to this folder, if you set the correct Output path.

Select the first .hgt.zip file and click the Start button. A command box will open and you will see the tool working away. It will produce numerous .arr.gz files which is quite rough data and requires more refinement with Terrafit (see below). At the moment you need to repeat this step for every file in your Data/SRTM-30/ folder.

Once completed we can move onto the next tool.

Terrafit

The Terrafit tool is used to process the .arr.gz files that you just created into a more refined data. The data collected so far would show flat land and requires more work, so lets use Terrafit to enhance our data.

The three boxes Min Points, Max Points and Max Error can be left blank, unless you are an advanced user. The tool currently uses the default setting for these figures which are sufficient for use in FlightGear. Now simply use the browse button to point the tool to the Work/SRTM-30/ folder where the .aar.gz files are stored. Press the Start button and Terrafit will converte all our data to the correct elevation data required, leaving .fit files in the Work/SRTM-30/ folder.

Genapt

What is scenery without airport in a flight simulator? If your tile does not contain any airports, you can skip this part of the manual on continue with ogr-decode.

First create the Data/Airports/ directory. Then locate FlightGears apt.dat.gz file, which is usually in $FG_ROOT/Airports/. Copy this file to your newly created Airports/ folder. Unzip the file before you continue.

Use the upper browse button to locate your, just unzipped, apt.dat file. In the second box, use the browse button to locate your Work/ folder. If you only want to create the scenery for a specific airport you can enter the ICAO name into the relevant field. If you want to create a larger piece of scenery you can also enter min/max lat and lon co-ordinates. If you do not enter any information in any of the boxes, the tool will run through the entire apt.dat file, which can take a long time.

Click the Start button. Genapts will create two sub-directories in your Work/ directory, namely AirportArea and AirportObj. These define the definitions of the airport layout and any objects present (e.g. windsocks and beacons). Right, that’s the airports sorted out.

ogr-decode

Now we need to decode the shapefiles into TerraGear format. This is done with the ogr-decode tool. There are several important command-line arguments to OGR decode:

  • Filename of the shapefile (without the .shp extension for shape decode) you want to decode.
  • Directory you want to write the data to.
  • Material type to use.

Each of the shapefiles maps onto one of the material types defined in your $FG_ROOT/materials.xml files. The mapping is pretty obvious, e.g. v0_roads maps to Roads etc.

Warning: v0_landmass MUST be mapped onto the type Default.

So this is what we need to begin. A shapefiles directory in your Data/ folder. Then for each of the different shapefiles you are going to create a folder with that name in the Work/ directory. see the image below for example.

fgfs-construct

The fgfs-construct tool brings all your gathered data together, throws it in a washing machine and spits it out the otherside in format ready for use with FlightGear.

Using the Browse button, select the Work/ directory. Then select the Output/ directory we created at the start of the manual. The next two fields are for the centre of the area you have chosen. The next two fields are the outward distance from the centre in degrees. If you click on the Get Folders button it will populate the empty field with all the folders in your Work/ directory. Highlite them all, holding Shift and clicking the first and last items in the list.

Press Create Scenery to fianlly generate your scenery. This may take a long time depending on the size of the area you are creating the scenery for and the level of detail in your shapefiles. Simple and small sceneries will take a couple of minutes, where larger, more detailed areas can take over an hour! So trying new things on small areas first will save you a lot of time.

The folders and files in the Output/ directory are ready to use scenery. You can set the scenery path of FlightGear to this directory to check if the scenery is generated correctly.