v2.0.0
Loading...
Searching...
No Matches
UTILSLIB::PolhemusCoregistration Class Reference

Head–device coregistration engine driven by a Polhemus Fastrak. More...

#include <polhemus_coregistration.h>

Classes

struct  OpticalCalibSample

Public Types

enum class  PivotState { Idle , WaitingForStart , Collecting , Done }

Signals

void devicePoseChanged (const QMatrix4x4 &deviceToWorld)
void penPoseChanged (const QVector3D &position, const QQuaternion &orientation)
void probePoseChanged (const QVector3D &position, const QQuaternion &orientation)
void penButtonPressed (const QVector3D &position, const QQuaternion &orientation)
void registrationChanged ()
void pivotStateChanged (PolhemusCoregistration::PivotState state)
void pivotCalibrationDone (const QVector3D &offset, float residualMm)
void pivotSampleCollected (int sampleCount, float angularSpanDeg)
void opticalCalibrationChanged ()

Public Member Functions

 PolhemusCoregistration (QObject *parent=nullptr)
 ~PolhemusCoregistration () override=default
void setTrackerStation (int station)
void setPenStation (int station)
void setProbeStation (int station)
int trackerStation () const
int penStation () const
int probeStation () const
void setPenTipOffset (const QVector3D &offset)
QVector3D penTipOffset () const
void setTipOffsetEnabled (bool on)
bool tipOffsetEnabled () const
void setAxisMirror (bool mirrorX, bool mirrorY)
 Negate X and/or Y of incoming Polhemus positions.
bool mirrorX () const
bool mirrorY () const
void startPivotCalibration ()
void cancelPivotCalibration ()
PivotState pivotState () const
int pivotSampleCount () const
float pivotResidualMm () const
void setTrackerToDeviceOffset (const QVector3D &translation, const QQuaternion &rotation)
 Set the rigid offset from the tracker sensor body frame to the device frame.
QVector3D trackerToDeviceTranslation () const
QQuaternion trackerToDeviceRotation () const
bool captureOpticalCalibSample ()
 Record one calibration sample (current tracker pose + current pen position).
int opticalCalibSampleCount () const
void clearOpticalCalibSamples ()
bool captureObjectiveCenter ()
 Capture the current pen position as the objective lens center.
bool hasObjectiveCenter () const
void clearObjectiveCenter ()
QVector3D objectiveCenterLocal () const
bool solveOpticalCalibration ()
 Fit a 3D line through the focus points in tracker-local frame.
void setKnownTrackerToObjectiveDistance (float metres)
 Set the known perpendicular distance from tracker sensor to the objective center (metres).
float knownTrackerToObjectiveDistance () const
bool opticalCalibrationValid () const
QVector3D opticalAxisLocal () const
QVector3D opticalCenterLocal () const
float opticalCalibResidualMm () const
float opticalCalibDepthSpreadMm () const
bool applyOpticalAxisFineAdjust (const QVector3D &targetWorldPos, float &correctionDeg)
 Fine-adjust the optical axis so it passes through a known world-frame point (e.g. the probe tip touched with the stylus).
bool opticalFineAdjustApplied () const
float opticalFineAdjustDeg () const
void clearOpticalFineAdjust ()
bool opticalRayInWorld (QVector3D &origin, QVector3D &direction) const
 Compute the current optical axis ray in Polhemus world frame.
bool opticalUpInWorld (QVector3D &up) const
void setConnection (PolhemusConnection *conn)
PolhemusConnection * connection () const
AcquiredPoints * acquiredPoints () const
bool captureCurrentPenPositionAsFiducial (FiducialId id)
bool captureCurrentPenPositionAsHeadShape ()
void setModelFiducial (FiducialId id, const QVector3D &posInModel)
bool hasModelFiducial (FiducialId id) const
bool hasAllModelFiducials () const
QVector3D modelFiducial (FiducialId id) const
bool hasAllPenFiducials () const
void setModelVertex (const QVector3D &pos)
bool hasModelVertex () const
QVector3D modelVertex () const
bool captureCurrentPenPositionAsVertex ()
bool hasPenVertex () const
QVector3D penVertex () const
bool computeRegistration ()
 Compute the head→device rigid transform from the three captured fiducials (NAS, LPA, RPA).
