@jspsych/plugin-tobii-calibration 0.1.1

package/src/calibration-display.ts

@@ -0,0 +1,359 @@
+/**
+ * Calibration display component
+ */
+
+import type { CalibrationPoint, CalibrationParameters } from './types';
+
+export class CalibrationDisplay {
+  private container: HTMLElement;
+  private currentPoint: HTMLElement | null = null;
+  private progressElement: HTMLElement | null = null;
+  private currentX: number = 0.5; // Start at center
+  private currentY: number = 0.5;
+
+  constructor(
+    private displayElement: HTMLElement,
+    private params: CalibrationParameters
+  ) {
+    this.container = this.createContainer();
+    this.displayElement.appendChild(this.container);
+
+    if (params.show_progress) {
+      this.progressElement = this.createProgressIndicator();
+      this.displayElement.appendChild(this.progressElement);
+    }
+  }
+
+  /**
+   * Create container element
+   */
+  private createContainer(): HTMLElement {
+    const container = document.createElement('div');
+    container.className = 'tobii-calibration-container';
+    return container;
+  }
+
+  /**
+   * Create progress indicator
+   */
+  private createProgressIndicator(): HTMLElement {
+    const progress = document.createElement('div');
+    progress.className = 'tobii-calibration-progress';
+    progress.setAttribute('role', 'status');
+    progress.setAttribute('aria-live', 'polite');
+    return progress;
+  }
+
+  /**
+   * Show instructions
+   */
+  async showInstructions(): Promise<void> {
+    const wrapper = document.createElement('div');
+    wrapper.className = 'tobii-calibration-instructions';
+    wrapper.setAttribute('role', 'dialog');
+    wrapper.setAttribute('aria-label', 'Eye tracker calibration instructions');
+
+    const content = document.createElement('div');
+    content.className = 'instructions-content';
+
+    const heading = document.createElement('h2');
+    heading.textContent = 'Eye Tracker Calibration';
+    content.appendChild(heading);
+
+    const paragraph = document.createElement('p');
+    paragraph.innerHTML =
+      this.params.instructions || 'Look at each point and follow the instructions.';
+    content.appendChild(paragraph);
+
+    if (this.params.calibration_mode === 'click') {
+      const button = document.createElement('button');
+      button.className = 'calibration-start-btn';
+      button.textContent = this.params.button_text || 'Start Calibration';
+      content.appendChild(button);
+    } else {
+      const autoMsg = document.createElement('p');
+      autoMsg.textContent = 'Starting in a moment...';
+      content.appendChild(autoMsg);
+    }
+
+    wrapper.appendChild(content);
+    this.container.appendChild(wrapper);
+
+    if (this.params.calibration_mode === 'click') {
+      return new Promise((resolve) => {
+        const button = wrapper.querySelector('button');
+        button?.addEventListener('click', () => {
+          wrapper.remove();
+          resolve();
+        });
+      });
+    } else {
+      await this.delay(this.params.instruction_display_duration || 3000);
+      wrapper.remove();
+    }
+  }
+
+  /**
+   * Initialize the traveling point at screen center
+   */
+  async initializePoint(): Promise<void> {
+    if (this.currentPoint) return;
+
+    this.currentPoint = document.createElement('div');
+    this.currentPoint.className = 'tobii-calibration-point';
+    this.currentPoint.setAttribute('role', 'img');
+    this.currentPoint.setAttribute('aria-label', 'Calibration target point');
+
+    // Start at center
+    const x = 0.5 * window.innerWidth;
+    const y = 0.5 * window.innerHeight;
+    this.currentX = 0.5;
+    this.currentY = 0.5;
+
+    Object.assign(this.currentPoint.style, {
+      left: `${x}px`,
+      top: `${y}px`,
+      width: `${this.params.point_size || 20}px`,
+      height: `${this.params.point_size || 20}px`,
+      backgroundColor: this.params.point_color || '#ff0000',
+      transition: 'none',
+    });
+
+    this.container.appendChild(this.currentPoint);
+
+    // Brief pause to show point at center before traveling
+    await this.delay(this.params.zoom_duration || 300);
+  }
+
+  /**
+   * Travel to the next point location with smooth animation
+   */
+  async travelToPoint(point: CalibrationPoint, index: number, total: number): Promise<void> {
+    if (!this.currentPoint) {
+      await this.initializePoint();
+    }
+
+    // Update progress
+    if (this.progressElement) {
+      this.progressElement.textContent = `Point ${index + 1} of ${total}`;
+    }
+
+    // Update aria-label with current point number
+    this.currentPoint!.setAttribute(
+      'aria-label',
+      `Calibration target point ${index + 1} of ${total}`
+    );
+
+    // Calculate travel distance for dynamic duration
+    const dx = point.x - this.currentX;
+    const dy = point.y - this.currentY;
+    const distance = Math.sqrt(dx * dx + dy * dy);
+
+    // Travel duration: 150ms base + 200ms per normalized unit distance (quick travel)
+    const travelDuration = Math.max(150, Math.min(400, 150 + distance * 200));
+
+    // Convert normalized coordinates to pixels
+    const x = point.x * window.innerWidth;
+    const y = point.y * window.innerHeight;
+
+    // Set up travel transition
+    this.currentPoint!.style.transition = `left ${travelDuration}ms ease-in-out, top ${travelDuration}ms ease-in-out`;
+    this.currentPoint!.classList.remove(
+      'animation-explosion',
+      'animation-shrink',
+      'animation-pulse',
+      'animation-zoom-out',
+      'animation-zoom-in'
+    );
+
+    // Move to new position
+    this.currentPoint!.style.left = `${x}px`;
+    this.currentPoint!.style.top = `${y}px`;
+
+    // Update current position
+    this.currentX = point.x;
+    this.currentY = point.y;
+
+    // Wait for travel to complete
+    await this.delay(travelDuration);
+  }
+
+  /**
+   * Play zoom out animation (point grows larger)
+   */
+  async playZoomOut(): Promise<void> {
+    if (!this.currentPoint) return;
+
+    this.currentPoint.style.transition = 'none';
+    this.currentPoint.classList.remove(
+      'animation-shrink',
+      'animation-pulse',
+      'animation-explosion',
+      'animation-zoom-in'
+    );
+    this.currentPoint.classList.add('animation-zoom-out');
+
+    await this.delay(this.params.zoom_duration || 300);
+  }
+
+  /**
+   * Play zoom in animation (point shrinks to fixation size)
+   */
+  async playZoomIn(): Promise<void> {
+    if (!this.currentPoint) return;
+
+    this.currentPoint.classList.remove('animation-zoom-out');
+    this.currentPoint.classList.add('animation-zoom-in');
+
+    await this.delay(this.params.zoom_duration || 300);
+  }
+
+  /**
+   * Play explosion animation on the current point
+   */
+  async playExplosion(success: boolean): Promise<void> {
+    if (!this.currentPoint) return;
+
+    // Remove any existing animation classes
+    this.currentPoint.classList.remove('animation-pulse', 'animation-shrink');
+
+    // Add explosion animation class
+    this.currentPoint.classList.add('animation-explosion');
+
+    // Change color based on success
+    if (success) {
+      this.currentPoint.style.backgroundColor = '#4ade80'; // green
+    } else {
+      this.currentPoint.style.backgroundColor = '#f87171'; // red
+    }
+
+    // Wait for animation to complete
+    await this.delay(this.params.explosion_duration || 400);
+  }
+
+  /**
+   * Hide current calibration point (removes element)
+   */
+  async hidePoint(): Promise<void> {
+    if (this.currentPoint) {
+      this.currentPoint.remove();
+      this.currentPoint = null;
+    }
+    await this.delay(200);
+  }
+
+  /**
+   * Reset point state after explosion (keeps element for continued travel)
+   */
+  async resetPointAfterExplosion(): Promise<void> {
+    if (!this.currentPoint) return;
+
+    // Reset to normal size and opacity for next travel
+    this.currentPoint.classList.remove('animation-explosion');
+    this.currentPoint.style.transform = 'translate(-50%, -50%) scale(1)';
+    this.currentPoint.style.opacity = '1';
+    this.currentPoint.style.backgroundColor = this.params.point_color || '#ff0000';
+
+    await this.delay(50);
+  }
+
+  /**
+   * Wait for user click (in click mode)
+   */
+  waitForClick(): Promise<void> {
+    return new Promise((resolve) => {
+      const handleClick = () => {
+        document.removeEventListener('click', handleClick);
+        resolve();
+      };
+      document.addEventListener('click', handleClick);
+    });
+  }
+
+  /**
+   * Show calibration result
+   * @param success Whether calibration succeeded
+   * @param canRetry Whether a retry button should be shown on failure
+   * @returns 'retry' if user chose to retry, 'continue' otherwise
+   */
+  async showResult(success: boolean, canRetry: boolean = false): Promise<'retry' | 'continue'> {
+    const result = document.createElement('div');
+    result.className = 'tobii-calibration-result';
+    result.setAttribute('role', 'alert');
+    result.setAttribute('aria-live', 'assertive');
+
+    if (success) {
+      result.innerHTML = `
+        <div class="tobii-calibration-result-content success">
+          <h2>Calibration Successful!</h2>
+          <p>Continuing automatically...</p>
+        </div>
+      `;
+
+      this.container.appendChild(result);
+
+      // Auto-advance after showing result
+      await this.delay(this.params.success_display_duration || 2000);
+      result.remove();
+      return 'continue';
+    }
+
+    // Failure case: show buttons
+    const buttonsHTML = canRetry
+      ? `<button class="calibration-retry-btn">Retry</button>
+         <button class="calibration-continue-btn" style="margin-left: 10px;">Continue</button>`
+      : `<button class="calibration-continue-btn">Continue</button>`;
+
+    result.innerHTML = `
+      <div class="tobii-calibration-result-content error">
+        <h2>Calibration Failed</h2>
+        <p>Please try again or continue.</p>
+        ${buttonsHTML}
+      </div>
+    `;
+
+    this.container.appendChild(result);
+
+    return new Promise((resolve) => {
+      const retryBtn = result.querySelector('.calibration-retry-btn');
+      const continueBtn = result.querySelector('.calibration-continue-btn');
+
+      retryBtn?.addEventListener('click', () => {
+        result.remove();
+        resolve('retry');
+      });
+
+      continueBtn?.addEventListener('click', () => {
+        result.remove();
+        resolve('continue');
+      });
+    });
+  }
+
+  /**
+   * Reset display state for a retry attempt
+   */
+  resetForRetry(): void {
+    this.container.innerHTML = '';
+    this.currentPoint = null;
+    this.currentX = 0.5;
+    this.currentY = 0.5;
+  }
+
+  /**
+   * Clear display
+   */
+  clear(): void {
+    this.container.innerHTML = '';
+    if (this.progressElement) {
+      this.progressElement.textContent = '';
+    }
+  }
+
+  /**
+   * Delay helper
+   */
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,297 @@
+/**
+ * @title Tobii Calibration
+ * @description jsPsych plugin for Tobii eye tracker calibration. Provides a visual
+ * calibration procedure with animated points and real-time feedback.
+ * @version 1.0.0
+ * @author jsPsych Team
+ * @see {@link https://github.com/jspsych/jspsych-tobii/tree/main/packages/plugin-tobii-calibration#readme Documentation}
+ */
+import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from 'jspsych';
+declare const info: {
+    readonly name: "tobii-calibration";
+    readonly version: string;
+    readonly parameters: {
+        /** Number of calibration points (5 or 9) */
+        readonly calibration_points: {
+            readonly type: ParameterType.INT;
+            readonly default: 9;
+        };
+        /** Calibration mode: click or view */
+        readonly calibration_mode: {
+            readonly type: ParameterType.STRING;
+            readonly default: "view";
+        };
+        /** Size of calibration points in pixels */
+        readonly point_size: {
+            readonly type: ParameterType.INT;
+            readonly default: 20;
+        };
+        /** Color of calibration points */
+        readonly point_color: {
+            readonly type: ParameterType.STRING;
+            readonly default: "#ff0000";
+        };
+        /** Duration to show each point before data collection (ms) - allows user to fixate */
+        readonly point_duration: {
+            readonly type: ParameterType.INT;
+            readonly default: 500;
+        };
+        /** Show progress indicator */
+        readonly show_progress: {
+            readonly type: ParameterType.BOOL;
+            readonly default: true;
+        };
+        /** Custom calibration points */
+        readonly custom_points: {
+            readonly type: ParameterType.COMPLEX;
+            readonly default: null;
+        };
+        /** Instructions text */
+        readonly instructions: {
+            readonly type: ParameterType.STRING;
+            readonly default: "Look at each point as it appears on the screen. Keep your gaze fixed on each point until it disappears.";
+        };
+        /** Button text for click mode */
+        readonly button_text: {
+            readonly type: ParameterType.STRING;
+            readonly default: "Start Calibration";
+        };
+        /** Background color of the calibration container */
+        readonly background_color: {
+            readonly type: ParameterType.STRING;
+            readonly default: "#808080";
+        };
+        /** Primary button color */
+        readonly button_color: {
+            readonly type: ParameterType.STRING;
+            readonly default: "#007bff";
+        };
+        /** Primary button hover color */
+        readonly button_hover_color: {
+            readonly type: ParameterType.STRING;
+            readonly default: "#0056b3";
+        };
+        /** Retry button color */
+        readonly retry_button_color: {
+            readonly type: ParameterType.STRING;
+            readonly default: "#dc3545";
+        };
+        /** Retry button hover color */
+        readonly retry_button_hover_color: {
+            readonly type: ParameterType.STRING;
+            readonly default: "#c82333";
+        };
+        /** Success message color */
+        readonly success_color: {
+            readonly type: ParameterType.STRING;
+            readonly default: "#28a745";
+        };
+        /** Error message color */
+        readonly error_color: {
+            readonly type: ParameterType.STRING;
+            readonly default: "#dc3545";
+        };
+        /** Maximum number of retry attempts allowed on calibration failure */
+        readonly max_retries: {
+            readonly type: ParameterType.INT;
+            readonly default: 1;
+        };
+        /** Duration of zoom in/out animations in ms */
+        readonly zoom_duration: {
+            readonly type: ParameterType.INT;
+            readonly default: 300;
+        };
+        /** Duration of explosion animation in ms */
+        readonly explosion_duration: {
+            readonly type: ParameterType.INT;
+            readonly default: 400;
+        };
+        /** Duration to show success result before auto-advancing in ms */
+        readonly success_display_duration: {
+            readonly type: ParameterType.INT;
+            readonly default: 2000;
+        };
+        /** Duration to show instructions before auto-advancing in view mode in ms */
+        readonly instruction_display_duration: {
+            readonly type: ParameterType.INT;
+            readonly default: 3000;
+        };
+    };
+    readonly data: {
+        /** Calibration success status */
+        readonly calibration_success: {
+            readonly type: ParameterType.BOOL;
+        };
+        /** Number of calibration points used */
+        readonly num_points: {
+            readonly type: ParameterType.INT;
+        };
+        /** Calibration mode used */
+        readonly mode: {
+            readonly type: ParameterType.STRING;
+        };
+        /** Full calibration result data */
+        readonly calibration_data: {
+            readonly type: ParameterType.COMPLEX;
+        };
+        /** Number of calibration attempts made */
+        readonly num_attempts: {
+            readonly type: ParameterType.INT;
+        };
+    };
+};
+type Info = typeof info;
+declare class TobiiCalibrationPlugin implements JsPsychPlugin<Info> {
+    private jsPsych;
+    static info: {
+        readonly name: "tobii-calibration";
+        readonly version: string;
+        readonly parameters: {
+            /** Number of calibration points (5 or 9) */
+            readonly calibration_points: {
+                readonly type: ParameterType.INT;
+                readonly default: 9;
+            };
+            /** Calibration mode: click or view */
+            readonly calibration_mode: {
+                readonly type: ParameterType.STRING;
+                readonly default: "view";
+            };
+            /** Size of calibration points in pixels */
+            readonly point_size: {
+                readonly type: ParameterType.INT;
+                readonly default: 20;
+            };
+            /** Color of calibration points */
+            readonly point_color: {
+                readonly type: ParameterType.STRING;
+                readonly default: "#ff0000";
+            };
+            /** Duration to show each point before data collection (ms) - allows user to fixate */
+            readonly point_duration: {
+                readonly type: ParameterType.INT;
+                readonly default: 500;
+            };
+            /** Show progress indicator */
+            readonly show_progress: {
+                readonly type: ParameterType.BOOL;
+                readonly default: true;
+            };
+            /** Custom calibration points */
+            readonly custom_points: {
+                readonly type: ParameterType.COMPLEX;
+                readonly default: null;
+            };
+            /** Instructions text */
+            readonly instructions: {
+                readonly type: ParameterType.STRING;
+                readonly default: "Look at each point as it appears on the screen. Keep your gaze fixed on each point until it disappears.";
+            };
+            /** Button text for click mode */
+            readonly button_text: {
+                readonly type: ParameterType.STRING;
+                readonly default: "Start Calibration";
+            };
+            /** Background color of the calibration container */
+            readonly background_color: {
+                readonly type: ParameterType.STRING;
+                readonly default: "#808080";
+            };
+            /** Primary button color */
+            readonly button_color: {
+                readonly type: ParameterType.STRING;
+                readonly default: "#007bff";
+            };
+            /** Primary button hover color */
+            readonly button_hover_color: {
+                readonly type: ParameterType.STRING;
+                readonly default: "#0056b3";
+            };
+            /** Retry button color */
+            readonly retry_button_color: {
+                readonly type: ParameterType.STRING;
+                readonly default: "#dc3545";
+            };
+            /** Retry button hover color */
+            readonly retry_button_hover_color: {
+                readonly type: ParameterType.STRING;
+                readonly default: "#c82333";
+            };
+            /** Success message color */
+            readonly success_color: {
+                readonly type: ParameterType.STRING;
+                readonly default: "#28a745";
+            };
+            /** Error message color */
+            readonly error_color: {
+                readonly type: ParameterType.STRING;
+                readonly default: "#dc3545";
+            };
+            /** Maximum number of retry attempts allowed on calibration failure */
+            readonly max_retries: {
+                readonly type: ParameterType.INT;
+                readonly default: 1;
+            };
+            /** Duration of zoom in/out animations in ms */
+            readonly zoom_duration: {
+                readonly type: ParameterType.INT;
+                readonly default: 300;
+            };
+            /** Duration of explosion animation in ms */
+            readonly explosion_duration: {
+                readonly type: ParameterType.INT;
+                readonly default: 400;
+            };
+            /** Duration to show success result before auto-advancing in ms */
+            readonly success_display_duration: {
+                readonly type: ParameterType.INT;
+                readonly default: 2000;
+            };
+            /** Duration to show instructions before auto-advancing in view mode in ms */
+            readonly instruction_display_duration: {
+                readonly type: ParameterType.INT;
+                readonly default: 3000;
+            };
+        };
+        readonly data: {
+            /** Calibration success status */
+            readonly calibration_success: {
+                readonly type: ParameterType.BOOL;
+            };
+            /** Number of calibration points used */
+            readonly num_points: {
+                readonly type: ParameterType.INT;
+            };
+            /** Calibration mode used */
+            readonly mode: {
+                readonly type: ParameterType.STRING;
+            };
+            /** Full calibration result data */
+            readonly calibration_data: {
+                readonly type: ParameterType.COMPLEX;
+            };
+            /** Number of calibration attempts made */
+            readonly num_attempts: {
+                readonly type: ParameterType.INT;
+            };
+        };
+    };
+    constructor(jsPsych: JsPsych);
+    private static removeStyles;
+    private injectStyles;
+    trial(display_element: HTMLElement, trial: TrialType<Info>): Promise<void>;
+    /**
+     * Validate custom calibration points
+     */
+    private validateCustomPoints;
+    /**
+     * Get standard calibration points for the given grid size
+     */
+    private getCalibrationPoints;
+    /**
+     * Delay helper
+     */
+    private delay;
+}
+export default TobiiCalibrationPlugin;
+//# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAO3E,QAAA,MAAM,IAAI;;;;QAIN,4CAA4C;;;;;QAK5C,sCAAsC;;;;;QAKtC,2CAA2C;;;;;QAK3C,kCAAkC;;;;;QAKlC,sFAAsF;;;;;QAKtF,8BAA8B;;;;;QAK9B,gCAAgC;;;;;QAKhC,wBAAwB;;;;;QAMxB,iCAAiC;;;;;QAKjC,oDAAoD;;;;;QAKpD,2BAA2B;;;;;QAK3B,iCAAiC;;;;;QAKjC,yBAAyB;;;;;QAKzB,+BAA+B;;;;;QAK/B,4BAA4B;;;;;QAK5B,0BAA0B;;;;;QAK1B,sEAAsE;;;;;QAKtE,+CAA+C;;;;;QAK/C,4CAA4C;;;;;QAK5C,kEAAkE;;;;;QAKlE,6EAA6E;;;;;;;QAO7E,iCAAiC;;;;QAIjC,wCAAwC;;;;QAIxC,4BAA4B;;;;QAI5B,mCAAmC;;;;QAInC,0CAA0C;;;;;CAK7C,CAAC;AAEF,KAAK,IAAI,GAAG,OAAO,IAAI,CAAC;AAExB,cAAM,sBAAuB,YAAW,aAAa,CAAC,IAAI,CAAC;IAG7C,OAAO,CAAC,OAAO;IAF3B,MAAM,CAAC,IAAI;;;;YAtIT,4CAA4C;;;;;YAK5C,sCAAsC;;;;;YAKtC,2CAA2C;;;;;YAK3C,kCAAkC;;;;;YAKlC,sFAAsF;;;;;YAKtF,8BAA8B;;;;;YAK9B,gCAAgC;;;;;YAKhC,wBAAwB;;;;;YAMxB,iCAAiC;;;;;YAKjC,oDAAoD;;;;;YAKpD,2BAA2B;;;;;YAK3B,iCAAiC;;;;;YAKjC,yBAAyB;;;;;YAKzB,+BAA+B;;;;;YAK/B,4BAA4B;;;;;YAK5B,0BAA0B;;;;;YAK1B,sEAAsE;;;;;YAKtE,+CAA+C;;;;;YAK/C,4CAA4C;;;;;YAK5C,kEAAkE;;;;;YAKlE,6EAA6E;;;;;;;YAO7E,iCAAiC;;;;YAIjC,wCAAwC;;;;YAIxC,4BAA4B;;;;YAI5B,mCAAmC;;;;YAInC,0CAA0C;;;;;MAUzB;gBAEC,OAAO,EAAE,OAAO;IAEpC,OAAO,CAAC,MAAM,CAAC,YAAY;IAO3B,OAAO,CAAC,YAAY;IA4Md,KAAK,CAAC,eAAe,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAuHhF;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA0B5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAqH5B;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd;AAED,eAAe,sBAAsB,CAAC"}