Common Image Generator Interface (CIGI)


Contents
Related Links
  • Not Applicable

Common Image Generator Interface (CIGI) is a simulation interoperability standard that provides communication between a Host simulation and an Image Generator (IG). The currently supported CIGI versions include version 4.0 and version 3.3. The native CIGI implementation is only available with the Professional Plus variant.


Starting a Session

A CIGI session can be started by selecting either Start Host or Start IG under Networking, CIGI in the main menu bar. The CIGI session should be configured before attempting to connect (see below).


Session Configuration

CigiConfig.cfg

The CigiConfig.cfg file can be found in %APPDATA%\Lockheed Martin\Prepar3D v4\CigiConfig.cfg after Prepar3D has been launched at least once. This file is used by both the Prepar3D Host and Prepar3D IG modes. Most settings are shared between the Host and IG, however some are exclusive to either the Host or IG (i.e. clamp settings).

Common Options

Option Description
BufferSizeReceive The BufferSizeReceive setting represents the size of the receive buffer used to queue packets in bytes. Valid BufferSizeReceive range from 1024 to 65536. The default value is 32768.
BufferSizeSend The BufferSizeSend setting represents the size of the receive buffer used to queue packets in bytes. Valid BufferSizeSend range from 1024 to 65536. The default value is 32768.
CigiMajorVersion The CigiMajorVersion of this application instance. Currently supported CigiMajorVersion values are 4 or 3 (with a CigiMinorVersion of 0 or 3, respectively. i.e. 4.0 or 3.3).
CigiMinorVersion The CigiMinorVersion of this application instance. Currently supported CigiMinorVersion values are 0 or 3 (with a CigiMajorVersion of 4 or 3, respectively. i.e. 4.0 or 3.3).
Frequency The Frequency that the Host or IG will send IG Control and Start of Frame packets in Hertz. The Host or IG will send packets no faster than this value. This value only applies to the Host if the IsSynchronous option is set to 0 (i.e. asynchronous mode).
IsSynchronous The IsSynchronous option determines whether the session will be synchronous or asynchronous. Valid IsSynchronous range are 0 or 1. When set to 1 on the Host, the Host will not send an IG Control packet until it has received a Start of Frame packet from the IG (i.e. the Host waits on the IG). When set to 0 on the Host, the Host will continously send IG Control packets based on the Frequency option's value. This value should also be set for the Prepra3D IG based on the session's Host configuration.
ReceivePort The port that the Host or IG should receive packets on. For example, if the Host is sending on port 8001, the IG should be receiving on port 8001 and vice versa. Must be set on the Host and the IG. The default value is 8001.
SendAddress The IP address of the session's opposing computer (i.e. 192.168.1.1). For example, if this machine is the Host then the SendAddress should be that of the IG and vice versa. Must be set on the Host and the IG.
SendPort The port that the Host or IG should send packets on. For example, if the Host is sending on port 8000, the IG should be receiving on port 8000 and vice versa. Must be set on the Host and the IG. The default value is 8000.
ViewID The ViewID to be associated with the Prepar3D main window. As the Host, this ViewID will be used when broadcasting the Prepar3D main window View Control packet. As the IG, this ViewID will be used to associate an incoming View Control packet with the Prepar3D main window. Only one view is currently supported.

Host Exclusive Options

