[[TracNav(TracNav/TOC)]]


= osgVisual configuration =

To use osgVisual, you have to configure osgVisual according to your needs.

Basiccally, osgVisual provides two configuration mechanisms:
 * Via commandline parameters
 * Via configuration file



== Configuration via parameters ==

osgVisual is build on top of !OpenSceneGraph. The core module is osgViewer which provides all the background technology to render the scene graph on the screen. You can use all osg related command line options by adding these options to osgVisual. 

To get an overview of the available parmeters, execute
{{{
#!sh
osgviewer --help
}}}
or go to http://www.openscenegraph.org


== Configuration via configuration file ==

For all options which are not OSG but osgVisual related, the configuration mechanism is an XML configuration file. This file contains sections for each module to configure and for the scenery to display.

Example of a configuration file with module and scenery configuration:
{{{
#!xml
<?xml version="1.0" encoding="ISO-8859-1" ?>
<osgvisualconfiguration>
  <module name="distortion" enabled="no">
    <distortion channelname="center" renderimplemmentation="fbo" width="2048" height="2048" useshader="yes" hdr="yes" usetexturerectangle="no"></distortion>
  </module>
  <module name="sky_silverlining" enabled="yes"></module>
  <module name="vista2d" enabled="yes">
    <vista2d filename="absolute/path/to/you/vista2DProject.v" paintBackground="no" position_x="1" position_y="1" zoom="1.0" playanimation="yes"></vista2d>
  </module>
  <module name="dataio" enabled="yes">
    <dataio clusterrole="standalone"></dataio>
    <cluster implementation="enet" hardsync="yes" master_ip="10.10.10.10" port="1234" use_zlib_compressor="yes" ></cluster>
    <extlink implementation="vcl" filename="osgVisual.xml"></extlink>
  </module>
  <scenery>
    <terrain filename="relative/or/absolute/path/to/you/database1.ive" filename2="relative/or/absolute/path/to/you/database2.ive"></terrain>
    <animationpath filename="salzburg.path"></animationpath>
    <models>
      <model objectname="TestObject" trackingid="1" label="TestText!" dynamic="no">
        <position lat="47.8123" lon="12.94088" alt="700.0"></position>
        <attitude rot_x="0.0" rot_y="0.0" rot_z="0.0"></attitude>
        <updater>
          <position lat="" lon="" alt=""></position>
          <attitude rot_x="" rot_y="" rot_z=""></attitude>
          <label text=""></label>
        </updater>
        <cameraoffset>
          <translation trans_x="0.0" trans_y="0.0" trans_z="0.0"></translation>
          <rotation rot_x="0.0" rot_y="0.0" rot_z="0.0"></rotation>
        </cameraoffset>
        <geometry filename="../models/yourModel.flt">
          <offset rot_x="0.0" rot_y="0.0" rot_z="0.0"></offset>
          <scalefactor scale_x="1.0" scale_y="1.0" scale_z="1.0"></scalefactor>
        </geometry>
      </model>
      <trackmodel id="2" updater_slot="TRACKING_ID"></trackmodel> 
    </models>
    <datetime day="0" month="0" year="0" hour="12" minute="50"></datetime>
    <visibility range="50000" turbidity="2.2" ></visibility>
    <clouds>
      <cloudlayer slot="1" type="CUMULUS_CONGESTUS" enabled="yes" fadetime="15">
        <geometry baselength="50000" basewidth="50000" thickness="1600" baseHeight="1000" density="0.07"></geometry>
        <precipitation rate_mmPerHour_rain="5.0" rate_mmPerHour_drySnow="7.0" rate_mmPerHour_wetSnow="10.0" rate_mmPerHour_sleet="0.0"></precipitation>
      </cloudlayer>
    </clouds>
    <windlayer bottom="500.0" top="1100." speed="25.0" direction="90.0"></windlayer>
  </scenery>
</osgvisualconfiguration>
}}}

=== Module configuration ===

The "module" sections are parsed while instantiation the modules at the beginning of the startup process.
Each module configuration contains at least the name and the enabled/disabled status of the module. Further module parameters are optional and module dependent.
Some modules ignore the "enabled" attribute because they are mendatory in osgVisual. If a module is compiled and used in osgVisual but the correpsonding XML entry is not available in the configuration file, the modules will raise an error and remain unconfigured. The behavior of an unconfigured module is unpredictable and hence should be avoided.

