Methods Reference
Complete alphabetical reference of all methods in the TrialManager class. Methods are organized by category for easier navigation.
Initialization Methods
initializeExperiment()
PUBLICTop-level function that sets up event listeners and orchestrates the experiment initialization sequence.
Returns
void - No return value
initWebGazer()
ASYNCInitializes WebGazer with enhanced configuration including ridge regression, TFFacemesh tracking, and adaptive sampling.
Returns
Promise<void> - Resolves when initialization complete
initializeExclusions()
ASYNCDynamically imports object exclusion rules based on selected test type (Shapes/Colors/Abstract/Pictures).
Returns
Promise<void> - Resolves after exclusions loaded
showInitialsDialog()
ASYNCDisplays modal dialog for collecting participant initials, test type, and trial count.
Returns
Promise<void> - Resolves when dialog submitted
setupImages()
ASYNCLoads all stimulus images for selected test type. Image counts: Abstract (403), Shapes (193), Colors (10), Pictures (10).
Returns
Promise<void> - Resolves when all images loaded
Throws
Error - If unknown test type or image loading fails
Calibration Methods
startCalibrationPhase()
ASYNCExecutes 9-point calibration sequence with automatic validation and refinement.
Returns
Promise<void> - Resolves when calibration complete
validateCalibration()
ASYNCTests calibration quality at 5 validation points and returns normalized quality score (0-1).
Returns
Promise<number> - Quality score: 1 - (avgError / 200)
measureCalibrationError(point)
ASYNCMeasures average prediction error at a specific screen point by collecting 10 samples.
Parameters
Screen coordinates to test: {x: number, y: number}
Returns
Promise<number> - Average error distance in pixels
refineCalibration()
ASYNCAdds 3 refinement calibration points in high-error areas. Called automatically if quality < 0.75.
Returns
Promise<void> - Resolves when refinement complete
quickRecalibration()
ASYNCPerforms fast 3-point recalibration. Called automatically every 10 trials during experiments.
Returns
Promise<void> - Resolves when recalibration complete
runCalibrationSequence(points, showCount)
ASYNCInternal helper that displays calibration points sequentially and records clicks.
Parameters
Array of calibration points: [{x: 0-1, y: 0-1}, ...]
Whether to display remaining point counter. Default: true
Returns
Promise<void> - Resolves when all points clicked
Gaze Processing Methods
processGazeData(gazePoint, trialStartTime)
PUBLICCore gaze processing pipeline: outlier detection → head pose compensation → Kalman filtering → data enrichment → storage.
Parameters
Raw gaze coordinates: {x: number, y: number}
Trial start timestamp (milliseconds since epoch)
Returns
void - Stores data in currentGazeData and allGazeData
initKalmanFilter()
PUBLICInitializes Kalman filter states for X and Y coordinates with tuned parameters (q=0.01, r=0.1).
Returns
void - Sets this.kalmanX and this.kalmanY
kalmanFilter(measurement, kalmanState)
PUBLICApplies Kalman filter algorithm to smooth a single coordinate measurement.
Parameters
Raw measured value (x or y coordinate)
Filter state object: {q, r, p, x, k}
Returns
number - Filtered coordinate value
compensateForHeadMovement(gazePoint, headPoseData)
PUBLICApplies head pose compensation and Kalman filtering to raw gaze coordinates.
Parameters
Raw gaze point: {x: number, y: number}
Head pose angles (currently used for logging only)
Returns
Object - Compensated coordinates: {x: number, y: number}
isOutlier(gazePoint)
PUBLICDetects outliers based on off-screen position (±100px buffer) or excessive velocity (>500px jumps).
Parameters
Gaze point to check: {x: number, y: number}
Returns
boolean - true if point is outlier, false otherwise
calculateHeadPose(faceMesh)
PUBLICCalculates head pose angles (roll, pitch, yaw) and face distance from TFFacemesh 468-point landmarks.
Parameters
Facial landmark array from TFFacemesh (468 points)
Returns
Object | null - Head pose data: {roll, pitch, yaw, distance} or null if invalid
extractHeadPoseFeatures(faceMesh)
PUBLICExtracts raw head pose angles from key facial landmarks (nose: 1, left eye: 33, right eye: 263).
Parameters
Facial landmark array
Returns
Object - Raw angles: {roll: number, pitch: number, yaw: number}
calculateFaceDistance(faceMesh)
PUBLICCalculates approximate face distance from camera using inter-eye distance as proxy.
Parameters
Facial landmark array
Returns
number - Distance metric (larger = closer to camera)
shouldProcessSample(data)
PUBLICImplements adaptive sampling: 60fps (16ms) for fast movement (>100px/s), 30fps (33ms) for slow movement.
Parameters
Gaze data with coordinates: {x: number, y: number}
Returns
boolean - true if sample should be processed, false to skip
Trial Management Methods
startExperiment()
ASYNCMain experiment loop. Executes all trials with periodic recalibration, then saves/exports data.
Returns
Promise<void> - Resolves when experiment complete and data saved
runTrial(trialType)
ASYNCExecutes a single trial: display sample object → delay → display test objects → collect gaze data → store results.
Parameters
Trial type: 1 (target + 2 identical foils) or 2 (target + 2 different foils)
Returns
Promise<void> - Resolves when trial complete
Utility Methods
seededRandom(seed)
PUBLICCreates a deterministic pseudo-random number generator seeded by participant ID.
Parameters
Seed value (typically participant ID)
Returns
Function - PRNG function returning values 0-1
generateFileName()
PUBLICGenerates data export filename with format: {INITIALS}_{ISO_TIMESTAMP}_data.json
Returns
string - Generated filename
Example Output
"PS_2025-01-26T15-30-45-123Z_data.json"shuffleArray(array)
PUBLICFisher-Yates shuffle algorithm for randomizing array order in-place.
Parameters
Array to shuffle
Returns
Array - Shuffled array (same reference)
getRandomObjectNumber(exclude)
PUBLICSelects random object number from valid range, excluding specified objects.
Parameters
Array of object numbers to exclude from selection
Returns
number - Random object number (1 to totalImages)
getExcludedObjects(objectNum)
PUBLICRetrieves list of objects that should not appear together with specified object (perceptually similar items).
Parameters
Object number to get exclusions for
Returns
Array - Array of excluded object numbers
createImage(objectNum)
PUBLICCreates HTMLImageElement for specified object with proper path and class.
Parameters
Object number (1 to totalImages)
Returns
HTMLImageElement - Configured image element
showCentered(element)
PUBLICPositions element at center of test container and displays it.
Parameters
Element to center and show
Returns
void - Modifies DOM directly
showBlackScreen(duration)
PUBLICDisplays black overlay screen for specified duration (inter-stimulus interval).
Parameters
Display duration in milliseconds. Default: 1000
Returns
void - Screen removed automatically after duration
hide(element)
PUBLICHides element by setting display style to "none".
Parameters
Element to hide
Returns
void - Modifies element style
positionTestObjects(objects)
PUBLICPositions array of 3 test objects horizontally (left, center, right) and vertically centered.
Parameters
Array of 3 HTMLElements to position
Returns
void - Modifies element positions
Layout
objects[0]: left (containerWidth/2 - 200 - 30% offset)
objects[1]: center (containerWidth/2 - 200)
objects[2]: right (containerWidth/2 - 200 + 30% offset)