Skip to main content

Entities overview

This overview describes entities, the entity data model's components, and how Entity Manager supports distributed entity management.

Entities​

An entity is an interoperable data structure that powers a common operational picture (COP). A COP provides human and machine consumers with a shared view of the current state of the modeled world, which enhances situational awareness and facilitates decision-making.

Entities represent any type of known object that can be referenced or commanded.

Entities can be tangible or intangible, including:

  • Physical objects, such as vessels or drones.
  • Non-physical objects, such as signal detections.
  • Visual concepts, such as bounding boxes or control zones.

Entity shapes​

Although there is no strict type hierarchy, a user interface could group entities according to its ontology.template component. The three top-level groupings are track, asset, and geo-entity.

  • Tracks: any contact not directly under the control of friendly forces. This can include aircraft tracks generated from radar or sensor hits, signal detections, vehicles or people detected through cameras, or any other contact source.

    • Tracks include all entities with the following template types:
      • Track: An object detection.
      • Sensor point of interest: A sensor detection at a specific location.
      • Signal of interest: A signal detection with characteristics such as emitter notation, frequency, or lines of bearing.
    • Examples include:
      • An aircraft reporting its information using an Automatic Dependent Surveillance-Broadcast (ADS-B) transponder.
      • A surface vessel reporting its information using an Automatic Identification System (AIS) transponder.
      • A person detected by computer vision processing of camera images from a tower.
      • A signal detection with an estimated area and error ellipse.

  • Assets: entities directly under your control that generally can accept tasks from the operator. Examples include Anduril towers, Dive, and so on.

  • Geo-entities: shapes or points of interest drawn on the map. They might not physically exist in the world. A geo-entity could be a point representing an airfield or a control zone meant to constrain operations of an autonomous vehicle. Examples include:

    • A point of interest on the map manually created by one operator to share with other operators.
    • A zone around a training area.
    • A keep-out-zone on the map indicating an area where a hurricane develops.

The entity data model​

The entity data model is the canonical data model that represents all objects in the COP. It represents the known state of the world in Lattice, providing a common language to describe any object or concept that can enhance an operator's situational awareness.

An entity is a set of components​

The entity data model consists of different fields called components.

The entity data model observes these principles:

  • Components are optional, except those listed in Customize entities.
  • Components mustn't be duplicative. Avoid modeling the same underlying data on two different components.
  • Components are non-hierarchical. The data model is composable and not an inheritance tree.

For the full list of possible entity components, refer to the canonical entity data model.

Composition over inheritance​

The data model is based on the entity component system architecture and favors composition over inheritance. The presence or absence of components—rather than a strict type hierarchy—determines what an entity is or how it should be interacted with. Think of an entity as a bag of components that can be mixed and matched as needed.

Entity consumers key off specific components to decide how to process the entity. When producing an entity, only include components that are relevant to the entity you're modeling, along with the required components.

For example, to model a track you should include:

  • A location to render the track on the map.
  • An ontology to specify which icon type to render in Lattice UI.
  • A sensors component if the track has sensors. Downstream consumers that perform actions on sensors will behave correctly based on the presence of this component in your entity.

Partial data picture​

Because an entity is a collection of components, entities can sometimes be in incomplete states. An incomplete state means the entity is missing some expected components or values. This is a reasonable condition for situational awareness data in a COP, which is an aggregation of real-time, known data.

In some cases, the producers pushing data may not have the full picture yet. There's still value in distributing this partial state for situational awareness purposes. Therefore, it's important for services consuming entities to be robust against missing components.

Entity Manager​

Entity Manager is the backend Lattice service that powers the COP. Once an entity is available in the COP, operators can use it for other Lattice services, such as tasking or creating alerts.

Entity Manager provides a real-time, distributed COP:

  • Real-time: Entity Manager provides the current state of the COP by publishing entity events that follow the entity lifecycle of create, update, or delete. Entity Manager doesn't provide historical data.
  • Distributed: A layer on top of Lattice's mesh network, Entity Manager supports distributed entity management. Entity Manager instances in a mesh network can send entities to or receive entities from another Entity Manager instance in the mesh. The COP eventually becomes consistent between nodes, which store files, entities, and tasks in the Lattice system; each COP's view converges, subject to operator controls.

Entity lifecycle management​

Entities have a well-defined lifecycle of create, update, and delete. On each lifecycle state change, Entity Manager emits the state change event to the COP using the StreamEntityComponents call (gRPC | HTTP).

  • Create: When an entity first appears or re-appears after expiring, the entity is created.
  • Update: When data in the entity changes, Entity Manager emits the state change as an update event. Note that, for performance reasons, Entity Manager relies on changes to the provenance.source_update_time to trigger an update event. It does not perform a full proto diff to the provenance.source_update_time component to trigger an update event.
  • Delete: An entity is deleted when its expiry_time has passed or an update is sent with the is_live component set to false. You should handle a delete event by removing all references to it in memory or discarding it from your user interface.

On each lifecycle state change, the Entities API emits state change events via StreamEntityComponents (gRPC | HTTP).

It's the integration's responsibility to control an entity's lifecycle by sending updates and setting expiry times as needed.

Integrations​

In the Lattice ecosystem, integrations produce entities, achieved by publishing pre-populated entity objects to Lattice using the Entity Manager service gRPCs or HTTP SDKs.

The Entity Manager API provides the PublishEntity RPC to create or update entities. When beginning to integrate with Lattice, we recommend using this unary RPC because it provides validates its input and provides an immediate error response if the entity is malformed. It is also capable of high throughput. Exact numbers will vary greatly depending on the Lattice hardware you are integrating with.

If waiting for a unary response causes your publish task to fall behind, we also offer the PublishEntities gRPC client-streaming API to publish entities to Lattice. There are some tradeoffs to consider when deciding to use the client-streaming RPC:

  • You can achieve higher throughput because your publish task does not need to wait for a response from the server.
  • You may lose data if your stream connection with the server is terminated early. In most gRPC streaming implementations, outgoing messages are buffered locally prior to being sent over the wire. If the connection is terminated then all buffered messages are lost.
  • You will receive no feedback from the server regarding validity of the entity messages you publish.

Integrations can also consume entities from Lattice by streaming the COP from the Entity Manager API through the StreamEntityComponents endpoints (gRPC | HTTP).

Distribution​

In Lattice Mesh, the Lattice SDK can distribute entities between different Lattice nodes. Integrations only need to publish entities to their local Lattice node; Lattice Mesh takes care of sharing those entities with other Lattice nodes in the mesh network.

Lattice administrators have fine-grained control over this distribution. They can choose which Lattice nodes to distribute entities to by applying filters on a select majority of components in the entity data model.

Overrides​

Certain fields on the entity data model are annotated as overridable. Overrides enable a user or system to change the value of a component on an entity that exists in the COP. The user or system that creates the override doesn't have to be the original producer of the entity.

Overrides are distributed; an override created on one Lattice node will be visible on other Lattice nodes on the mesh.

Operators or services generally use overrides when they have new or different information about an entity. For example, an operator might manually mark a track's disposition to hostile-based according to standard operating procedures (SOPs).

Relationships​

The entity data model includes a relationships property, which describes a predefined relationship type between two or more entities. Relationships provide the means for entities to reference other entities, enabling graph-like lookup capabilities for special processing.

The entity data model typically models relationships between entities when the existence of a relationship component triggers special treatment in the Lattice UI or for consuming services. For example, the Lattice UI can use these relationships to render the group and its members together.

Relationships are distributed; a relationship created on one Lattice node in a mesh network appears on other nodes in the mesh network.