Mini-HOWTO: Configuring Views in FlightGear

24 April 2002

Jim Wilson


Introduction

This mini-HOWTO explains how to configure views in FlightGear. Views define the position of the eye in the rendered scene and what if any object the eye is focused on or tracking. The eye is the imaginary or constructed eye that is simulated by the 3D rendering. It makes the picture on your screen represent what things would look like if you were standing or sitting at a given location.

Formerly there were two views hard coded into FlightGear, but as this document describes, it is possible to configure any number of views with XML configuration files. Views may be configured to switch between pilot and co-pilot, tower view, or view of an observer on the ground.

1. Types of Views

There are two basic types of views:

LookFrom - This type requires a single coordinate position. The direction of the view is independant of any particular object. Adjusting the heading and pitch offsets moves the direction of observation around. In the default Flight Gear configuration panning with the mouse will move the view around as if the observer was turning their head.

LookAt - This type requires a two coordinate positions. The direction of the view is always oriented toward a target and tracks the target if it moves.

(see configuration examples below for usage of the <type> paramter)

2. Defining Positions

There are two methods to define a postion and orientation for use in configuring a view. One method is tied to a model which means the view references the position and orientation of a model (e.g. Aircraft 3D Model) and the other is an idependant postion which simply means that the view references location data directly (via the Flight Gear property tree):

Tied to a Model - This method allows definition of the "eye", that is where you are looking from and/or the "target" or objected being looked at based on a model position and orientation. The following illustrates defining the positon of a "Cockpit View" that is positioned and oriented according to the position and orientation of a model:

<sim>
  <view>
    <name>Cockpit View</name>
    <type>lookfrom</type>
    <internal type="bool">true</internal>
    <config>
      <from-model type="bool">true</from-model>
      <from-model-idx type="int">0</from-model-idx>
    </config>
  </view>
</sim>

Syntax for the eye position is:
    <from-model type="bool">true or false</from-model>
    <from-model-idx type="int">modelnumber</from-model-idx>
Syntax for the target or at position used in views of type "lookat" is:
    <at-model type="bool">true or false</at-model>
    <at-model-idx type="int">modelnumber</at-model-idx>

Note that from-model or at-model must be true in order for the position and orientation data from the model to be used.

Independant Position - This method allows definition of the eye, that is where you are looking from or the target (objected being looked at) based on arbitrary position and orientation data obtained from the property tree (i.e. any source). The following illustrates a Tower defined as a "lookat", a view that can be used to track or follow a moving model:

<sim>
  <view>
    <name>Tower View</name>
    <type>lookat</type>
    <config>
      <eye-lat-deg-path>/sim/tower/latitude-deg</eye-lat-deg-path>
      <eye-lon-deg-path>/sim/tower/longitude-deg</eye-lon-deg-path>
      <eye-alt-ft-path>/sim/tower/altitude-ft</eye-alt-ft-path>
      <eye-roll-deg-path>/sim/tower/roll-deg</eye-roll-deg-path>
      <eye-pitch-deg-path>/sim/tower/pitch-deg</eye-pitch-deg-path>
      <eye-heading-deg-path>/sim/tower/heading-deg</eye-heading-deg-path>

      <at-model type="bool">true</at-model>
      <at-model-idx type="int">0</at-model-idx>

    </config>
  </view>
</sim>

Note that the definition is constructed as a path to a numeric data item in the global property tree. If you are unfamiliar with these properties, take a look at the "Property Picker" dialog while Flight Gear is running and you can see the kinds of values in use. You may define your own static values, say for a fixed location of an observer, by adding the following xml to your setup (prefrences.xml or another file):

<somepath>
  <ground-observer-lon-deg>48.6124</ground-observer-lon-deg>
  <ground-observer-lat-deg>63.1243</ground-observer-lat-deg>
  <ground-observer-alt-ft>123.5</ground-observer-alt-ft>
</somepath>

These values can then then be referenced in your view by including their path in the definition. For example to reference the above longitude for the ground observer:

<sim>
  <view>
    <config>
      <eye-lat-deg-path>/somepath/ground-observer-lat-deg></eye-lon-deg-path>
      ..

All three longitude, latitude, and altitude must be defined to have a valid position (otherwise the missing items default to 0). You may also define orientation such as heading (the direction to look toward) and pitch (the angle up or down to be looking). In the case of a cockpit view the orientation will be that of the aircraft itself, but in the case of a "lookfrom" view like a ground observer or tower it can be an arbitrary view direction that is either static, or changing.

Syntax for the eye position and orientation is:
    <eye-lat-deg-path>path-to-property-value</eye-lat-deg-path>
    <eye-lon-deg-path>path-to-property-value</eye-lon-deg-path>
    <eye-alt-ft-path>path-to-property-value</eye-alt-ft-path>
    <eye-roll-deg-path>path-to-property-value</eye-roll-deg-path>
    <eye-pitch-deg-path>path-to-property-value</eye-pitch-deg-path>
    <eye-heading-deg-path>path-to-property-value</eye-heading-deg-path>

Syntax for the target or at position used in views of type "lookat" is:
    <target-lat-deg-path>path-to-property-value</target-lat-deg-path>
    <target-lon-deg-path>path-to-property-value</target-lon-deg-path>
    <target-alt-ft-path>path-to-property-value</target-alt-ft-path>

