vtkPlusDevice.h

Go to the documentation of this file.

/*=Plus=header=begin======================================================
Program: Plus
Copyright (c) Laboratory for Percutaneous Surgery. All rights reserved.
See License.txt for details.
=========================================================Plus=header=end*/

#ifndef __vtkPlusDevice_h
#define __vtkPlusDevice_h

// Local includes
#include "igsioCommon.h"
#include "PlusConfigure.h"
#include "PlusStreamBufferItem.h"
#include "vtkPlusChannel.h"
#include "vtkPlusDataCollectionExport.h"

// VTK includes
#include <vtkImageAlgorithm.h>
#include <vtkMultiThreader.h>
#include <vtkStdString.h>

#include <set>

// STL includes
#include <string>

class vtkPlusBuffer;
class vtkPlusDataCollector;
class vtkPlusDataSource;
class vtkPlusDevice;
class vtkPlusHTMLGenerator;
class vtkXMLDataElement;

typedef std::vector<vtkPlusChannel*> ChannelContainer;
typedef ChannelContainer::const_iterator ChannelContainerConstIterator;
typedef ChannelContainer::iterator ChannelContainerIterator;

typedef std::vector<vtkPlusBuffer*> StreamBufferContainer;
typedef StreamBufferContainer::const_iterator StreamBufferContainerConstIterator;
typedef StreamBufferContainer::iterator StreamBufferContainerIterator;

typedef std::map<int, vtkPlusBuffer*> StreamBufferMapContainer;
typedef StreamBufferMapContainer::const_iterator StreamBufferMapContainerConstIterator;
typedef StreamBufferMapContainer::iterator StreamBufferMapContainerIterator;

typedef std::vector<vtkPlusDevice*> DeviceCollection;
typedef std::vector<vtkPlusDevice*>::iterator DeviceCollectionIterator;
typedef std::vector<vtkPlusDevice*>::const_iterator DeviceCollectionConstIterator;

class vtkPlusDataCollectionExport vtkPlusDevice : public vtkImageAlgorithm
{
public:
  static vtkPlusDevice* New();
  vtkTypeMacro(vtkPlusDevice, vtkImageAlgorithm);
  virtual void PrintSelf(ostream& os, vtkIndent indent) VTK_OVERRIDE;

  static const std::string BMODE_PORT_NAME;
  static const std::string RFMODE_PORT_NAME;
  static const std::string PARAMETERS_XML_ELEMENT_TAG;
  static const std::string PARAMETER_XML_ELEMENT_TAG;

  virtual PlusStatus Probe();

  virtual std::string GetSdkVersion();

  virtual PlusStatus ReadConfiguration(vtkXMLDataElement*);

  virtual PlusStatus WriteConfiguration(vtkXMLDataElement*);

  virtual PlusStatus Connect();

  virtual PlusStatus ForceUpdate();

  virtual PlusStatus Disconnect();

  virtual bool IsResettable();

  virtual PlusStatus StartRecording();

  virtual PlusStatus StopRecording();

  static PlusStatus GetToolReferenceFrameFromTrackedFrame(igsioTrackedFrame& aFrame, std::string& aToolReferenceFrameName);

  //virtual PlusStatus SetBuffer(vtkPlusBuffer* newBuffer);

  virtual PlusStatus SetBufferSize(vtkPlusChannel& aChannel, int FrameBufferSize, const std::string& aSourceId = std::string(""));
  virtual PlusStatus GetBufferSize(vtkPlusChannel& aChannel, int& outVal, const std::string& aSourceId = std::string(""));

  virtual void SetStartTime(double startTime);

  virtual double GetStartTime();

  virtual bool IsTracker() const;

  virtual bool IsVirtual() const;

  virtual PlusStatus Reset();

  void ClearAllBuffers();

  virtual PlusStatus WriteToolsToSequenceFile(const std::string& filename, bool useCompression = false);

  void DeepCopy(const vtkPlusDevice& device);

  double GetInternalUpdateRate() const;

  PlusStatus GetDataSource(const char* aSourceId, vtkPlusDataSource*& aSource);
  PlusStatus GetDataSource(const std::string& aSourceId, vtkPlusDataSource*& aSource);

  PlusStatus GetTool(const char* aToolSourceId, vtkPlusDataSource*& aTool) const;
  PlusStatus GetTool(const std::string& aToolSourceId, vtkPlusDataSource*& aTool) const;

  PlusStatus GetFirstActiveTool(vtkPlusDataSource*& aTool) const;

