`entity-state-to-eyetracking`

entity-state-to-eyetracking aggregates gaze samples for a whole session into four zone percentages. It emits one value channel for the EyeTracking widget.

Entity-state records are the JSON records array that hydrate-protobuf-v2 emits with extractionTarget: EntityState. For each record the node takes one gaze sample from the first entity that carries a gaze component, whatever that entity is named. The sample is assigned to left, right, up or down by its dominant axis. The output is each zone’s share of all valid samples.

It reports the session as a whole. For duration-weighted compass sectors see entity-state-to-viewport-tracking.

When to use

Use this node when a Next dashboard needs the EyeTracking percentage grid and the capture includes headset or desktop eye-tracking data.

Pipeline position


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

The node reads the latest output of one parent.

Configuration

Configuration is optional.

Key	Type	Required	Default	Description
`entriesPath`	string	No	`records[*]`	JMESPath (a query language for JSON) to the array of time-ordered records.
`entitiesPath`	string	No	`entity_state.entity`	JMESPath from each record to its entity object or array of objects.
`componentsPath`	string	No	`components`	Dotted path from an entity to its components array.
`gazeField`	string	No	`gaze`	Component field name for gaze data.
`gazeOriginField`	string	No	`gaze_origin`	Field within gaze for the combined origin vector.
`gazeDirectionField`	string	No	`gaze_direction`	Field within gaze for the combined direction vector.
`gazeLeftOriginField`	string	No	`left_gaze_origin`	Field within gaze for the left eye origin.
`gazeRightOriginField`	string	No	`right_gaze_origin`	Field within gaze for the right eye origin.
`gazeLeftDirField`	string	No	`left_gaze_direction`	Field within gaze for the left eye direction.
`gazeRightDirField`	string	No	`right_gaze_direction`	Field within gaze for the right eye direction.
`realmName`	string	No	`overview`	Realm name.
`channelId`	string	No	`eyetracking`	Channel id.
`channelName`	string	No	`EyeTracking`	Display name.
`backgroundImageUrl`	string	No	none	Image drawn behind the gaze grid. The widget uses its own default when omitted.

Output

A data service payload with one value channel in group eyetracking.


{
  "$heat-dataservice": {
    "version": "1.0",
    "groups": [{ "id": "eyetracking", "name": "Eye Tracking" }],
    "realms": [
      {
        "name": "overview",
        "channels": [
          {
            "id": "eyetracking",
            "name": "EyeTracking",
            "groupId": "eyetracking",
            "shape": "value",
            "data": [
              {
                "code": "GAZE_EYE",
                "datasets": [
                  {
                    "left": { "value": 33, "text": "Left" },
                    "right": { "value": 0, "text": "Right" },
                    "top": { "value": 0, "text": "Up" },
                    "bottom": { "value": 67, "text": "Down" }
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "dashboard_users": []
}

The gaze vector comes from gazeDirectionField. When that field is absent, as with desktop eye trackers, the node falls back to the gaze_screen_point field and uses its offset from screen centre.
A sample with neither field, for example during a blink, is excluded rather than forced into a zone.
Zone assignment uses the dominant axis. When the vertical component is larger the sample is up or down, otherwise it is right or left. A zero vector counts as left.
Percentages are rounded independently and may not sum to exactly 100.
backgroundImageUrl, when set, is copied onto the GAZE_EYE entry.

Limitations

One parent, latest output only.
One sample per record. Within one record the first gaze-bearing entity wins.
The node fails when no record contains usable gaze data.

EyeTracking (Next) renders the value channel.
entity-state-to-viewport-tracking emits duration-weighted horizontal and vertical distributions.
entity-state-to-lookout detects large gaze movements as events.

HEAT documentation team. Last updated 2 October 2026.

Opens your browser's print dialog. Choose "Save as PDF" as the destination.