Class representing a tracking device which generates random positions / orientations. No hardware is needed for tracking device. More...

#include <mitkVirtualTrackingDevice.h>

Inheritance diagram for mitk::VirtualTrackingDevice:

[legend]

Collaboration diagram for mitk::VirtualTrackingDevice:

[legend]

List of all members.

Public Types
typedef VirtualTrackingDevice	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	SetRefreshRate (unsigned int _arg)
	Sets the refresh rate of the virtual tracking device in ms.
virtual unsigned int	GetRefreshRate () const
	Returns the refresh rate in ms.
virtual bool	StartTracking ()
	Starts the tracking.
virtual bool	StopTracking ()
	Stops the tracking.
virtual bool	OpenConnection ()
	Opens the connection to the device. This have to be done before the tracking is started.
virtual bool	CloseConnection ()
	Closes the connection and clears all resources.
virtual unsigned int	GetToolCount () const
TrackingTool *	GetTool (unsigned int toolNumber) const
TrackingTool *	AddTool (const char *toolName)
	Adds a tool to the tracking device.
virtual void	SetBounds (mitk::ScalarType data[])
	Set the tracking volume bounds.
const mitk::ScalarType *	GetBounds () const
	return the tracking volume bounds
mitk::ScalarType	GetSplineChordLength (unsigned int idx)
	return the approximate length of the spline for tool with index idx in millimeter
void	SetToolSpeed (unsigned int idx, mitk::ScalarType roundsPerSecond)
	sets the speed of the tool idx in rounds per second
Static Public Member Functions
static Pointer	New ()
Protected Types
typedef mitk::VirtualTrackingTool::SplineType::ControlPointType	ControlPointType
typedef std::vector < VirtualTrackingTool::Pointer >	ToolContainer
	container type for tracking tools
Protected Member Functions
	VirtualTrackingDevice ()
	~VirtualTrackingDevice ()
void	TrackTools ()
	This method tracks tools as long as the variable m_Mode is set to "Tracking". Tracking tools means generating random numbers for the tool position and orientation.
void	InitializeSpline (mitk::VirtualTrackingTool *t)
	initializes the spline path of the tool t with random control points inside the current tracking volume
ControlPointType	GetRandomPoint ()
	returns a random position inside the tracking volume (defined by m_Bounds)
mitk::VirtualTrackingTool *	GetInternalTool (unsigned int idx)
Static Protected Member Functions
static ITK_THREAD_RETURN_TYPE	ThreadStartTracking (void *data)
	static start method for tracking thread
Protected Attributes
ToolContainer	m_AllTools
	container for all tracking tools
itk::FastMutexLock::Pointer	m_ToolsMutex
	mutex for coordinated access of tool container
itk::MultiThreader::Pointer	m_MultiThreader
	MultiThreader that starts continuous tracking update.
int	m_ThreadID
unsigned int	m_RefreshRate
	refresh rate of the internal tracking thread in milliseconds (NOT refreshs per second!)
unsigned int	m_NumberOfControlPoints
	number of control points for the random path generation
mitk::ScalarType	m_Bounds [6]
	bounding box of the tracking volume stored as {xMin, xMax, yMin, yMax, zMin, zMax}

Detailed Description

Class representing a tracking device which generates random positions / orientations. No hardware is needed for tracking device.

Documentation This TrackingDevice class does not interface with a physical tracking device. It simulates a tracking device by moving the tools on a randomly generated spline path.

Definition at line 40 of file mitkVirtualTrackingDevice.h.

Member Typedef Documentation

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

Reimplemented from mitk::TrackingDevice.

Definition at line 44 of file mitkVirtualTrackingDevice.h.

typedef mitk::VirtualTrackingTool::SplineType::ControlPointType mitk::VirtualTrackingDevice::ControlPointType [protected]

Definition at line 170 of file mitkVirtualTrackingDevice.h.

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

Reimplemented from mitk::TrackingDevice.

Definition at line 44 of file mitkVirtualTrackingDevice.h.

typedef VirtualTrackingDevice mitk::VirtualTrackingDevice::Self