The order of the <module> entries is arbitrary, you must only take care of its position in the the hierarchy in the XML file.
Example: 
{{{
#!xml
  <module name="distortion" enabled="yes">
    <distortion channelname="center"></distortion>
  </module>
}}}

A full list of all available modules with their XML configuration options is available [wiki:XmlModuleConfiguration here].

=== Scenery configuration ===

==== Terrain ====
It is possible to load one or more terrain databases with the following command:
{{{
#!xml
<terrain filename="relative/or/absolute/path/to/you/database1.ive" filename2="relative/or/absolute/path/to/you/database2.ive"></terrain>
}}}
You can add further databases with attributes beginning with "filename", follow by a number (e.g. filename3="")

==== Animation Path ====
You can load an animation path file and use the !OpenSceneGraph animation path camera manipulator to animate the camera movement.
It is possible to record camera movements and playback these movements with the animation path. It is also useful to start osgVisual with teh camera at a specific location.
{{{
#!xml
<animationpath filename="salzburg.path"></animationpath>
}}}

==== Models ====
Inside the XML "<models>" entry you can specify a list of models to displayed. It is possible to attach some of the model attributes to data slots to allow animation.
Example:
{{{
#!xml
<models>
 <model objectname="TestObject" trackingid="1" label="TestText!" dynamic="no">
  <position lat="47.8123" lon="12.94088" alt="700.0"></position>
  <attitude rot_x="0.0" rot_y="0.0" rot_z="0.0"></attitude>
  <updater>
   <position lat="" lon="" alt=""></position>
   <attitude rot_x="" rot_y="" rot_z=""></attitude>
   <label text=""></label>
  </updater>
  <cameraoffset>
   <translation trans_x="0.0" trans_y="0.0" trans_z="0.0"></translation>
   <rotation rot_x="0.0" rot_y="0.0" rot_z="0.0"></rotation>
  </cameraoffset>
  <geometry filename="../models/yourModel.flt">
   <offset rot_x="0.0" rot_y="0.0" rot_z="0.0"></offset>
   <scalefactor scale_x="1.0" scale_y="1.0" scale_z="1.0"></scalefactor>
  </geometry>
 </model>
 <model ...>
  ...
 </model>
 <model ...>
  ...
 </model>
</models>
}}}
A full description and explenation of the model configuration via XML is available [wiki:XmlModelConfiguration here].

You can track models based on their trackingID. It is possible to configure a slot which content is used to update the trackingId the camera should track:
{{{
#!xml
<trackmodel id="2" updater_slot="slotNameToUpdateTrackingId"></trackmodel> 
}}}
You should specify the <trackmodel ..> entry after the models, otherwise the model with the trackingId you want to track is not yet available and the tracking would be disabled.

==== Daytime ====
To configure the date and time of the scenery, use:
{{{
#!xml
<datetime day="" month="" year="" hour="12" minute="50"></datetime>
}}}
The basic setup is the system time of the IG. You cna override the systmetime by the XML entry. To skip overriding a value set a emtpy value.

==== Visibility ====
To configure the visibility settings, use:
{{{
#!xml
<visibility range="50000" turbidity="2.2" ></visibility>
}}}
You have to specify the visibility range as well as the turbidity. A turbidity of 2.2 represents a usual day.

==== Cloudlayer ====
To configure a cloudlayer, use:
{{{
#!xml
<clouds>
 <cloudlayer slot="1" type="CUMULUS_CONGESTUS" enabled="yes" fadetime="15">
  <geometry baselength="50000" basewidth="50000" thickness="1600" baseHeight="1000" density="0.07"></geometry>
  <precipitation rate_mmPerHour_rain="5.0" rate_mmPerHour_drySnow="7.0" rate_mmPerHour_wetSnow="10.0" rate_mmPerHour_sleet="0.0"></precipitation>
 </cloudlayer>
</clouds>
}}}
A full description and explenation of the cloudlayer configuration via XML is available [wiki:XmlCloudLayerConfiguration here].

==== Windlayer ====
To configure a windlayer, use:
{{{
#!xml
<windlayer bottom="500.0" top="1100." speed="25.0" direction="90.0"></windlayer>
}}}
You have to specify the bottom altitude and the top altitude of the wind volume, as well as the direction and the speed.