TerraGear GUI: Difference between revisions

Jump to navigation Jump to search
m
→‎For GNU/Linux users: Add HelpLines for common Errors
m (+ OS, thanks MILTSD)
m (→‎For GNU/Linux users: Add HelpLines for common Errors)
(57 intermediate revisions by 12 users not shown)
Line 1: Line 1:
{{Infobox Software
{{Infobox Software
| title                 = TerraGear GUI
| title                 = TerraGear GUI
| image                 = TerraGearGUI.jpg
| image                 = TerraGear GUI download San Francisco.png
| developedby           = Alex Park
| alt                  = The download page with the San Francisco bay area selected.
| initialrelease         = March 24, 2009
| developedby           = Gijs de Rooy (original by Alex Park)
| os                     = Windows
| initialrelease       = March 24, 2009 (original)<br>March 27, 2010
| latestrelease = 0.9.x (2012)
| writtenin            = C++ (Qt)
| os                   = Windows, Linux, Mac OS X
| website = https://sourceforge.net/p/flightgear/fgscenery/terrageargui/ci/master/tree/
}}
}}
Since March 2009 a '''GUI''' tool for '''[[TerraGear]]''' is available at [http://www.flightgear.org/forums/viewtopic.php?p=30238#p30238 the forum], available on Windows. This tool makes the use of commandlines redundant, through which it's easy to use for everyone not known with commandlines.
The '''GUI''' tool for '''[[TerraGear]]''' allows people to create [[scenery]] for [[FlightGear]] without using commandlines.


=Manual=
== Obtaining the GUI ==
Create a <tt>TerraGearWork/</tt> folder somewhere on your computer and create the following three folders inside that one:
You can either build the GUI [https://sourceforge.net/p/flightgear/fgscenery/terrageargui/ci/master/tree/ from source], or download a pre-compiled build:
* '''Data/''': used to collect the raw unprocessed data we need to feed the tools.
* [http://liveries.flightgear.org/terrageargui/ Windows builds]
* '''Output/''': used at the very end and is where your newly processed scenery is finally stored.
Please note that:
* '''Work/''': we will keep the files and folders here we will be generating with the TerraGear Tools.
* you need to download/compile a recent version of [[TerraGear]] as well;
* for Windows users, you'll need to add three DLLs to you TerraGear GUI root directory:
** msvcp71.dll (see [[TerraGear_Installation_for_Windows]] to know how to get it)
** mscvr71.dll (see [[TerraGear_Installation_for_Windows]] to know how to get it)
** gdal12.dll (this can be retrieved from ftp://ftp.ihg.uni-duisburg.de/FlightGear/Win32/terragear-cs-Win32-20101002.zip )


==Obtaining data==
==== For GNU/Linux users ====
====Elevation data====
# Grab the sources and store it where you want:<br/><pre>git clone git://git.code.sf.net/p/flightgear/fgscenery/terrageargui</pre>
The best elevation data currently available is from the Shuttle Radar Topography Mission (SRTM). There are two types of SRTM data:
# Then go in the source:<br/><pre>cd terrageargui</pre>
*'''SRTM-1''': Highly accurate 1-arcsecond resolution data, for the USA.
# Create a build dir:<br/><pre>mkdir build && cd build</pre>
*'''SRTM-3''': Less accurate 3-arcsecond data, for the rest of the world.
# Now build it:<br/><pre>qmake .. </pre> or<pre>qmake-qt4 ..</pre> then<pre>make</pre>
From now on, we will assume that you are using SRTM-3 data. Unless otherwise noted, the process for SRTM-1 is identical.  
:::<sub>In case of ERRORS You may have to add the following via SYNAPTIC:</sub>
:::*<sub>for "/usr/lib/i386-linux-gnu/qt4/bin/uic: Command not found" add: libqt4-dev-bin</sub>
:::*<sub>for "QtGui/QApplication: No such file or directory" add: qt4-dev-tools</sub>
<br />
# You can now start it with:<br/><pre>"./bin/TerraGUI" or "./build/TerraGUI"</pre>


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.
You're done!


Unzip all of the .hgt.zip files using your favorite software.
== Using the GUI ==
The GUI exist of several tabs. For normal scenery creation, all the tabs should be gone through in the order they are arranged.


===Land use data===
=== Start ===
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:
# Set the TerraGear directory, in which you'll find the subdirectories bin/ and share/. TerraGear must be downloaded/build seperatly from the GUI!
*'''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.  
# Set the project's directory. In this directory, all project related stuff will be stored throughout the process. You best choose an empty directory specific to your project.
*'''Land use data''': defines whether a piece of land is forest, urban, sand, lava, glacier etc. These are usually VMAP0 data, defined as polygons.
# Set your FlightGear's root ([[$FG_ROOT]]). This is used to retrieve the list of available terrain materials.
*'''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.
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 [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.).
=== Download ===
Specify boundaries in the boxes on the left, or select an area on the map. Next select a source to download shapefiles for that area. Note that OpenStreetMap only includes line date (roads, rivers), so you'll need some polygon data for the actual terrain. Both [[World Custom Scenery Project|Custom Scenery]] and [[CORINE]] (only Europe) provide that. The GUI downloads and unpacks the package to your <tt>{project's directory}/data/</tt>.


==Using the GUI==
Alternatively you can download shapefiles from [http://mapserver.flightgear.org/download.psp the mapserver by hand]. Unpack the downloaded file(s) to your <tt>{project's directory}/data/</tt>.
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===
==== Elevation data ====
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.  
Elevation files are optional, but of course required to generate scenery with elevation offsets (even flat countries like the Netherlands need elevation data, since no country is completely at sealevel. Simply select a data source and then click the button to download the HGT files that span your specified area. The original source is usgs.gov, but a cleaned variant of the same data is available from fgx.ch (see [http://downloads.fgx.ch/geodata/data/srtm/README.txt the readme] for more information). The data will be saved in in <tt>{project's directory}/data/SRTM-3</tt>.  


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.  
===== By hand =====
[[File:HGT tiles example.png|thumb|An example of HGT file tiles.]]
Downloading tiles by hand is somewhat tricky. If your scenery has a boundary of:
{| class="wikitable"
!
! Min
! max
|-
! Latitude
| 33
| 37
|-
! Longitude
| -2
| 2
|}
The GUI would display the range as <tt>N33W002-N37E002</tt>. This means you have to download all tiles in that range, which are all the tiles as shown in the image on the right. Unpack the downloaded elevation file(s) in <tt>{project's directory}/data/SRTM-3</tt>.


Once completed we can move onto the next tool.
If you don't know how to find the boundaries range you can use Google Earth with this KMZ file : [http://clemaez.fr/flightgear/grid_1_degree.kmz grid_1_degree.kmz]
# Download KMZ file above
# Open it with Google Earth and active it (if not yet active). A lot of red lines should appears
# Zoom where you want know the boundaries range
# Click on the bottom left boundary wanted and report the displayed value in TerraGear GUI. (i.e: if Google Earth value is "W9_N42", report Minimum Latitude value "42" and Minimum Longitude value "-9")
# Click on the top right boundary wanted and report the displayed value in TerraGear GUI. (i.e: if Google Earth value is "E6_N45", report Maximum Latitude value "45" and Maximum Longitude value "6")


===Terrafit===
=== Elevation ===
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.
This will convert the .hgt.zip files (that you have downloaded earlier) into a form that TerraGear can read. Simply select the directory in which you placed the elevation downloads (probably <tt>{project's directory}/data/SRTM-3</tt>). Make sure you do set the correct resolution! For the USA this can be 1 arcsec, while the rest of the world is provided in 3 arcsec resolution.


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.
=== Airports ===
What is scenery without airports in a flight simulator? If your area does not contain any airports, you can skip this part and continue with [[#ogr-decode|ogr-decode]].


===Genapt===
You can do two things now:
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]].
*'''Already-made airports:''' use FlightGear's <tt>apt.dat.gz</tt> file, which is usually in <tt>[[$FG ROOT]]/Airports/</tt>.
*'''Home-made airports:''' if you created an airport in [[WorldEditor]], use the .dat file that you exported.


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>.
Use the button to browse to the .dat file of your choice.
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.  
* '''All airports in area''' generates all the airports within the boundaries as set on the start tab.
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.
* '''Single airport''' to generate the scenery for a specific airport. Enter the ICAO code into the field.  
* '''Single tile''' only processes airports that are located on the given tileid.
* '''All airports in apt.dat''' the tool will run through the entire apt.dat file, which can take a long (!) time when using the default apt.dat from FlightGear.


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.
=== Materials ===
Now we need to decode the shapefiles into TerraGear format, which we do with OGR Decode. After clicking the "Retrieve shapefiles" button, the list will be populated with the shapefiles from your project's data directory. The GUI will try to assign fitting materials. If a shapefile has no material, you'll need to assign it by hand. Each single shapefile must have a material.


===ogr-decode===
You can delete shapefiles from the list by double-clicking on them. A single click on a material will allow you to edit it; to create custom materials that are not (yet) in materials.xml (do note that FlightGear will apply the default material to those landclasses, untill you create the material in materials.xml!).  
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 <tt>[[$FG_ROOT]]/materials.xml</tt> files. The mapping is pretty obvious, e.g. v0_roads maps to Roads etc.


'''Warning: v0_landmass MUST be mapped onto the type Default.'''
Line width is only used on line-data (like roads, rivers and railroads). If you leave the line width fields empty, a default width of 10 meters is used.


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.
===== Example =====


===fgfs-construct===
{| class="wikitable"
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.
|-
! Shapefile !! Material !! Line width (in meters)
|-
| osm_canal || Canal || 12
|-
| osm_motorway || Road-Motorway || 12
|-
| osm_primary || Road-Primary || 10
|-
| osm_rail || Railroad || 5
|-
| osm_river || Canal || 8
|-
| osm_secondary || Road-Secondary || 8
|-
| osm_stream || Stream || 3
|-
| osm_tertiary || Road-Tertiary || 6
|-
| osm_trunk || Road-Trunk || 18
|}


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.  
=== Construct ===
[[Image:TerraGearGUI.png|thumb|270px|The construction page.]]
'''Note: with recent TerraGear builds, it is required to add the used material-names to the default_priorities.txt file.'''


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 tg-construct tool brings all your gathered data together, throws it in a washing machine and spits it out the otherside in a format ready for use with FlightGear. Click the "Update list" button to populate the field with all decoded shapefiles. In the list you select all types that you'd like to include in your scenery.


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.
After clicking the "Generate scenery" button, it may take a long time for TerraGear to finish. 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.


==GUI development==
=== Running the scenery ===
The GUI will undergo a large rebuild. Feel free to add feature requests and/or bug reports.
The folders and files in your project's <tt>output/</tt> directory are ready to use as scenery. You can set the [[$FG_SCENERY|scenery path]] of FlightGear to this directory to check if the scenery is generated correctly.
===Requested features===
 
* --tile-id option in fgfs-construct, to easily generate just one tile which can be used for fast scenery in-cooperation.
== GUI development ==
* A larger list or maybey a dropdown menu with the ogr-decode tool to select shapefiles and material mappings. Right now it's very hard and takes a long time to search through the list for the correct shapefiles/materials.
The current source code can be retrieved [https://sourceforge.net/p/flightgear/fgscenery/terrageargui/ci/master/tree/ from SourceForge].
* Materials (in fgfs-construct) in alphabetical order.
 
* Ability to select multiple (non linear) folders using the Ctrl key (so not selecting everything between click and click, but just the folders I click).
Feel free to add feature requests and/or bug reports to this page. Anyone interested in helping is invited to contact Gijs at the forum.
* Resizable dialogs.
 
* A topmenu showing all the tools, so there's no need to return to the mainmenu every time you continue to the next step.
=== Requested features ===
* Creating automatically all needed folders for shapefiles and the decoded ones
Also see [[TerraGear scenery build server]]
* Maybe error reports possible? So you get a message when a certain file isn't found, or a certain  path isn't set. Right now it only appears in the console, but it's hard to read the fast scrolling text.
 
===Bug reports===
[[File:TerraGear-GUI-Remote-Mode.png|thumb|Prototyping a remote mode for [[TerraGear]] as part of [[TerraGear GUI]]]]
* Decoding with points width gives no output.
 
* Just using airport ICAO in genapts gives no output.
* Multi-threading, so the GUI doesn't freeze when running a process [http://forum.flightgear.org/viewtopic.php?f=5&t=25688&p=235873&hilit=#p235623]
* Support a new "Setup" page where people can decide if TerraGear is installed locally or remotely {{Not done}}
* Add a command handler abstraction so that commands  can be easily run over SSH [http://doc.qt.digia.com/qtcreator-extending/utils-sshconnection.html] {{Not done}}
* File retrieval would ideally be wrapped via SFTP {{Not done}}
 
== External link ==
* [http://forum.flightgear.org/viewtopic.php?f=5&t=7485 Forum topic]


[[Category:Scenery enhancement]]
[[Category:Scenery enhancement]]
[[Category:TerraGear]]
652

edits

Navigation menu