entity-state-to-viewport-tracking

entity-state-to-viewport-tracking reduces gaze samples to two duration-weighted distributions. One covers eight horizontal compass sectors and the other covers high, mid and low vertical zones.

Entity-state records are the JSON records array that hydrate-protobuf-v2 emits with extractionTarget: EntityState. The node reads the gaze_direction vector from every entity that carries a gaze component, whatever that entity is named. It converts each vector to a yaw and a pitch, assigns the sample to a sector and a zone, and weights it by the time until the next sample.

It differs from entity-state-to-eyetracking, which counts samples equally and reports four screen quadrants.

When to use

Use this node when a Next dashboard needs to show how much of the session a trainee spent looking in each direction around them, for example ahead, to the sides or behind.

Pipeline position

hydrate-protobuf-v2 (EntityState) -> entity-state-to-viewport-tracking -> json-merge -> dashboard-v2

The node reads the latest output of one parent.

Configuration

Configuration is optional.

Output

A data service payload with two value channels.

{
  "$heat-dataservice": {
    "version": "1.0",
    "groups": [{ "id": "eyetracking", "name": "Eye Tracking" }],
    "realms": [
      {
        "name": "overview",
        "channels": [
          {
            "id": "eyetracking-horizontal",
            "name": "Viewport Horizontal",
            "groupId": "eyetracking",
            "shape": "value",
            "data": {
              "value": [
                { "id": "horizontal-n", "label": "0°", "angleStart": 337.5, "angleEnd": 22.5, "percentage": 62 },
                { "id": "horizontal-ne", "label": "45°", "angleStart": 22.5, "angleEnd": 67.5, "percentage": 14 }
              ]
            }
          },
          {
            "id": "eyetracking-vertical",
            "name": "Viewport Vertical",
            "groupId": "eyetracking",
            "shape": "value",
            "data": {
              "value": [
                { "id": "high", "zone": "high", "percentage": 10 },
                { "id": "mid", "zone": "mid", "percentage": 80 },
                { "id": "low", "zone": "low", "percentage": 10 }
              ]
            }
          }
        ]
      }
    ]
  },
  "dashboard_users": []
}

• The horizontal value always lists all eight sectors, from horizontal-n through horizontal-nw, each 45 degrees wide. Straight ahead is 0 degrees.
• The vertical value always lists high, mid and low.
• Each sample is weighted by the time until the next sample. The last sample takes the duration of the interval before it.
• When gaze_direction is absent, as with desktop eye trackers, the node falls back to the gaze_screen_point field. The offset from screen centre is scaled by a default field of view of 90 degrees horizontally and 60 degrees vertically. Such samples never reach the side or rear sectors.
• When total duration is zero, every sector or zone receives an equal share.

No component page documents the viewport tracking widget today. Bind the two channels as value channels in the layout.

Limitations

• One parent, latest output only.
• Percentages are rounded independently and may not sum to exactly 100.
• The node fails when no sample yields a gaze direction or screen point.

Related

• entity-state-to-eyetracking reports four screen quadrants for the EyeTracking widget.
• entity-state-to-lookout detects large gaze movements as events.
• EyeTracking (Next) is the sibling percentage grid widget.

HEAT documentation team. Last updated 2 October 2026.