Airplane parameters in xml, airplane model version 2

Also see helicopter model, version 1.

0 About this document

This document is not complete yet. It may be inaccurate or wrong, too.

This document should not provide examples. Please take a look at the files you got when downloading/installing CRRCSim. At the time of this writing only superzagi.xml uses more features than other files.

You need to know basics about xml files: they are structured text. Whitespace and line breaks do not matter in most places. Just take a look at the examples and you will understand.

The files can be edited using a text editor. There are lots of them. Use something like notepad, vi, emacs, joe...

0.1 Changes

1 General information

  
<?xml version="1.0" encoding="iso-8859-1" ?>
<CRRCSim_airplane version="2">
  <description>
    <en>
        This plane has been automatically converted from superzagi.air. 
        Please update this text if you know more about it.
    </en>
  </description>
  <changelog>
    <change>
      <date>Unknown</date>
      <author>CRRCSim 0.9.5</author>
      <en>Automatically converted from .air file.</en>
    </change>
    <change>
      <date>Please write date.</date>
      <author>Please write your name and email.</author>
      <en>Please write down what you changed.</en>
    </change>
  </changelog>
  
  

2 Units

Some sections have an attribute units, which tells which units are used for the values in that section. The tables below have a column named 'unit' if the unit is fixed, otherwise they have columns like 'units=0' and 'units=1'.

For example, the section aero has attribute units. Its documentation below tells you that you can set this attribute to '0' or '1', which lets CRRCSim expect a value with the unit indicated by just that table column.

There is a file called non_SI_units.txt in the CRRCSim distribution which explains some strange units.

Some parameters (especially aerodynamic coefficients) are without dimension, so their unit is just '1' (not to be confused with 'units=0' or 'units=1'!).

Some parameters (like filenames) of course can't be said to have a unit, so their table entry is '-'.

3 Aerodynamics: section aero

This section can stand on its own, but can also be a subsection of config.

3.1 Subsection ref

The following table explains attributes in that subsection.

3.2 Subsection misc

3.2.1 CG_arm

Email from Mark Drela, 10.01.2006:

The stall model computes the values (dCL_left, dCL_cent, dCL_right) which represent the changes in CL due to stall.
To get the stall effect on the Cm, these are multiplied by the length CG_arm, which is the distance between the CG and the effective point of application of dCL:
dCm_stall = (0.25*dCL_left + 0.5*dCL_cent + 0.25*dCL_right)*CG_arm;

The typical value CG_arm = 0.25 means that the point of application of the averaged dCL is 0.25*chord ahead of the CG.

This CG_arm can be deduced from airfoil data. If dCL and dCm are the changes due to stall, the implied CG_arm is
CG_arm = dCm/dCL
Typically, both dCm and dCL will be negative, so CG_arm is positive.

You can also adjust CG_arm to get a realistic simulator pitch response due to stall. The larger CG_arm is, the more pitch-down you will get during stall.

3.3 Subsection m

These parameters deal with pitching moment, or how the airplane rotates about the pitch axis (up or down elevator). The actual value would be foot-pounds or Newton-meters. What we have here are coeffients, that do not have dimensions, so we can apply them to airplanes of similar configuration, but different sizes, airspeeds and air densities.

To take one of these coefficients and convert it to the actual moment we would use the equation:
M= 1/2 * rho * velocity^2 * wing area * wing chord * Cm

Note that the yaw and roll deriviatvies use the wing span as the reference length instead of the chord. That is Bref in the AVL output and aero.ref.span in this file.

There are several terms that add up to the total pitching moment.

3.4 Subsection lift

3.5 Subsection drag

3.6 Subsection Y

3.7 Subsection l

3.8 Subsection n

3.9 Subsection flaps

Lift, drag and moment coefficients are altered when using flaps. For an example, see Skorpion.xml and Wasabi.xml.

Usually changing flap setting change pitching moment and thus alter the trimmed angle of attack (AoA), so that elevator position must be adjusted (trimmed) to either keep the angle of attack unchanged or to trim to the new desired AoA. If you set flap.moment = 0, then the trimmed AoA will stay constant.

Flap (camber changing flap) can also be used "mixed" with elevator, so that an elevator input also generate a flap deflection to optimize airfoil camber for the desired lift coefficient (e.g. flaps are lowered when elevator is pulled). To achieve this effect the elevator should be mixed into flap input: the right amount of mixing is model dependent.

3.10 Subsection spoiler

This is similar to flap, except that the drag effect is linear not quadratic and that there is no eff_ratio parameter (spoiler effect is linear).

3.11 Subsection retract

This subsection describes how a retractable gear influences drag and lift (similar to a spoiler). For an example, see sport.xml.

Please note that retract.lift is usually a negative coefficient, because the gear will disturb the airflow when it is not fully retracted and the wheel wells are open.

3.12 Subsection prop