Reimplemented from mitk::TrackingDevice.

Definition at line 44 of file mitkVirtualTrackingDevice.h.

typedef TrackingDevice mitk::VirtualTrackingDevice::Superclass

Reimplemented from mitk::TrackingDevice.

Definition at line 44 of file mitkVirtualTrackingDevice.h.

typedef std::vector<VirtualTrackingTool::Pointer> mitk::VirtualTrackingDevice::ToolContainer [protected]

container type for tracking tools

Definition at line 175 of file mitkVirtualTrackingDevice.h.

Constructor & Destructor Documentation

mitk::VirtualTrackingDevice::VirtualTrackingDevice ( ) [protected]

Definition at line 30 of file mitkVirtualTrackingDevice.cpp.

References m_Bounds, m_ToolsMutex, mitk::TrackingDevice::m_Type, New(), and mitk::VirtualTracker.

                                                 : mitk::TrackingDevice(), 
  m_AllTools(), m_ToolsMutex(NULL), m_MultiThreader(NULL), m_ThreadID(-1), m_RefreshRate(100), m_NumberOfControlPoints(20)
{ 
  m_Type = VirtualTracker;
  m_Bounds[0] = m_Bounds[2] = m_Bounds[4] = -400.0;  // initialize bounds to -400 ... +400 (mm) cube
  m_Bounds[1] = m_Bounds[3] = m_Bounds[5] =  400.0;
  m_ToolsMutex = itk::FastMutexLock::New();
}

mitk::VirtualTrackingDevice::~VirtualTrackingDevice ( ) [protected]

Definition at line 40 of file mitkVirtualTrackingDevice.cpp.

{
  if (this->GetState() == Tracking)
  {
    this->StopTracking();
  }
  if (this->GetState() == Ready)
  {
    this->CloseConnection();
  }
  /* cleanup tracking thread */
  if (m_MultiThreader.IsNotNull() && (m_ThreadID != -1))
  {
    m_MultiThreader->TerminateThread(m_ThreadID);
    m_MultiThreader = NULL;
  }  
  m_AllTools.clear();
}

Member Function Documentation

mitk::TrackingTool * mitk::VirtualTrackingDevice::AddTool ( const char * toolName )

Adds a tool to the tracking device.

The tool will have a random path on which it will move around. The path is created with a spline function and random control points inside the tracking volume.

Parameters:

tool	The tool which will be added.

Returns:: Returns true if the tool has been added, false otherwise.

Definition at line 60 of file mitkVirtualTrackingDevice.cpp.

References mitk::VirtualTrackingTool::New(), and QuadProgPP::t().

{
  //if (this->GetState() == Tracking)
  //{
  //  return NULL;
  //}
  mitk::VirtualTrackingTool::Pointer t = mitk::VirtualTrackingTool::New();
  t->SetToolName(toolName);
  t->SetVelocity(0.1);
  this->InitializeSpline(t);
  MutexLockHolder lock(*m_ToolsMutex); // lock and unlock the mutex
  m_AllTools.push_back(t);
  return t;
}

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

Closes the connection and clears all resources.

Implements mitk::TrackingDevice.

Definition at line 181 of file mitkVirtualTrackingDevice.cpp.

{
  bool returnValue = true; 
  if(this->GetState() == Setup)
    return true;

  this->SetState(Setup);
  return returnValue;
}

const mitk::ScalarType* mitk::VirtualTrackingDevice::GetBounds ( ) const [inline]

return the tracking volume bounds

This will return the tracking volume as an axis aligned bounding box defined by the six bounds values xMin, xMax, yMin, yMax, zMin, zMax

Definition at line 129 of file mitkVirtualTrackingDevice.h.

    {
      return m_Bounds;
    };

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

Reimplemented from mitk::TrackingDevice.

mitk::VirtualTrackingTool * mitk::VirtualTrackingDevice::GetInternalTool ( unsigned int idx ) [protected]

Definition at line 215 of file mitkVirtualTrackingDevice.cpp.

