superclass for specific MIRCOBIRD tracking Devices More...

#include <mitkMicroBirdTrackingDevice.h>

Inheritance diagram for mitk::MicroBirdTrackingDevice:

Collaboration diagram for mitk::MicroBirdTrackingDevice:

Public Types
typedef MicroBirdTrackingDevice	Self
typedef TrackingDevice	Superclass
typedef itk::SmartPointer< Self >	Pointer
typedef itk::SmartPointer < const Self >	ConstPointer
Public Member Functions
virtual const char *	GetClassName () const
virtual void	SetType (TrackingDeviceType _arg)
	Set the type of the microBird Tracking Device because it can not yet handle this itself.
virtual bool	OpenConnection ()
	Builds up the connection (loads tools, initializes and enables them)
virtual bool	CloseConnection ()
	Closes the connection.
virtual bool	StartTracking ()
	Start the tracking.
virtual bool	StopTracking ()
	here we use the superclass method.
virtual TrackingTool *	GetTool (unsigned int toolNumber)
	returns a tracking tool that contains positional information about one of the sensors
virtual unsigned int	GetToolCount () const
	returns a the number of attached sensors
virtual const char *	GetErrorMessage () const
	returns description of most recent error.
Static Public Member Functions
static Pointer	New ()
Protected Types
typedef InternalTrackingTool	ToolType
typedef std::vector < ToolType::Pointer >	ToolContainerType
Protected Member Functions
void	HandleError (int errorCode)
bool	CompareError (int errorCode, int errorConstant)
	MicroBirdTrackingDevice ()
virtual	~MicroBirdTrackingDevice ()
ToolType *	GetMicroBirdTool (unsigned int toolNumber)
	returns a tracking tool that contains positional information about one of the sensors
virtual void	InvalidateAll ()
	invalidates all tools (on stoptracking, closeconnection)
bool	SwitchTransmitter (bool switchOn)
	Switches the transmitter on resp. off.
virtual void	TrackTools ()
	tracks the position and orientation of all tools until StopTracking() is called.
virtual void	SetErrorMessage (const char *_arg)
	set error message
Static Protected Member Functions
static ITK_THREAD_RETURN_TYPE	ThreadStartTracking (void *data)
	Helper function, because the itk::MultiThreader can only start a new thread with a static member function.
Protected Attributes
itk::FastMutexLock::Pointer	m_ToolsMutex
ToolContainerType	m_Tools
std::string	m_ErrorMessage
	current error message
itk::MultiThreader::Pointer	m_MultiThreader
int	m_ThreadID
DOUBLE_POSITION_QUATERNION_TIME_Q_RECORD	record
DOUBLE_POSITION_QUATERNION_TIME_Q_RECORD *	pRecord
	One tracking data record (quaternion orientation format)
SYSTEM_CONFIGURATION	m_SystemConfig
	The system configuration - used to specify its use.
SENSOR_CONFIGURATION *	m_SensorConfig
	The sensor configuration - used to get and set the sensor properties.
TRANSMITTER_CONFIGURATION *	m_TransmitterConfig
	The transmitter configuration - used to get and set the transmitter properties.
BOOL	m_metric
	Specifies whether metric measurement is used.
double	m_measurementRate
	Specifies the measurement rate - default set to maximum.
double	m_pl
	Specifies the power line frequency (Europe 50Hz, USA 60Hz)
bool	m_agcModeBoth
	AGC (automatic gain control) mode flag.
AGC_MODE_TYPE	m_agc

Detailed Description

superclass for specific MIRCOBIRD tracking Devices

Documentation This class connects to a Ascension Microbird tracking device. You can not add tools manually. All connected tools are discovered during OpenConnection() and added automatically. Retrieve them with GetTool(unsigned int toolNumber) and GetToolCount() after a call to OpenConnection().

Definition at line 34 of file mitkMicroBirdTrackingDevice.h.

Member Typedef Documentation

typedef itk::SmartPointer<const Self> mitk::MicroBirdTrackingDevice::ConstPointer

Reimplemented from mitk::TrackingDevice.

