Out Of The Box: What Triggers are available?

This guide explains the different Trigger modules that DLStream comes with and how to use them.

If you have never used DLStream, make sure to check out: Introduction to experiments.

If you want to directly design an experiment based on our out-of-the-box selection: Click here!

If you are looking for some inspiration for your next DLStream powered experiment, look no further.

Although we recommend the wiki sections My first experiment and Adapting an existing experiment if you want to directly dive into implementing your own experiment.

Triggers

Single posture triggers:

• HeaddirectionTrigger - Allocentric

  A trigger that checks the headdirection angle of an animal in relation to a reference point. Checks an angle window (e.g. 60° around reference).

• EgoHeaddirectionTrigger - Egocentric

  A trigger that checks the egocentric headdirection angle of an animal between tailroot, neck and nose. Checks an angle window (e.g. 60°) and direction (left/right).

• DirectionTrigger - Allocentric

  Similiar to Headdirection trigger, but uses user-defined bodyparts as input. Checks the bodypart angle of an animal in relation to a reference point.

• ScreenTrigger - Allocentric

  Similiar to DirectionTrigger, but checks if the bodypart angle of an animal is facing NORTH, SOUTH, EAST or WEST in the image.

• RegionTrigger - ROI-based

  Region of Interest based trigger, that checks whether a user-defined bodypart or a list of bodyparts is in the region defined by the user. The possible regions include circles, ellipses and rectangles.

• OutsideTrigger - ROI-based

  Similiar to RegionTrigger, but checks whether the animal is NOT in the Region of Interest.

Posture sequence triggers:

• SpeedTrigger - Parameter-based

  Calculates speed of user-defined bodyparts in a user-defined frame/time window and reacts if a user-defined threshold was surpassed.

• FreezeTrigger - Parameter-based

  Similiar to SpeedTrigger, but checks whether the animal is slower then the user-defined threshold.

Combination triggers:

• HeaddirectionROITrigger- Allocentric, ROI-based

  A trigger that checks the headdirection angle and position/distance of an animal in relation to a reference point. Checks an angle window (e.g. 60° around reference) and if a user-defined bodypart or a list of bodyparts is in the region defined by the user. The possible regions include circles, ellipses and rectangles.

Output & Input:

All Trigger modules have the same input and output, when engaged by the Experiment. Trigger modules are only initiated differently from each other.

Input:

The function MyTrigger.check_skeleton(skeleton) takes the DLStream provided posture estimation (skeleton) and evaluates it.

Output

The function MyTrigger.check_skeleton(skeleton) has the output response which consists of a boolean result (True/False) and a response_body which can be used to plot a visual feedback on the video stream.

Initializing a Trigger Module

To initialize any Trigger module import the module from /experiments/base/triggers.py or /experiments/custom/triggers.py in the beginning of the script and initialize it by creating a variable like this:

from experiments.custom.triggers import MyTrigger my_trigger = MyTrigger(parameter1, parameter2)

Note that each Trigger module has slightly different initialization parameters and you can use them to tune an already existing Trigger to your own needs.

You can use these triggers within our out-of-the-box experiment design

To learn how to implement any Trigger in a custom Experiment, check out the next guide: Adapting an existing experiment or directly create your own experiment from scratch: My first experiment