void resetRegistration ()
 Reset the registration state (headToWorld, headToDevice) to identity. Call this when the user clears all fiducials.
void saveSessionState (QSettings &settings, const QString &prefix=QStringLiteral("polhemus")) const
bool restoreSessionState (QSettings &settings, const QString &prefix=QStringLiteral("polhemus"))
bool registrationValid () const
QMatrix4x4 deviceToWorld () const
QMatrix4x4 headToWorld () const
QMatrix4x4 headToDevice () const
QMatrix4x4 worldToModel () const
QVector3D penPosition () const
QQuaternion penOrientation () const
bool haveLivePenPosition () const
QVector3D probePosition () const
QQuaternion probeOrientation () const
bool haveLiveProbePosition () const

Detailed Description

Head–device coregistration engine driven by a Polhemus Fastrak.

The class wires itself to a PolhemusConnection and maintains:

  • A continuously updated device-to-world transform (from the tracker station + user-supplied calibration offset).
  • An AcquiredPoints store filled by explicit capture calls or automatically on pen-button press.
  • The computed head–device transform after computeRegistration.

Definition at line 84 of file polhemus_coregistration.h.

Inheritance diagram for UTILSLIB::PolhemusCoregistration:
Inheritance graph

Member Enumeration Documentation

◆ PivotState

Enumerator
Idle 
WaitingForStart 
Collecting 
Done 

Definition at line 168 of file polhemus_coregistration.h.

Constructor & Destructor Documentation

◆ PolhemusCoregistration()

PolhemusCoregistration::PolhemusCoregistration ( QObject * parent = nullptr)
explicit

Definition at line 33 of file polhemus_coregistration.cpp.

◆ ~PolhemusCoregistration()

UTILSLIB::PolhemusCoregistration::~PolhemusCoregistration ( )
overridedefault

Member Function Documentation

◆ acquiredPoints()

AcquiredPoints * UTILSLIB::PolhemusCoregistration::acquiredPoints ( ) const
inline

Definition at line 420 of file polhemus_coregistration.h.

◆ applyOpticalAxisFineAdjust()

bool PolhemusCoregistration::applyOpticalAxisFineAdjust ( const QVector3D & targetWorldPos,
float & correctionDeg )

Fine-adjust the optical axis so it passes through a known world-frame point (e.g. the probe tip touched with the stylus).

The correction rotates m_opticalAxisLocal in the tracker body frame so that a ray from the optical center would pass through targetWorldPos at the current tracker pose.

Parameters
targetWorldPosDesired focus point in Polhemus world frame.
[out]correctionDegAngle of the applied correction (degrees).
Returns
true on success; false if calibration or tracker data is unavailable, or the correction would exceed 10°.

Definition at line 1057 of file polhemus_coregistration.cpp.

◆ cancelPivotCalibration()

void PolhemusCoregistration::cancelPivotCalibration ( )

Definition at line 543 of file polhemus_coregistration.cpp.

◆ captureCurrentPenPositionAsFiducial()

bool PolhemusCoregistration::captureCurrentPenPositionAsFiducial ( FiducialId id)

Definition at line 86 of file polhemus_coregistration.cpp.

◆ captureCurrentPenPositionAsHeadShape()

bool PolhemusCoregistration::captureCurrentPenPositionAsHeadShape ( )

Definition at line 125 of file polhemus_coregistration.cpp.

◆ captureCurrentPenPositionAsVertex()

bool PolhemusCoregistration::captureCurrentPenPositionAsVertex ( )

Definition at line 187 of file polhemus_coregistration.cpp.

◆ captureObjectiveCenter()

bool PolhemusCoregistration::captureObjectiveCenter ( )

Capture the current pen position as the objective lens center.

Touch the pen stylus to the center of the OPMI objective lens while the tracker is live. The point is stored in the tracker's local frame and used by the solver as a direct measurement of the optical center, replacing the sphere-distance constraint.

Returns
true on success, false if pen or tracker data unavailable.

Definition at line 710 of file polhemus_coregistration.cpp.

◆ captureOpticalCalibSample()

bool PolhemusCoregistration::captureOpticalCalibSample ( )

Record one calibration sample (current tracker pose + current pen position).

Returns
true if both pen and tracker data are available, false otherwise.

Definition at line 636 of file polhemus_coregistration.cpp.

◆ clearObjectiveCenter()

void PolhemusCoregistration::clearObjectiveCenter ( )

Clear the captured objective center.

Definition at line 749 of file polhemus_coregistration.cpp.

◆ clearOpticalCalibSamples()

void PolhemusCoregistration::clearOpticalCalibSamples ( )

Discard all calibration samples and reset the optical calibration.

Definition at line 699 of file polhemus_coregistration.cpp.

◆ clearOpticalFineAdjust()

void PolhemusCoregistration::clearOpticalFineAdjust ( )

Undo the last fine adjustment, restoring the original solved axis.

Definition at line 1130 of file polhemus_coregistration.cpp.

◆ computeRegistration()

bool PolhemusCoregistration::computeRegistration ( )

Compute the head→device rigid transform from the three captured fiducials (NAS, LPA, RPA).

Returns
true on success; false if any fiducial is missing or the fiducials are degenerate (collinear).

Definition at line 202 of file polhemus_coregistration.cpp.

◆ connection()

PolhemusConnection * UTILSLIB::PolhemusCoregistration::connection ( ) const
inline

Definition at line 411 of file polhemus_coregistration.h.

◆ devicePoseChanged

void UTILSLIB::PolhemusCoregistration::devicePoseChanged ( const QMatrix4x4 & deviceToWorld)
signal

◆ deviceToWorld()

QMatrix4x4 UTILSLIB::PolhemusCoregistration::deviceToWorld ( ) const
inline

Definition at line 506 of file polhemus_coregistration.h.

◆ hasAllModelFiducials()

bool PolhemusCoregistration::hasAllModelFiducials ( ) const

Definition at line 170 of file polhemus_coregistration.cpp.

◆ hasAllPenFiducials()

bool PolhemusCoregistration::hasAllPenFiducials ( ) const

Definition at line 180 of file polhemus_coregistration.cpp.

◆ hasModelFiducial()

bool PolhemusCoregistration::hasModelFiducial ( FiducialId id) const

Definition at line 165 of file polhemus_coregistration.cpp.

◆ hasModelVertex()

bool UTILSLIB::PolhemusCoregistration::hasModelVertex ( ) const
inline

Definition at line 452 of file polhemus_coregistration.h.

◆ hasObjectiveCenter()

bool UTILSLIB::PolhemusCoregistration::hasObjectiveCenter ( ) const
inline
Returns
Whether an objective center has been captured.

Definition at line 262 of file polhemus_coregistration.h.

◆ hasPenVertex()

bool UTILSLIB::PolhemusCoregistration::hasPenVertex ( ) const
inline

Definition at line 462 of file polhemus_coregistration.h.

◆ haveLivePenPosition()

bool UTILSLIB::PolhemusCoregistration::haveLivePenPosition ( ) const
inline

Definition at line 530 of file polhemus_coregistration.h.

◆ haveLiveProbePosition()

bool UTILSLIB::PolhemusCoregistration::haveLiveProbePosition ( ) const
inline

Definition at line 543 of file polhemus_coregistration.h.

◆ headToDevice()

QMatrix4x4 UTILSLIB::PolhemusCoregistration::headToDevice ( ) const
inline

Definition at line 514 of file polhemus_coregistration.h.

◆ headToWorld()

QMatrix4x4 UTILSLIB::PolhemusCoregistration::headToWorld ( ) const
inline

Definition at line 510 of file polhemus_coregistration.h.

◆ knownTrackerToObjectiveDistance()

float UTILSLIB::PolhemusCoregistration::knownTrackerToObjectiveDistance ( ) const
inline

Definition at line 304 of file polhemus_coregistration.h.

◆ mirrorX()

bool UTILSLIB::PolhemusCoregistration::mirrorX ( ) const
inline

Definition at line 155 of file polhemus_coregistration.h.

◆ mirrorY()

bool UTILSLIB::PolhemusCoregistration::mirrorY ( ) const
inline

Definition at line 159 of file polhemus_coregistration.h.

◆ modelFiducial()

QVector3D PolhemusCoregistration::modelFiducial ( FiducialId id) const

Definition at line 175 of file polhemus_coregistration.cpp.

◆ modelVertex()

QVector3D UTILSLIB::PolhemusCoregistration::modelVertex ( ) const
inline

Definition at line 456 of file polhemus_coregistration.h.

◆ objectiveCenterLocal()

QVector3D UTILSLIB::PolhemusCoregistration::objectiveCenterLocal ( ) const
inline

Captured objective center in tracker body frame (metres).

Returns
Objective center in the tracker body frame in metres; only meaningful if hasObjectiveCenter() is true.

Definition at line 275 of file polhemus_coregistration.h.

◆ opticalAxisLocal()

QVector3D UTILSLIB::PolhemusCoregistration::opticalAxisLocal ( ) const
inline

Direction of the optical axis in the tracker body frame (unit vector).

Returns
Unit optical-axis direction in the tracker body frame; only meaningful if opticalCalibrationValid() is true.

Definition at line 320 of file polhemus_coregistration.h.

◆ opticalCalibDepthSpreadMm()

float UTILSLIB::PolhemusCoregistration::opticalCalibDepthSpreadMm ( ) const
inline

Depth spread of calibration samples along the optical axis (mm).

Returns
Extent of the calibration focus points along the optical axis in millimetres.

Definition at line 350 of file polhemus_coregistration.h.

◆ opticalCalibrationChanged

void UTILSLIB::PolhemusCoregistration::opticalCalibrationChanged ( )
signal

◆ opticalCalibrationValid()

bool UTILSLIB::PolhemusCoregistration::opticalCalibrationValid ( ) const
inline
Returns
Whether a valid optical calibration has been computed.

Definition at line 310 of file polhemus_coregistration.h.

◆ opticalCalibResidualMm()

float UTILSLIB::PolhemusCoregistration::opticalCalibResidualMm ( ) const
inline

RMS residual of the last optical calibration (mm).

Returns
RMS distance of the focus points from the fitted optical axis in millimetres.

Definition at line 340 of file polhemus_coregistration.h.

◆ opticalCalibSampleCount()

int UTILSLIB::PolhemusCoregistration::opticalCalibSampleCount ( ) const
inline
Returns
Number of calibration samples recorded so far.

Definition at line 241 of file polhemus_coregistration.h.

◆ opticalCenterLocal()

QVector3D UTILSLIB::PolhemusCoregistration::opticalCenterLocal ( ) const
inline

Position of the optical center in the tracker body frame (metres).

Returns
Optical center in the tracker body frame in metres.

Definition at line 330 of file polhemus_coregistration.h.

◆ opticalFineAdjustApplied()

bool UTILSLIB::PolhemusCoregistration::opticalFineAdjustApplied ( ) const
inline
Returns
Whether a fine adjustment has been applied.

Definition at line 372 of file polhemus_coregistration.h.

◆ opticalFineAdjustDeg()

float UTILSLIB::PolhemusCoregistration::opticalFineAdjustDeg ( ) const
inline
Returns
The angle of the last fine adjustment (degrees).

Definition at line 378 of file polhemus_coregistration.h.

◆ opticalRayInWorld()

bool PolhemusCoregistration::opticalRayInWorld ( QVector3D & origin,
QVector3D & direction ) const

Compute the current optical axis ray in Polhemus world frame.

Parameters
[out]originRay origin (optical center in world frame).
[out]directionRay direction (optical axis in world frame, unit vector).
Returns
true if tracker data and calibration are available.

Definition at line 1004 of file polhemus_coregistration.cpp.

◆ opticalUpInWorld()

bool PolhemusCoregistration::opticalUpInWorld ( QVector3D & up) const

Returns the "up" direction of the optical path in world coordinates. This is the tracker's local Y axis rotated into the world frame, orthogonalised against the optical axis so it can be used directly as an orientation hint for projected overlays.

Parameters
[out]upUnit vector pointing "up" in the microscope view.
Returns
true if tracker data and calibration are available.

Definition at line 1030 of file polhemus_coregistration.cpp.

◆ penButtonPressed

void UTILSLIB::PolhemusCoregistration::penButtonPressed ( const QVector3D & position,
const QQuaternion & orientation )
signal

◆ penOrientation()

QQuaternion UTILSLIB::PolhemusCoregistration::penOrientation ( ) const
inline

Definition at line 526 of file polhemus_coregistration.h.

◆ penPoseChanged

void UTILSLIB::PolhemusCoregistration::penPoseChanged ( const QVector3D & position,
const QQuaternion & orientation )
signal

◆ penPosition()

QVector3D UTILSLIB::PolhemusCoregistration::penPosition ( ) const
inline

Definition at line 522 of file polhemus_coregistration.h.

◆ penStation()

int UTILSLIB::PolhemusCoregistration::penStation ( ) const
inline

Definition at line 104 of file polhemus_coregistration.h.

◆ penTipOffset()

QVector3D UTILSLIB::PolhemusCoregistration::penTipOffset ( ) const
inline

Definition at line 121 of file polhemus_coregistration.h.

◆ penVertex()

QVector3D UTILSLIB::PolhemusCoregistration::penVertex ( ) const
inline

Definition at line 466 of file polhemus_coregistration.h.

◆ pivotCalibrationDone

void UTILSLIB::PolhemusCoregistration::pivotCalibrationDone ( const QVector3D & offset,
float residualMm )
signal

◆ pivotResidualMm()

float UTILSLIB::PolhemusCoregistration::pivotResidualMm ( ) const
inline

Definition at line 186 of file polhemus_coregistration.h.

◆ pivotSampleCollected

void UTILSLIB::PolhemusCoregistration::pivotSampleCollected ( int sampleCount,
float angularSpanDeg )
signal

◆ pivotSampleCount()

int UTILSLIB::PolhemusCoregistration::pivotSampleCount ( ) const
inline

Definition at line 182 of file polhemus_coregistration.h.

◆ pivotState()

PivotState UTILSLIB::PolhemusCoregistration::pivotState ( ) const
inline

Definition at line 178 of file polhemus_coregistration.h.

◆ pivotStateChanged

void UTILSLIB::PolhemusCoregistration::pivotStateChanged ( PolhemusCoregistration::PivotState state)
signal

◆ probeOrientation()

QQuaternion UTILSLIB::PolhemusCoregistration::probeOrientation ( ) const
inline

Definition at line 539 of file polhemus_coregistration.h.

◆ probePoseChanged

void UTILSLIB::PolhemusCoregistration::probePoseChanged ( const QVector3D & position,
const QQuaternion & orientation )
signal

◆ probePosition()

QVector3D UTILSLIB::PolhemusCoregistration::probePosition ( ) const
inline

Definition at line 535 of file polhemus_coregistration.h.

◆ probeStation()

int UTILSLIB::PolhemusCoregistration::probeStation ( ) const
inline

Definition at line 108 of file polhemus_coregistration.h.

◆ registrationChanged

void UTILSLIB::PolhemusCoregistration::registrationChanged ( )
signal

◆ registrationValid()

bool UTILSLIB::PolhemusCoregistration::registrationValid ( ) const
inline

Definition at line 497 of file polhemus_coregistration.h.

◆ resetRegistration()

void PolhemusCoregistration::resetRegistration ( )

Reset the registration state (headToWorld, headToDevice) to identity. Call this when the user clears all fiducials.

Definition at line 144 of file polhemus_coregistration.cpp.

◆ restoreSessionState()

bool PolhemusCoregistration::restoreSessionState ( QSettings & settings,
const QString & prefix = QStringLiteral("polhemus") )

Definition at line 1286 of file polhemus_coregistration.cpp.

◆ saveSessionState()

void PolhemusCoregistration::saveSessionState ( QSettings & settings,
const QString & prefix = QStringLiteral("polhemus") ) const

Definition at line 1201 of file polhemus_coregistration.cpp.

◆ setAxisMirror()

void UTILSLIB::PolhemusCoregistration::setAxisMirror ( bool mirrorX,
bool mirrorY )
inline

Negate X and/or Y of incoming Polhemus positions.

The Polhemus Fastrak coordinate system depends on the physical placement and orientation of the transmitter. When the transmitter is oriented such that its axes are mirrored relative to the expected neuroscience convention, enable the corresponding mirror flags here.

Parameters
[in]mirrorXTrue to negate the X coordinate of incoming positions.
[in]mirrorYTrue to negate the Y coordinate of incoming positions.

Definition at line 150 of file polhemus_coregistration.h.

◆ setConnection()

void PolhemusCoregistration::setConnection ( PolhemusConnection * conn)

Definition at line 70 of file polhemus_coregistration.cpp.

◆ setKnownTrackerToObjectiveDistance()

void UTILSLIB::PolhemusCoregistration::setKnownTrackerToObjectiveDistance ( float metres)
inline

Set the known perpendicular distance from tracker sensor to the objective center (metres).

When nonzero, the solver constrains the optical center to lie at this distance from the tracker origin, vastly improving accuracy. Default: 0.200 m (~200 mm for ZEISS Kinevo). Set to 0 to disable.

Parameters
[in]metresTracker-to-objective distance in metres; 0 disables the constraint.

Definition at line 300 of file polhemus_coregistration.h.

◆ setModelFiducial()

void PolhemusCoregistration::setModelFiducial ( FiducialId id,
const QVector3D & posInModel )

Definition at line 158 of file polhemus_coregistration.cpp.

◆ setModelVertex()

void UTILSLIB::PolhemusCoregistration::setModelVertex ( const QVector3D & pos)
inline

Definition at line 447 of file polhemus_coregistration.h.

◆ setPenStation()

void PolhemusCoregistration::setPenStation ( int station)

Definition at line 49 of file polhemus_coregistration.cpp.

◆ setPenTipOffset()

void UTILSLIB::PolhemusCoregistration::setPenTipOffset ( const QVector3D & offset)
inline

Definition at line 117 of file polhemus_coregistration.h.

◆ setProbeStation()

void PolhemusCoregistration::setProbeStation ( int station)

Definition at line 54 of file polhemus_coregistration.cpp.

◆ setTipOffsetEnabled()

void UTILSLIB::PolhemusCoregistration::setTipOffsetEnabled ( bool on)
inline

Definition at line 125 of file polhemus_coregistration.h.

◆ setTrackerStation()

void PolhemusCoregistration::setTrackerStation ( int station)

Definition at line 44 of file polhemus_coregistration.cpp.

◆ setTrackerToDeviceOffset()

void PolhemusCoregistration::setTrackerToDeviceOffset ( const QVector3D & translation,
const QQuaternion & rotation )

Set the rigid offset from the tracker sensor body frame to the device frame.

Parameters
translationTranslation in metres, expressed in the tracker body frame.
rotationRotation from tracker body frame to device frame.

Definition at line 61 of file polhemus_coregistration.cpp.

◆ solveOpticalCalibration()

bool PolhemusCoregistration::solveOpticalCalibration ( )

Fit a 3D line through the focus points in tracker-local frame.

Requires at least 2 samples. Computes the optical axis direction and the optical center offset in the tracker body frame.

Returns
true on success; false if insufficient or degenerate data.

Definition at line 755 of file polhemus_coregistration.cpp.

◆ startPivotCalibration()

void PolhemusCoregistration::startPivotCalibration ( )

Definition at line 533 of file polhemus_coregistration.cpp.

◆ tipOffsetEnabled()

bool UTILSLIB::PolhemusCoregistration::tipOffsetEnabled ( ) const
inline

Definition at line 129 of file polhemus_coregistration.h.

◆ trackerStation()

int UTILSLIB::PolhemusCoregistration::trackerStation ( ) const
inline

Definition at line 100 of file polhemus_coregistration.h.

◆ trackerToDeviceRotation()

QQuaternion UTILSLIB::PolhemusCoregistration::trackerToDeviceRotation ( ) const
inline

Definition at line 209 of file polhemus_coregistration.h.

◆ trackerToDeviceTranslation()

QVector3D UTILSLIB::PolhemusCoregistration::trackerToDeviceTranslation ( ) const
inline

Definition at line 205 of file polhemus_coregistration.h.

◆ worldToModel()

QMatrix4x4 UTILSLIB::PolhemusCoregistration::worldToModel ( ) const
inline

Definition at line 518 of file polhemus_coregistration.h.


The documentation for this class was generated from the following files: