gaze-eye-metrics (Processing Node)

The Gaze Eye Metrics node classifies 3D gaze direction data into spatial zones (Far, Near, Left, Right) using KMeans clustering with Mahalanobis distance augmentation. It produces an overall gaze distribution, raw gaze vectors, and a per-second timeline of zone percentages. When an optional phase-boundaries parent is connected, results are also computed per phase.

This node is domain-agnostic — it operates on any upstream payload that supplies three gaze direction columns and a timestamp — and is currently hosted inside the Aviation Metrics runner.

Single-user scope: The classification pipeline assumes all gaze samples belong to a single participant. If the upstream payload contains gaze data from multiple users, the clustering will conflate them and produce incorrect results. For multi-user sessions, pre-filter the data to a single entity upstream (e.g. via json-template or tabular-query) before feeding it into this node.

Configuration Schema

All properties are optional. The node works with an empty configuration ({}).

Expected Upstream Input

Parent 1 (required): bio input (default: rapid-preprocess)

A JSON object containing a bio_input key with an array of sample objects. Each sample must include the configured gaze direction columns and a timestamp:

{
  "bio_input": [
    {
      "COMBINED GazeDirection X (Float)": 0.12,
      "COMBINED GazeDirection Y (Float)": -0.03,
      "COMBINED GazeDirection Z (Float)": 0.99,
      "CAPTURED DATE TIME (IS0 8601)": "2025-06-15T10:00:00.000Z"
    }
  ]
}

Parent 2 (optional): phase boundaries (default: phase-segment)

A JSON object keyed by phase name. Each value has the same shape as the root payload above (containing its own bio_input array). When present, the node produces per-phase results in addition to the full-session result.

{
  "take_off": { "bio_input": [ ... ] },
  "downwind": { "bio_input": [ ... ] },
  "final_approach": { "bio_input": [ ... ] }
}

Required Upstream Columns

Behaviour

1. The processor reads the upstream bio payload (from primaryInputNode, default rapid-preprocess) and extracts bio_input.
2. Raw gaze vectors (x, y, z, timestamp) are assembled into the gaze_data.values output.
3. The bio samples are passed to the gaze classification pipeline: a. A Circuit_Number column is added if absent (defaults to circuit 1). b. Data is split by circuit number. c. For each circuit, gaze feature columns are cleaned: coerced to numeric, rows with all-NaN gaze are dropped, remaining NaNs are interpolated then median-imputed. d. Features are standardised and a Mahalanobis distance from the global centroid is appended as a fourth feature. e. KMeans clustering is run on the augmented feature space (default 5 clusters). f. Clusters are labelled: highest mean Z = Far, lowest Z = Near, highest mean X = Right, lowest X = Left. Extra clusters are assigned to their nearest label. g. If any of the four labels is missing, ~1% of data points are reassigned from the nearest feature-space neighbours.
4. Per-bucket (default per-second) gaze label percentages are computed to form the timeline.
5. Overall gaze percentages are computed across all samples.
6. If a phase-boundaries parent is connected, steps 1—5 are repeated independently for each phase slice.

Output Artefact

The node outputs JSON. The top-level key full_session is always present. When phase data is available, additional keys are added for each phase name.

{
  "full_session": {
    "gaze_data": {
      "values": [
        { "x": 0.12, "y": -0.03, "z": 0.99, "timestamp": "2025-06-15T10:00:00.000Z" }
      ]
    },
    "gaze_percentages": {
      "Near": 25.0,
      "Left": 15.0,
      "Right": 20.0,
      "Far": 40.0
    },
    "gaze_timeline": [
      {
        "second": "2025-06-15T10:00:00+00:00",
        "Near": 20.0,
        "Left": 10.0,
        "Right": 30.0,
        "Far": 40.0
      }
    ]
  },
  "take_off": { "..." : "same structure as full_session" },
  "downwind": { "..." : "same structure as full_session" }
}

When no valid gaze data is available for a block, the output uses stable defaults: gaze_data: {}, all percentages at 0.0, and an empty gaze_timeline.

Example Configuration

Minimal (all defaults):

{}

Customised (non-RAPID context):

{
  "gazeColumns": {
    "x": "EyeTracker_GazeX",
    "y": "EyeTracker_GazeY",
    "z": "EyeTracker_GazeZ"
  },
  "timestampColumn": "sample_timestamp",
  "nClusters": 6,
  "timelineResolution": "500ms",
  "primaryInputNode": "my-bio-preprocess",
  "phaseInputNode": "my-phase-splitter"
}

Integration in a Session Template

1. Place a gaze-eye-metrics node in your session template.
2. Connect a parent node that produces a { "bio_input": [...] } JSON payload with gaze direction columns. By default the processor looks for rapid-preprocess; set primaryInputNode in config to use a different parent.
3. Optionally connect a phase-boundaries parent to enable per-phase scoring. By default the processor looks for phase-segment; set phaseInputNode in config to use a different parent.
4. Supply configuration to override gaze column names, cluster count, timeline resolution, or parent node names. Leave the config empty ({}) for default RAPID behaviour.
5. Connect downstream consumers:
   • Dashboard transforms (e.g. am-transform-circuits-dashboard, rapid-transform-intercept-dashboard) — read gaze_percentages for eye-tracking chart panels.
   • timeline-metrics — can consume gaze_timeline for unified timeline rendering.

Related Concepts

• Aviation Metrics Runner
• Cognitive Load Metrics
• Node Templates
• Session Templates