Option Description
ClampModeAircraft The ClampModeAircraft clamps the aircraft entities. Valid ClampModeAircraft values are 0 for No Clamp, 1 for Non-Conformal, 2 for Conformal.
ClampModeBoat The ClampModeBoat clamps the boat entities. Valid ClampModeBoat values are 0 for No Clamp, 1 for Non-Conformal, 2 for Conformal.
ClampModeGround The ClampModeGround clamps the ground entities. Valid ClampModeGround values are 0 for No Clamp, 1 for Non-Conformal, 2 for Conformal.
ClampModeLifeform The ClampModeLifeform clamps the lifeform entities. Valid ClampModeLifeform values are 0 for No Clamp, 1 for Non-Conformal, 2 for Conformal.
EnableMoon The EnableMoon enables sending moon data. Valid EnableMoon range from 0 to 1.
EnableSmoothing The EnableSmoothing enables dead reckoning on the IG. Valid EnableSmoothing range from 0 to 1.
EnableStars The EnableStars enables sending star data. Valid EnableStars range from 0 to 1.
EnableSun The EnableSun enables sending sun data. Valid EnableSun range from 0 to 1.
SensorID The SensorID of the CIGI instance. The SensorID should be a unique int value for each CIGI instance. Currently only supports whether a sensor is on or off, and if it's white hot or black hot.
StarIntensity The StarIntensity specifies the intensity of the star field within the sky model. Valid StarIntensity range from 0 to 100.
UseExtendedType The UseExtendedType determines whether to use extended entity types or not (only valid for CIGI version 4.0). Valid UseExtendedType range from 0 to 1.

IG Exclusive Options

Option Description
LosResponseLimit The LosResponseLimit limits the number Line Of Sight Response packets sent. Valid LosResponseLimit values are any integer value. Note that the current method used for these packets is expensive, so the higher the LosResponseLimit value is the worse the performance will be. The default value is 1.
EnableLosDebugVisuals When enabled, the EnableLosDebugVisuals will draw lines in 3D space where the raycast is traveling. A green line represents a raycast that hit something. A red line represents a raycast that hit nothing. The lines will start to disappear after 5 seconds pass from the Line Of Sight call, and will be completely gone after 10 seconds pass. If the same Line Of Sight packet ID is called before the line disappears, it will update the lines location and reset the disappearance timer. Valid EnableLosDebugVisuals values are 0 and 1. The default value is 0.
EnableHatHotDebugVisuals When enabled, the EnableHatHotDebugVisuals will draw spheres in 3D space where the Hat/Hot requests are happening. The color of the spheres will change between Red, Blue, and Green based on a modulus 3 in regards to the Hat/Hot ID. The spheres will start to disappear after 5 seconds pass from a Hat/Hot call, and will be completely gone after 10 seconds pass. If the same Hat/Hot packet ID is called before the sphere disappears, it will update the spheres location and reset the disappearance timer. Valid EnableHatHotDebugVisuals values are 0 and 1. The default value is 0.


Animation Configuration

CigiAnimations.xml

The embedded CigiAnimations.xml file is used to map entity types to animation effects. CigiAnimations.xml can be found in %PROGRAMDATA%\Lockheed Martin\Prepar3D v4\CigiAnimations.xml after Prepar3D has been launched at least once. This file applies to both the Prepar3D Host and Prepar3D IG modes.

<SimBase.Document Type="Cigi Animations" version="4,3" id="CigiAnimations">
    <Descr>CIGI Animations File</Descr>
    <Filename>CigiAnimations.xml</Filename>
    <AnimationDefinitions>
        <AnimationDefinition>
            <EntityTypeID>40000</EntityTypeID>
            <EffectFileName>fx_dirtcrash</EffectFileName>
        </AnimationDefinition>
    </AnimationDefinitions>
</SimBase.Document>

AnimationDefinitions

Property Description
AnimationDefinition This is where the animation type id and the effect's filename are stored.

AnimationDefinition

Property Description
EntityTypeID This stores the ID to be shared with the Host and the IG. Must be a unique EntityTypeID. This should be an integer value from 0-65535. Extended entity type is not supported for animations.
EffectFileName This is where the animation effect's filename is stored.

Articulated Part Configuration

CigiArticulatedParts.xml

The embedded CigiArticulatedParts.xml file is used to simulation variables and registered properties to CIGI articulated part values and units. CigiArticulatedParts.xml can be found in %PROGRAMDATA%\Lockheed Martin\Prepar3D v4\CigiArticulatedParts.xml after Prepar3D has been launched at least once. This file applies to both the Prepar3D Host and Prepar3D IG modes.

