ENH: Added option to change the tracking frequency in NDICAPI

src/Documentation/UserManual/DeviceNDI.dox

@@ -32,6 +32,12 @@ Any NDI tracking device is supported that uses the common API, such as <a href="
 
 - \xmlAtt \b MeasurementVolumeNumber Measurement volume number. It can be used for defining volume type (dome, cube) and size. First valid volume number is 1. 0 means that the default volume is used. If an invalid value is set (for example -1) then the list of available volumes is logged. See VSEL command in the NDI API documentation for details.\OptionalAtt{0}
 
+- \xmlAtt \b TrackingFrequencyNumber Tracking frequency number. The tracking refreshing rate is set with respect to the frame frequency (60Hz on Polaris). The values are:
+0 = 1/3 of frame frequency => tracking at 20Hz
+1 = 1/2 of frame frequency => tracking at 30Hz
+2 = 1/1 of frame frequency => tracking at 60Hz
+The default value is 0. See IRATE command in the NDI API documentation for details.\OptionalAtt{0}
+
 - \xmlElem \ref DataSources
   - \xmlElem \ref DataSource there must be one child tool element \RequiredAtt
     - \xmlAtt \b Type = \c "Tool" \RequiredAtt

src/PlusDataCollection/NDICAPITracking/vtkPlusNDITracker.cxx

@@ -91,6 +91,7 @@ vtkPlusNDITracker::vtkPlusNDITracker()
   , MeasurementVolumeNumber(0)
   , NetworkHostname("")
   , NetworkPort(8765)
+  , TrackingFrequencyNumber(0)
   , CommandMutex(vtkIGSIORecursiveCriticalSection::New())
 {
   memset(this->CommandReply, 0, VTK_NDI_REPLY_LEN);
@@ -131,6 +132,7 @@ void vtkPlusNDITracker::PrintSelf(ostream& os, vtkIndent indent)
   os << indent << "BaudRate: " << this->BaudRate << std::endl;
   os << indent << "IsDeviceTracking: " << this->IsDeviceTracking << std::endl;
   os << indent << "MeasurementVolumeNumber: " << this->MeasurementVolumeNumber << std::endl;
+  os << indent << "TrackingFrequencyNumber: " << this->TrackingFrequencyNumber << std::endl;
   os << indent << "CommandReply: " << this->CommandReply << std::endl;
   os << indent << "LastFrameNumber: " << this->LastFrameNumber << std::endl;
   os << indent << "LeaveDeviceOpenAfterProbe: " << this->LeaveDeviceOpenAfterProbe << std::endl;
@@ -313,6 +315,7 @@ PlusStatus vtkPlusNDITracker::InternalConnect()
   }
 
   SelectMeasurementVolume();
+  SelectTrackingFrequency();
 
   if (this->EnableToolPorts() != PLUS_SUCCESS)
   {
@@ -1041,6 +1044,7 @@ PlusStatus vtkPlusNDITracker::ReadConfiguration(vtkXMLDataElement* rootConfigEle
     this->BaudRate = 0;
   }
   XML_READ_SCALAR_ATTRIBUTE_OPTIONAL(int, MeasurementVolumeNumber, deviceConfig);
+  XML_READ_SCALAR_ATTRIBUTE_OPTIONAL(int, TrackingFrequencyNumber, deviceConfig);
 
   XML_READ_STRING_ATTRIBUTE_OPTIONAL(NetworkHostname, deviceConfig);
   XML_READ_SCALAR_ATTRIBUTE_OPTIONAL(int, NetworkPort, deviceConfig);
@@ -1134,6 +1138,10 @@ PlusStatus vtkPlusNDITracker::WriteConfiguration(vtkXMLDataElement* rootConfig)
   {
     trackerConfig->SetIntAttribute("MeasurementVolumeNumber", this->MeasurementVolumeNumber);
   }
+  if (this->TrackingFrequencyNumber > 0)
+  {
+    trackerConfig->SetIntAttribute("TrackingFrequencyNumber", this->TrackingFrequencyNumber);
+  }
   trackerConfig->SetAttribute("CheckDSR", this->CheckDSR ? "true" : "false");
 
   return PLUS_SUCCESS;
@@ -1369,6 +1377,49 @@ PlusStatus vtkPlusNDITracker::SelectMeasurementVolumeDeprecated()
   return PLUS_SUCCESS;
 }
 
