fly/fgdata
1
0
Fork 0
Code Activity
fgdata/Docs/README.scenery
mfranz c8f0839185 tweaks (to keep cvslogs busy :-)
2006-04-12 16:11:19 +00:00

518 lines
17 KiB
Text
Raw Blame History

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.
It does *not* describe how to generate terrain. For that see
http://www.terragear.org/.
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 scenery object 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 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
--------------------
defines taxiway or runway sign. The syntax is like that of OBJECT_SHARED
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 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 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 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}17
{@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>
<pitch-deg>1.234</pitch-deg> <!-- static, just for fun -->
</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 scenery object editor
-----------------------------
The ufo has a scenery object editor built-in. It uses the model manager
described in section 4. To place objects with 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. (See the ?-key dialog for futher
available keys.)
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"/>
The path is 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
View git blame Copy permalink