Howto:Add shared models manually

You can add your own objects, known as "shared models" to FlightGear's world. This howto explains one way to do so. It assumes that you already have a model for the object. There are many that come standard with FG; they are stored in the $FG_ROOT/Models directory.

You can also create one using a suitable modeling program such as blender. The most common file format used is .ac, but you can use any format that PLIB supports, such as AC3D.

Adding Shared Models to FlightGear's World

Step 1

If you plan to use one of the standard FG models, skip to step 4.

If you have created your own model, create a new directory for it under $FG_ROOT/Models (to keep your models separate from the standard ones). We'll use $FG_ROOT/Models/MyModels as an example.

Step 2

Copy your .ac file containing the model into the $FG_ROOT/Models/MyModels directory. We'll use MyModel.ac as the name of that file.

Step 3 (optional)

If you intend to include animation, create an XML file called MyModel.xml inside the $FG_ROOT/Models/MyModels directory with the following contents:

<?xml version="1.0"?>
<PropertyList>
 <path>MyModel.ac</path>
 <animation>
  <type>range</type>
  <min-m>0</min-m>
  <max-m>20000</max-m>
 </animation>
</PropertyList>

This file references the .ac model file and tells FlightGear that it must be visible from 0 meters up to 20 km.

An XML file is only necessary if you are intending to include animation; it is not required to render a model at a fixed location in FlightGear.

Step 4

Next, you have to determine where to place the model in FG's world.

A really useful resource at this stage is TerraServer. Enter a street name, city, and state. Then you can choose from several types of public-domain aerial photography from the US Geological Survey. When you get a good photo of your feature, click on the Info link. Your image will be broken into tiles with latitude and longitude of the edges of the tiles. This is good way to get close to the position you want. Google Earth is also a good way to obtain position information, and there are other websites that will provide it also, or you can get it from a GPS.

Then, you need to place the object precisely. An easy way do this is with the UFO "airplane". In addition to making it easy to move around (or not), it allows you to place objects and see what they look like there. It calculates the positioning details for you and writes them out in the correct format. See Howto: Place 3D objects with the UFO. Here, though, we'll continue by describing a manual way to do it, for people who may need or want to know the inside details.

Start FG and fly to the location where you want to place the object. Open up the property browser in FG (File->Browse Internal Properties), and the /position key. Write down the values for latitude-deg, longitude-deg, and ground-elev-m. If you want to place the object above ground level, then add the appropriate number of meters. Then, go to the /environment key and write down the tile number (current-tile-id).

Step 5

Next, locate a .stg file into which you will place a reference to the object's model and its position.

The .stg files are named according to tile number and stored under the scenery directories. The default installation places a limited amount of scenery (for the area around San Francisco) in $FG_ROOT/scenery but you may have scenery in other directories, as specified in $FG_SCENERY. (See Howto: Install scenery.) Under each scenery directory, you will find directories called Objects and Terrain, and under them directories that group tiles into larger and smaller quadrants. Thus, if the tile number is 942058, you will find 942058.stg under $FG_ROOT as $FG_Root/Scenery/Objects/w130n30/w123n37/942058.stg (and possibly elsewhere).

There is generally more than one .stg file for a given tile, in different directories. It's important to edit one that will actually be read by flightgear (see below). One thing you can do is create a personal customized scenery directory separate from the standard installation. That way, if you upgrade FG your customizations won't get overwritten. If you create such a directory, list it first in $FG_SCENERY, create a directory structure inside it parallel to the one in the standard scenery story, and create a .stg file in the appropriate place. Similarly, it is best not to edit the .stg files in the folder where TerraSync stores the scenery it has fetched, since TerraSync may overwrite them with newer versions. Objects associated with airports are usually put into a .stg file under a "Terrain" directory; other objects are put under "Objects".

Step 6

Add the following lines to the stg file you've chosen, replacing the parameters with your own :

OBJECT_SHARED Models/MyModels/MyModel.xml -55.5 30.3 1000.0 0.00 

In brief, the format is :

OBJECT_SHARED path longitude latitude altitude rotation

The path is relative to the $FG_ROOT directory. If you have an XML file for the model, specify it here, otherwise specify the .ac file. Altitude is in meters above mean sea level. Rotation is counter-clockwise from north (not clockwise as in the rest of FG).

There are more details on the .stg file format below.

Step 7

Restart FG and fly to where you added the model; it should be there.

STG file format

There is documention for the .stg files used by FlightGear in $FG_ROOT/Docs/README.scenery. Only information relevant for placing shared objects is included here.

Scenery files are loaded by default from $FG_ROOT/Scenery. Alternate locations (a "scenery path") can be specified in $FG_SCENERY (or from the command line); the first-named directories have highest priority. Thus, if you create a local directory for storing custom scenery you create, include it first in the scenery path.

Lines for shared objects in the .stg file look like this:

OBJECT_SHARED	Models/Misc/trigpoint.xml	-122.377127	37.71570833	1.756719854	20
Type	filename path	Longitude	Latitude	Elevation	Heading

The filename path is relative to $FG_ROOT. Longitude and latitude are expressed as decimal numbers (not degrees/minutes/seconds), with negative values representing west and south. Elevation is in meters above mean sea-level. Heading is in degrees, counter-clockwise from North as 0.0 (i.e. when looking from above). Note that this is opposite from headings in other places in FlightGear, which are clockwise.

Some more examples:

OBJECT_SHARED Models/MidAtl/cape-may-light.ac   -74.959970 38.933332 -93.0 0.00
OBJECT_SHARED Models/Airport/windsock.xml -122.360843 37.613877 1 0
OBJECT_SHARED Models/Structures/vordme.xml -122.37389 37.61948 -0.404 0

Alternately, there is a way to include this same information in XML configuration files that are loaded at runtime; see Howto: Place 3D objects with the UFO or $FG_ROOT/Docs/README.scenery for more details. This approach has the advantage of keeping your new scenery clearly separate from the standard scenery files without having to create your own custom scenery directory structure. Further, you can then manually control whether or not to load it at run-time, using the --config option on the command line. You can also include it in one of the standard startup files (such as .fgfsrc) but this will load it into memory every time you start FG, whether or not you are flying in the area. If you place the scenery information in .stg files, it is only loaded into memory when needed.