Skip to main content

Attributes and label trees


Tator allows users to define their own metadata on a project by project basis. It uses a system of entities and attributes. Entities are objects that can be described. Attributes are descriptors for entities with one of several data types. Four classes of entities can be described with attributes in Tator:

  • Media: May be an image, video, or multi-stream video.
  • Localizations: May be a box, line, or dot.
  • States: Collections of other items, either media, localizations, or video frames.
  • Leaves: Used to create trees for hierarchical labeling, such as taxonomies.

Each entity type definition may include an arbitrary number of attribute type definitions. Attribute data types include:

  • Boolean
  • Integer
  • Float
  • Enumeration
  • String
  • Datetime
  • Geoposition

All of these attribute types share the same schema, but only some fields are used for each data type. For example, boolean data types optionally accept a default value, whereas enumeration accepts a required choices list, optional labels list, and optional default value.

Tator stores attribute values in two databases: PostgreSQL and Elasticsearch. In PostgreSQL, attribute values are stored in JSON fields, allowing a uniform database schema across all projects. In Elasticsearch, attribute values are indexed using a data type corresponding to the attribute's data type. To facilitate renaming of attributes, Tator uses Elasticsearch's aliasing feature - the actual index is named as a unique ID which is pointed to by a named alias. Therefore, attributes can be renamed quickly. Changing the data type of an attribute requires a "mutation", which is effectively a database migration within Elasticsearch.

Label trees

String attributes accept a parameter called autocomplete that enables a suggestion interface when typing data for these fields in the web UI. The source data for autocomplete is a label tree, a hierarchy of labels such as a taxonomy. The levels of the label tree used for autocomplete suggestion can be restricted to certain layers. The label tree can be defined using Leaf objects in Tator. A leaf contains the name of the label, a parent, and custom attribute values. Once a hierarchy is created and registered with an attribute type, letters typed into the web UI will be globbed against all or a subset of leaves in the label tree, and the top results will be shown in a dropdown interface.

Read more