Howto:Add shared models manually

From FlightGear wiki
Revision as of 02:52, 14 March 2011 by AlbertBickford (talk | contribs) (→‎Adding Shared Models: more detailed and accurate instructions)
Jump to navigation Jump to search
Cleanup.png This article may require cleanup to meet the quality standards of the wiki. Please improve this article if you can.

Note: You may include scenery objects in any format that PLIB supports. Currently, this means in addition to the 3ds models mentioned, you may use AC3D and other formats. This howto assumes that you already have a model. If not, create one using a suitable modeling program such as blender.

Adding Objects to FlightGear's World

Here are instructions on how to add objects (known as "shared models") to the current version of FlightGear, either a model that you've created or one of the models that comes with FG.

Step 1

If you plan to use one of the standard FG models that are stored in the $FG_ROOT/Models directory, skip to step 4.

If you created your own model, create a directory under $FG_ROOT/Models. We'll use $FG_ROOT/Models/MyModels as an example.

Step 2

Save 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 xml 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.

Then, you need to place the object precisely. An easy way do this is with the UFO model, which allows you to place objects and see what they look like there; see Howto: Place 3D objects with the UFO. It calculates the positioning details for you and writes them out in the correct format, but for completeness I'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 model. 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 you'll have to add the appropriate number of meters yourself.) Then, go to the /environment key and write down the tile number (current-tile-id).

An alternate way to get the tile number is with a perl program in Git called calc-tile.pl that works out what stg file a geodetic coordinate falls in. You can get it here if you don't feel like playing with Git and don't have the Git branch installed: http://gitorious.org/fg/flightgear/blobs/raw/next/scripts/perl/scenery/calc-tile.pl. Run the perl script in a terminal window, passing it the longitude and latitude that you wrote down in step 4. You'll probably have to install perl first if you run on a MS OS's. Example :

$ ./calc-tile.pl -55.5 30.3
Longitude: -55.5
Latitude: 30.3
Tile: 2039314
Path: "w060n30/w056n30/2039314.stg"

Finally, you can use FGSD for steps 4 to 6.

Step 5

Next locate a .stg file into which you will place a reference to the new 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 in $FG_ROOT/scenery but you may have scenery in other directories as specified in $FG_SCENERY. Under the scenery directories, 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 2039314, you might find 2039314.stg at $FG_ROOT/Scenery/Terrain/w060n30/w056n30/2039314.stg.

There may be more than one such file with that name, in different directories. You can (presumably) modify any of them, but it is best if you create a personal customized scenery directory separate from the standard installation. That way, if you upgrade FG your customizations won't get overwritten. (If create such a directory, add it to $FG_SCENERY, create an internal directory structure like the one in the standard scenery story, and create a .stg file in the appropriate place.) For the same reason, it is best not to edit the .stg files in the folder where TerraSync stores the scenery it has fetched. (Another page in the wiki currently recommends modifying or creating the .stg file under the Terrain directory rather than under the Objects directory; the current editor knows no reason to prefer one over the other. Try one and see if it works. It seems that FG takes all objects that it finds mentioned in any .stg file with the appropriate name and places them all into the world.)

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 

The format is :

OBJECT_SHARED relative_path_to_model_file longitude latitude altitude_above_sea_level_(meters) ellipsoid_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.

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 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. However it requires either manually loading the config file from the command line or mentioning it in one of the standard startup files (such as .fgfsrc) and having it loaded every time you start FG, whether or not you are going to be flying in the area. If you place the scenery information in .stg files, it is only loaded when needed.

Step 7

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

.STG file format

Currently, no documention exists for the .stg files used by FlightGear other than this. There is none in the 'mini-docs' folder bundled with the source.

Each line of the STG file has the following format:

OBJECT_STATIC KSFO-maint-1-fb.ac -122.377127 37.71570833 1.756719854 20
Type Relative path Longitude Latitude Elevation Heading

About Altitude. Looking at the files shipped with FG, there are some strange, to me, figures for altitude. Some are negative numbers. That seems odd, since objects are being placed on the surface. It suggests that above surface may be negative on the Z axis. COMMENT: Much more likely these are objects which are purposely sunk into the terrain to adjust their height.

I ran across a comment: 3D object need scenery to compute their height. This is why scenery must be associated with an existing land surface file (whatever you call it).

This is what a line with an XML file specifying the model looks like.

OBJECT_SHARED Models/MidAtl/cape-may-light.xml   -74.959970 38.933332 -93.0 0.00

This is what a line specifying the model file directly looks like.

OBJECT_SHARED Models/MidAtl/cape-may-light.ac   -74.959970 38.933332 -93.0 0.00

A second example from the FlightGear KSFO scenery. Although taken from different STG files for the same area, you can see the mix of objects.

OBJECT_STATIC KSFO-terminal-fb.ac -122.3859635 37.61748958 3 90
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
OBJECT_STATIC KSFO-maint-1-fb.ac -122.377127 37.62647917 0.5 62
OBJECT_STATIC candlestickpark-fb.xml -122.3838418 37.71570833 1.756719854 0