Definition at line 24 of file mitkMicroBirdTrackingDevice.h.

typedef itk::SmartPointer<Self> mitk::MicroBirdTrackingDevice::Pointer

Reimplemented from mitk::TrackingDevice.

Definition at line 24 of file mitkMicroBirdTrackingDevice.h.

typedef MicroBirdTrackingDevice mitk::MicroBirdTrackingDevice::Self

Reimplemented from mitk::TrackingDevice.

Definition at line 24 of file mitkMicroBirdTrackingDevice.h.

typedef TrackingDevice mitk::MicroBirdTrackingDevice::Superclass

Reimplemented from mitk::TrackingDevice.

Definition at line 24 of file mitkMicroBirdTrackingDevice.h.

typedef std::vector<ToolType::Pointer> mitk::MicroBirdTrackingDevice::ToolContainerType [protected]

Definition at line 74 of file mitkMicroBirdTrackingDevice.h.

typedef InternalTrackingTool mitk::MicroBirdTrackingDevice::ToolType [protected]

Definition at line 73 of file mitkMicroBirdTrackingDevice.h.

Constructor & Destructor Documentation

mitk::MicroBirdTrackingDevice::MicroBirdTrackingDevice ( ) [protected]

Definition at line 25 of file mitkMicroBirdTrackingDevice.cpp.

References mitk::AscensionMicroBird, m_MultiThreader, m_Tools, m_ToolsMutex, mitk::TrackingDevice::m_Type, New(), pRecord, and record.

                                                     : TrackingDevice(),
m_ErrorMessage(""),
m_ThreadID(0),
m_pl(50), // 50 Hz for Europe
m_metric(true),
m_agcModeBoth(true),
m_measurementRate(68.3), // 68.3 for mid-range transmitter, 40.5 for flat transmitter
m_TransmitterConfig(NULL),
m_SensorConfig(NULL)
{
  // Flat transmitter needs measurement rate: 40.5
  // Mid-range transmitter needs measurement rate: 68.3;

  // Set the tracker type
  this->m_Type = AscensionMicroBird;

  // Clear tools vector
  m_Tools.clear();

  // Create tools vector mutex
  m_ToolsMutex = itk::FastMutexLock::New();

  // Prepare multi-threading
  m_MultiThreader = itk::MultiThreader::New();

  // Pointer to record member variable
  pRecord = &record;
}

mitk::MicroBirdTrackingDevice::~MicroBirdTrackingDevice ( ) [protected, virtual]

Definition at line 55 of file mitkMicroBirdTrackingDevice.cpp.

{
  if (m_MultiThreader)
    m_MultiThreader->TerminateThread(m_ThreadID);
  m_MultiThreader = NULL;
  if (m_ToolsMutex)
    m_ToolsMutex->Unlock();
  m_ToolsMutex = NULL;

  this->StopTracking();
  this->CloseConnection();

  if (m_TransmitterConfig != NULL)
    delete [] m_TransmitterConfig;
  if (m_SensorConfig != NULL)
    delete [] m_SensorConfig;

  //\TODO: Do we need to clean up the pointers to PCIBird data like DOUBLE_POSITION_QUATERNION_TIME_Q_RECORD?
}

Member Function Documentation

bool mitk::MicroBirdTrackingDevice::CloseConnection ( ) [virtual]

Closes the connection.

Documentation

Implements mitk::TrackingDevice.

Definition at line 257 of file mitkMicroBirdTrackingDevice.cpp.

{
  SwitchTransmitter(false); // Switch off the transmitter

  int errorCode = CloseBIRDSystem(); // Close connection. This function can take a few seconds

  // Error checking
  if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
    HandleError(errorCode);

  // Delete configuration
  if (m_TransmitterConfig != NULL)
  {
    delete [] m_TransmitterConfig;
    m_TransmitterConfig = NULL;
  }
  if (m_SensorConfig != NULL)
  {
    delete [] m_SensorConfig;
    m_SensorConfig = NULL;
  }
  // Change mode and release mutex
  this->SetState(Setup);

  // Clear error message
  this->SetErrorMessage("");

  return true; 
}