This subsection describes model-dependant interaction effects between propeller and aerodynamics. For an example, see Angel_S30E.xml.

Please note that prop.torquefactor shall be a coefficient < 1 (default to 0.25), because propeller's slipstream produces an aerodynamic rolling moment counteracting torque effect. Changing the sign of prop.torquefactor to negative change the net rolling effect from rolling left to rolling right, i.e. simulating a counterclockwise rotating propeller (seen from the cockpit).

4 Configuration: section config

There can be more than one configuration for an airplane, so there may be several config sections. Because of this, each config needs a description.

  <config version="1">
    <descr_long>
      <en> Powerful motor which makes this config heavy, too.</en>
    </descr_long>
    <descr_short>
      <en>powerful and heavy</en>
    </descr_short>
  

Additionally, instead of using the general aero section, a config section can contain its own aero section (see k2.xml for an example).

4.1 Subsection mass_inertia

4.2 Subsection sound

The sound subsection contains the description of the sound samples used for this airplane. Each sample is described in a sample subsubsection.

4.2.1 Subsubsection sample

4.3 Subsection power

There is a separate documentation (../power_propulsionspower_propulsion.html) which explains the power and propulsion system.

5 Graphics: section graphics

5.1 Specifying a 3D model file

This section binds one or more 3D models to an XML file. The 3D model is what you actually see on screen when loading this model XML file. There can be more than one graphical representation for an airplane (e.g. for different configurations or different finishs), so there may be several graphics sections. Because of this, each graphics needs a description.

    <graphics version="1" model="zagi.ac" >
      <descr_long>
        <en>Automatically converted from superzagi.air.</en>
      </descr_long>
      <descr_short>
        <en>default</en>
      </descr_short>
    

Currently you only need to specify the name of the graphics file.

5.2 A word on 3D model files

The PLIB library used in CRRCsim to display the airplane model graphics can handle a lot of different file types. However, files in AC3D format (.ac) or 3DStudioMax format (.3ds) seem to work best. Any decent modelling tool should be able to export at least one of these formats. AC3D, Blender and Wings3D have been reported to work fine for creating CRRCsim models.

5.3 Object names in 3D files

3D modelling tools usually compose the whole model (the content of the 3D model file) from objects. An object is a group of surfaces (or faces for short) defined by connected vertices (a vertex is a single point in 3D space).

On object level, a modelling tool usually allows the user to define arbitrary names for single objects. These names provide better orientation while modelling. In CRRCsim, object names are also used to manipulate objects in several ways, like animating model parts or controlling the rendering process. Therefore the following conventions have been defined:

• The object name assigned to a model part in a 3D modelling tool may contain blanks (space characters). However, CRRCsim only uses everything up to the first blank as the object's real name. If you assign the name "Right wing" to an object, CRRCsim will internally refer to this object as "Right". Therefore it is recommended to substitute blanks by underscore characters ("Right_wing") or use CamelCase notation ("RightWing").
• The rest of an object's name (everything after the first blank character) is treated as additional information ("attributes")for the 3D rendering process. An object with the name "Rotor_disc -shadow" is internally referred to as "Rotor_disc", and the attribute "-shadow" tells the 3D engine not to render a shadow for this part of the model.

5.4 Object attributes

The following rendering attributes (see the preceding section) are currently defined for 3D objects:

6 Hard points and wheels: section wheels

This section contains a number of entries, each of them describing one hard point on the airplane. The caster angle is specified with respect to the plane body's z-axis, a value of zero means that the wheel is oriented straight ahead (which should be the case for most gears).

6.1 Subsection pos

Position of hard point in body axes with regard to center of gravity. Unit is feet (units="0") or meters (units="1"). x positive forward, y positive right, z positive down.

Remark: 3D modelling tools sometimes use other coordinate system orientations. In this case the coordinates of a hard point have to be converted into the CRRCsim coordinate system. Here's an example for AC3D and Blender:

This means that a point in AC3D at X = -3.28, Y = 0.55, Z = -0.37 (this could be the right wingtip of a 2m sailplane) will result in the following position tag:

        <pos x="-0.37" y="3.28" z="-0.55" />
      

Hardpoints may be located on animated control surfaces (e.g. on a retractable gear). In this case, specify an additional attribute "animation" that contains the name of the control surface animation that controls this part of the 3D model. Example (from sport.xml):

        <pos x="0.41677001" y="0" z="0.52499998" animation="nose_gear" />
      

In this case, the <animations> section of the file should of course contain an element <object name="nose_gear" /> that defines the actual movement. See section 8 for more details on animations.

6.2 Subsection spring

This subsection defines the springiness of the hardpoint, e.g. if a collision of this hardpoint with ground makes the plane bounce, is damped by the hardpoint's flexibility or leads to a crash.

