`entity-state-to-mapdisplay`

entity-state-to-mapdisplay turns time-ordered entity-state records into one mapdisplay channel of movement tracks. The MapDisplay widget plays those tracks back on a map.

Entity-state records are the JSON records array that hydrate-protobuf-v2 emits with extractionTarget: EntityState. entity-state-to-records emits the same shape from DIS traffic. The node groups records by simulation time, evaluates JMESPath (a query language for JSON) expressions to read each entity’s position, and builds one movement per entity.

The output is one Channel inside a data service payload. It is not a flight path. Use entity-state-to-flightpath for the 3D FlightPath widget.

When to use

Use this node when a Next dashboard needs a playable map of where entities were. It covers ground, surface and air tracks equally.

Pipeline position


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

The node reads the latest output of one parent.

Configuration

Configuration is required. latField and lonField must be set.

Key	Type	Required	Default	Description
`entriesPath`	string	No	`records[*]`	JMESPath to the array of time-ordered records.
`timeField`	string	No	`simulation_time_seconds`	Dotted path from each record to its simulation time.
`entitiesPath`	string	No	`entity_state.entity`	JMESPath from each record to its entity object or array of objects.
`entityNameField`	string	No	`name`	Dotted path from each entity to its name.
`entityNames`	array of string	No	none	Names of entities to plot. When absent or empty, every entity with latitude and longitude values is plotted.
`latField`	string	Yes	none	JMESPath from each entity to its latitude.
`lonField`	string	Yes	none	JMESPath from each entity to its longitude.
`headingField`	string	No	`""`	Optional JMESPath to heading. Omitted from points when empty.
`speedField`	string	No	`""`	Optional JMESPath to speed. Omitted from points when empty.
`altField`	string	No	`""`	Optional JMESPath to altitude. Omitted from points when empty.
`baseCapturedAt`	string	No	`""`	ISO 8601 base time stamp. When set, simulation time is a relative offset from this base. When empty, simulation time is absolute Unix epoch seconds.
`realmName`	string	No	`overview`	Realm name. The channel id becomes `mapdisplay-<realmName>`.
`movementName`	string	No	`Tracks`	Display name of the movement channel.
`deploymentEntityPattern`	string	No	`""`	Name prefix for entities whose visibility depends on a status field.
`deploymentStatusField`	string	No	`""`	JMESPath to the status value checked for entities matching `deploymentEntityPattern`. Those entities are plotted only while the value is `6`, as integer, float, string, or the matching protobuf enum name.
`falseDetectionConfig`	object	No	none	Classifies detection tracks as true or false by whether they are still present at session end. See below.

falseDetectionConfig keys:

Key	Type	Required	Default	Description
`entityPattern`	string	Yes	none	Name prefix identifying detection tracks. Matching entities are plotted even when absent from `entityNames`.
`endToleranceSeconds`	number	No	`1`	A track is true when its last-seen time is within this many seconds of the session’s last recorded time.
`trueSymbol`	object	No	none	Symbol config (`allegiance`, `domain`, `unitType`) for true tracks. Unused today, because true tracks are dropped from the output.
`falseSymbol`	object	No	none	Symbol config (`allegiance`, `domain`, `unitType`) applied to false tracks.

Output

A data service payload with one mapdisplay channel. Coordinate fields are strings, as the mapdisplay shape requires.


{
  "$heat-dataservice": {
    "version": "1.0",
    "groups": [{ "id": "mapdisplay", "name": "Map" }],
    "realms": [
      {
        "name": "overview",
        "channels": [
          {
            "id": "mapdisplay-overview",
            "name": "Tracks",
            "groupId": "mapdisplay",
            "shape": "mapdisplay",
            "data": {
              "movements": [
                {
                  "name": "ENTITY-A",
                  "movement": [
                    { "latitude": "51.5", "longitude": "-1.5", "heading": "180.0", "speed": "5.0", "altitude": "0.0", "capturedDate": "2026-06-10T00:00:10Z" }
                  ]
                }
              ],
              "mapStats": []
            }
          }
        ]
      }
    ]
  },
  "dashboard_users": []
}

Records are grouped by simulation time and sorted ascending. Input order within a time bucket does not matter.
capturedDate is an ISO 8601 UTC string derived from baseCapturedAt plus the offset, or from epoch seconds when baseCapturedAt is empty.
An entity with a missing or non-numeric position at one time stamp is skipped for that time stamp only.
When falseDetectionConfig is set, tracks classified false carry "hideAfterEnd": true so the MapDisplay widget hides the marker after its last point. Tracks classified true are not emitted, because the real entity already has its own track.

Limitations

One parent, latest output only.
The node fails when no entity has a valid position anywhere in the input.
hideAfterEnd is read by the MapDisplay widget only. The TacticalMap widget consumes the same shape but keeps the marker at its last point.

MapDisplay (Next) renders the channel.
TacticalMap (Next) renders the same shape offline against a fixed background image.
entity-state-to-flightpath builds the 3D flight path from the same records.
entity-state-to-records supplies records from DIS traffic.

HEAT documentation team. Last updated 2 October 2026.

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