+//----------------------------------------------------------------------------
+PlusStatus vtkPlusNDITracker::SelectTrackingFrequency()
+{
+  if (this->TrackingFrequencyNumber > 0)
+  {
+    std::string reply = this->Command("GET:Param.Tracking.Track Frequency");
+
+    int errnum = ndiGetError(this->Device);
+    if (errnum)
+    {
+      return SelectTrackingFrequencyDeprecated();
+    }
+    else
+    {
+      // Use SET command with parameter
+      std::string frequencySelectCommandReply = this->Command("SET:Param.Tracking.Track Frequency=%d", this->TrackingFrequencyNumber);
+      int errnum = ndiGetError(this->Device);
+      if (errnum)
+      {
+        LOG_ERROR("Failed to set tracking frequency " << this->TrackingFrequencyNumber << ": " << ndiErrorString(errnum));
+        CloseDevice(this->Device);
+        return PLUS_FAIL;
+      }
+    }
+  }
+
+  return PLUS_SUCCESS;
+}
+
+//----------------------------------------------------------------------------
+PlusStatus vtkPlusNDITracker::SelectTrackingFrequencyDeprecated()
+{
+  auto frequencySelectCommandReply = this->Command("IRATE:%d", this->TrackingFrequencyNumber);
+  int errnum = ndiGetError(this->Device);
+  if (errnum)
+  {
+    LOG_ERROR("Failed to set tracking frequency " << this->TrackingFrequencyNumber << ": " << ndiErrorString(errnum));
+    return PLUS_FAIL;
+  }
+
+  return PLUS_SUCCESS;
+}
+
 //----------------------------------------------------------------------------
 int vtkPlusNDITracker::ConvertBaudToNDIEnum(int baudRate)
 {

src/PlusDataCollection/NDICAPITracking/vtkPlusNDITracker.h

@@ -167,6 +167,16 @@ class vtkPlusDataCollectionExport vtkPlusNDITracker : public vtkPlusDevice
   vtkSetMacro(MeasurementVolumeNumber, int);
   vtkGetMacro(MeasurementVolumeNumber, int);
 
+  /*!
+  Tracking frequency number. It can be used for changing the frequency at which tools are tracked.
+  Default is 0, i.e. the tracking frequency is 1/3 of the frame frequency.
+  1 makes the tracking frequency 1/2 of the frame frequency.
+  2 makes the tracking frequency match the frame frequency.
+  See IRATE command in the NDI API documentation for details.
+*/
+  vtkSetMacro(TrackingFrequencyNumber, int);
+  vtkGetMacro(TrackingFrequencyNumber, int);
+
   /*!
     Get an update from the tracking system and push the new transforms
     to the tools.  This should only be used within vtkTracker.cxx.
@@ -275,6 +285,17 @@ class vtkPlusDataCollectionExport vtkPlusNDITracker : public vtkPlusDevice
   */
   PlusStatus SelectMeasurementVolumeDeprecated();
 
+  /*!
+  Select the tracking frequency, fallback to deprecated
+  */
+  PlusStatus SelectTrackingFrequency();
+
+  /*!
+    Select the tracking frequency using deprecated commands
+    Only used if newer commands are not supported by a device
+  */
+  PlusStatus SelectTrackingFrequencyDeprecated();
+
   /*! Lookup table function to convert from baudrate to enum */
   static int ConvertBaudToNDIEnum(int baudRate);
 
@@ -298,6 +319,7 @@ class vtkPlusDataCollectionExport vtkPlusNDITracker : public vtkPlusDevice
 
   std::string                       NetworkHostname;
   int                               NetworkPort;
+  int                               TrackingFrequencyNumber;
 
 private:
   vtkPlusNDITracker(const vtkPlusNDITracker&);