3. View Offsets

There are two types of offsets, but only one is used in building viewer configurations. This is an offset from the eye position applied to the position defined for the eye as described in the section on Defining Positon.

These offsets are defined in meters. Here is an example of a Cockpit View definition that includes offsets for the pilot's eye:

<sim>
  <view>
    <name>Cockpit View</name>
    <type>lookfrom</type>
    <internal type="bool">false</internal>
    <config>
      <from-model type="bool">true</from-model>
      <from-model-idx type="int">0</from-model-idx>

      <x-offset-m type="double">-0.22</x-offset-m>
      <y-offset-m type="double">0.30</y-offset-m>
      <z-offset-m type="double">-0.45</z-offset-m>
    </config>
  </view>
</sim>

Note that these offsets are actually best applied differently to specific aircraft models. The size of the aircraft and the actual position of the pilot's seat make a big difference. So typically these offset entries are included per aircraft in the aircraft-set.xml files.

In other circumstances, such as defining a Chase View, you can possibly get away with defining the x-offsets in a more global location so that they apply to all aircraft. Here is an example of a Chase View configuration that includes offsets to define the eye as being 25 meters behind the model origin:

<sim>
  <view>
    <name>Chase View</name>
    <type>lookat</type>
    <config>
      <from-model type="bool">true</from-model>
      <from-model-idx type="int">0</from-model-idx>
      <at-model type="bool">true</at-model>
      <at-model-idx type="int">0</at-model-idx>

      <x-offset-m type="double">0</x-offset-m>
      <y-offset-m type="double">0</y-offset-m>
      <z-offset-m type="double">-25</z-offset-m>
    </config>
  </view>
</sim>

At the time of this writing (and this is subject to change), offsets define the change in eye position as follows:

x-offset-m
Positive values to the right of origin (view position).
y-offset-m
Positive values move up from origin.
z-offset-m
Positive values move back (or in) from origin.

4. Ground Level Near Plane

Generally, a higher Near Plane value will result in a better quality rendering of distant scenery and models. Currently when the aircraft is in flight the Near Plane is set at 10 meters.

Any object (including terrain) that is closer to the eye or camera than 10 meters will not be visible. For this reason, when the eye is close to the ground, the Near Plane must be set lower. Here is an example of a Cockpit view that is configured to have only a 0.5 meter Near Plane when sitting on the ground (or below a given flight level which currently defaults to 30ft AGL altitude).

  <view>
    <name>Cockpit View</name>
    <type>lookfrom</type>
    <internal type="bool">false</internal>
    <config>
      <from-model type="bool">true</from-model>
      <from-model-idx type="int">0</from-model-idx>

      <ground-level-nearplane-m type="double">0.5f</ground-level-nearplane-m>
    </config>
  </view>

The example Tower View however, is able to set the value to 10 meters since the tower position is 50ft AGL altitude to start with:

  <view>
    <name>Tower View</name>
    <type>lookat</type>
    <config>
      <eye-lat-deg-path>/sim/tower/latitude-deg</eye-lat-deg-path>
      <eye-lon-deg-path>/sim/tower/longitude-deg</eye-lon-deg-path>
      <eye-alt-ft-path>/sim/tower/altitude-ft</eye-alt-ft-path>
      <eye-roll-deg-path>/sim/tower/roll-deg</eye-roll-deg-path>
      <eye-pitch-deg-path>/sim/tower/pitch-deg</eye-pitch-deg-path>
      <eye-heading-deg-path>/sim/tower/heading-deg</eye-heading-deg-path>

      <at-model type="bool">true</at-model>
      <at-model-idx type="int">0</at-model-idx>

      <ground-level-nearplane-m type="double">10.0f</ground-level-nearplane-m>

    </config>
  </view>

5. Other examples

Example 1 - The configuration of a Chase View without a rotating frutstum (the view does not tilt with the aircraft's roll and pitch) is easy. Since the aircraft model's orientation is contained in it's location definition, you must set from-model property to false so you may define your own source for position and orientation. Then define eye position properties for the appropriate values. If you leave eye-roll-deg and eye-pitch-deg out then they will be fixed at 0 degrees. Note that technically this example does rotate, but only on the heading :)

  <view>
    <name>Chase View</name>
    <type>lookat</type>
    <config>
      <from-model type="bool">false</from-model>
      <from-model-idx type="int">0</from-model-idx>
      <eye-lat-deg-path>/position/latitude-deg</eye-lat-deg-path>
      <eye-lon-deg-path>/position/longitude-deg</eye-lon-deg-path>
      <eye-alt-ft-path>/position/altitude-ft</eye-alt-ft-path>
      <eye-heading-deg-path>/orientation/heading-deg</eye-heading-deg-path>

      <at-model type="bool">true</at-model>
      <at-model-idx type="int">0</at-model-idx>

      <ground-level-nearplane-m type="double">0.5f</ground-level-nearplane-m>

      <x-offset-m type="double">0</x-offset-m>
      <y-offset-m type="double">0</y-offset-m>
      <z-offset-m type="double">-25</z-offset-m>
    </config>
  </view>

more to come?


Jim Wilson, 24 April 2002 - last update 11 June 2002

Curtis L. Olson