{
  MutexLockHolder toolsMutexLockHolder(*m_ToolsMutex); // lock and unlock the mutex
  if (idx < m_AllTools.size())
    return m_AllTools.at(idx);
  else
    return NULL;
}

mitk::VirtualTrackingDevice::ControlPointType mitk::VirtualTrackingDevice::GetRandomPoint ( ) [protected]

returns a random position inside the tracking volume (defined by m_Bounds)

Definition at line 308 of file mitkVirtualTrackingDevice.cpp.

{
  ControlPointType pos;
  pos[0] = m_Bounds[0] + (m_Bounds[1] - m_Bounds[0]) * (rand() / (RAND_MAX + 1.0));  // X =  xMin + xRange * (random number between 0 and 1)
  pos[1] = m_Bounds[2] + (m_Bounds[3] - m_Bounds[2]) * (rand() / (RAND_MAX + 1.0));  // Y
  pos[2] = m_Bounds[4] + (m_Bounds[5] - m_Bounds[4]) * (rand() / (RAND_MAX + 1.0));  // Z
  return pos;
}

virtual unsigned int mitk::VirtualTrackingDevice::GetRefreshRate ( ) const [virtual]

Returns the refresh rate in ms.

Returns:: Returns the refresh rate in ms.

mitk::ScalarType mitk::VirtualTrackingDevice::GetSplineChordLength ( unsigned int idx )

return the approximate length of the spline for tool with index idx in millimeter

if the index idx is not a valid tool index, a std::invalid_argument exception is thrown. GetSplineChordLength() returns the distance between all control points of the spline in millimeter. This can be used as an approximation for the length of the spline path.

Definition at line 192 of file mitkVirtualTrackingDevice.cpp.

References mitk::VirtualTrackingTool::GetSplineLength(), and QuadProgPP::t().

{
  mitk::VirtualTrackingTool* t = this->GetInternalTool(idx);
  if (t != NULL)
    return t->GetSplineLength();
  else
    throw std::invalid_argument("invalid index");
}

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

Parameters:

toolNumber The number of the tool which should be given back.

Returns:: Returns the tool which the number "toolNumber". Returns NULL, if there is no tool with this number.

Implements mitk::TrackingDevice.

Definition at line 123 of file mitkVirtualTrackingDevice.cpp.

{
  MutexLockHolder lock(*m_ToolsMutex); // lock and unlock the mutex
  if ( toolNumber < m_AllTools.size()) 
    return this->m_AllTools.at(toolNumber);
  return NULL;
}

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

Returns:: Returns the number of tools which have been added to the device.

Implements mitk::TrackingDevice.

Definition at line 116 of file mitkVirtualTrackingDevice.cpp.

{
  MutexLockHolder lock(*m_ToolsMutex); // lock and unlock the mutex
  return static_cast<unsigned int>(this->m_AllTools.size());
}

void mitk::VirtualTrackingDevice::InitializeSpline ( mitk::VirtualTrackingTool * t ) [protected]

initializes the spline path of the tool t with random control points inside the current tracking volume

Definition at line 146 of file mitkVirtualTrackingDevice.cpp.

References mitk::VirtualTrackingTool::GetSpline(), and mitk::VirtualTrackingTool::SetSplineLength().

{
  if (t == NULL)
  return;

  typedef mitk::VirtualTrackingTool::SplineType SplineType;
  /* create random control points */
  SplineType::ControlPointListType controlPoints;
  controlPoints.reserve(m_NumberOfControlPoints + 1);

  controlPoints.push_back(this->GetRandomPoint()); // insert point 0
  double length = 0.0;  // estimate spline length by calculating line segments lengths
  for (unsigned int i = 1; i < m_NumberOfControlPoints - 1; ++i) // set points 1..n-2
  {
    SplineType::ControlPointType pos;
    pos = this->GetRandomPoint();
    length += controlPoints.at(i - 1).EuclideanDistanceTo(pos);
    controlPoints.push_back(pos);
  }
  controlPoints.push_back(controlPoints.at(0));  // close spline --> insert point last control point with same value as first control point
  length += controlPoints.at(controlPoints.size() - 2).EuclideanDistanceTo(controlPoints.at(controlPoints.size() - 1));

  /* Create knot list. TODO: rethink knot list values and list size. Is there a better solution? */
  SplineType::KnotListType knotList;
  knotList.push_back(0.0);
  for (unsigned int i = 1; i < controlPoints.size() + t->GetSpline()->GetSplineOrder() + 1; ++i)
    knotList.push_back(i);
  knotList.push_back(controlPoints.size() + t->GetSpline()->GetSplineOrder() + 1);

  t->GetSpline()->SetControlPoints(controlPoints);
  t->GetSpline()->SetKnots(knotList);
  t->SetSplineLength(length);
}

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