bool mitk::MicroBirdTrackingDevice::CompareError	(	int	errorCode,
		int	errorConstant
	)		`[protected]`

Definition at line 452 of file mitkMicroBirdTrackingDevice.cpp.

{
  return ((errorCode & 0xffff) == errorConstant);
}

virtual const char* mitk::MicroBirdTrackingDevice::GetClassName ( ) const [virtual]

Reimplemented from mitk::TrackingDevice.

virtual const char* mitk::MicroBirdTrackingDevice::GetErrorMessage ( ) const [virtual]

returns description of most recent error.

Documentation

Reimplemented from mitk::TrackingDevice.

mitk::MicroBirdTrackingDevice::ToolType * mitk::MicroBirdTrackingDevice::GetMicroBirdTool ( unsigned int toolNumber ) [protected]

returns a tracking tool that contains positional information about one of the sensors

Documentation

Definition at line 432 of file mitkMicroBirdTrackingDevice.cpp.

References QuadProgPP::t().

{
  ToolType* t = NULL;

  MutexLockHolder toolsMutexLockHolder(*m_ToolsMutex); // lock and unlock the mutex
  if (toolNumber < m_Tools.size())
  {
    t = m_Tools.at(toolNumber);
  }  
  return t;
}

mitk::TrackingTool * mitk::MicroBirdTrackingDevice::GetTool ( unsigned int toolNumber ) [virtual]

returns a tracking tool that contains positional information about one of the sensors

Documentation

Definition at line 426 of file mitkMicroBirdTrackingDevice.cpp.

{
  return static_cast<TrackingTool*>(GetMicroBirdTool(toolNumber));
}

unsigned int mitk::MicroBirdTrackingDevice::GetToolCount ( ) const [virtual]

returns a the number of attached sensors

Documentation

Implements mitk::TrackingDevice.

Definition at line 445 of file mitkMicroBirdTrackingDevice.cpp.

{
  MutexLockHolder toolsMutexLockHolder(*m_ToolsMutex); // lock and unlock the mutex
  return m_Tools.size();
}

void mitk::MicroBirdTrackingDevice::HandleError ( int errorCode ) [protected]

Definition at line 458 of file mitkMicroBirdTrackingDevice.cpp.

{
  char buffer[1024];
  char* pBuffer = &buffer[0];

  while(!CompareError(errorCode, BIRD_ERROR_SUCCESS))
  {
    // Print error number on screen
    //cout << "MicroBIRD Error Code: " << errorCode << endl;
    // Print error message on screen
    errorCode = GetErrorText(errorCode, pBuffer, sizeof(buffer), SIMPLE_MESSAGE);
    this->SetErrorMessage(buffer);
  }
}

void mitk::MicroBirdTrackingDevice::InvalidateAll ( ) [protected, virtual]

invalidates all tools (on stoptracking, closeconnection)

Definition at line 475 of file mitkMicroBirdTrackingDevice.cpp.

{
  MutexLockHolder toolsMutexLockHolder(*m_ToolsMutex); // lock and unlock the mutex
  for (ToolContainerType::iterator iterator = m_Tools.begin(); iterator != m_Tools.end(); ++iterator)
    (*iterator)->SetDataValid(false);
}

static Pointer mitk::MicroBirdTrackingDevice::New ( ) [static]

Referenced by QmitkIGTExampleView::ConfigureTrackingDevice(), and MicroBirdTrackingDevice().

bool mitk::MicroBirdTrackingDevice::OpenConnection ( ) [virtual]

Builds up the connection (loads tools, initializes and enables them)

Documentation

Implements mitk::TrackingDevice.

Definition at line 76 of file mitkMicroBirdTrackingDevice.cpp.

