8.6 - Transforming Nodes Programmatically

Table of Contents

• 8.6.1 Node Transformation Components
• 8.6.2 Anatomy of a Meta File
  • 8.6.2.1 Anatomy of a Meta File
• 8.6.3 Adding New Transforms
• 8.6.4 Restrictions and Limitations

You can associate code with particular nodes in a scene graph using a configuration file called a meta file.

A meta file lets you change the behavior of an object without having to recompile code. This approach is used to animate windsocks, and flags on terrain and ships. For example, windsocks rotate based on wind direction and change state based on the speed of the wind. The parameters that control how the windsock responds are in its meta file.

Note

This feature is still experimental and can only be applied under particular circumstances on particular nodes in the scene graph.

8.6.1 Node Transformation Components

Programmatic node transformation depends on the interaction of a meta file, a properly annotated model, and supporting code.

• Meta file. A meta file is a JSON document that describes the matching criteria for a node (node name or annotation), the type of code object to be created when a match is found (for example, the code for rotating flags), and configuration information (for example, which wind speed corresponds to which switch state).

  You can associate meta files with objects and with terrains.

  To associate a meta file with an object, you add the metaFileName attribute to its model definition and specify the meta file.

  To associate a meta file with a terrain, place the meta file in the same directory as the medf file. The meta file must have the same name as the medf file, but with the extension meta. For example, for the terrain file ./data/Terrain/myTerrain/Geometry/mountain.medf, the meta file should be ./data/Terrain/myTerrain/Geometry/mountain.meta.

• Code. If you are creating a custom action, add your code to VR-Vantage and register it with the DtMetaFileManager. When a node matches the criteria in a meta file (by name or by annotation), an object of the type requested is created. In the VR-Vantage code, the objects are derived from DtTickable and added to the DtTickableManager so that they are executed every frame. However, it is not necessary to derive from DtTickable in every case.

• Model. For a meta file to work, it must match specific annotations or node names in the model.

8.6.2 Anatomy of a Meta File

A meta file uses a JSON format and parser to convert the document into data that VR-Vantage can use. As with all JSON files, braces ({}) are used to hold different name/value pairs, square brackets ([]) are used for arrays, and name:value is used for name/value pairs. VR-Vantage emits a warning message when there is a syntax error. It is usually easier to copy a working file and modify it than to write one from scratch.

Note

There are several JSON editors available online (such as https://www.jsoneditoronline.org/) or plugins for NotePad++ that color code the structure of the file and indicate any errors.

8.6.2.1 Anatomy of a Meta File

The following is an example meta file:

{
  "NodeFeatures": [
    {
      "Linkage": {
        "Comment": "Traversal will match based on node name or annotation",
        "NodeName": "sw1",
        "AnnotationName": ""
      },
      "FeatureData": [
        {
           "FeatureName": "WindSwitchPart",
           "Comment1": "Change state based on wind speed (km/h).",
           "Comment2": "0-5 km/h is for switch state 0, 5-10 is for state 1, ...",
           "WindSpeed": [
             5,
             10,
             15
           ],
           "WindState": [
             0,
             1,
             2
           ]
        }
      ]
    }
  ]
}

The keywords in the example meta file are as follows:

• NodeFeatures. Indicates an array of Linkage and FeatureData data.

• Linkage. The Linkage specifies which node attributes will be used to search for matching nodes. In the example, the Linkage component has three members: Comment, NodeName, and AnnotationName.

  • Comment. JSON files do not have a unique syntax for comments, so you have to add them as a field/value pair.
  • NodeName. The name of the node to use for matching. In the example, if 5 nodes had a node name of "sw1", then all 5 would match and have a link to code being executed in VR-Vantage.
  • AnnotationName. An annotation to use for matching (also called a node description in OpenSceneGraph). In VR-Vantage models, annotations are normally of the form '@dis switch 7234'. (For more information about node annotations, please see The WRM Specification (DIS Notes), in VR-Vantage Users Guide . These types of annotations can be put into the AnnotationName field as well as custom annotations such as 'flag switch' or whatever terms are convenient to use.

• FeatureData. Specifies the object to create in the code when there is a match with the NodeName or AnnotationName. It consists of the FeatureName and whatever extra parameters are needed to specify the state of the created object.
  • FeatureName. This name is used to match against classes registered with the DtMetaObjectFactory.
  • WindSpeed, WindState. Examples of parameters. Custom parameters would replace WindSpeed and WindState and would be read with custom code.

8.6.3 Adding New Transforms

If you want to add your own programmatic transforms, you must:

1. Edit the models that you want to change programmatically. To do this you need an editing tool such as Presagis Creator.

2. Create a new meta file. Specify the node names or annotations to match. Specify the feature name that matches the name of the meta object in the code. Specify an additional parameters for the object.

3. Write the code. DtWindSwitchTickable and DtShipFlagDirTickable are examples of custom meta file updating and configuration code. The new class must be derived from DtVirtualBaseClass. The examples that have been implemented in VR-Vantage inherit from DtTickable and DtVirtualBaseClass. However, the only required class to derive from is the DtVirtualBaseClass.
4. Create a creator for the new object. See DtMetaObjectCreator.h. The creator class should derive from DtMetaObjectCreator.

5. Register your object with the DtMetaObjectFactory. See examples in vrvOsg.cxx. The following code shows how to register DtWindSwitchTickable with the DtMetaObjectFactory:

   DtMetaObjectFactory& mof = DtMetaObjectFactory::instance(de);
            
   mof.addCreator(DtWindSwitchTickable::theWindSwitchFeatureName, new DtWindSwitchTickableCreator());

   The variable, theWindSwitchFeatureName, matches the FeatureName in the meta file. This lets VR-Vantage know what type of object to create.

6. For objects that have model definitions, add a metaFileName entry to the model definition. For items such as terrain patches, which do not have model definitions, put the meta file in the same directory as the medf file for the terrain.

8.6.4 Restrictions and Limitations

The following are restrictions and limitations apply to prgrammatically transforming nodes:

• Only switch, multiswitch, and doftransform node types are supported.
• Only classes derived from DtTickable have been created so far. Custom classes must inherit from DtVirtualBaseClass and multiply inherit from whatever other classes are needed to process the object.
• Currently, DtTerrainPatch and DtOsgArticulatedModels are the only types of objects that support meta files.
• The entity and watercraft have metaFileName entries. Other types will require changing the schema for those types to add a field called 'metaFileName' which is of type FileName.
• Instancing is supported for models using the class DtOsgArticulatedModel (that is, models that have parts or switches that can be changed).

It is easier to use similar orientations and facing directions for multiple nodes (ex. multiple flags on terrain). Different orientations (ex. A circle of flags oriented in different directions) would need more sophisticated code to undo the local transforms and put the flags into a common space for calculating wind direction.

For an example of how to use meta files and code, see Example of Transforming Nodes Programmatically.

[<< Making OpenGL Calls from OSG Drawables] [Home] [Top of Page] [Example of Transforming Nodes Programmatically >>]