Referenced by QmitkIGTExampleView::ConfigureTrackingDevice(), main(), mitkTrackingDeviceSourceTest(), mitkVirtualTrackingDeviceTest(), QmitkImageGuidedTherapyTutorialView::OnStartIGT(), and VirtualTrackingDevice().

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

Opens the connection to the device. This have to be done before the tracking is started.

Implements mitk::TrackingDevice.

Definition at line 132 of file mitkVirtualTrackingDevice.cpp.

{
  if (m_NumberOfControlPoints < 1)
  {
    this->SetErrorMessage("to few control points for spline interpolation");
    return false;
  }
  srand(time(NULL)); //Init random number generator

  this->SetState(Ready);
  return true;
}

virtual void mitk::VirtualTrackingDevice::SetBounds ( mitk::ScalarType data[] ) [virtual]

Set the tracking volume bounds.

This will set the tracking volume as an axis aligned bounding box defined by the six bounds values xMin, xMax, yMin, yMax, zMin, zMax. Note that the random path of existing tools will not be updated with the new tracking volume. Tools that are created after calling SetBounds() will use the new tracking volume

virtual void mitk::VirtualTrackingDevice::SetRefreshRate ( unsigned int _arg ) [virtual]

Sets the refresh rate of the virtual tracking device in ms.

Returns:: Sets the refresh rate of the virtual tracking device in ms

void mitk::VirtualTrackingDevice::SetToolSpeed	(	unsigned int	idx,
		mitk::ScalarType	roundsPerSecond
	)

sets the speed of the tool idx in rounds per second

The virtual tools will travel along a closed spline path. This method sets the speed of a tool as a factor of how many rounds per second the tool should move. A setting of 1.0 will indicate one complete round per second. Together with GetSplineChordLength(), the speed in millimeter per second can be estimated. roundsPerSecond must be positive and larger than 0.0001.

Warning:: Tool speed is currently not used. : use tool speed

Definition at line 202 of file mitkVirtualTrackingDevice.cpp.

References mitk::VirtualTrackingTool::SetVelocity(), and QuadProgPP::t().

{ 
  if (roundsPerSecond < 0.0001)
    throw std::invalid_argument("Minimum tool speed is 0.0001 rounds per second");

    mitk::VirtualTrackingTool* t = this->GetInternalTool(idx);
    if (t != NULL)
      t->SetVelocity(roundsPerSecond);
    else
      throw std::invalid_argument("invalid index");
}

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

Starts the tracking.

After StartTracking() is called, the tools will move on their spline paths with a constant velocity that can be set with SetToolSpeed(). The standard velocity is 10 seconds for one complete cycle along the spline path.

Warning:: tool speed is not yet used in the current version

Returns:: Returns true if the tracking is started. Returns false if there was an error.

Implements mitk::TrackingDevice.

Definition at line 76 of file mitkVirtualTrackingDevice.cpp.

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

{
  if (this->GetState() != Ready)
    return false;
  this->SetState(Tracking);            // go to mode Tracking
  this->m_StopTrackingMutex->Lock();  
  this->m_StopTracking = false;
  this->m_StopTrackingMutex->Unlock();

  m_TrackingFinishedMutex->Unlock(); // transfer the execution rights to tracking thread

  mitk::TimeStamp::GetInstance()->Start(this);
  
  if (m_MultiThreader.IsNotNull() && (m_ThreadID != -1))
    m_MultiThreader->TerminateThread(m_ThreadID);
  if (m_MultiThreader.IsNull())
    m_MultiThreader = itk::MultiThreader::New();

  m_ThreadID = m_MultiThreader->SpawnThread(this->ThreadStartTracking, this);    // start a new thread that executes the TrackTools() method
  return true;
}

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