{
  /* Check whether in setup mode */
  if (this->GetState() != Setup)
  {
    this->SetErrorMessage("Can only try to open the connection if in setup mode");
    return false;
  }

  int errorCode; // Holds error code

  /* Initialize the PCIBIRD driver and DLL */
  errorCode = InitializeBIRDSystem(); // this function can take a few seconds
  if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
  {
    HandleError(errorCode);
    return false;
  }
  // Serial numbers could be compared to known ones for some simple
  //    parameters sanity check (measurement frequency etc.)

  /* Get system configuration */
  errorCode = GetBIRDSystemConfiguration(&m_SystemConfig);
  if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
  {
    HandleError(errorCode);
    return false;
  }

  /* use metric measurements in mm */
  errorCode = SetSystemParameter(METRIC, &m_metric, sizeof(m_metric)); 
  if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
  {
    HandleError(errorCode);
    return false;
  }

  /* Set the measurement rate to m_measurementRate */
  if ((m_measurementRate > 30) && (m_measurementRate < 80))
  {
    errorCode = SetSystemParameter(MEASUREMENT_RATE, &m_measurementRate, sizeof(m_measurementRate)); 
    if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
    {
      HandleError(errorCode);
      return false;
    }
  }

  /* Set power line frequency */
  if ((m_pl >= 50) && (m_pl <= 60))
  {
    errorCode = SetSystemParameter(POWER_LINE_FREQUENCY, &m_pl, sizeof(m_pl));
    if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
    {
      HandleError(errorCode);
      return false;
    }
  }

  /* Set AGC mode */
  m_agc = m_agcModeBoth ? TRANSMITTER_AND_SENSOR_AGC : SENSOR_AGC_ONLY;
  errorCode = SetSystemParameter(AGC_MODE, &m_agc, sizeof(m_agc));
  if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
  {
    HandleError(errorCode);
    return false;
  }

  /* Get system configuration */
  errorCode = GetBIRDSystemConfiguration(&m_SystemConfig);
  if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
  {
    HandleError(errorCode);
    return false;
  }

  /* Get sensor information */
  m_SensorConfig = new SENSOR_CONFIGURATION[m_SystemConfig.numberSensors];
  for (int i = 0; i < m_SystemConfig.numberSensors; i++)
  {
    errorCode = GetSensorConfiguration(i, &(m_SensorConfig[i]));
    if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
    {
      HandleError(errorCode);
    }

    /* Initialize the quality parameter structure */
    QUALITY_PARAMETERS qualityParameters; // = { 164, 0, 32, 3072 };
    GetSensorParameter(i, QUALITY, &qualityParameters, sizeof(qualityParameters));

    /* Set data format to matrix format */
    //DATA_FORMAT_TYPE tempBuffer = DOUBLE_POSITION_MATRIX_TIME_Q;
    /* Set data format to quaternion format */
    DATA_FORMAT_TYPE tempBuffer = DOUBLE_POSITION_QUATERNION_TIME_Q;

    /* Set data format for sensor */
    DATA_FORMAT_TYPE *pTempBuffer = &tempBuffer;
    errorCode = SetSensorParameter(i, DATA_FORMAT, pTempBuffer, sizeof(tempBuffer));  
    if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
    {
      HandleError(errorCode);
    }
  }

  /* Initialize tools vector */
  {
    MutexLockHolder(*m_ToolsMutex);
    for (int i = 0; i < m_SystemConfig.numberSensors; i++)
    {
      if (m_SensorConfig[i].attached)
        m_Tools.push_back(ToolType::New());

    }
  }

  /* Get transmitter configuration */
  m_TransmitterConfig = new TRANSMITTER_CONFIGURATION[m_SystemConfig.numberTransmitters];
  for (int i = 0; i < m_SystemConfig.numberTransmitters; i++)
  {
    errorCode = GetTransmitterConfiguration(i, &(m_TransmitterConfig[i]));
    if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
    {
      HandleError(errorCode);
    }
  }

  /* Switch off transmitter */
  SwitchTransmitter(true);
  SwitchTransmitter(false);

  // @todo : set up error scaling?

  /* finish  - now all tools should be added, initialized and enabled, so that tracking can be started */
  this->SetState(Ready);
  this->SetErrorMessage("");
  return true; // Return success
}

virtual void mitk::MicroBirdTrackingDevice::SetErrorMessage ( const char * _arg ) [protected, virtual]

set error message

Reimplemented from mitk::TrackingDevice.

