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 |
Head–device coregistration engine driven by a Polhemus Fastrak.
The class wires itself to a PolhemusConnection and maintains:
Definition at line 84 of file polhemus_coregistration.h.

|
strong |
| Enumerator | |
|---|---|
| Idle | |
| WaitingForStart | |
| Collecting | |
| Done | |
Definition at line 168 of file polhemus_coregistration.h.
|
explicit |
Definition at line 33 of file polhemus_coregistration.cpp.
|
overridedefault |
|
inline |
Definition at line 420 of file polhemus_coregistration.h.
| 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.
| targetWorldPos | Desired focus point in Polhemus world frame. | |
| [out] | correctionDeg | Angle of the applied correction (degrees). |
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.
| void PolhemusCoregistration::cancelPivotCalibration | ( | ) |
Definition at line 543 of file polhemus_coregistration.cpp.
| bool PolhemusCoregistration::captureCurrentPenPositionAsFiducial | ( | FiducialId | id | ) |
Definition at line 86 of file polhemus_coregistration.cpp.
| bool PolhemusCoregistration::captureCurrentPenPositionAsHeadShape | ( | ) |
Definition at line 125 of file polhemus_coregistration.cpp.
| bool PolhemusCoregistration::captureCurrentPenPositionAsVertex | ( | ) |
Definition at line 187 of file polhemus_coregistration.cpp.
| 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.
true on success, false if pen or tracker data unavailable. Definition at line 710 of file polhemus_coregistration.cpp.
| bool PolhemusCoregistration::captureOpticalCalibSample | ( | ) |
Record one calibration sample (current tracker pose + current pen position).
true if both pen and tracker data are available, false otherwise. Definition at line 636 of file polhemus_coregistration.cpp.
| void PolhemusCoregistration::clearObjectiveCenter | ( | ) |
Clear the captured objective center.
Definition at line 749 of file polhemus_coregistration.cpp.
| void PolhemusCoregistration::clearOpticalCalibSamples | ( | ) |
Discard all calibration samples and reset the optical calibration.
Definition at line 699 of file polhemus_coregistration.cpp.
| void PolhemusCoregistration::clearOpticalFineAdjust | ( | ) |
Undo the last fine adjustment, restoring the original solved axis.
Definition at line 1130 of file polhemus_coregistration.cpp.
| bool PolhemusCoregistration::computeRegistration | ( | ) |
Compute the head→device rigid transform from the three captured fiducials (NAS, LPA, RPA).
true on success; false if any fiducial is missing or the fiducials are degenerate (collinear). Definition at line 202 of file polhemus_coregistration.cpp.
|
inline |
Definition at line 411 of file polhemus_coregistration.h.
|
signal |
|
inline |
Definition at line 506 of file polhemus_coregistration.h.
| bool PolhemusCoregistration::hasAllModelFiducials | ( | ) | const |
Definition at line 170 of file polhemus_coregistration.cpp.
| bool PolhemusCoregistration::hasAllPenFiducials | ( | ) | const |
Definition at line 180 of file polhemus_coregistration.cpp.
| bool PolhemusCoregistration::hasModelFiducial | ( | FiducialId | id | ) | const |
Definition at line 165 of file polhemus_coregistration.cpp.
|
inline |
Definition at line 452 of file polhemus_coregistration.h.
|
inline |
Definition at line 262 of file polhemus_coregistration.h.
|
inline |
Definition at line 462 of file polhemus_coregistration.h.
|
inline |
Definition at line 530 of file polhemus_coregistration.h.
|
inline |
Definition at line 543 of file polhemus_coregistration.h.
|
inline |
Definition at line 514 of file polhemus_coregistration.h.
|
inline |
Definition at line 510 of file polhemus_coregistration.h.
|
inline |
Definition at line 304 of file polhemus_coregistration.h.
|
inline |
Definition at line 155 of file polhemus_coregistration.h.
|
inline |
Definition at line 159 of file polhemus_coregistration.h.
| QVector3D PolhemusCoregistration::modelFiducial | ( | FiducialId | id | ) | const |
Definition at line 175 of file polhemus_coregistration.cpp.
|
inline |
Definition at line 456 of file polhemus_coregistration.h.
|
inline |
Captured objective center in tracker body frame (metres).
Definition at line 275 of file polhemus_coregistration.h.
|
inline |
Direction of the optical axis in the tracker body frame (unit vector).
Definition at line 320 of file polhemus_coregistration.h.
|
inline |
Depth spread of calibration samples along the optical axis (mm).
Definition at line 350 of file polhemus_coregistration.h.
|
signal |
|
inline |
Definition at line 310 of file polhemus_coregistration.h.
|
inline |
RMS residual of the last optical calibration (mm).
Definition at line 340 of file polhemus_coregistration.h.
|
inline |
Definition at line 241 of file polhemus_coregistration.h.
|
inline |
Position of the optical center in the tracker body frame (metres).
Definition at line 330 of file polhemus_coregistration.h.
|
inline |
Definition at line 372 of file polhemus_coregistration.h.
|
inline |
Definition at line 378 of file polhemus_coregistration.h.
| bool PolhemusCoregistration::opticalRayInWorld | ( | QVector3D & | origin, |
| QVector3D & | direction ) const |
Compute the current optical axis ray in Polhemus world frame.
| [out] | origin | Ray origin (optical center in world frame). |
| [out] | direction | Ray direction (optical axis in world frame, unit vector). |
true if tracker data and calibration are available. Definition at line 1004 of file polhemus_coregistration.cpp.
| 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.
| [out] | up | Unit vector pointing "up" in the microscope view. |
true if tracker data and calibration are available. Definition at line 1030 of file polhemus_coregistration.cpp.
|
signal |
|
inline |
Definition at line 526 of file polhemus_coregistration.h.
|
signal |
|
inline |
Definition at line 522 of file polhemus_coregistration.h.
|
inline |
Definition at line 104 of file polhemus_coregistration.h.
|
inline |
Definition at line 121 of file polhemus_coregistration.h.
|
inline |
Definition at line 466 of file polhemus_coregistration.h.
|
signal |
|
inline |
Definition at line 186 of file polhemus_coregistration.h.
|
signal |
|
inline |
Definition at line 182 of file polhemus_coregistration.h.
|
inline |
Definition at line 178 of file polhemus_coregistration.h.
|
signal |
|
inline |
Definition at line 539 of file polhemus_coregistration.h.
|
signal |
|
inline |
Definition at line 535 of file polhemus_coregistration.h.
|
inline |
Definition at line 108 of file polhemus_coregistration.h.
|
signal |
|
inline |
Definition at line 497 of file polhemus_coregistration.h.
| 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.
| bool PolhemusCoregistration::restoreSessionState | ( | QSettings & | settings, |
| const QString & | prefix = QStringLiteral("polhemus") ) |
Definition at line 1286 of file polhemus_coregistration.cpp.
| void PolhemusCoregistration::saveSessionState | ( | QSettings & | settings, |
| const QString & | prefix = QStringLiteral("polhemus") ) const |
Definition at line 1201 of file polhemus_coregistration.cpp.
|
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.
| [in] | mirrorX | True to negate the X coordinate of incoming positions. |
| [in] | mirrorY | True to negate the Y coordinate of incoming positions. |
Definition at line 150 of file polhemus_coregistration.h.
| void PolhemusCoregistration::setConnection | ( | PolhemusConnection * | conn | ) |
Definition at line 70 of file polhemus_coregistration.cpp.
|
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.
| [in] | metres | Tracker-to-objective distance in metres; 0 disables the constraint. |
Definition at line 300 of file polhemus_coregistration.h.
| void PolhemusCoregistration::setModelFiducial | ( | FiducialId | id, |
| const QVector3D & | posInModel ) |
Definition at line 158 of file polhemus_coregistration.cpp.
|
inline |
Definition at line 447 of file polhemus_coregistration.h.
| void PolhemusCoregistration::setPenStation | ( | int | station | ) |
Definition at line 49 of file polhemus_coregistration.cpp.
|
inline |
Definition at line 117 of file polhemus_coregistration.h.
| void PolhemusCoregistration::setProbeStation | ( | int | station | ) |
Definition at line 54 of file polhemus_coregistration.cpp.
|
inline |
Definition at line 125 of file polhemus_coregistration.h.
| void PolhemusCoregistration::setTrackerStation | ( | int | station | ) |
Definition at line 44 of file polhemus_coregistration.cpp.
| void PolhemusCoregistration::setTrackerToDeviceOffset | ( | const QVector3D & | translation, |
| const QQuaternion & | rotation ) |
Set the rigid offset from the tracker sensor body frame to the device frame.
| 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.
| 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.
true on success; false if insufficient or degenerate data. Definition at line 755 of file polhemus_coregistration.cpp.
| void PolhemusCoregistration::startPivotCalibration | ( | ) |
Definition at line 533 of file polhemus_coregistration.cpp.
|
inline |
Definition at line 129 of file polhemus_coregistration.h.
|
inline |
Definition at line 100 of file polhemus_coregistration.h.
|
inline |
Definition at line 209 of file polhemus_coregistration.h.
|
inline |
Definition at line 205 of file polhemus_coregistration.h.
|
inline |
Definition at line 518 of file polhemus_coregistration.h.