`entity-state-to-lookout`

entity-state-to-lookout detects moments when gaze direction changes sharply between consecutive samples. It emits an events channel that a chart can show as a lookout lane.

Entity-state records are the JSON records array that hydrate-protobuf-v2 emits with extractionTarget: EntityState. The node collects the gaze_direction vector from every entity that carries a gaze component, whatever that entity is named, sorts the samples by time and measures the angle between each pair of consecutive vectors. When the angle crosses thresholdDegrees the lookout state toggles and an event point is written.

It is a scan detector, not a fixation map. For where the trainee looked see entity-state-to-eyetracking.

When to use

Use this node when a Next dashboard chart needs an event lane showing when a trainee was actively scanning.

Pipeline position


hydrate-protobuf-v2 (EntityState) -> entity-state-to-lookout -> 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. The direction is always read from its `gaze_direction` field.
`timeField`	string	No	`packet_timestamp_unix_ms`	Dotted path to the record time stamp in milliseconds.
`thresholdDegrees`	number	No	`10`	Minimum change in gaze direction between consecutive samples that counts as a lookout.
`realmName`	string	No	`overview`	Realm name.
`channelId`	string	No	`lookout`	Channel id. The channel name is set to the same value today.
`channelName`	string	No	`Lookout`	Declared in the manifest but not applied to the channel today.
`groupId`	string	No	`lookout`	Group id.
`groupName`	string	No	`Lookout`	Group display name.

Output

A data service payload with one events channel.


{
  "$heat-dataservice": {
    "version": "1.0",
    "groups": [{ "id": "lookout", "name": "Lookout" }],
    "realms": [
      {
        "name": "overview",
        "channels": [
          {
            "id": "lookout",
            "name": "lookout",
            "groupId": "lookout",
            "shape": "events",
            "data": [
              { "timeMs": 1718000001000, "occurred": true },
              { "timeMs": 1718000004000, "occurred": false }
            ]
          }
        ]
      }
    ]
  },
  "dashboard_users": []
}

occurred is true while the angle between consecutive samples is at or above the threshold and false when it falls below.
A point is written at each toggle and at the first comparison.
timeMs is the record time stamp of the later sample in each pair.

entity-state-to-lookout

When to use

Pipeline position

Configuration

Output

Limitations

Related

`entity-state-to-lookout`