Howto:3D Aircraft Models
This howto explains how to add 3D aircraft models to FlightGear, and how to animate and position those models. No C++ programming is required, but the user will need some knowledge of FlightGear's property system and XML markup, and will need to understand the coordinate system FlightGear uses for its models:
- distances are in metres
- angles are in degrees
- the x-axis runs lengthwise, towards the back
- the y-axis runs sideways, towards the right
- the z-axis runs upwards
- roll is a rotation around the x-axis, where positive is clockwise viewed towards the back
- pitch is a rotation around the y-axis, where positive is clockwise viewed towards the right
- heading is a rotation around the z-axis, where positive is clockwise viewed upwards
Loading the model
The property /sim/model/path in the main FlightGear property tree controls what model will be loaded; it takes a string value giving the relative path of the model from $FG ROOT.
The easiest way to load a new model is to set the property at startup with the --prop: command line option; for example, to use a 3D aircraft model that you have installed in $FG_ROOT/Models/my-cessna.ac, you could invoke FlightGear like this (under Unix-like systems):
(Note: Normally all textures used by the model must appear in the same directory. If my-cessna.ac uses the textures cessna01.rgb and cessna02.rgb, you should also install those textures in $FG_ROOT/Models/. It is howerever possible to specify a path (relative to the model path) to specify where the textures could be found.)
When you want to set a 3D model permanently as the default for an aircraft rather than specifying it on the command line, you need to edit an aircraft settings file. In the $FG_ROOT/Aircraft/ directory there is a series of files ending in -set.xml, such as c172-set.xml, dc3-yasim-set.xml, and beech99-uiuc-set.xml. When you start FlightGear with the --aircraft option, it reads the properties from one of these files; for example
Loads the properties from $FG_ROOT/Aircraft/dc3-yasim-set.xml into the main FlightGear property tree. These files are in the same XML property-list format as $FG_ROOT/preferences.xml and the FlightGear save files. There may be many XML files with different startup conditions, sounds, panels, 3D models, etc. for any single aircraft type, so you are best off copying an existing one, renaming it, then changing the value inside the path element inside model inside sim:
<PropertyList> <sim> <model> <path>Models/my-cessna.ac</path> <texture-path>./Textures</texture-path> </model> </sim> </PropertyList>
So far, all of the examples have had the /sim/model/path property point directly at the 3D model file (Models/my-cessna.ac); however, if you want to be able to reposition or animate the model, you need to point to an intermediate XML file instead, and then put the repositioning and animation information into the XML file. Here's a simple example of a 3D-model wrapper file, with no repositioning or animation information:
<PropertyList> <path>my-cessna.ac</path> <texture-path>./Textures</texture-path> </PropertyList>
Like the -set.xml files, this file is in XML property list format, but the properties in it are not added to the main FlightGear property tree; they're used only while loading the model. The following sections will explain how to add repositioning and animation information to the file; for now, the only property to worry about is path: it provides the relative path to the actual 3D file from the XML wrapper file (not from FG_ROOT!). Usually, you should put the wrapper file in the same directory as the 3D file, and then have /sim/model/path point to the wrapper file, either on the command line
or in the -set.xml file:
<PropertyList> <sim> <model> <path>Models/my-cessna.xml</path> </model> </sim> </PropertyList>
Repositioning the model
Often, an aircraft model not designed specifically for FlightGear will not be positioned or oriented correctly; for example, it might be too far off the ground, and the nose might point to the side or even straight up.
Inside the XML wrapper file (not the main FlightGear property tree), there are six properties that allow you to tweak the default position and orientation of the model:
- The distance to reposition the model along the x-axis.
- The distance to reposition the model along the y-axis.
- The distance to reposition the model along the z-axis.
- The angle by which to rotate the model around the z-axis.
- The angle by which to rotate the model around the x-axis.
- The angle by which to rotate the model around the y-axis.
For example, if you wanted to use the 3D model my-cessna.ac but found that the nose was pointing to the right instead of straight-ahead and the wheels were 1.5 metres off the ground, you could reorient it in the XML wrapper file like this:
<PropertyList> <path>my-cessna.ac</path> <offsets> <pitch-deg>0</pitch-deg> <heading-deg>270</heading-deg> <roll-deg>0</roll-deg> <x-m>0</x-m> <y-m>0</y-m> <z-m>-1.5</z-m> </offsets> </PropertyList>
It usually takes a bit of experimentation to get the model positioned correctly. Also note that if your values are zero the offsets do not have to be included. All are demonstrated above to show the format.
Animating the model
See Howto: Animate models for the main article about this subject.
Now for the interesting part. FlightGear allows you to animate models by having parts rotate or spin in response to property changes. When animating your model, it is very helpful to find an aircraft with parts similar to yours and use it as an example. Cut and paste the code into your wrapper file and then edit to suit.