<?xml version="1.0" encoding="UTF-8"?>

<SimBase.Document Type="Cigi Articulated Parts" version="3,1" id="CigiArticulatedParts">
    <Descr>Cigi Articulated Parts File</Descr>
    <Filename>CigiArticulatedParts.xml</Filename>
    <ArticulatedPartDefinition Name="Native Airplane" DefinitionGuid="{3389C282-752D-49C8-B6C1-B60D357B8DC7}">
        <ArticulatedPart ID="1">
            <ValueDefinition PropertyGet="RUDDER DEFLECTION" ValueType="Heading" Units="Degrees" />
        </ArticulatedPart>
        <ArticulatedPart ID="2">
            <ValueDefinition PropertyGet="AILERON LEFT DEFLECTION" ValueType="Pitch" Units="Degrees" />
        </ArticulatedPart>
        <ArticulatedPart ID="3">
            <ValueDefinition PropertyGet="AILERON RIGHT DEFLECTION" ValueType="Pitch" Units="Degrees" />
        </ArticulatedPart>
    </ArticulatedPartDefinition>
</SimBase.Document>

ArticulatedPartDefinition

Property Description Required
Name This is the friendly name of the articulated part definition. No
DefinitionGuid The DefinitionGuid is used to look up ArticulatedPartDefinition sets. This GUID should be unique for each ArticulatedPartDefinition. If a definition is not found, no articulated part data will be sent or processed by that entity. See also Custom Articulated Part XML File. Yes
ArticulatedPart This set stores a unique ID for an articulated part as well as the type and units of movement the part performs. Yes

ArticulatedPart

Property Description Required
ID The unique ID of the articulated part. Yes
ValueDefinition This set stores the type and units of movement the articulated part performs. Yes

ValueDefinition

Property Description Required
ValueType The type of movement for this articulated part. Values should be one of the following:
  • Pitch
  • Bank
  • Heading
  • XOffset
  • YOffset
  • ZOffset
Yes
PropertyGet

The property or simulation variable to be used to retrieve the ArticulatedPart value.

Yes
PropertySet

The property or simulation variable to be used to apply the ArticulatedPart value. If this value is not present, the PropertyGet value will be used instead.

No
Units

The units to be used when getting or setting the PropertyGet and PropertySet variables.

Yes
Offset

This value will be added to the ArticulatedPart property value before it is sent or subtracted from the ArticulatedPart value after it is received. This value will be added before the scale value is multiplied if being sent or subtracted after the scale value is divided if being received. The default value is 0.0.

If being sent, the formula is:

SendValue = (Property + Offset) * Scale

If being received, the formula is:

Property = (ReceivedValue / Scale) - Offset

No
Scale

This value will be multiplied against the ArticulatedPart property value before it is sent or divided from the ArticulatedPart value after it is received. This value will be multiplied after the offset value is added if being sent or subtracted after the scale value is divided if being received. The default value is 1.0.

If being sent, the formula is:

SendValue = (Property + Offset) * Scale

If being received, the formula is:

Property = (ReceivedValue / Scale) - Offset

No
WrapMode

This value is optional and should be one of 180 or 360. This setting determines how angles should be wrapped, either -180 to 180 or 0 to 360. This setting is only used when the application is in IG mode, so it only has an effect when setting a property based on the incoming packet value.

No

Custom Articulated Parts XML File

In addition to the default CigiArticulatedParts.xml, a vehicle specific CigiArticulatedParts.xml file can be created on a per-SimObject basis. This file must be saved in the SimObject's folder (in the same folder as the aircraft.cfg or sim.cfg file). The GUID that is defined for the ArticulatedPartDefinition, in the XML file, must be set in the configuration file under the [GENERAL] section in a CigiArticulatedPartDefinitionGuid property (see example below). It must be a unique GUID for the vehicle (see Generating GUIDs).

An example CigiArticulatedParts.xml:

<?xml version="1.0" encoding="UTF-8"?>

