Welcome Guest, you are in: Login

ScrewTurn Wiki



Search the wiki

Element Icon ROI Element
Category: Behaviour Control AddIn: Base Elements
Creator: OkazoLab Team Scope: Parent Event
Owns Snippets: Triggered Usage: Runtime Screen,Snippets


Genetic properties

NameDescriptionAttributesValue Type
Area shapeDefines the shape of the “watched area” stTargetShape
Border visibleDefines, if a border is shown around the ROI area at runtime. Boolean
Radar providerDefines which of the parent events in the layer hierarchy provides the positional data String
Triggering modeDefines the conditional mode that trigger the element.DstTargetHitMode
Fixation durationDefines the duration (in ms) of the fixation interval when the element works in the "fixation" mode. Otherwise, the value is not used.D,RUInt64
Runtime info
Is OverIndicates at the runtime if the positional input is currently inside of the "watched area".R, Read-onlyBoolean
Is TriggeredIndicates if the element has been triggered starting from current activation of the parent event.R, Read-onlyBoolean
Trigger timeShows event's time (ms) when the element was triggered.R, Read-onlyUInt64
Visual appearance
AntiAliasingif true, the rendered content will be antialiased for smoother visual appeariance. If false, rendering will be authentic to its source, e.g. a bitmap. Boolean
PositionPosition of the element on the screen areaD,R,*clPoint (X.Y,R,Theta)
SizeSize of the elementD,R,*clSize (Width,Height, aWidth,aHeight)
Z orderIndicates Z Order of the element on the given eventR, Read-onlyInt32
AlignmentDefines alignment of the "monitored" area to its position. The default value is the central alignment.D,R,*stAlignment Int32
Color maskProduces a multiplicative combination of the original pixels and the selected mask color (except the alpha channel). The effect emulates a look through a colored glass. White or transparent mask color dont change the original pixels.D,R,*clColor
SaturationSaturation of the rendered content. Double

+=== Properties inherited from clElement === Inherited properties of clElement
NameDescriptionConstraintsValue TypeUpon Change
Is EnabledIf set to false the element is completely omitted when the experiment is run.Boolean
TitleTitle of the element.String


ROI element continuously evaluates any tracking data, e.g. the gaze or mouse positions, relatively to a selected region on the screen. The element can also detect specific tracking patterns, e.g perpetual fixations and saccades in and out of the region, and collect timing statistics of such patterns.

Practical use

In the simplest case, the ROI element can be used to report whether a tracking position is inside of the selected screen region. For that purpose, monitor the "Is Over" property of the element at runtime. Another property, "Viewing Time", returns the accumulative time of the tracking position being inside of the selected region between the onset and offset of element's parent event. In addition, the ROI element can automatically detect and signal the common patterns in a positional data. When the pattern is detected, the element gets triggered. Then the triggering time is recorded and Triggered snippet is invoked, if it's defined. The ROI element can work in one of three triggering modes:

On the first spot

In this mode the element detects when a tracking position input enters the monitored screen region for the first time since the onset of the parent event.

On perpetual fixation

In this mode the element detects when s tracking position enters the monitored region and stays there for a certain time period. The duration of that period is defined by the [Fixation duration] property of the AOI element. The element is not triggered, if any of tracking position goes out of the region before the period is expired. However, the element can be triggered later, if tracking positions returns and stay in the region again.

On fixation break

In this mode the element detect a moment when the input position leaves the element's region (assuming that it has been inside before onset of the parent event). This mode is handy for when breaks in previously archived fixation have to detected.

You can choose only between the rectangular or elliptical shape for the "element's region. It's sufficient for most of scenarios but, however, you can always create radar areas with complex shapes by combining several radar area elements in the same event. In this case, you may need to check the states of multiple radar area elements manually, in your snippets.


  • The ROI element can be triggered only once during the parent event. If you need multiple triggering, redesign your experiment flow (e.g. use several events) or reactivate the parent event. Alternatively, you can still read 'Is Over' property of the element that provides a status of positional input even after the element has been triggered.
  • the ROI element can be affected by the solar visual transformations, if they are applied to the parent event. In such cases, relations between positional input and watched areas can be incorrectly estimated. Always place radar area elements in events that have no such transformations.
  • if you have several active ROI elements that monitor the same screen area, they can be triggered at the same time.

ScrewTurn Wiki version Some of the icons created by FamFamFam.