Stops the tracking.

Returns:: Returns true if the tracking is stopped. Returns false if there was an error.

Reimplemented from mitk::TrackingDevice.

Definition at line 99 of file mitkVirtualTrackingDevice.cpp.

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

{
  if (this->GetState() == Tracking) // Only if the object is in the correct state
  {
    m_StopTrackingMutex->Lock();  // m_StopTracking is used by two threads, so we have to ensure correct thread handling
    m_StopTracking = true;
    m_StopTrackingMutex->Unlock();
    this->SetState(Ready);
  }

  mitk::TimeStamp::GetInstance()->Stop(this);
  m_TrackingFinishedMutex->Lock();

  return true;
}

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

static start method for tracking thread

Definition at line 286 of file mitkVirtualTrackingDevice.cpp.

References m_ThreadID, and TrackTools().

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

  if (trackingDevice != NULL) 
    trackingDevice->TrackTools();

  trackingDevice->m_ThreadID = -1; // reset thread ID because we end the thread here
  return ITK_THREAD_RETURN_VALUE;
}

void mitk::VirtualTrackingDevice::TrackTools ( ) [protected]

This method tracks tools as long as the variable m_Mode is set to "Tracking". Tracking tools means generating random numbers for the tool position and orientation.

Definition at line 225 of file mitkVirtualTrackingDevice.cpp.

References QuadProgPP::t().

Referenced by ThreadStartTracking().

{
  try
  {
    bool localStopTracking;       // 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 

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

    /* lock the TrackingFinishedMutex to signal that the execution rights are now transfered to the tracking thread */
    if (!localStopTracking) MutexLockHolder trackingFinishedLockHolder(*m_TrackingFinishedMutex); // keep lock until end of scope
    this->m_StopTrackingMutex->Unlock();

    mitk::ScalarType t = 0.0;
    while ((this->GetState() == Tracking) && (localStopTracking == false))
    {
      //for (ToolContainer::iterator itAllTools = m_AllTools.begin(); itAllTools != m_AllTools.end(); itAllTools++)
      for (unsigned int i = 0; i < this->GetToolCount(); ++i)  // use mutexed methods to access tool container
      {
        mitk::VirtualTrackingTool::Pointer currentTool = this->GetInternalTool(i);
        mitk::VirtualTrackingTool::SplineType::PointType pos;
        /* calculate tool position with spline interpolation */
        pos = currentTool->GetSpline()->EvaluateSpline(t);
        mitk::Point3D mp;
        mitk::itk2vtk(pos, mp); // convert from SplineType::PointType to mitk::Point3D
        currentTool->SetPosition(mp);
        // Currently, a constant speed is used. TODO: use tool velocity setting
        t += 0.001;
        if (t >= 1.0)
          t = 0.0;

        mitk::Quaternion quat;
        /* fix quaternion rotation */
        quat.x() = 1.0;
        quat.y() = 1.0;
        quat.z() = 1.0;
        quat.r() = 1.0;
        currentTool->SetOrientation(quat);
        // TODO: rotate once per cycle around a fixed rotation vector

        currentTool->SetTrackingError( 2 * (rand() / (RAND_MAX + 1.0)));  // tracking error in 0 .. 2 Range
        currentTool->SetDataValid(true);
      }
      itksys::SystemTools::Delay(m_RefreshRate);
      /* Update the local copy of m_StopTracking */
      this->m_StopTrackingMutex->Lock();
      localStopTracking = m_StopTracking;
      this->m_StopTrackingMutex->Unlock();
    } // tracking ends if we pass this line

    m_TrackingFinishedMutex->Unlock(); // transfer control back to main thread
  }
  catch(...)
  {
    m_TrackingFinishedMutex->Unlock();
    this->StopTracking();
    this->SetErrorMessage("Error while trying to track tools. Thread stopped.");
  }
}