The flight dynamics model calculates the forces on each hardpoint resulting from interaction with the ground or solid objects. If this value exceeds the specified max_force, the plane will be considered as crashed. The max_force attribute is optional; if it is not specified, it will internally be set to a very high default value so that this hardpoint will only cause a crash on insanely high load.

6.3 Subsection steering

In this subsection a mapping of the hardpoint to an R/C channel can be defined. Possible values for the "mapping" parameter are "NOTHING" (which makes this subsection redundant), "RUDDER", "AILERON" or "ELEVATOR". By specifying a negative value for max_angle the coupling from the control input to the wheel will be reversed. A positive angle should be correct for a tail wheel while a steerable nose wheel usually needs a negative angle.

Example: this maps a nose wheel to the rudder channel, giving 20 degrees (= 0.349 radians) of wheel deflection at full rudder input.

        <steering mapping="RUDDER" max_angle="-0.349" />
      

7 Center of gravity: section CG

Position of center of gravity in body axes with regard to coordinates used by wheels and the 3D graphics file.
Unit is feet (units="0") or meters (units="1"). x positive forward, y positive right, z positive down. Example:

          <CG units="0" x="-0.2234252" y="0" z="-0.043131893" />
        

This section and values do not have to exist, it is optional. However, it gives you the following advantage: There is no need to create the 3D model (and the points in the wheels section) around the center of gravity. You can use any reference point and give the position of the CG using your coordinates in this section.

This also makes it possible to change the location of the CG without changing the 3D model and wheels.

You can visually check the position of the CG using test mode, as the airplane rotates around the center of gravity (given that throttle=0).

8 Animated parts: section animations

This section contains information needed to animate parts of the model, e.g. to move the control surfaces according to stick input. It is optional to define animations for a model; however it is strongly recommended to make use of this feature because it adds much to the appearance of a model.

To animate a part of a 3D model it is required that this part is modelled as an independent object in the 3D model file, and that the object has a unique name. A proper 3D modelling tool should allow one to group surfaces to objects and give them names, so this shouldn't be a problem.

The <animations> section contains one <animation> subsection per animated object. The <animation> tag must contain a type attribute to define the kind of animation that should be created. Currently only the type ControlSurface is implemented.

8.1 Animation type ControlSurface

This kind of animation is used to rotate an object of the 3D model around an arbitrary axis according to stick input. It can be used to animate control surfaces like elevator or ailerons, or to animate gears that retract with a rotational movement.

8.1.1 Subsection object

This subsection defines the object to which the animation is applied and the maximum amount of movement.

8.1.2 Subsection control

This subsection defines how the surface interacts with the input from the controller. mapping can be set to one of RUDDER, ELEVATOR, AILERON, THROTTLE, FLAP, SPOILER, RETRACT or PITCH. There can be more than one control section for a surface, e.g. there will be a mapping to ELEVATOR and AILERON if the model has elevon controls (aka "delta-mix"). The gain setting determines the relationship of the control input to the surface deflection. A gain value of 1.0 means that the surface will travel the full max_angle from the object section above if the associated control is moved to its extents. Negative gain values will reverse the surface movement.

8.1.3 Subsection hinge

To define the rotation axis of the control surface it is mandatory to define exactly two <hinge> subsections. The rotation will occur around an imaginary axis from the first to the second hinge, and the direction of the rotation can be determined by applying the right-hand rule to this axis. The X/Y/Z values are kind of unit-less ("OpenGL"-units). They can be determined by selecting a vertex close to the hinge point in the 3D modelling tool and then transforming the displayed vertex coordinates into the coordinate system described below (same as with the <wheel> positions described above).

This is an example for the animation of left and right aileron on an 1.6m aerobatics model, giving 20 degrees (= 0.349 radians) of control surface deflection at full aileron input, assuming that the aileron objects of the 3D model are called ail_right and ail_left:

        <animations>
          <animation type="ControlSurface">
            <object name="ail_right" max_angle="0.349" />
            <control mapping="AILERON" gain="-1.0" />
            <hinge x="-0.56" y="0.63" z="0.03" />
            <hinge x="-2.64" y="0.40" z="0.02" />
          </animation>
          <animation type="ControlSurface">
            <object name="ail_left" max_angle="0.349" />
            <control mapping="AILERON" gain="-1.0" />
            <hinge x="0.56" y="0.63" z="0.03" />
            <hinge x="2.64" y="0.40" z="0.02" />
          </animation>
        </animations>
        

9 Launch presets: section launch

This section is optional. It contains launch presets that will be shown in the launch dialog of the GUI if this airplane is currently selected. The <launch> section shall only contain <preset> tags, each one containing the attributes that describe the launch process like in CRRCsim's main configuration file.

Example:

      <launch>
        <preset name_en="Gap65 default (ground)" altitude="0" velocity_rel="0" angle="0.22" sal="0" 
                rel_to_player="1" rel_front="1" rel_right="-2" />
      </launch>