diff --git a/Docs/README.scenery b/Docs/README.scenery new file mode 100644 index 000000000..16486848d --- /dev/null +++ b/Docs/README.scenery @@ -0,0 +1,511 @@ +This file describes how to place 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.) + + + + +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 + +The is relative to the data directory (FG_ROOT). + is in meter and relative to mean sea-level (in the fgfs world). + 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 and + 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 map of a +texture font entry in $FG_ROOT/materials.xml. It just +happens that the entry for '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. 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{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 arrows: + + 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 with "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 yellow "Direction, Destination, Boundary" sign + @R @R1 @R2 @R3 red "Mandatory Instruction" sign + @L @L1 @L2 @L3 framed/black "Location" sign (yellow text/frame) + @B @B4 @B5 black "Runway Distance Remaining" sign + +The number versions define the panel heights according to the spec. If +they are 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: + + + + pony + Local/pony.ac + -115.8352869 + 37.24302849 + 4534.691321 + 0 + 0 + 0 + + + +The is relative to $FG_ROOT, the 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.1 static 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: + + + + -115.8352869/ + 37.24302849 + 4534.691321 + 0 + + + + + + pony + Local/pony.ac + /local/pony/longitude-deg + /local/pony/latitude-deg + /local/pony/elevation-ft + /local/pony/heading-deg + + + +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 entry under , +initialize all properties there ( or , +etc.), and finally you create a child of any type in this group. +This is the signal for the model manager to load the object. You can +remove the property after that. It has no further meaning. + +To remove a model-manager model at runtime, you simply delete the whole + 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: + + + +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 +