@jspsych/plugin-tobii-user-position 0.1.1

package/dist/index.js

@@ -0,0 +1,687 @@
+import { ParameterType } from 'jspsych';
+
+var version = "0.1.1";
+
+class PositionDisplay {
+  constructor(container, options) {
+    this.BOX_WIDTH = 400;
+    this.BOX_HEIGHT = 300;
+    this.MIN_FACE_SCALE = 0.4;
+    this.MAX_FACE_SCALE = 1.6;
+    this.OPTIMAL_FACE_SCALE = 1;
+    this.container = container;
+    this.options = options;
+    this.createDisplay();
+  }
+  createDisplay() {
+    this.container.innerHTML = "";
+    this.messageElement = document.createElement("div");
+    this.messageElement.className = "tobii-user-position-message";
+    this.messageElement.textContent = this.options.message;
+    this.container.appendChild(this.messageElement);
+    const guideContainer = document.createElement("div");
+    guideContainer.className = "tobii-user-position-guide";
+    this.container.appendChild(guideContainer);
+    this.trackingBoxElement = document.createElement("div");
+    this.trackingBoxElement.className = "tobii-tracking-box";
+    this.trackingBoxElement.setAttribute("role", "img");
+    this.trackingBoxElement.setAttribute("aria-label", "Head position tracking display");
+    this.trackingBoxElement.style.cssText = `
+      position: relative;
+      width: ${this.BOX_WIDTH}px;
+      height: ${this.BOX_HEIGHT}px;
+      border: 3px solid #666;
+      border-radius: 12px;
+      background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+      overflow: hidden;
+      box-shadow: inset 0 0 30px rgba(0,0,0,0.5);
+    `;
+    guideContainer.appendChild(this.trackingBoxElement);
+    const optimalZone = document.createElement("div");
+    optimalZone.style.cssText = `
+      position: absolute;
+      top: 50%;
+      left: 50%;
+      transform: translate(-50%, -50%);
+      width: 60%;
+      height: 70%;
+      border: 2px dashed rgba(255,255,255,0.2);
+      border-radius: 8px;
+    `;
+    this.trackingBoxElement.appendChild(optimalZone);
+    this.faceOutlineElement = document.createElement("div");
+    this.faceOutlineElement.className = "tobii-face-outline";
+    this.faceOutlineElement.setAttribute("aria-hidden", "true");
+    this.faceOutlineElement.style.cssText = `
+      position: absolute;
+      top: 50%;
+      left: 50%;
+      transform: translate(-50%, -50%);
+      transition: all 0.1s ease-out;
+    `;
+    this.trackingBoxElement.appendChild(this.faceOutlineElement);
+    this.createFaceSVG();
+    if (this.options.showDistanceFeedback) {
+      this.distanceBarContainer = document.createElement("div");
+      this.distanceBarContainer.style.cssText = `
+        position: absolute;
+        right: -40px;
+        top: 10%;
+        width: 20px;
+        height: 80%;
+        background: rgba(0,0,0,0.3);
+        border-radius: 10px;
+        border: 2px solid #444;
+        overflow: hidden;
+      `;
+      guideContainer.appendChild(this.distanceBarContainer);
+      const closeLabel = document.createElement("div");
+      closeLabel.textContent = "Close";
+      closeLabel.style.cssText = `
+        position: absolute;
+        right: -70px;
+        top: 0;
+        font-size: 10px;
+        color: #888;
+      `;
+      guideContainer.appendChild(closeLabel);
+      const farLabel = document.createElement("div");
+      farLabel.textContent = "Far";
+      farLabel.style.cssText = `
+        position: absolute;
+        right: -55px;
+        bottom: 10%;
+        font-size: 10px;
+        color: #888;
+      `;
+      guideContainer.appendChild(farLabel);
+      this.distanceBarFill = document.createElement("div");
+      this.distanceBarFill.style.cssText = `
+        position: absolute;
+        bottom: 0;
+        left: 0;
+        width: 100%;
+        height: 50%;
+        background: ${this.options.goodColor};
+        border-radius: 8px;
+        transition: all 0.1s ease-out;
+      `;
+      this.distanceBarContainer.appendChild(this.distanceBarFill);
+      const optimalMarker = document.createElement("div");
+      optimalMarker.style.cssText = `
+        position: absolute;
+        left: -2px;
+        right: -2px;
+        top: 40%;
+        height: 20%;
+        border: 2px solid rgba(255,255,255,0.5);
+        border-radius: 4px;
+        pointer-events: none;
+      `;
+      this.distanceBarContainer.appendChild(optimalMarker);
+    }
+    this.feedbackElement = document.createElement("div");
+    this.feedbackElement.className = "tobii-position-feedback";
+    this.feedbackElement.setAttribute("role", "status");
+    this.feedbackElement.setAttribute("aria-live", "polite");
+    this.feedbackElement.style.cssText = `
+      margin-top: 20px;
+      font-size: 1.1em;
+      font-weight: 600;
+      text-align: center;
+    `;
+    this.container.appendChild(this.feedbackElement);
+  }
+  createFaceSVG() {
+    const baseWidth = 120;
+    const baseHeight = 150;
+    const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    svg.setAttribute("width", `${baseWidth}`);
+    svg.setAttribute("height", `${baseHeight}`);
+    svg.setAttribute("viewBox", `0 0 ${baseWidth} ${baseHeight}`);
+    svg.style.cssText = "overflow: visible;";
+    const faceOutline = document.createElementNS("http://www.w3.org/2000/svg", "ellipse");
+    faceOutline.setAttribute("cx", "60");
+    faceOutline.setAttribute("cy", "80");
+    faceOutline.setAttribute("rx", "50");
+    faceOutline.setAttribute("ry", "65");
+    faceOutline.setAttribute("fill", "none");
+    faceOutline.setAttribute("stroke", "#888");
+    faceOutline.setAttribute("stroke-width", "3");
+    faceOutline.setAttribute("stroke-dasharray", "8,4");
+    svg.appendChild(faceOutline);
+    this.leftEyeElement = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+    this.leftEyeElement.setAttribute("cx", "40");
+    this.leftEyeElement.setAttribute("cy", "65");
+    this.leftEyeElement.setAttribute("r", "12");
+    this.leftEyeElement.setAttribute("fill", this.options.poorColor);
+    this.leftEyeElement.setAttribute("stroke", "#fff");
+    this.leftEyeElement.setAttribute("stroke-width", "2");
+    svg.appendChild(this.leftEyeElement);
+    this.rightEyeElement = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+    this.rightEyeElement.setAttribute("cx", "80");
+    this.rightEyeElement.setAttribute("cy", "65");
+    this.rightEyeElement.setAttribute("r", "12");
+    this.rightEyeElement.setAttribute("fill", this.options.poorColor);
+    this.rightEyeElement.setAttribute("stroke", "#fff");
+    this.rightEyeElement.setAttribute("stroke-width", "2");
+    svg.appendChild(this.rightEyeElement);
+    const nose = document.createElementNS("http://www.w3.org/2000/svg", "path");
+    nose.setAttribute("d", "M60,75 L55,95 L65,95 Z");
+    nose.setAttribute("fill", "none");
+    nose.setAttribute("stroke", "#666");
+    nose.setAttribute("stroke-width", "2");
+    svg.appendChild(nose);
+    this.faceOutlineElement.appendChild(svg);
+  }
+  /**
+   * Update the display with new position data
+   */
+  updatePosition(positionData) {
+    if (!positionData) {
+      this.showNoData();
+      return;
+    }
+    const avgX = this.getAveragePosition(positionData.leftX, positionData.rightX, positionData.leftValid, positionData.rightValid);
+    const avgY = this.getAveragePosition(positionData.leftY, positionData.rightY, positionData.leftValid, positionData.rightValid);
+    const avgZ = this.getAveragePosition(positionData.leftZ, positionData.rightZ, positionData.leftValid, positionData.rightValid);
+    this.updateFaceDisplay(avgX, avgY, avgZ, positionData);
+    if (this.options.showDistanceFeedback && avgZ !== null) {
+      this.updateDistanceBar(avgZ);
+    }
+    this.updateEyeIndicators(positionData);
+    this.updateTextualFeedback(avgX, avgY, avgZ);
+  }
+  getAveragePosition(left, right, leftValid, rightValid) {
+    if (leftValid && rightValid && left !== null && right !== null) {
+      return (left + right) / 2;
+    } else if (leftValid && left !== null) {
+      return left;
+    } else if (rightValid && right !== null) {
+      return right;
+    }
+    return null;
+  }
+  updateFaceDisplay(x, y, z, _positionData) {
+    if (x === null || y === null) {
+      this.faceOutlineElement.style.opacity = "0.3";
+      return;
+    }
+    this.faceOutlineElement.style.opacity = "1";
+    const offsetX = (x - 0.5) * this.BOX_WIDTH * 0.8;
+    const offsetY = (0.5 - y) * this.BOX_HEIGHT * 0.8;
+    let scale = this.OPTIMAL_FACE_SCALE;
+    if (z !== null) {
+      scale = this.MIN_FACE_SCALE + z * (this.MAX_FACE_SCALE - this.MIN_FACE_SCALE);
+      scale = Math.max(this.MIN_FACE_SCALE, Math.min(this.MAX_FACE_SCALE, scale));
+    }
+    this.faceOutlineElement.style.transform = `translate(calc(-50% + ${offsetX}px), calc(-50% + ${offsetY}px)) scale(${scale})`;
+  }
+  updateDistanceBar(z) {
+    if (!this.distanceBarFill)
+      return;
+    const fillPercent = z * 100;
+    this.distanceBarFill.style.height = `${fillPercent}%`;
+    const goodMin = 0.5 - this.options.distanceThresholdGood;
+    const goodMax = 0.5 + this.options.distanceThresholdGood;
+    const fairMin = 0.5 - this.options.distanceThresholdFair;
+    const fairMax = 0.5 + this.options.distanceThresholdFair;
+    let color;
+    if (z >= goodMin && z <= goodMax) {
+      color = this.options.goodColor;
+    } else if (z >= fairMin && z <= fairMax) {
+      color = this.options.fairColor;
+    } else {
+      color = this.options.poorColor;
+    }
+    this.distanceBarFill.style.background = color;
+  }
+  updateEyeIndicators(positionData) {
+    if (this.leftEyeElement) {
+      const leftColor = positionData.leftValid ? this.options.goodColor : this.options.poorColor;
+      this.leftEyeElement.setAttribute("fill", leftColor);
+    }
+    if (this.rightEyeElement) {
+      const rightColor = positionData.rightValid ? this.options.goodColor : this.options.poorColor;
+      this.rightEyeElement.setAttribute("fill", rightColor);
+    }
+  }
+  updateTextualFeedback(x, y, z) {
+    if (!this.feedbackElement)
+      return;
+    if (x === null || y === null || z === null) {
+      this.feedbackElement.textContent = "Eyes not detected - please position yourself in front of the tracker";
+      this.feedbackElement.style.color = this.options.poorColor;
+      return;
+    }
+    const quality = this.assessPositionQuality(x, y, z);
+    let feedback;
+    let color;
+    if (quality.isGoodPosition) {
+      feedback = "\u2713 Position is good";
+      color = this.options.goodColor;
+    } else {
+      const issues = [];
+      const posFairThreshold = this.options.positionThresholdFair;
+      if (x < 0.5 - posFairThreshold)
+        issues.push("move right");
+      else if (x > 0.5 + posFairThreshold)
+        issues.push("move left");
+      if (y < 0.5 - posFairThreshold)
+        issues.push("move up");
+      else if (y > 0.5 + posFairThreshold)
+        issues.push("move down");
+      const distFairThreshold = this.options.distanceThresholdFair;
+      if (z > 0.5 + distFairThreshold)
+        issues.push("move back");
+      else if (z < 0.5 - distFairThreshold)
+        issues.push("move closer");
+      if (issues.length > 0) {
+        feedback = `Please ${issues.join(" and ")}`;
+      } else {
+        feedback = "Position: Almost there...";
+      }
+      color = quality.distanceStatus === "poor" || quality.horizontalStatus === "poor" || quality.verticalStatus === "poor" ? this.options.poorColor : this.options.fairColor;
+    }
+    this.feedbackElement.textContent = feedback;
+    this.feedbackElement.style.color = color;
+  }
+  assessPositionQuality(x, y, z) {
+    const xOffset = Math.abs(x - 0.5);
+    let horizontalStatus;
+    if (xOffset < this.options.positionThresholdGood)
+      horizontalStatus = "good";
+    else if (xOffset < this.options.positionThresholdFair)
+      horizontalStatus = "fair";
+    else
+      horizontalStatus = "poor";
+    const yOffset = Math.abs(y - 0.5);
+    let verticalStatus;
+    if (yOffset < this.options.positionThresholdGood)
+      verticalStatus = "good";
+    else if (yOffset < this.options.positionThresholdFair)
+      verticalStatus = "fair";
+    else
+      verticalStatus = "poor";
+    const zOffset = Math.abs(z - 0.5);
+    let distanceStatus;
+    if (zOffset < this.options.distanceThresholdGood)
+      distanceStatus = "good";
+    else if (zOffset < this.options.distanceThresholdFair)
+      distanceStatus = "fair";
+    else
+      distanceStatus = "poor";
+    const isGoodPosition = horizontalStatus === "good" && verticalStatus === "good" && distanceStatus === "good";
+    return {
+      isGoodPosition,
+      horizontalStatus,
+      verticalStatus,
+      distanceStatus,
+      averageX: x,
+      averageY: y,
+      averageZ: z
+    };
+  }
+  showNoData() {
+    if (this.feedbackElement) {
+      this.feedbackElement.textContent = "Waiting for tracker data...";
+      this.feedbackElement.style.color = this.options.poorColor;
+    }
+    this.faceOutlineElement.style.opacity = "0.3";
+  }
+  /**
+   * Get current position quality
+   */
+  getCurrentQuality(positionData) {
+    if (!positionData) {
+      return {
+        isGoodPosition: false,
+        horizontalStatus: "poor",
+        verticalStatus: "poor",
+        distanceStatus: "poor",
+        averageX: null,
+        averageY: null,
+        averageZ: null
+      };
+    }
+    const avgX = this.getAveragePosition(positionData.leftX, positionData.rightX, positionData.leftValid, positionData.rightValid);
+    const avgY = this.getAveragePosition(positionData.leftY, positionData.rightY, positionData.leftValid, positionData.rightValid);
+    const avgZ = this.getAveragePosition(positionData.leftZ, positionData.rightZ, positionData.leftValid, positionData.rightValid);
+    if (avgX === null || avgY === null || avgZ === null) {
+      return {
+        isGoodPosition: false,
+        horizontalStatus: "poor",
+        verticalStatus: "poor",
+        distanceStatus: "poor",
+        averageX: avgX,
+        averageY: avgY,
+        averageZ: avgZ
+      };
+    }
+    return this.assessPositionQuality(avgX, avgY, avgZ);
+  }
+  /**
+   * Remove the display
+   */
+  destroy() {
+    this.container.innerHTML = "";
+  }
+}
+
+const info = {
+  name: "tobii-user-position",
+  version,
+  parameters: {
+    /** Duration to show the position guide (ms), null for manual */
+    duration: {
+      type: ParameterType.INT,
+      default: null
+    },
+    /** Message to display */
+    message: {
+      type: ParameterType.STRING,
+      default: "Please position yourself so the indicators are green"
+    },
+    /** Update interval (ms) */
+    update_interval: {
+      type: ParameterType.INT,
+      default: 100
+    },
+    /** Show distance feedback */
+    show_distance_feedback: {
+      type: ParameterType.BOOL,
+      default: true
+    },
+    /** Show position feedback */
+    show_position_feedback: {
+      type: ParameterType.BOOL,
+      default: true
+    },
+    /** Button text for manual continuation */
+    button_text: {
+      type: ParameterType.STRING,
+      default: "Continue"
+    },
+    /** Only show button when position is good */
+    require_good_position: {
+      type: ParameterType.BOOL,
+      default: false
+    },
+    /** Background color */
+    background_color: {
+      type: ParameterType.STRING,
+      default: "#f0f0f0"
+    },
+    /** Good position color */
+    good_color: {
+      type: ParameterType.STRING,
+      default: "#28a745"
+    },
+    /** Fair position color */
+    fair_color: {
+      type: ParameterType.STRING,
+      default: "#ffc107"
+    },
+    /** Poor position color */
+    poor_color: {
+      type: ParameterType.STRING,
+      default: "#dc3545"
+    },
+    /** Button color */
+    button_color: {
+      type: ParameterType.STRING,
+      default: "#007bff"
+    },
+    /** Button hover color */
+    button_hover_color: {
+      type: ParameterType.STRING,
+      default: "#0056b3"
+    },
+    /** Font size */
+    font_size: {
+      type: ParameterType.STRING,
+      default: "18px"
+    },
+    /** Position offset threshold for "good" status (normalized, default 0.15) */
+    position_threshold_good: {
+      type: ParameterType.FLOAT,
+      default: 0.15
+    },
+    /** Position offset threshold for "fair" status (normalized, default 0.25) */
+    position_threshold_fair: {
+      type: ParameterType.FLOAT,
+      default: 0.25
+    },
+    /** Distance offset threshold for "good" status (normalized, default 0.1) */
+    distance_threshold_good: {
+      type: ParameterType.FLOAT,
+      default: 0.1
+    },
+    /** Distance offset threshold for "fair" status (normalized, default 0.2) */
+    distance_threshold_fair: {
+      type: ParameterType.FLOAT,
+      default: 0.2
+    }
+  },
+  data: {
+    /** Average X position during trial */
+    average_x: {
+      type: ParameterType.FLOAT
+    },
+    /** Average Y position during trial */
+    average_y: {
+      type: ParameterType.FLOAT
+    },
+    /** Average Z position (distance) during trial */
+    average_z: {
+      type: ParameterType.FLOAT
+    },
+    /** Whether position was good at end */
+    position_good: {
+      type: ParameterType.BOOL
+    },
+    /** Horizontal position status */
+    horizontal_status: {
+      type: ParameterType.STRING
+    },
+    /** Vertical position status */
+    vertical_status: {
+      type: ParameterType.STRING
+    },
+    /** Distance status */
+    distance_status: {
+      type: ParameterType.STRING
+    },
+    /** Duration of trial */
+    rt: {
+      type: ParameterType.INT
+    }
+  }
+};
+class TobiiUserPositionPlugin {
+  constructor(jsPsych) {
+    this.jsPsych = jsPsych;
+  }
+  static {
+    this.info = info;
+  }
+  static removeStyles() {
+    const el = document.getElementById("tobii-user-position-styles");
+    if (el) {
+      el.remove();
+    }
+  }
+  injectStyles(trial) {
+    TobiiUserPositionPlugin.removeStyles();
+    const css = `
+      .tobii-user-position-container {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        width: 100%;
+        height: 100vh;
+        font-family: 'Open Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+        font-size: ${trial.font_size};
+      }
+
+      .tobii-user-position-message {
+        margin-bottom: 40px;
+        text-align: center;
+        font-weight: 500;
+        color: #333;
+      }
+
+      .tobii-user-position-guide {
+        position: relative;
+        margin-bottom: 40px;
+      }
+
+      .tobii-position-feedback {
+        text-align: center;
+        margin-bottom: 30px;
+        font-weight: 600;
+        font-size: 1.1em;
+      }
+
+      .tobii-user-position-button {
+        padding: 12px 32px;
+        font-size: 16px;
+        font-weight: 500;
+        border: none;
+        border-radius: 6px;
+        background-color: ${trial.button_color};
+        color: white;
+        cursor: pointer;
+        transition: all 0.2s ease;
+        box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
+      }
+
+      .tobii-user-position-button:hover:not(:disabled) {
+        background-color: ${trial.button_hover_color};
+        box-shadow: 0 4px 8px rgba(0, 0, 0, 0.3);
+        transform: translateY(-1px);
+      }
+
+      .tobii-user-position-button:disabled {
+        background-color: #ccc;
+        cursor: not-allowed;
+        opacity: 0.6;
+      }
+
+      .tobii-center-marker {
+        position: absolute;
+        top: 50%;
+        left: 50%;
+        transform: translate(-50%, -50%);
+        width: 30px;
+        height: 30px;
+        border: 2px dashed #666;
+        border-radius: 50%;
+        opacity: 0.5;
+      }
+    `;
+    const styleElement = document.createElement("style");
+    styleElement.id = "tobii-user-position-styles";
+    styleElement.textContent = css;
+    document.head.appendChild(styleElement);
+  }
+  trial(display_element, trial) {
+    return new Promise((resolve) => {
+      this.injectStyles(trial);
+      const tobiiExtension = this.jsPsych.extensions.tobii;
+      if (!tobiiExtension) {
+        throw new Error("Tobii extension not loaded");
+      }
+      display_element.innerHTML = `
+        <div class="tobii-user-position-container">
+        </div>
+      `;
+      const container = display_element.querySelector(
+        ".tobii-user-position-container"
+      );
+      const positionDisplay = new PositionDisplay(container, {
+        message: trial.message,
+        showDistanceFeedback: trial.show_distance_feedback,
+        showPositionFeedback: trial.show_position_feedback,
+        backgroundColor: trial.background_color,
+        goodColor: trial.good_color,
+        fairColor: trial.fair_color,
+        poorColor: trial.poor_color,
+        fontSize: trial.font_size,
+        positionThresholdGood: trial.position_threshold_good,
+        positionThresholdFair: trial.position_threshold_fair,
+        distanceThresholdGood: trial.distance_threshold_good,
+        distanceThresholdFair: trial.distance_threshold_fair
+      });
+      let continueButton = null;
+      if (trial.duration === null) {
+        continueButton = document.createElement("button");
+        continueButton.className = "tobii-user-position-button";
+        continueButton.textContent = trial.button_text;
+        if (trial.require_good_position) {
+          continueButton.disabled = true;
+        }
+        container.appendChild(continueButton);
+      }
+      const positionSamples = [];
+      const startTime = performance.now();
+      const updateInterval = setInterval(async () => {
+        try {
+          const positionData = await tobiiExtension.getUserPosition();
+          positionDisplay.updatePosition(positionData);
+          const quality = positionDisplay.getCurrentQuality(positionData);
+          positionSamples.push(quality);
+          if (continueButton && trial.require_good_position) {
+            continueButton.disabled = !quality.isGoodPosition;
+          }
+        } catch (error) {
+          console.error("Error updating user position:", error);
+        }
+      }, trial.update_interval);
+      const cleanup = () => {
+        clearInterval(updateInterval);
+        positionDisplay.destroy();
+        display_element.innerHTML = "";
+        TobiiUserPositionPlugin.removeStyles();
+      };
+      const endTrial = () => {
+        const validSamples = positionSamples.filter(
+          (s) => s.averageX !== null && s.averageY !== null && s.averageZ !== null
+        );
+        let averageX = null;
+        let averageY = null;
+        let averageZ = null;
+        let finalQuality = null;
+        if (validSamples.length > 0) {
+          averageX = validSamples.reduce((sum, s) => sum + s.averageX, 0) / validSamples.length;
+          averageY = validSamples.reduce((sum, s) => sum + s.averageY, 0) / validSamples.length;
+          averageZ = validSamples.reduce((sum, s) => sum + s.averageZ, 0) / validSamples.length;
+          finalQuality = positionSamples[positionSamples.length - 1];
+        }
+        const trialData = {
+          average_x: averageX,
+          average_y: averageY,
+          average_z: averageZ,
+          position_good: finalQuality?.isGoodPosition ?? false,
+          horizontal_status: finalQuality?.horizontalStatus ?? "poor",
+          vertical_status: finalQuality?.verticalStatus ?? "poor",
+          distance_status: finalQuality?.distanceStatus ?? "poor",
+          rt: Math.round(performance.now() - startTime)
+        };
+        cleanup();
+        this.jsPsych.finishTrial(trialData);
+        resolve();
+      };
+      if (continueButton) {
+        continueButton.addEventListener("click", endTrial);
+      }
+      if (trial.duration != null) {
+        this.jsPsych.pluginAPI.setTimeout(endTrial, trial.duration);
+      }
+    });
+  }
+}
+
+export { TobiiUserPositionPlugin as default };
+//# sourceMappingURL=index.js.map