<SimBase.Document Type="Cigi Articulated Parts" version="3,1" id="CigiArticulatedParts">
    <Descr>Cigi Articulated Parts File</Descr>
    <Filename>CigiArticulatedParts.xml</Filename>
    <ArticulatedPartDefinition Name="6x4 Truck MRBM Launcher" DefinitionGuid="{A2C4A4F0-6AAF-4FF9-AE0C-86BFF426A637}">
        <ArticulatedPart ID="1">
            <ValueDefinition PropertyGet="SteerAngle:0" PropertySet="SteerAngleSet:0" ValueType="Heading" Units="Degrees" />
        </ArticulatedPart>
        <ArticulatedPart ID="2">
            <ValueDefinition PropertyGet="SteerAngle:1" PropertySet="SteerAngleSet:1" ValueType="Heading" Units="Degrees" />
        </ArticulatedPart>
        <ArticulatedPart ID="3">
            <ValueDefinition PropertyGet="TurretHeadingAngle" PropertySet="TurretHeadingAngleSet" ValueType="Heading" Units="Degrees" />
            <ValueDefinition PropertyGet="TurretPitchAngle" PropertySet="TurretPitchAngleSet" ValueType="Pitch" Units="Degrees" />
        </ArticulatedPart>
    </ArticulatedPartDefinition>

Inside aircraft.cfg or sim.cfg:

...
[General]
...
CigiArticulatedPartDefinitionGuid={A2C4A4F0-6AAF-4FF9-AE0C-86BFF426A637}
...


Entity Type Configuration

Entity Type XML File

The DISEntityTypes.xml file is also used by CIGI to map SimObject container titles to CIGI entity types. The file can be located within the %PROGRAMDATA%\Lockheed Martin\Prepar3D v4 directory after Prepar3D has been launched at least once. Most default included SimObjects have already been mapped to an appropriate extended entity type where possible, however users are able to expand the included list. Multiple EntityType entries can be present.

Entity Type ID

The EntityTypeID is an integer value ranged from 0 to 65535 used to bind a container title to a given entity type.

Note: This value is required for CIGI version 3.3. For CIGI version 4.0, this value is required if the UseExtendedType option is set to 0, otherwise EntityTypeString is required.


Entity Type String

The entity type string is a period delimited numerical string used to define the type of a given entity. Each integer represents properties of the entity type in the following order: Kind, Domain, Country, Category, Subcategory, Specific, and Extra. Asterisks (*) can be used as wildcards for each of the entity type properties. If an entity type property is not explicitly set it will be considered a wildcard. For example, an entity type string with all digits explicitly defined such as 1.2.225.85.11.0.0 would only be matched to other exact types. On the other hand, a wildcard-based entity type string with such as 1.2 or 1.2.*.*.*.*.* would be matched to all aircraft-based platforms.

Note: This value is not available in CIGI version 3.3. This value is required for CIGI version 4.0 if UseExtendedType is set to 1, otherwise EntityTypeID is required.


Example Entity Type Strings:
1.2.225.85.11
1.2.225.85.11.*.*
1.2.*.85.11
1.2.225.85.11.0.0
    // Implicit Wildcards
    // Explicit Wildcards (same as above)
    // Explicit Inner and Implicit Outer Wildcards
    // Explicit definition (7 digits defined)


Example DISEntityTypes.xml file:

<SimBase.Document Type="DIS Entity Types" version="3,1" id="DISEntityTypes">
    <Descr>DIS Entity Type Map File</Descr>
    <Filename>DISEntityTypes.xml</Filename>
    <DIS.EntityTypes>
        <EntityType>
            <EntityTypeID>20001</EntityTypeID>
            <EntityTypeString>1.2.225.85.11.0.0</EntityTypeString>
            <ContainerTitle>Mooney Bravo</ContainerTitle>
        </EntityType>
    </DIS.EntityTypes>
</SimBase.Document>

Supported Packets

The following packets are currently supported: