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 82 of file polhemus_coregistration.h.

Inheritance diagram for UTILSLIB::PolhemusCoregistration:

Member Enumeration Documentation

PivotState

enum class UTILSLIB::PolhemusCoregistration::PivotState

strong

Enumerator
Idle
WaitingForStart
Collecting
Done

Definition at line 132 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 301 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

	targetWorldPos	Desired focus point in Polhemus world frame.
[out]	correctionDeg	Angle 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 1027 of file polhemus_coregistration.cpp.

cancelPivotCalibration()

void PolhemusCoregistration::cancelPivotCalibration

(

)

Definition at line 528 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 186 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 695 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 621 of file polhemus_coregistration.cpp.

clearObjectiveCenter()

void PolhemusCoregistration::clearObjectiveCenter

(

)

Clear the captured objective center.

Definition at line 734 of file polhemus_coregistration.cpp.

clearOpticalCalibSamples()

void PolhemusCoregistration::clearOpticalCalibSamples

(

)

Discard all calibration samples and reset the optical calibration.

Definition at line 684 of file polhemus_coregistration.cpp.

clearOpticalFineAdjust()

void PolhemusCoregistration::clearOpticalFineAdjust

(

)

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

Definition at line 1097 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 200 of file polhemus_coregistration.cpp.

connection()

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

inline

Definition at line 295 of file polhemus_coregistration.h.

devicePoseChanged

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

signal

deviceToWorld()

QMatrix4x4 UTILSLIB::PolhemusCoregistration::deviceToWorld ( ) const

inline

Definition at line 365 of file polhemus_coregistration.h.

hasAllModelFiducials()

bool PolhemusCoregistration::hasAllModelFiducials

(

)

const

Definition at line 169 of file polhemus_coregistration.cpp.

hasAllPenFiducials()

bool PolhemusCoregistration::hasAllPenFiducials

(

)

const

Definition at line 179 of file polhemus_coregistration.cpp.

hasModelFiducial()

bool PolhemusCoregistration::hasModelFiducial

(

FiducialId

id

)

const

Definition at line 164 of file polhemus_coregistration.cpp.

hasModelVertex()

bool UTILSLIB::PolhemusCoregistration::hasModelVertex ( ) const

inline

Definition at line 326 of file polhemus_coregistration.h.

hasObjectiveCenter()

bool UTILSLIB::PolhemusCoregistration::hasObjectiveCenter ( ) const

inline

Returns

Whether an objective center has been captured.

Definition at line 201 of file polhemus_coregistration.h.

hasPenVertex()

bool UTILSLIB::PolhemusCoregistration::hasPenVertex ( ) const

inline

Definition at line 330 of file polhemus_coregistration.h.

haveLivePenPosition()

bool UTILSLIB::PolhemusCoregistration::haveLivePenPosition ( ) const

inline

Definition at line 371 of file polhemus_coregistration.h.

haveLiveProbePosition()

bool UTILSLIB::PolhemusCoregistration::haveLiveProbePosition ( ) const

inline

Definition at line 375 of file polhemus_coregistration.h.

headToDevice()

QMatrix4x4 UTILSLIB::PolhemusCoregistration::headToDevice ( ) const

inline

Definition at line 367 of file polhemus_coregistration.h.

headToWorld()

QMatrix4x4 UTILSLIB::PolhemusCoregistration::headToWorld ( ) const

inline

Definition at line 366 of file polhemus_coregistration.h.

knownTrackerToObjectiveDistance()

float UTILSLIB::PolhemusCoregistration::knownTrackerToObjectiveDistance ( ) const

inline

Definition at line 228 of file polhemus_coregistration.h.

mirrorX()

bool UTILSLIB::PolhemusCoregistration::mirrorX ( ) const

inline

Definition at line 125 of file polhemus_coregistration.h.

mirrorY()

bool UTILSLIB::PolhemusCoregistration::mirrorY ( ) const

inline

Definition at line 126 of file polhemus_coregistration.h.

modelFiducial()

QVector3D PolhemusCoregistration::modelFiducial

(

FiducialId

id

)

const

Definition at line 174 of file polhemus_coregistration.cpp.

modelVertex()

QVector3D UTILSLIB::PolhemusCoregistration::modelVertex ( ) const

inline

Definition at line 327 of file polhemus_coregistration.h.

objectiveCenterLocal()

QVector3D UTILSLIB::PolhemusCoregistration::objectiveCenterLocal ( ) const

inline

Captured objective center in tracker body frame (metres).

Definition at line 207 of file polhemus_coregistration.h.

opticalAxisLocal()

QVector3D UTILSLIB::PolhemusCoregistration::opticalAxisLocal ( ) const

inline

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

Definition at line 234 of file polhemus_coregistration.h.

opticalCalibDepthSpreadMm()

float UTILSLIB::PolhemusCoregistration::opticalCalibDepthSpreadMm ( ) const

inline

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

Definition at line 243 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 231 of file polhemus_coregistration.h.

opticalCalibResidualMm()

float UTILSLIB::PolhemusCoregistration::opticalCalibResidualMm ( ) const

inline

RMS residual of the last optical calibration (mm).

Definition at line 240 of file polhemus_coregistration.h.

opticalCalibSampleCount()

int UTILSLIB::PolhemusCoregistration::opticalCalibSampleCount ( ) const

inline

Returns

Number of calibration samples recorded so far.

Definition at line 183 of file polhemus_coregistration.h.

opticalCenterLocal()

QVector3D UTILSLIB::PolhemusCoregistration::opticalCenterLocal ( ) const

inline

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

Definition at line 237 of file polhemus_coregistration.h.

opticalFineAdjustApplied()

bool UTILSLIB::PolhemusCoregistration::opticalFineAdjustApplied ( ) const

inline

Returns

Whether a fine adjustment has been applied.

Definition at line 262 of file polhemus_coregistration.h.

opticalFineAdjustDeg()

float UTILSLIB::PolhemusCoregistration::opticalFineAdjustDeg ( ) const

inline

Returns

The angle of the last fine adjustment (degrees).

Definition at line 265 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]	origin	Ray origin (optical center in world frame).
[out]	direction	Ray direction (optical axis in world frame, unit vector).

Returns

true if tracker data and calibration are available.

Definition at line 978 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]

up

Unit vector pointing "up" in the microscope view.

Returns

true if tracker data and calibration are available.

Definition at line 1002 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 370 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 369 of file polhemus_coregistration.h.

penStation()

int UTILSLIB::PolhemusCoregistration::penStation ( ) const

inline

Definition at line 99 of file polhemus_coregistration.h.

penTipOffset()

QVector3D UTILSLIB::PolhemusCoregistration::penTipOffset ( ) const

inline

Definition at line 107 of file polhemus_coregistration.h.

penVertex()

QVector3D UTILSLIB::PolhemusCoregistration::penVertex ( ) const

inline

Definition at line 331 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 138 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 137 of file polhemus_coregistration.h.

pivotState()

PivotState UTILSLIB::PolhemusCoregistration::pivotState ( ) const

inline

Definition at line 136 of file polhemus_coregistration.h.

pivotStateChanged

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

signal

probeOrientation()

QQuaternion UTILSLIB::PolhemusCoregistration::probeOrientation ( ) const

inline

Definition at line 374 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 373 of file polhemus_coregistration.h.

probeStation()

int UTILSLIB::PolhemusCoregistration::probeStation ( ) const

inline

Definition at line 100 of file polhemus_coregistration.h.

registrationChanged

void UTILSLIB::PolhemusCoregistration::registrationChanged ( )

signal

registrationValid()

bool UTILSLIB::PolhemusCoregistration::registrationValid ( ) const

inline

Definition at line 359 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 1249 of file polhemus_coregistration.cpp.

saveSessionState()

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

Definition at line 1166 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.

Definition at line 124 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.

Definition at line 227 of file polhemus_coregistration.h.

setModelFiducial()

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

Definition at line 157 of file polhemus_coregistration.cpp.

setModelVertex()

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

inline

Definition at line 325 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 106 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 108 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

translation	Translation in metres, expressed in the tracker body frame.
rotation	Rotation 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 740 of file polhemus_coregistration.cpp.

startPivotCalibration()

void PolhemusCoregistration::startPivotCalibration

(

)

Definition at line 518 of file polhemus_coregistration.cpp.

tipOffsetEnabled()

bool UTILSLIB::PolhemusCoregistration::tipOffsetEnabled ( ) const

inline

Definition at line 109 of file polhemus_coregistration.h.

trackerStation()

int UTILSLIB::PolhemusCoregistration::trackerStation ( ) const

inline

Definition at line 98 of file polhemus_coregistration.h.

trackerToDeviceRotation()

QQuaternion UTILSLIB::PolhemusCoregistration::trackerToDeviceRotation ( ) const

inline

Definition at line 155 of file polhemus_coregistration.h.

trackerToDeviceTranslation()

QVector3D UTILSLIB::PolhemusCoregistration::trackerToDeviceTranslation ( ) const

inline

Definition at line 154 of file polhemus_coregistration.h.

worldToModel()

QMatrix4x4 UTILSLIB::PolhemusCoregistration::worldToModel ( ) const

inline

Definition at line 368 of file polhemus_coregistration.h.

---

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

• src/libraries/utils/polhemus/polhemus_coregistration.h
• src/libraries/utils/polhemus/polhemus_coregistration.cpp