Organize Events with Episodes

This section is about the Episodes tab.

See also

An episode is a set of identification events that feature objects of the same origin (face and body images of the same person and images of the same vehicle) detected within a specific period. As events on the Events tab show up in an arbitrary order, a large number of miscellaneous events can make the work difficult and unproductive. With the episodes, the system uses AI to organize incoming events based on the objects’ similarity and detection time. This allows for easy processing of diverse events, even in large numbers.

In this chapter:

About Episodes

There are two stages of an episode lifecycle:

  • LIVE: an episode is currently active, to which new events can be possibly added.

  • Closed: an episode is closed, no events can be added.

Episodes are classified as individual episodes and vehicle episodes. Individual episodes feature face and body images of people, detected within a specific period, while vehicle episodes contain vehicle images and license plate.

Grant Rights for Episodes

A user receives a notification of a new episode if they have rights to the first event. Viewing new events in the episode also requires proper rights.

The right to an event consists of the rights for a corresponding camera and watch list.

Note

To see unmatched events, you only need the rights to a camera.

To manage the rights of a role for the entire Episode entity, open permissions for this role and adjust the following permissions:

  • humanepisode: individuals episodes

  • carepisode: vehicle episodes

Tip

See Role and User Management.

episode_permissions_en

View Episodes

You can find the list of episodes with filters and statistics on the Episodes & Events -> Episodes tab. Episodes are sorted subject to the object’s origin: there are individual episodes and vehicle episodes.

Once an object is detected, it is either added to an existing LIVE episode or used as a starting point for a new episode. Each episode is assigned an identifier which can be later used to filter events and episodes.

episodes_en

When working with the episodes, the following default filters may come in handy:

Note

Some filters from the list below may be hidden, subject to enabled recognition features.

Filters for individuals and vehicles

  • Individuals type: display events only for faces or bodies.

  • Matches: faces: display episodes only with/without face matches, or all episodes.

  • Matches: bodies: display episodes only with/without body matches, or all episodes.

  • Matches: display episodes only with/without vehicle matches, or all episodes.

  • Watch lists: display episodes only for a selected watch list.

  • Acknowledged: display only acknowledged/unacknowledged episodes, or all episodes.

  • Camera groups: display only episodes from a selected group of cameras.

  • Cameras: display only episodes from a selected camera.

  • Camera IDs: display only episodes from a camera with a given ID.

  • Date and time: display only episodes that occurred within a certain period.

  • Video archive ID: display episodes related to the video archive with a given ID.

  • Record name: display only episodes with a given record name.

  • Episode ID: display an episode with a given ID.

  • Counts events: display only episodes with a given number of events.

Specific filters for faces

  • Age: display episodes with people of a given age.

  • Gender: display episodes with people of a given gender.

  • Emotions: display episodes with given emotions.

  • Beard: filter episodes by the fact of having a beard.

  • Eyes: filter episodes based on whether the eyes are open or closed or if they are blocked by an object.

  • Glasses: filter episodes by the fact of wearing glasses.

  • Face mask: filter episodes by the fact of wearing a face mask.

  • Head turn: filter episodes by degree of head turn.

  • Head tilt: filter episodes by degree of head tilt.

  • Liveness: filter episodes by face liveness.

Specific filters for bodies

  • Age by body: display episodes with a body of a given age.

  • Gender by body: display episodes with a body of a given gender.

  • Upper clothes type: display only episodes with a person wearing upper body wear of a given specific type: jacket, coat, sleeveless, sweatshirt, T-shirt, shirt, dress.

  • Upper body clothes: display only episodes with a person wearing upper body wear of a given generalized category: long sleeves, short sleeves, no sleeve.

  • Upper clothes color: display only episodes with a person wearing a top of a given color.

  • Lower body clothes: display only episodes with a person wearing lower body wear of a given type: pants, nondescript, skirt, shorts.

  • Lower clothes color: display only episodes with a person wearing a bottom of a given color.

  • Headwear: display only episodes with a person wearing headgear of a given type: hat/cap, hood/scarf, none.

  • Bag in hand: display only episodes with a person wearing/not wearing a bag in hand.

  • Bag on the back: display only episodes with a person wearing/not wearing a bag on the back.

  • Vest: display only episodes with a person wearing a vest of a given color.

  • Helmet: display only episodes with a person wearing a helmet of a given color.

  • Fall: display episodes by the fact a person falls.

  • Smoking: display episodes with smoking people.

  • Phone usage: display episodes with people using their phone.

  • Phone talk: display episodes with people calling or talking on the phone.

  • Taking pictures: display episodes with people taking pictures of the screen, document, etc. with their phone.

Specific filters for vehicle episodes

  • Make: filter vehicle episodes by vehicle make.

  • Model: filter vehicle episodes by vehicle model.

  • Vehicle body color: display only episodes with vehicles of a given color.

  • Vehicle body type: display only episodes with vehicles of a given body type: minivan, limousine.

  • Country: display only episodes with vehicles registered in a given country.

  • License plate number: display an episode with a given plate number.

  • Vehicle category: display only episodes with vehicles belonging to a given category: motorcycle, scooter, car, car with a trailer, truck, truck with a trailer, bus, articulated bus, other.

  • Vehicle weight and body size: display only episodes with vehicles of a given weight and body size.

  • Special vehicle: display only episodes with vehicles belonging to a given type: taxi, public road transport, carsharing, ambulance, police, fire service and emergencies ministry vehicles, gas rescue and emergency services, military, municipal vehicles, other or not special.

  • Vehicle orientation: display only episodes with vehicles of a given orientation: unknown, front, rear, side.

  • Region: display only episodes with vehicles registered in a given region.

  • License plate color: display only episodes with a given license plate color.

Note

License plate region is predicted for the United Arab Emirates (UAE) and Thailand. License plate color is predicted for Saudi Arabia only. The values of these attributes will be marked as unknown for other countries.

To view episode events, click the episode on the list. You will be redirected to the Matched Episode or Unmatched Episode tab with the episode information and related events.

episodes_events_en

Work with the Events tab as described in Work with Events.

Event and Episode Acknowledging

To acknowledge an entire episode, click Acknowledge for this episode or episode_check_acknowledge on the list. As a result, all events in the episode will be automatically acknowledged, including those that are yet-to-appear (in the case of a LIVE episode).

episode_accept_en

An episode is also automatically acknowledged after acknowledging all its events one by one.

Episode Settings

To configure the episodes, use the /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py configuration file. Find the following parameters in the FFSECURITY section:

  • FACE_EPISODES_THRESHOLD, BODY_EPISODES_THRESHOLD, CAR_EPISODES_THRESHOLD: Similarity thresholds that the system is using when searching for recent events in order to construct an episode. The default values are set to the optimum. If necessary, you can change them. Be sure to consult with our technical experts prior (support@ntechlab.com).

  • FACE_EPISODE_SEARCH_INTERVAL, BODY_EPISODE_SEARCH_INTERVAL, CAR_EPISODE_SEARCH_INTERVAL: The period preceding an event, for which the system searches the feature vector database for already existing events with similar objects. If no such event is found, the system creates a new episode. Otherwise, it sorts out the 100 most recent similar objects and picks up the most relevant event from a LIVE episode.

  • EPISODE_MAX_DURATION: Maximum episode duration (in seconds). After this time, an episode automatically closes.

  • EPISODE_EVENT_TIMEOUT: Maximum waiting time (in seconds) for new events within an open episode. After this time elapses, the episode automatically closes if no new events have been added.

  • EPISODE_KEEP_ONLY_BEST_EVENT: When closing an episode, delete all events in it, except the one with the best object. Use this option to save disk space.

If, during the time specified by EPISODE_EVENT_TIMEOUT, the system registers a new event with a detected similar object (face, body, vehicle), this event is appended to the current episode, and the EPISODE_EVENT_TIMEOUT timer is reset. This process repeats until the total duration of the episode reaches the value of EPISODE_MAX_DURATION (300 seconds by default). If no new events occur within the EPISODE_EVENT_TIMEOUT period, the episode is automatically closed. In scenarios where the object is continuously present in the observation area, and the system continuously registers events related to its detection, new episodes will be created every EPISODE_MAX_DURATION.

Upon the arrival of a new event, the system performs a search for the most suitable open episode within the FACE_EPISODE_SEARCH_INTERVAL | BODY_EPISODE_SEARCH_INTERVAL | CAR_EPISODE_SEARCH_INTERVAL interval (in seconds). The search is based on the comparison of feature vectors between the new event and events already associated with open episodes. The new event is appended to the episode containing the most similar event. If a suitable episode is not found, a new episode is created, and the event is associated with this new episode.

An episode is closed under one of the following conditions:

  • No new events are received within the time defined by the EPISODE_EVENT_TIMEOUT parameter (in seconds).

  • The maximum episode duration, specified by the EPISODE_MAX_DURATION parameter (in seconds), is exceeded.

After an episode is closed, a cluster event is formed from it, provided that the quality of the highest-quality event in the episode exceeds the FACE_CLUSTER_EVENT_MIN_QUALITY | BODY_CLUSTER_EVENT_MIN_QUALITY | CAR_CLUSTER_EVENT_MIN_QUALITY value, and the number of events in the episode exceeds the FACE_CLUSTER_EVENT_MIN_EPISODE_EVENTS | BODY_CLUSTER_EVENT_MIN_EPISODE_EVENTS | CAR_CLUSTER_EVENT_MIN_EPISODE_EVENTS value.

If events with a detected object are received from different cameras, the system aggregates these events into a single episode, according to the rules outlined above.

When processing different video archives, each containing events with a detected object, separate episodes are generated for each video archive. The rules for episode creation and closure, including EPISODE_EVENT_TIMEOUT and EPISODE_MAX_DURATION, remain identical to those applied to episodes originating from surveillance cameras.

sudo vi /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py

...

FFSECURITY = {
      ...
      # episodes specific matching threshold that is used to join faces in an episode
      'FACE_EPISODES_THRESHOLD': 0.663,  # FAR = 1.00E-06  # model: [nectarine_l_320]
      'BODY_EPISODES_THRESHOLD': 0.75,  # model: [durga]
      'CAR_EPISODES_THRESHOLD': 0.61,  # model: [bottas]
      ...
      # when closing episode, delete all events except the best episode event
      'EPISODE_KEEP_ONLY_BEST_EVENT': False,
      # delete episode events after delay in seconds
      'EPISODE_DELETE_EVENTS_DELAY': 60,
      ...
      # maximum event age in seconds than could be added to an episode.
      'FACE_EPISODE_SEARCH_INTERVAL': 60,
      'BODY_EPISODE_SEARCH_INTERVAL': 60,
      'CAR_EPISODE_SEARCH_INTERVAL': 60,
      # maximum episode duration (episode is closed after)
      'EPISODE_MAX_DURATION': 300,
      # if no new event added to an episode during this timeout, episode will be closed.
      'EPISODE_EVENT_TIMEOUT': 30,
      ...
}

...

Restart all FindFace Multi containers.

cd /opt/findface-multi/
sudo docker-compose restart

See also

Geo