  PlusStatus GetToolByPortName(const char* aPortName, vtkPlusDataSource*& aSource);
  PlusStatus GetToolByPortName(const std::string& aPortName, vtkPlusDataSource*& aSource);
  PlusStatus GetVideoSourcesByPortName(const char* aPortName, std::vector<vtkPlusDataSource*>& sources);
  PlusStatus GetVideoSourcesByPortName(const std::string& aPortName, std::vector<vtkPlusDataSource*>& sources);

  DataSourceContainerConstIterator GetToolIteratorBegin() const;

  DataSourceContainerConstIterator GetToolIteratorEnd() const;

  PlusStatus AddTool(vtkPlusDataSource* tool, bool requireUniquePortName = true);

  virtual int GetNumberOfTools() const;

  PlusStatus GetVideoSource(const char* aSourceId, vtkPlusDataSource*& aVideoSource);

  std::vector<vtkPlusDataSource*> GetVideoSources() const;

  PlusStatus GetVideoSourceByIndex(const unsigned int index, vtkPlusDataSource*& aVideoSource);

  PlusStatus GetFirstVideoSource(vtkPlusDataSource*& anImage);

  DataSourceContainerConstIterator GetVideoSourceIteratorBegin() const;

  DataSourceContainerConstIterator GetVideoSourceIteratorEnd() const;

  PlusStatus AddVideoSource(vtkPlusDataSource* anImage);

  virtual int GetNumberOfVideoSources() const;

  PlusStatus GetFieldDataSource(const char* aSourceId, vtkPlusDataSource*& aSource) const;
  PlusStatus GetFieldDataSource(const std::string& aSourceId, vtkPlusDataSource*& aSource) const;

  DataSourceContainerConstIterator GetFieldDataSourcessIteratorBegin() const;

  DataSourceContainerConstIterator GetFieldDataSourcessIteratorEnd() const;

  PlusStatus AddFieldDataSource(vtkPlusDataSource* aSource);

  virtual int GetNumberOfFieldDataSources() const;

  void SetToolReferenceFrameName(const std::string& frameName);
  std::string GetToolReferenceFrameName() const;

  virtual bool GetCorrectlyConfigured() const;

  virtual void SetDataCollector(vtkPlusDataCollector* _arg);

  void SetToolsBufferSize(int aBufferSize);

  void SetFieldDataSourcesBufferSize(int aBufferSize);

  virtual void SetLocalTimeOffsetSec(double aTimeOffsetSec);
  virtual double GetLocalTimeOffsetSec() const;

  virtual PlusStatus InternalUpdate();

  PlusStatus GetInputDevices(std::vector<vtkPlusDevice*>& outDeviceList) const;
  PlusStatus GetInputDevicesRecursive(std::vector<vtkPlusDevice*>& outDeviceList) const;

  // Parameter interface
  virtual PlusStatus SetParameter(const std::string& key, const std::string& value);
  virtual std::string GetParameter(const std::string& key) const;
  virtual PlusStatus GetParameter(const std::string& key, std::string& outValue) const;

  //BTX
  // These are used by static functions in vtkPlusDevice.cxx, and since
  // VTK doesn't generally use 'friend' functions they are public
  // instead of protected.  Do not use them anywhere except inside
  // vtkPlusDevice.cxx.
  vtkIGSIORecursiveCriticalSection* UpdateMutex;
  vtkTimeStamp UpdateTime;
  double InternalUpdateRate;
  //ETX

  virtual double GetAcquisitionRate() const;
  PlusStatus SetAcquisitionRate(double aRate);

  virtual bool IsRecording() const;

  /* Return the id of the device */
  virtual std::string GetDeviceId() const;
  // Set the device Id
  void SetDeviceId(const std::string& id);

  virtual unsigned long GetFrameNumber() const;

  virtual double GetFrameTimeStamp() const;

  vtkSetMacro(UpdateWithDesiredTimestamp, int);
  vtkGetMacro(UpdateWithDesiredTimestamp, int);
  vtkBooleanMacro(UpdateWithDesiredTimestamp, int);

  vtkSetMacro(DesiredTimestamp, double);
  vtkGetMacro(DesiredTimestamp, double);

  vtkGetMacro(TimestampClosestToDesired, double);

  virtual int GetConnected() const;
  virtual bool IsConnected() const;

  virtual PlusStatus SetInputFrameSize(vtkPlusDataSource& aSource, unsigned int x, unsigned int y, unsigned int z);

  virtual PlusStatus GetInputFrameSize(vtkPlusChannel& aChannel, unsigned int& x, unsigned int& y, unsigned int& z) const;

  virtual PlusStatus GetInputFrameSize(vtkPlusChannel& aChannel, FrameSizeType& dim) const;

  virtual PlusStatus GetOutputFrameSize(vtkPlusChannel& aChannel, unsigned int& x, unsigned int& y, unsigned int& z) const;

  virtual PlusStatus GetOutputFrameSize(vtkPlusChannel& aChannel, FrameSizeType& dim) const;

  virtual PlusStatus SetPixelType(vtkPlusChannel& aChannel, igsioCommon::VTKScalarPixelType pixelType);
  virtual igsioCommon::VTKScalarPixelType GetPixelType(vtkPlusChannel& aChannel);

  virtual PlusStatus SetImageType(vtkPlusChannel& aChannel, US_IMAGE_TYPE imageType);
  virtual US_IMAGE_TYPE GetImageType(vtkPlusChannel& aChannel);

  PlusStatus AddOutputChannel(vtkPlusChannel* aChannel);

  PlusStatus GetFirstOutputChannel(vtkPlusChannel*& aChannel);
  PlusStatus GetOutputChannelByName(vtkPlusChannel*& aChannel, const char* aChannelId);
  PlusStatus GetOutputChannelByName(vtkPlusChannel*& aChannel, const std::string& aChannelId);

  virtual int OutputChannelCount() const;

  ChannelContainerConstIterator GetOutputChannelsStart() const;
  ChannelContainerConstIterator GetOutputChannelsEnd() const;
  ChannelContainerIterator GetOutputChannelsStart();
  ChannelContainerIterator GetOutputChannelsEnd();

  PlusStatus AddInputChannel(vtkPlusChannel* aChannel);

  virtual PlusStatus NotifyConfigured();

  virtual int RequestInformation(vtkInformation*, vtkInformationVector**, vtkInformationVector*);

  virtual int RequestData(vtkInformation*, vtkInformationVector**, vtkInformationVector*);

  /* Accessors for the grace period value */
  vtkSetMacro(MissingInputGracePeriodSec, double);
  double GetMissingInputGracePeriodSec() const;

  virtual PlusStatus CreateDefaultOutputChannel(const char* channelId = NULL, bool addSource = true);

  PlusStatus GetFirstActiveOutputVideoSource(vtkPlusDataSource*& aVideoSource);

  virtual PlusStatus GetImageMetaData(igsioCommon::ImageMetaDataList& imageMetaDataItems);

  virtual PlusStatus GetImage(const std::string& requestedImageId, std::string& assignedImageId, const std::string& imageReferencFrameName, vtkImageData* imageData, vtkMatrix4x4* ijkToReferenceTransform);

  virtual PlusStatus SendText(const std::string& textToSend, std::string* textReceived = NULL);

protected:
  static void* vtkDataCaptureThread(vtkMultiThreader::ThreadInfo* data);

  virtual PlusStatus InternalConnect();

  virtual PlusStatus InternalDisconnect();

  virtual PlusStatus InternalStartRecording();

  virtual PlusStatus InternalStopRecording();

  virtual PlusStatus AddVideoItemToVideoSources(const std::vector<vtkPlusDataSource*>& videoSources, const igsioVideoFrame& frame, long frameNumber, double unfilteredTimestamp = UNDEFINED_TIMESTAMP,
      double filteredTimestamp = UNDEFINED_TIMESTAMP, const igsioFieldMapType* customFields = NULL);

  virtual PlusStatus AddVideoItemToVideoSources(const std::vector<vtkPlusDataSource*>& videoSources, void* imageDataPtr, US_IMAGE_ORIENTATION usImageOrientation, const FrameSizeType& frameSizeInPx,
      igsioCommon::VTKScalarPixelType pixelType, unsigned int numberOfScalarComponents, US_IMAGE_TYPE imageType, int numberOfBytesToSkip, long frameNumber, double unfilteredTimestamp = UNDEFINED_TIMESTAMP,
      double filteredTimestamp = UNDEFINED_TIMESTAMP, const igsioFieldMapType* customFields = NULL);

  virtual PlusStatus ToolTimeStampedUpdate(const std::string& aToolSourceId, vtkMatrix4x4* matrix, ToolStatus status, unsigned long frameNumber, double unfilteredtimestamp, const igsioFieldMapType* customFields = NULL);

  virtual PlusStatus ToolTimeStampedUpdateWithoutFiltering(const std::string& aToolSourceId, vtkMatrix4x4* matrix, ToolStatus status, double unfilteredtimestamp, double filteredtimestamp, const igsioFieldMapType* customFields = NULL);

  vtkXMLDataElement* FindThisDeviceElement(vtkXMLDataElement* rootXMLElement);
  vtkXMLDataElement* FindOutputChannelElement(vtkXMLDataElement* rootXMLElement, const char* aChannelId);
  vtkXMLDataElement* FindInputChannelElement(vtkXMLDataElement* rootXMLElement, const char* aChannelId);
  virtual void InternalWriteOutputChannels(vtkXMLDataElement* rootXMLElement);
  virtual void InternalWriteInputChannels(vtkXMLDataElement* rootXMLElement);

  PlusStatus EnsureUniqueDataSourceId(const std::string& aSourceId);

  vtkSetMacro(CorrectlyConfigured, bool);

  vtkSetMacro(StartThreadForInternalUpdates, bool);
  bool GetStartThreadForInternalUpdates() const;

  vtkSetMacro(RecordingStartTime, double);
  double GetRecordingStartTime() const;

  virtual vtkPlusDataCollector* GetDataCollector();

  bool HasGracePeriodExpired();

  vtkPlusDevice();
  virtual ~vtkPlusDevice();

protected:
  bool ThreadAlive;

  /* Is device connected */
  int Connected;

  vtkMultiThreader* Threader;

  int ThreadId;

  ChannelContainer  OutputChannels;
  ChannelContainer  InputChannels;

  StreamBufferItem*   CurrentStreamBufferItem;
  DataSourceContainer Tools;
  DataSourceContainer VideoSources;
  DataSourceContainer Fields;

  std::string ToolReferenceFrameName;

  std::string DeviceId;

  vtkPlusDataCollector* DataCollector;

  double AcquisitionRate;

  /* Flag whether the device is recording */
  int Recording;

  double DesiredTimestamp;
  int UpdateWithDesiredTimestamp;
  double TimestampClosestToDesired;

  unsigned long FrameNumber;
  double FrameTimeStamp;

  int OutputNeedsInitialization;

  bool CorrectlyConfigured;

  bool StartThreadForInternalUpdates;

  double LocalTimeOffsetSec;

  double MissingInputGracePeriodSec;
  double RecordingStartTime;

  std::set<std::string> ReportedUnknownTools;

  std::map<std::string, std::string> Parameters;

  static const int VIRTUAL_DEVICE_FRAME_RATE;

protected:
  /*
  When defining a device, it may be a tracker or imaging device
  These variables allow a device to define which commonly used attributes it is expecting
  */
  bool RequireImageOrientationInConfiguration;
  bool RequirePortNameInDeviceSetConfiguration;

private:
  vtkPlusDevice(const vtkPlusDevice&);   // Not implemented.
  void operator=(const vtkPlusDevice&);   // Not implemented.
};

#define XML_FIND_DEVICE_ELEMENT_REQUIRED_FOR_READING(deviceConfig, rootConfigElement) \
  if( Superclass::ReadConfiguration(rootConfigElement) != PLUS_SUCCESS )  \
  { \
    LOG_ERROR("Unable to continue reading configuration of "<<this->GetClassName()<<". Generic device configuration reading failed.");  \
    return PLUS_FAIL; \
  } \
  vtkXMLDataElement* deviceConfig = this->FindThisDeviceElement(rootConfigElement);  \
  if (deviceConfig == NULL)  \
  { \
    LOG_ERROR("Unable to continue configuration of "<<this->GetClassName()<<". Could not find corresponding element.");  \
    return PLUS_FAIL; \
  }

#define XML_FIND_DEVICE_ELEMENT_REQUIRED_FOR_WRITING(deviceConfig, rootConfigElement) \
  if( Superclass::WriteConfiguration(rootConfigElement) == PLUS_FAIL ) \
  { \
    LOG_ERROR("Unable to continue writing configuration of "<<this->GetClassName()<<". Generic device configuration writing failed.");  \
    return PLUS_FAIL; \
  } \
  vtkXMLDataElement* deviceConfig = this->FindThisDeviceElement(rootConfigElement); \
  if (deviceConfig == NULL) \
  { \
    LOG_ERROR("Cannot find or add "<<this->GetClassName()<<" device in XML tree"); \
    return PLUS_FAIL; \
  }

#endif