NaviTrack Tutorial:Creating module:Module structure
Contents
Three types of nodes
Sink nodes (XxxxSink.h, [XxxxSink.cxx])
Leaves in the graph and receive their data values from external sources, such as Polaris optraciking system, and send put the data into NaviTrack data flow graph.
Source nodes (XxxxSource.h, [XxxxSource.cxx])
Leaves to propagate their data values received from other nodes to external outputs.
Filter nodes (we don't use this in the tutorial)
Intermediate nodes and modify the values received from other nodes.
Two types of Modules
Normal module
Each node of modules has event handling functions to put, pull and process data, and these are called whenever corresponding events occure. Therefore, the timing of processing is detemined only by NaviTrack events.
Thread module
In some application, a module has to call certain procedures with its own timing, e.g. monitoring hardware, acquiring data from a device. For this purpose, NaviTrack allows us to create a module with threading capability. The structure of thread module will be described later.
Classes for normal module
Module class
This class is used to configure and manage source and sink nodes.
The following example class contains only essential functions for a NaviTrack module.
MyTutorialModule.h:
#ifndef __MY_TUTORIAL_MODULE_H__ #define __MY_TUTORIAL_MODULE_H__ #include <OpenTracker/OpenTracker.h> #include <OpenTracker/dllinclude.h> #include <OpenTracker/input/SPLModules.h> #include <OpenTracker/input/MyTutorialSink.h> #include <OpenTracker/input/MyTutorialSource.h> #include <string> namespace ot { class OPENTRACKER_API MyTutorialModule : public Module, public NodeFactory { public: // Constructor and destructor MyTutorialModule(); virtual ~MyTutorialModule(); Node* createNode( const std::string& name, ot::StringTable& attributes); void pushEvent(); void pullEvent() {}; void init(StringTable&, ConfigNode *); private: MyTutorialSink* sink; MyTutorialSource* source; friend class MyTutorialSink; friend class MyTutorialSource; }; OT_MODULE(MyTutorialModule); } // end of namespace ot #endif // __MY_TUTORIAL_MODULE_H__
init()
Function init() is called when the NaviTrack detects MyTutorialConfig in configuration section of the XML file, during starting up. You can put codes to initialize the module into this function.
void MyTutorialModule::init(StringTable& attributes, ConfigNode * localTree) { std::cout << "MyTutorialModule::init() is called." << std::endl; std::string strName=attributes.get("name"); std::cout << "MyTutorialModule::init(): attribute \"name\" is " << strName << std::endl; }
Also, you can get a parameter in configuration section of the XML file, by calling attributes.get(<parameter name>);
createNode()
When the NaviTrack detects either MyTutorialSource or MyTutorialSink in the XML file, function createNode is called. The code for this function might be as following:
ot::Node * MyTutorialModule::createNode( const std::string& name, ot::StringTable& attributes) { if( name.compare("MyTutorialSink") == 0 ) { std::string strName=attributes.get("name"); std::cout << "MyTutorialModule::createNode(): creating a MyTutorialSink node" << std::endl; std::cout << "MyTutorialModule::createNode(): attribute\"name\" is " << strName << std::endl; sink = new MyTutorialSink(); return sink; } if(name.compare("MyTutorialSource") == 0 ) { std::string strName=attributes.get("name"); std::cout << "MyTutorialModule::createNode(): creating a MyTutorialSource node" << std::endl; std::cout << "MyTutorialModule::createNode(): attribute\"name\" is " << strName << std::endl; source = new MyTutorialSource(strName); return source; } return NULL; }
Note that the class in above example can have only one sink node and one source node. But you can manage more than two nodes with same type, by using array or vector, since createNode is called each time the NaviTrack detects the corresponding type of node.
You can get any parameters specified for a certain node in XML configuration file, by calling attribute.get(<parameter name>) function, as shown in above code.
pushEvent() and pullEvent()
These are a sort of event handling function. These are called whenever a push or pull event occurs.
Sink class
This class is for a Sink node itself. The following example class contains only essential functions for a Sink node.
MyTutorialSink.h:
#ifndef __MY_TUTORIAL_SINK_H__ #define __MY_TUTORIAL_SINK_H__ #include <OpenTracker/OpenTracker.h> namespace ot { class MyTutorialSink : public ot::Node { public: MyTutorialSink(); ~MyTutorialSink(); public: virtual int isEventGenerator() {return 1;}; virtual void onEventGenerated(Event&, Node&); }; } // end of namespace ot #endif // end of __MY_TUTORIAL_SINK_H
isEventGenerator()
This function lets NaviTrack know whether the node is event generating node.
It returns 1, if the node has event generator.
onEventGenerated()
This is an event handler for generated event.
Source class
This class is a Source node itself. The following example class contains only essential functions for a Source node.
MyTutorialSource.h:
#ifndef __MY_TUTORIAL_SOURCE_H__ #define __MY_TUTORIAL_SOURCE_H__ #include <OpenTracker/OpenTracker.h> #include <string> namespace ot { class MyTutorialSource : public Node { private: public: std::string StationName; public: MyTutorialSource(std::string stationName) {}; virtual int isEventGenerator() {return 1;}; int changed; Event event; }; } // end of namespace ot #endif // __MYTUTORIAL_SOURCE_H__
isEventGenerator()
This is same as isEventGenerator() in Sink class.
Classes for thread module
Module class
In a thread module, the only difference from a normal module is a module class, where a thread is implemented.
MyTutorialThreadModule.h
#ifndef __MY_TUTORIAL_THREAD_MODULE_H__ #define __MY_TUTORIAL_THREAD_MODULE_H__ #include <OpenTracker/OpenTracker.h> #include <OpenTracker/dllinclude.h> #include <OpenTracker/input/SPLModules.h> #include <OpenTracker/input/MyTutorialThreadSink.h> #include <OpenTracker/input/MyTutorialThreadSource.h> #include <string> namespace ot { class OPENTRACKER_API MyTutorialThreadModule : public ThreadModule, public NodeFactory { private: int stop; protected: void run(); public: // Constructor and destructor MyTutorialThreadModule(); virtual ~MyTutorialThreadModule(); Node* createNode(const std::string& name, ot::StringTable& attributes); void pushEvent(); void pullEvent() {}; void init(StringTable&, ConfigNode *); virtual void start(); virtual void close(); private: MyTutorialThreadSink* sink; MyTutorialThreadSource* source; friend class MyTutorialThreadSink; friend class MyTutorialThreadSource; }; OT_MODULE(MyTutorialThreadModule); } // end of namespace ot #endif // __MY_TUTORIAL_THREAD_MODULE_H__
The differences from MyTutorialModule.h is :
- MyTutorialThreadModule inherits ThreadModule instead of Module class.
- init(): ThreadModule::init() needs to be called in init() for threading.
- run(): a main part of the thread.
- start(): a function to start the thread.
- close(): a function to stop the thread.
init()
void MyTutorialThreadModule::init(StringTable& attributes, ConfigNode * localTree) { std::cout << "MyTutorialThreadModule::init() is called." << std::endl; ThreadModule::init( attributes, localTree ); std::string strName=attributes.get("name"); std::cout << "MyTutorialThreadModule::init(): attribute \"name\" is " << strName << std::endl; }
run()
void MyTutorialThreadModule::run() { std::cout << "MyTutorialThreadModule::run() is called." << std::endl; while (stop == 0) { sleep(1); std::cout << "MyTutorialThreadModule::run(): looping." << std::endl; } }
start()
void MyTutorialThreadModule::start() { std::cout << "MyTutorialThreadModule::start() is called." << std::endl; stop = 0; if (isInitialized() && source != NULL) ThreadModule::start(); }
NOTE that start() function may be called even if the module is not specified in the configuration XML file. Therefore, you should explicitly check if the module is used before calling ThreadModule::start().
close()
void MyTutorialThreadModule::close() { std::cout << "MyTutorialThreadModule::close() is called." << std::endl; lock(); stop = 1; unlock(); }
Sink class
Same as MyTutorialSink.
Source class
Same as MyTutorialSource.
Go back to Creating module.