515 lines
17 KiB
Text
515 lines
17 KiB
Text
This file describes how FlightGear searches and loads scenery, and how to
|
|
add static objects to the scenery as well as the syntax of *.stg files.
|
|
|
|
|
|
|
|
|
|
Contents ----------------------------------------------------------------------
|
|
|
|
1 scenery path
|
|
2 terrasync
|
|
|
|
3 stg files
|
|
3.1 OBJECT_BASE
|
|
3.2 OBJECT
|
|
3.4 OBJECT_SHARED
|
|
3.3 OBJECT_STATIC
|
|
3.5 OBJECT_TAXI_SIGN
|
|
3.6 OBJECT_RUNWAY_SIGN
|
|
|
|
4 model manager ("/models/model")
|
|
4.1 static objects
|
|
4.2 dynamic objects
|
|
4.3 loading/unloading at runtime
|
|
|
|
5 tools for object placing
|
|
5.1 calc-tile.pl
|
|
5.2 ufo model editor
|
|
|
|
|
|
|
|
|
|
|
|
1 scenery path ----------------------------------------------------------------
|
|
|
|
FlightGear loads scenery by default from the Scenery/ subdirectory of its
|
|
data directory. The path to this data directory can be set via environment
|
|
variable FG_ROOT or the --fg-root option. The scenery path can be set
|
|
independently via environment variable FG_SCENERY or option --fg-scenery.
|
|
The order of precedence is as follows:
|
|
|
|
--fg-scenery=/some/dir ... highest priority
|
|
$FG_SCENERY
|
|
$FG_ROOT/Scenery/ ... lowest priority
|
|
|
|
|
|
A scenery specification may be a list of paths, separated by the OS-specific
|
|
path separator (colon on Unix/OSX, semicolon on MS Windows). The paths are
|
|
searched in the order from left to right:
|
|
|
|
FG_SCENERY=/first/dir:/second/dir:/third/dir
|
|
(likewise with --fg-scenery option)
|
|
|
|
|
|
Each of the scenery paths can follow one of two possible layouts: with or
|
|
without Terrain/ and Objects/ subdirectories. As soon as either or both
|
|
of these subdirectories are found, scenery is only searched *in* these two,
|
|
but not in any other directory on the same hierarchy level!
|
|
|
|
This example shows which directories are used to search for scenery:
|
|
|
|
$ ls /first/dir
|
|
w130n30/ searched
|
|
|
|
$ ls /second/dir
|
|
Objects/ searched
|
|
Terrain/ searched
|
|
w130n30/ *not* searched
|
|
|
|
$ ls /third/dir
|
|
Terrain/ searched
|
|
w130n30/ *not* searched
|
|
|
|
|
|
If FlightGear searches for a particular "tile" file, let's say for
|
|
"w130n30/w123n37/942050.stg", then (using the above examples) it looks
|
|
into
|
|
|
|
/first/dir/w130n30/w123n37/942050.stg (A)
|
|
|
|
/second/dir/Terrain/w130n30/w123n37/942050.stg (B)\__ same path element
|
|
/second/dir/Objects/w130n30/w123n37/942050.stg (C)/ /second/dir
|
|
|
|
/third/dir/Terrain/w130n30/w123n37/942050.stg (D)
|
|
|
|
but as soon as it finds an OBJECT_BASE entry it only finishes this
|
|
path element and then stops scanning. So, if (B) contains an entry
|
|
"OBJECT_BASE 942050.btg, then the twin Objects/ directory (C) will
|
|
be read, too. But (D) will *not*! Objects/ and Terrain/ directories
|
|
are laid out equally. Airport and elevation data, as well as airport
|
|
inventory objects are usually put into Terrain/, while other objects
|
|
are put into Objects/.
|
|
|
|
This searching behavior is usually used to collect user-added
|
|
custom objects first, then to read in standard scenery and objects
|
|
that came with the distribution (San Francisco Bay area), and to
|
|
use locally added scenery everywhere else. So a typical scenery
|
|
path specification could look like this:
|
|
|
|
FG_SCENERY=$HOME/.fgfs/Scenery:$FG_ROOT/Scenery:$FG_ROOT/WorldScenery
|
|
|
|
The third path would then be populated by the user with unpacked scenery
|
|
archives downloaded from http://www.flightgear.org/Downloads/scenery.html,
|
|
or by using terrasync (see next section). Additional objects can be
|
|
downloaded from the FlightGear Objects Database (http://fgfsdb.stockill.org/).
|
|
(Note that those objects are regularly merged into the flightgear.org/terrasync
|
|
packages, so you may end up with doubled entries!)
|
|
|
|
Using a private directory for downloaded add-on scenery and adding
|
|
that path to FG_SCENERY is the preferred way. This separates default
|
|
data from locally added data, and makes administration and later updates
|
|
easier.
|
|
|
|
HINT: if you want to see where FlightGear is searching and finding
|
|
terrain/objects, start it with the --log-level=info option.
|
|
|
|
|
|
|
|
|
|
|
|
2 terrasync -------------------------------------------------------------------
|
|
|
|
FlightGear comes with a utility "terrasync" that allows downloading
|
|
scenery (literally) "on-the-fly. Given the scenery path setup from
|
|
section 1 you could use terrasync with a script like this:
|
|
|
|
#!/bin/bash
|
|
PORT=5503
|
|
nice terrasync -p $PORT -d $FG_ROOT/WorldScenery&
|
|
fgfs --atlas=socket,out,1,localhost,$PORT,udp $*
|
|
killall terrasync
|
|
|
|
If you name it "fgfsterra", then you can use it just like you would use
|
|
"fgfs", but behind the scenes it would update your scenery everywhere in
|
|
sight and save the files to $FG_ROOT/WorldScenery. Example:
|
|
|
|
$ ./fgfsterra --aircraft=ufo --airport=LOXZ
|
|
|
|
Note, however, that if it downloads scenery for the area around your
|
|
starting location, then you'll only see that after the next start, or
|
|
after you flew or teleported to a distant location and then back.
|
|
terrasync depends on the rsync application and an open port 873,
|
|
so it may not be available/usable on MS Windows.
|
|
|
|
|
|
|
|
|
|
|
|
3 stg files -------------------------------------------------------------------
|
|
|
|
stg files ("static terragear") define the static elements of a scenery
|
|
"tile", including the terrain elevation data, airport geometry, and all
|
|
static objects placed on this tile. (See section 5 for how to find out which
|
|
geo coordinates belong to which tile.) Four of the available key words
|
|
are followed by a string and four numbers. The meaning of these numbers
|
|
is always the same and described in section 3.3.
|
|
|
|
|
|
|
|
|
|
3.1 OBJECT_BASE
|
|
----------------
|
|
|
|
specifies the terrain elevation data file. These files are generated with
|
|
the TerraGear tools (http://www.terragear.org/) and have file extension
|
|
".btg" ("binary terragear"; there used to be an "*.atg" file, too, where
|
|
the 'a' stood for ASCII).
|
|
|
|
Example:
|
|
|
|
OBJECT_BASE 942050.btg
|
|
|
|
The entry may be anywhere in the 942050.stg file, on a separate line.
|
|
|
|
|
|
|
|
|
|
3.2 OBJECT
|
|
-----------
|
|
|
|
specifies an airport geometry 'drop-in' file. The scenery elevation file
|
|
has cut out holes for airports, that are filled with such objects. They
|
|
are usually called after the airport ICAO id:
|
|
|
|
Example:
|
|
|
|
OBJECT KSFO.btg
|
|
|
|
These files are, again, created by TerraGear tools and are usually gzipped,
|
|
so you'll find that file stored as KSFO.btg.gz.
|
|
|
|
|
|
|
|
|
|
3.3 OBJECT_SHARED
|
|
------------------
|
|
|
|
add static object to the tile.
|
|
|
|
Example:
|
|
|
|
OBJECT_SHARED Models/Airport/tower.xml -122.501090 37.514830 15.5 0.00
|
|
|
|
Syntax:
|
|
|
|
OBJECT_SHARED <object-path> <longitude> <latitude> <elevation-m> <heading-deg>
|
|
|
|
The <object-path> is relative to the data directory (FG_ROOT).
|
|
<elevation-m> is in meter and relative to mean sea-level (in the fgfs world).
|
|
<heading-deg> is in degree, counter-clockwise with North being 0.0. Note
|
|
that this differs from about every other place in FlightGear, most notably
|
|
the /position/heading-deg entry in the property system, which is clockwise.
|
|
OBJECT_SHARED models are cached and reused. They are only once in memory
|
|
and never freed. (See also the next section 3.4.)
|
|
|
|
|
|
|
|
|
|
3.4 OBJECT_STATIC
|
|
------------------
|
|
|
|
add static objects to the tile, just like OBJECT_SHARED. There are three
|
|
differences to OBJECT_SHARED (apart from the name):
|
|
|
|
(A) the path is relative to the tile directory where the *.stg file with
|
|
this entry is located. For example, relative to 130n30/w123n37/. This
|
|
usually means that all 3D object files, textures, and XML animation
|
|
files are in this tile directory, too.
|
|
|
|
(B) these objects are *not* cached and kept loaded, but rather freed with
|
|
the tile (that is, when you leave that area).
|
|
|
|
(C) the animation XML files may contain Nasal blocks <nasal><load> and
|
|
<nasal><unload> which are executed on loading/unloading.
|
|
|
|
Example:
|
|
|
|
OBJECT_STATIC ggb-fb.xml -122.4760494 37.81876042 0 105
|
|
|
|
|
|
|
|
|
|
3.5 OBJECT_TAXI_SIGN
|
|
--------------------
|
|
|
|
define taxiway or runway signs. The syntax is like that of OBJECT_STATIC
|
|
entries, except that the path is replaced with a sign contents specification.
|
|
|
|
Example:
|
|
|
|
OBJECT_TAXI_SIGN {@R}10L-28R{@L}C -122.35797457 37.61276290 -0.5398 74.0
|
|
|
|
The sign specification defines the sign contents and dimensions.
|
|
In the simplest form it contains just 'normal' text, for example:
|
|
|
|
EXIT
|
|
|
|
This will create a black panel of 1m height with "EXIT" written on it
|
|
in white versal letters. Actually, each of those characters are
|
|
single-letter-glyph-names that are looked up in the <glyph> map of a
|
|
texture font <material> entry in $FG_ROOT/materials.xml. It just
|
|
happens that the <glyph> entry for <name> 'E' maps to a drawn 'E' in
|
|
the font texture. This isn't true for all ASCII characters. Many aren't
|
|
mapped at all (and thus not available), others are mapped to non-standard
|
|
drawings. The '_', for example, is mapped to an empty black area and can
|
|
therefore be used as a space. (The sign specification must not contain
|
|
real spaces.) But this is not hard-coded.
|
|
|
|
Some glyph-names contain more than one character, and can't, thus, be
|
|
used directly. They have to be put in a pair of curly braces:
|
|
|
|
{right-down}
|
|
|
|
creates an arrow that points to the right and down. Several glyph-names
|
|
can be put into a pair of braces, separated by commas (no space!).
|
|
Single-letter-glyph-names can be used that way, too, or in any mixture
|
|
of both methods:
|
|
|
|
EXIT
|
|
{E,X,I,T}
|
|
{E}{X}{I}{T}
|
|
EX{I,T}
|
|
E{X,I}T{left-up,right-down}
|
|
|
|
Besides single- or multi-letter-glyph-names, there are also commands.
|
|
These always start with an '@'.
|
|
|
|
{@rd}EXIT{@dr}
|
|
|
|
Both @rd and @dr are abbreviations for the "right-down" arrow, and
|
|
the line is equivalent to
|
|
|
|
{right-down}EXIT{right-down}
|
|
|
|
|
|
|
|
The following abbreviations are available -- all expand to arrow symbols:
|
|
|
|
abbrev. glyph-name
|
|
-----------------------------------------------------------------
|
|
@u -> up (not really an abbreviation :-)
|
|
@d -> down
|
|
@l -> left
|
|
@r -> right
|
|
@ru @ur -> right-up
|
|
@rd @dr -> right-down
|
|
@lu @ul -> left-up
|
|
@ld @dl -> left-down
|
|
|
|
|
|
|
|
The following commands are available, for (A) sign properties:
|
|
|
|
@size=2.3 set sign height to 2.3m (width is derived from that
|
|
and not separately settable)
|
|
|
|
@material=foo use texture font <material> with <name> "foo"
|
|
(see $FG_ROOT/materials.xml)
|
|
|
|
@light=0 make sign non-emissive (default: 1, which uses the
|
|
emission defined for the material in materials.xml)
|
|
(Turning emission "off" currently sets it to 0.3,0.3,0.3)
|
|
|
|
|
|
|
|
and commands for (B) pre-defined sign types according to the FAA
|
|
specification (5345-44; see http://www.google.com/search?q=5345-44g).
|
|
|
|
@Y @Y1 @Y2 @Y3 "Direction, Destination, Boundary" sign (black on yellow)
|
|
@R @R1 @R2 @R3 "Mandatory Instruction" sign (white on red with black outline)
|
|
@L @L1 @L2 @L3 "Location" sign (yellow text and frame on black)
|
|
@B @B4 @B5 "Runway Distance Remaining" sign (white on black)
|
|
|
|
The number versions define the panel heights according to the spec. If
|
|
the number is omitted, then a default size is used (@Y3, @R3, @L3, @B4). If
|
|
such a pre-defined sign type is used, then fgfs takes (more or less)
|
|
care of opening and closing frames, and of inserting the proper spaces.
|
|
(You can avoid this automatism by setting the sign properties yourself,
|
|
using @size and @material.
|
|
|
|
Examples:
|
|
|
|
{@R}10L-28R{@L}C
|
|
{@Y,@l}P|{@ul}N{@L}F{@Y}F{@ur}
|
|
{@Y}{@dl}C ... same as any of {@Y,@dl}C {@Y,@dl,C} {@Y,left-down,C}
|
|
{@B}70
|
|
{@material=RedSign,@size=1.6,no-exit}
|
|
|
|
|
|
Syntax errors are reported in --log-level=debug, in the SG_TERRAIN
|
|
group. You can use this command line to filter out such messages:
|
|
|
|
$ fgfs --log-level=debug 2>&1|grep _TAXI_
|
|
|
|
|
|
|
|
|
|
3.6 OBJECT_RUNWAY_SIGN
|
|
-----------------------
|
|
|
|
are experimental entries and not of much use.
|
|
|
|
Example:
|
|
|
|
OBJECT_RUNWAY_SIGN OMG_Ponies -122.35797457 37.61276290 -0.5398 74.0
|
|
|
|
The second element is a texture name from $FG_ROOT/materials.xml. The
|
|
texture is put on a sign of dimension 3m x 1m (WxH) that floats 25cm
|
|
above ground and is invisible from the backside. (Reference point is
|
|
the middle of the base.) This entry will likely change in the future
|
|
or be removed altogether. Better don't use it!
|
|
|
|
|
|
|
|
|
|
|
|
4 model manager ("/models/model") --------------------------------------------
|
|
|
|
|
|
4.1 static objects
|
|
-------------------
|
|
|
|
Another way to add objects to the scenery is via the "model manager".
|
|
It reads all /models/model entries at startup and places these objects
|
|
in the scenery. Just load a definition like the following into the
|
|
property tree, for example by putting it into $FG_ROOT/preferences.xml, or
|
|
better: an XML file that you load with e.g. --config=$HOME/.fgfs/stuff.xml:
|
|
|
|
<models>
|
|
<model n="0">
|
|
<name>pony</name>
|
|
<path>Local/pony.ac</path>
|
|
<longitude-deg>-115.8352869</longitude-deg>
|
|
<latitude-deg>37.24302849</latitude-deg>
|
|
<elevation-ft>4534.691321</elevation-ft>
|
|
<heading-deg>0</heading-deg>
|
|
<pitch-deg>0</pitch-deg>
|
|
<roll-deg>0</roll-deg>
|
|
</model>
|
|
</models>
|
|
|
|
The <path> is relative to $FG_ROOT, the <name> is optional. One can leave the
|
|
heading/pitch/roll entries away, in which case they are set to zero. The values
|
|
are fixed and unchangeable at runtime.
|
|
|
|
|
|
|
|
|
|
4.2 dynamic objects
|
|
--------------------
|
|
|
|
Any of the model properties can be made changeable at runtime by appending
|
|
"-prop" and using a property path name instead of the fixed value:
|
|
|
|
<local>
|
|
<pony>
|
|
<longitude-deg>-115.8352869/<longitude-deg>
|
|
<latitude-deg>37.24302849</latitude-deg>
|
|
<elevation-ft>4534.691321</elevation-ft>
|
|
<heading-deg>0</heading-deg>
|
|
</pony>
|
|
</local>
|
|
|
|
<models>
|
|
<model n="1">
|
|
<name>pony</name>
|
|
<path>Local/pony.ac</path>
|
|
<longitude-deg-prop>/local/pony/longitude-deg</longitude-deg-prop>
|
|
<latitude-deg-prop>/local/pony/latitude-deg</latitude-deg-prop>
|
|
<elevation-ft-prop>/local/pony/elevation-ft</elevation-ft-prop>
|
|
<heading-deg-prop>/local/pony/heading-deg</heading-deg-prop>
|
|
</model>
|
|
</models>
|
|
|
|
Then one can move the pony around by changing the values in /local/pony/ in
|
|
the property system. One can, of course, use other animals, too.
|
|
|
|
|
|
|
|
|
|
4.3 loading/unloading at runtime
|
|
--------------------------------
|
|
|
|
Both dynamic and static model-manager-models can be loaded and unloaded
|
|
at runtime. For loading you first create a new <model> entry under <models>,
|
|
initialize all properties there (<longitude-deg> or <longitude-deg-prop>,
|
|
etc.), and finally you create a child <load> of any type in this group.
|
|
This is the signal for the model manager to load the object. You can
|
|
remove the <load> property after that. It has no further meaning.
|
|
|
|
To remove a model-manager model at runtime, you simply delete the whole
|
|
<model> group.
|
|
|
|
|
|
|
|
|
|
|
|
5 tools for object placing ----------------------------------------------------
|
|
|
|
|
|
5.1 calc-tile.pl
|
|
----------------
|
|
|
|
For finding out the tile number for a given geo coordinate pair there's
|
|
a script "scripts/perl/scenery/calc-tile.pl" in the FlightGear sources.
|
|
You feed longitude and latitude to it and it returns the path to the
|
|
*.stg file where you have to add the object entry.
|
|
|
|
$ perl calc-tile.pl 16.1234 48.5678
|
|
Longitude: 16.1234
|
|
Latitude: 48.5678
|
|
Tile: 3220128
|
|
Path: "e010n40/e016n48/3220128.stg"
|
|
|
|
|
|
|
|
|
|
5.2 ufo model editor
|
|
--------------------
|
|
|
|
The ufo can be used to place objects in the scenery. It uses the model manager
|
|
described in section 4. To use it, start fgfs, optionally with specifying
|
|
an initial model type (cursor) and a list of subdirectories of $FG_ROOT where
|
|
the ufo should search for available 3D models (source):
|
|
|
|
$ fgfs --aircraft=ufo --prop:cursor=Models/Airport/radar.xml \
|
|
--prop:source=Models,Scenery/Objects
|
|
|
|
Then click anywhere on the terrain to add a model (left mouse button).
|
|
You can open the adjustment dialog (Tab-key) to make adjustments to
|
|
position and orientation. Click as often as you like, choose further
|
|
models from the m-key dialog. You can select an already placed object
|
|
by clicking at its base (not the object itself, but the surface point
|
|
where it's located!) while holding the space-bar down. You can remove the
|
|
selected object with the Backspace-key.
|
|
|
|
And finally, you dump the object data to the terminal (d-key) or export
|
|
them to a file $HOME/.fgfs/ufo-model-export.xml (Unix) or
|
|
%APPDATA%\flightgear.org\ufo-model-export.xml (MS Windows).
|
|
|
|
You can now put the generated object entries into the specified *.stg
|
|
file to make them permanent. Or load the whole exported *.xml file
|
|
under the /models node in your XML config:
|
|
|
|
<models include="ufo-model-export.xml"/>
|
|
|
|
Path relative to the path where your XML config resides. Unfortunately,
|
|
this does currently not add shadows, and the models stay in memory, no
|
|
matter where you are actually flying, so the *.stg method is preferred.
|
|
|
|
|
|
|
|
|
|
|
|
Melchior FRANZ, 2006/04/12
|
|
|