virtual void mitk::MicroBirdTrackingDevice::SetType ( TrackingDeviceType _arg ) [virtual]

Set the type of the microBird Tracking Device because it can not yet handle this itself.

Documentation

Reimplemented from mitk::TrackingDevice.

bool mitk::MicroBirdTrackingDevice::StartTracking ( ) [virtual]

Start the tracking.

Documentation A new thread is created, which reads the position and orientation information of each tool and stores them inside the tools.

Implements mitk::TrackingDevice.

Definition at line 313 of file mitkMicroBirdTrackingDevice.cpp.

References mitk::TimeStamp::GetInstance(), and mitk::TimeStamp::Start().

{
  if (this->GetState() != Ready)
    return false;

  this->SetState(Tracking);

  /* Switch on transmitter */
  SwitchTransmitter(true);

  /* Update the local copy of m_StopTracking */
  this->m_StopTrackingMutex->Lock();
  this->m_StopTracking = false;
  this->m_StopTrackingMutex->Unlock();

  m_TrackingFinishedMutex->Unlock(); // transfer the execution rights to tracking thread 
  m_ThreadID = m_MultiThreader->SpawnThread(this->ThreadStartTracking, this); // start a new thread that executes the TrackTools() method
  mitk::TimeStamp::GetInstance()->Start(this);
  return true;
}

bool mitk::MicroBirdTrackingDevice::StopTracking ( ) [virtual]

here we use the superclass method.

Documentation

Reimplemented from mitk::TrackingDevice.

Definition at line 303 of file mitkMicroBirdTrackingDevice.cpp.

References mitk::TrackingDevice::StopTracking().

{
  TrackingDevice::StopTracking(); // Call superclass method

  SwitchTransmitter(false); // Switch off transmitter
  InvalidateAll(); // Invalidate all tools
  return true;   // \todo : think about return value
}

bool mitk::MicroBirdTrackingDevice::SwitchTransmitter ( bool switchOn ) [protected]

Switches the transmitter on resp. off.

Definition at line 216 of file mitkMicroBirdTrackingDevice.cpp.

{ 
  if (switchOn)
  {
    /* Search for the first attached transmitter and turn it on */
    for (short id = 0; id < m_SystemConfig.numberTransmitters; id++)
    {
      if (m_TransmitterConfig[id].attached)
      {
        // Transmitter selection is a system function.
        // Using the SELECT_TRANSMITTER parameter we send the id of the
        // transmitter that we want to run with the SetSystemParameter() call
        int errorCode = SetSystemParameter(SELECT_TRANSMITTER, &id, sizeof(id));
        if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
        {
          HandleError(errorCode);
          return false;
        }
        else 
          return true; //break; // \TODO: Stop after the first attached transmitter was turned off?
      }
    }
  }
  else
  {
    /* Transmitter selection is a system function, Note: a selector of -1 switches off the current transmitter */
    short TRANSMITTER_OFF = -1;
    int errorCode = SetSystemParameter(SELECT_TRANSMITTER, &TRANSMITTER_OFF, sizeof(TRANSMITTER_OFF));
    if (!CompareError(errorCode, BIRD_ERROR_SUCCESS))
    {
      HandleError(errorCode);
      return false;
    }
    else
      return true;
  }
  // Return success
  return true;
}

ITK_THREAD_RETURN_TYPE mitk::MicroBirdTrackingDevice::ThreadStartTracking ( void * data ) [static, protected]

Helper function, because the itk::MultiThreader can only start a new thread with a static member function.

Definition at line 288 of file mitkMicroBirdTrackingDevice.cpp.

References TrackTools().

{
  /* extract this pointer from Thread Info structure */
  struct itk::MultiThreader::ThreadInfoStruct * pInfo = (struct itk::MultiThreader::ThreadInfoStruct*)pInfoStruct;
  if ((pInfo == NULL) || (pInfo->UserData == NULL))
    return ITK_THREAD_RETURN_VALUE;

  MicroBirdTrackingDevice *trackingDevice = (MicroBirdTrackingDevice*)pInfo->UserData;
  if (trackingDevice != NULL)
    trackingDevice->TrackTools();             // call TrackTools() from the original object

  return ITK_THREAD_RETURN_VALUE;
}

void mitk::MicroBirdTrackingDevice::TrackTools ( ) [protected, virtual]

tracks the position and orientation of all tools until StopTracking() is called.

Documentation This function should only be executed by a new thread (through StartTracking() and ThreadStartTracking())

Get tool (current sensor)

Definition at line 335 of file mitkMicroBirdTrackingDevice.cpp.

References mitk::InternalTrackingTool::SetDataValid(), mitk::InternalTrackingTool::SetOrientation(), mitk::InternalTrackingTool::SetPosition(), and mitk::InternalTrackingTool::SetTrackingError().

Referenced by ThreadStartTracking().

{
  if (this->GetState() != Tracking)
    return;

  /* Frequency configuration */
  double updateRate = 1000.0 / m_SystemConfig.measurementRate;
  double measurementDuration = 0.0;


  // lock the TrackingFinishedMutex to signal that the execution rights
  //   are now transfered to the tracking thread
  MutexLockHolder trackingFinishedLockHolder(*m_TrackingFinishedMutex); // keep lock until end of scope

  // Because m_StopTracking is used by two threads, access has to be guarded
  //   by a mutex. To minimize thread locking, a local copy is used here 
  bool localStopTracking;

  /* update the local copy of m_StopTracking */
  this->m_StopTrackingMutex->Lock();
  localStopTracking = this->m_StopTracking;
  this->m_StopTrackingMutex->Unlock();

  /* Tracking loop */
  while ((this->GetState() == Tracking) && (localStopTracking == false))
  {
    int errorCode;
    unsigned int nOfAttachedSensors = 0;
    double timeStamp = 0.0;   
    int toolNumber = 0; // Numbers for attached sensors only

    for (int sensorID = 0; sensorID < m_SystemConfig.numberSensors; sensorID++) // for each sensor grep data
    {
      if (!m_SensorConfig[sensorID].attached)
        continue;

      // sensor attached so get record
      errorCode = GetAsynchronousRecord(sensorID, pRecord, sizeof(record));
      if (CompareError(errorCode, BIRD_ERROR_SUCCESS))      
      { // On SUCCESS, parse sensor information
        nOfAttachedSensors++;       
        timeStamp += record.time; // Get timestamp from record
        ToolType* tool = GetMicroBirdTool(toolNumber); 
        if (tool != NULL)
        {
          tool->SetTrackingError(record.quality); // Set tracking error (quality) from record
          mitk::Point3D position;
          position[0] = record.x;
          position[1] = record.y;
          position[2] = record.z;
          tool->SetPosition(position);  // Set position
          mitk::Quaternion orientation(record.q[1], record.q[2], record.q[3],record.q[0]);
          tool->SetOrientation(orientation); // Set orientation as quaternion \todo : verify quaternion order q(r,x,y,z)
          tool->SetDataValid(true); // Set data state to valid
        }        
        toolNumber++; // Increment tool number
      }  
      else
      { // ERROR while reading sensor information
        HandleError(errorCode);
      }      
    }

    // Average timestamp: timeStamp/nOfAttachedSensors

    // Compute sleep time
    double sleepTime = updateRate - measurementDuration;
    // Sleep
    if (sleepTime > 0.0 && sleepTime < 500.0)
    {
      // Note: we only have to approximately sleep one measurement cycle,
      //    since the tracker keeps track of the measurement rate itself
      itksys::SystemTools::Delay(sleepTime)
      //Sleep(static_cast<DWORD>(sleepTime));
    }

    // Update the local copy of m_StopTracking
    this->m_StopTrackingMutex->Lock();  
    localStopTracking = m_StopTracking;
    this->m_StopTrackingMutex->Unlock();
  }

  // @bug (#1813) : maybe we need to check for localStopTracking=true here?
  //    m_StopTracking should only ever be updated by StopTracking(), so
  //    maybe we should not unlock a mutex that nobody is waiting for?

  return; // returning from this function (and ThreadStartTracking()) this will end the thread
}