Tobii XR Devzone > Develop > Tobii Ocumen > Ocumen Filters > Python >

Ocumen Filters - Python API

This page outlines the Python API for Tobii Ocumen Filters.

API Overview

Functions

Freestanding callables inside the module.

Enums

Groups of related constants.

  • Aggregation - Aggregation type for calculating values within a window.
  • BlinkStatePerEye - Describes the openness of an eye in discrete steps. What exactly constitues
  • Eye - Which eye(s) to invalidate.
  • FilterError - Error type returned from filter functions.
  • LogLevel - Log level for Ocumen functions.
  • MissingValueStrategy - How to treat invalid data. Specific values can be provided in handle missing value field.
  • ResampleMethod - Method used when resampling data.
  • Scaling - Scaling for the results of the STFT with windowing functions.
  • SmoothGazeData - Which component of the gaze ray to apply smoothing to.
  • WindowingFunction - Windowing function to use for STFT calculation.

Data Structs

Composite data used by functions and methods.


Data Structs

BinocularGaze

Gaze rays for the left and right eye.

Coordinates in here are local space of the eye tracker, relative to a fictional reference point between the eyes. To transform them to world space you need to use the CameraPose struct.

Fields

  • left - Gaze origin and direction of the left eye.
  • right - Gaze origin and direction of the right eye.

Definition

class BinocularGaze(ctypes.Structure):

    _fields_ = [
        ("left", Rayf32),
        ("right", Rayf32),
    ]

    def __init__(self, left: Rayf32 = None, right: Rayf32 = None):
        ...

BlinkState

Encodes blink states for each eye.

Fields

  • left - Left eye blink state.
  • right - Right eye blink state.

Definition

class BlinkState(ctypes.Structure):

    _fields_ = [
        ("left", ctypes.c_int),
        ("right", ctypes.c_int),
    ]

    def __init__(self, left: ctypes.c_int = None, right: ctypes.c_int = None):
        ...

CameraPose

View matrices of the combined camera sitting between both eyes.

Fields

  • camera_to_world_matrix - The (assumed by non-existent) place where the camera that sits between both eyes would be. this is local-to-world, use case is to describe where head is; we expect a left-handed coordinate system; with z-axis facing forward (away) from user.

Definition

class CameraPose(ctypes.Structure):

    _fields_ = [
        ("camera_to_world_matrix", Matrix4f32),
    ]

    def __init__(self, camera_to_world_matrix: Matrix4f32 = None):
        ...

CatmullRomResamplingConfig

Config for resampling using a Catmull-Rom spline.

Fields

  • output_interval_us - The output rate of interpolated samples. Output rate = 1 / output interval. Interval is given in microseconds (µs)
  • single_eye_resampling - Allow to resample just one eye if there is not enough data for both eyes.

Definition

class CatmullRomResamplingConfig(ctypes.Structure):

    _fields_ = [
        ("output_interval_us", ctypes.c_int64),
        ("single_eye_resampling", ctypes.c_bool),
    ]

    def __init__(self, output_interval_us: int = None, single_eye_resampling: bool = None):
        ...

Complexf32

A complex number in Cartesian form.

Fields

  • re - Real portion of the complex number
  • im - Imaginary portion of the complex number

Definition

class Complexf32(ctypes.Structure):

    _fields_ = [
        ("re", ctypes.c_float),
        ("im", ctypes.c_float),
    ]

    def __init__(self, re: float = None, im: float = None):
        ...

DispersionAnglesFilterConfig

Configuration for the dispersion angle filter.

Fields

  • max_angle_for_fixations_deg - How close subsequent gaze direction vectors have to be to detect a fixation.
  • min_duration_for_fixation_us - How long gaze has to be within a certain direction to consider it a fixation. Duration is given in microseconds (µs)
  • max_outliers - Maximum number of outliers allowed before a fixation is aborted.

Definition

class DispersionAnglesFilterConfig(ctypes.Structure):

    _fields_ = [
        ("max_angle_for_fixations_deg", ctypes.c_float),
        ("min_duration_for_fixation_us", ctypes.c_int64),
        ("max_outliers", ctypes.c_uint64),
    ]

    def __init__(self, max_angle_for_fixations_deg: float = None, min_duration_for_fixation_us: int = None, max_outliers: int = None):
        ...

EntrancePupilData

Entrance pupil data.

Fields

  • left - Left eye data.
  • right - Right eye data.

Definition

class EntrancePupilData(ctypes.Structure):

    _fields_ = [
        ("left", Vector3f32),
        ("right", Vector3f32),
    ]

    def __init__(self, left: Vector3f32 = None, right: Vector3f32 = None):
        ...

FixationOutput

Output for left and right eye produced by a fixation filter.

Fields

  • is_fixation_left - Whether a fixation was detected for the left eye. A value of none means that there was insufficient data to determine if a fixation happened.
  • is_fixation_right - Whether a fixation was detected for the right eye. A value of none means that there was insufficient data to determine if a fixation happened.

Definition

class FixationOutput(ctypes.Structure):

    _fields_ = [
        ("is_fixation_left", Optionbool),
        ("is_fixation_right", Optionbool),
    ]

    def __init__(self, is_fixation_left: Optionbool = None, is_fixation_right: Optionbool = None):
        ...

InvalidateEyeConfig

The configuration for the invalidate eyes filter.

Fields

  • eye - Which eye(s) to invalidate.

Definition

class InvalidateEyeConfig(ctypes.Structure):

    _fields_ = [
        ("eye", ctypes.c_int),
    ]

    def __init__(self, eye: ctypes.c_int = None):
        ...

InvalidateNearBlinkConfig

Configuration for the invalidate near blink filter.

Fields

  • before_us - Inclusive time before blink to invalidate data.
  • after_us - Inclusive time after blink to invalidate data.
  • min_blink_duration_us - Inclusive minimum time for a blink.

Definition

class InvalidateNearBlinkConfig(ctypes.Structure):

    _fields_ = [
        ("before_us", ctypes.c_int64),
        ("after_us", ctypes.c_int64),
        ("min_blink_duration_us", ctypes.c_int64),
    ]

    def __init__(self, before_us: int = None, after_us: int = None, min_blink_duration_us: int = None):
        ...

LamThompsonCorbett1987FilterConfig

Configuration for the Lam Thompson Corbett 1987 filter.

Fields

  • loewenfeld_criterion_mm - The Loewenfeld criterion to use, minimum difference in mm to consider for anisocoria.
  • ltc_criterion_ratio - The Lam, Thompson & Corbett criterion to use, minimum difference in relative area to consider for anisocoria.

Definition

class LamThompsonCorbett1987FilterConfig(ctypes.Structure):

    _fields_ = [
        ("loewenfeld_criterion_mm", ctypes.c_float),
        ("ltc_criterion_ratio", ctypes.c_float),
    ]

    def __init__(self, loewenfeld_criterion_mm: float = None, ltc_criterion_ratio: float = None):
        ...

LogMessage

A single message recorded by our library.

Fields

  • level - The level of the message.
  • message - ASCII encoded actual message.
  • file - Our source file where this message originated from.
  • line - Line number where this message originated from.

Definition

class LogMessage(ctypes.Structure):

    _fields_ = [
        ("level", ctypes.c_int),
        ("message", ctypes.POINTER(ctypes.c_char)),
        ("file", ctypes.POINTER(ctypes.c_char)),
        ("line", ctypes.c_uint32),
    ]

    def __init__(self, level: ctypes.c_int = None, message: str = None, file: str = None, line: int = None):
        ...

LoggerConfiguration

Configures how logging should be handled.

Fields

  • log_level - The minimal log level to log.
  • max_log_wait_ms - When initializing the logger, with a previous logger present, how long shall we try to wait replacing the previous logger if it is locked.

Definition

class LoggerConfiguration(ctypes.Structure):

    _fields_ = [
        ("log_level", ctypes.c_int),
        ("max_log_wait_ms", ctypes.c_uint32),
    ]

    def __init__(self, log_level: ctypes.c_int = None, max_log_wait_ms: int = None):
        ...

Matrix4f32

A 4x4 transformation matrix.

Fields

  • m - Array member elements in column major order.

Definition

class Matrix4f32(ctypes.Structure):

    _fields_ = [
        ("m", ctypes.c_float * 16),
    ]

    def __init__(self, m = None):
        ...

NearBlinkOutput

Value indicating blink or near blink.

Fields

  • left - Value indicating if the left eye is a blink or near blink.
  • right - Value indicating if the right eye is a blink or near blink.

Definition

class NearBlinkOutput(ctypes.Structure):

    _fields_ = [
        ("left", ctypes.c_bool),
        ("right", ctypes.c_bool),
    ]

    def __init__(self, left: bool = None, right: bool = None):
        ...

NoiseConfig

Configuration for noise filter.

Fields

  • seed - The seed to use for predictable results. If set to 0 a random seed will be generated instead.
  • mean_origin - The mean of the normal distribution for the origin of the ray.
  • mean_direction - The mean of the normal distribution for the direction of the ray.
  • std_dev_origin - The standard deviation of the normal distribution for the origin of the ray. Recommended value is 0.02
  • std_dev_direction - The standard deviation of the normal distribution for the direction of the ray. Recommended value is 0.05

Definition

class NoiseConfig(ctypes.Structure):

    _fields_ = [
        ("seed", ctypes.c_uint64),
        ("mean_origin", ctypes.c_float),
        ("mean_direction", ctypes.c_float),
        ("std_dev_origin", ctypes.c_float),
        ("std_dev_direction", ctypes.c_float),
    ]

    def __init__(self, seed: int = None, mean_origin: float = None, mean_direction: float = None, std_dev_origin: float = None, std_dev_direction: float = None):
        ...

Point2f32

A point in 2D space.

Fields

  • x - x component.
  • y - y component.

Definition

class Point2f32(ctypes.Structure):

    _fields_ = [
        ("x", ctypes.c_float),
        ("y", ctypes.c_float),
    ]

    def __init__(self, x: float = None, y: float = None):
        ...

Point3f32

A point in 3D space.

Fields

  • x - x component.
  • y - y component.
  • z - z component.

Definition

class Point3f32(ctypes.Structure):

    _fields_ = [
        ("x", ctypes.c_float),
        ("y", ctypes.c_float),
        ("z", ctypes.c_float),
    ]

    def __init__(self, x: float = None, y: float = None, z: float = None):
        ...

PositionGuide

The 2D position of the eyes in the headset.

Fields

  • left - X and Y position of left eye.
  • right - X and Y position of right eye.

Definition

class PositionGuide(ctypes.Structure):

    _fields_ = [
        ("left", Point2f32),
        ("right", Point2f32),
    ]

    def __init__(self, left: Point2f32 = None, right: Point2f32 = None):
        ...

PupilOutput

Output for Lam Thompson Corbett pupil filter.

Fields

  • difference_mm - The observed size difference in mm. A value of none means that the value couldn’t be calculated due to one or both eyes not having valid data.
  • loewenfeld_anisocoria - Was a pupillary inequality of at least “loewenfeld criterion” mm observed? A value of none means that the value couldn’t be calculated due to one or both eyes not having valid data.
  • ltc_anisocoria - Was an inequality of “ltc criterion ratio” % surface area observed? A value of none means that the value couldn’t be calculated due to one or both eyes not having valid data.
  • left - Left eye. A value of none means that the value couldn’t be calculated due to one or both eyes not having valid data.
  • right - Right eye. A value of none means that the value couldn’t be calculated due to one or both eyes not having valid data.

Definition

class PupilOutput(ctypes.Structure):

    _fields_ = [
        ("difference_mm", Optionf32),
        ("loewenfeld_anisocoria", Optionbool),
        ("ltc_anisocoria", Optionbool),
        ("left", OptionPupilPerEye),
        ("right", OptionPupilPerEye),
    ]

    def __init__(self, difference_mm: Optionf32 = None, loewenfeld_anisocoria: Optionbool = None, ltc_anisocoria: Optionbool = None, left: OptionPupilPerEye = None, right: OptionPupilPerEye = None):
        ...

PupilPerEye

Per eye data for pupil filter output.

Fields

  • pupil_area_mm2 - Computed pupil area.

Definition

class PupilPerEye(ctypes.Structure):

    _fields_ = [
        ("pupil_area_mm2", ctypes.c_float),
    ]

    def __init__(self, pupil_area_mm2: float = None):
        ...

PupilSizeAbsolute

Pupil diameter in millimeters for both eyes.

Fields

  • left - Left eye pupil diameter.
  • right - Right eye pupil diameter.

Definition

class PupilSizeAbsolute(ctypes.Structure):

    _fields_ = [
        ("left", PupilSizePerEye),
        ("right", PupilSizePerEye),
    ]

    def __init__(self, left: PupilSizePerEye = None, right: PupilSizePerEye = None):
        ...

PupilSizePerEye

Pupil diameter for the eye

Fields

  • size_mm - Pupil diameter in millimeters for the eye.

Definition

class PupilSizePerEye(ctypes.Structure):

    _fields_ = [
        ("size_mm", ctypes.c_float),
    ]

    def __init__(self, size_mm: float = None):
        ...

Rayf32

A ray with an origin and direction.

Fields

  • origin - Origin of the ray.
  • direction - Direction of the ray.

Definition

class Rayf32(ctypes.Structure):

    _fields_ = [
        ("origin", Point3f32),
        ("direction", Vector3f32),
    ]

    def __init__(self, origin: Point3f32 = None, direction: Vector3f32 = None):
        ...

SaccadeOutput

Output for left and right eye produced by a saccade filter.

Fields

  • is_saccade_left - Whether a saccade was detected on left eye data. A value of none means that there was insufficient data to determine if a saccade happened.
  • is_saccade_right - Whether a saccade was detected on right eye data. A value of none means that there was insufficient data to determine if a saccade happened.

Definition

class SaccadeOutput(ctypes.Structure):

    _fields_ = [
        ("is_saccade_left", Optionbool),
        ("is_saccade_right", Optionbool),
    ]

    def __init__(self, is_saccade_left: Optionbool = None, is_saccade_right: Optionbool = None):
        ...

SavitzkyGolaySmoothingConfig

Config for smoothing using fitted Savitzky Golay polynomial functions.

Fields

  • polynomial_degree - The order of the polynomial function to fit in the window.
  • half_window_size - The number of additional samples on either side of the target sample to use when fitting a polynomial curve. Total window size = 2 * half_window_size + 1 and it must be greater than the polynomial_degree.
  • smooth_gaze - Select what part of the eye tracking data to smooth: gaze direction, origin or both

Definition

class SavitzkyGolaySmoothingConfig(ctypes.Structure):

    _fields_ = [
        ("polynomial_degree", ctypes.c_uint64),
        ("half_window_size", ctypes.c_uint64),
        ("smooth_gaze", ctypes.c_int),
    ]

    def __init__(self, polynomial_degree: int = None, half_window_size: int = None, smooth_gaze: ctypes.c_int = None):
        ...

SmeetsHoogeFilterConfig

Configuration for the Smeets Hooge filter.

Fields

  • lower_threshold_deg_per_sec - The velocity threshold for detecting a saccade.
  • fixation_sigma_threshold - How many standard deviations from mean fixation velocity to detect onset and offset of a saccade
  • fixation_velocity_window_start_us - The time before the saccade peak to start calculating average fixation velocity. Duration is given in microseconds (µs)
  • fixation_velocity_window_size_us - The size of the window used to compute the average velocity of the fixation preceding the saccade. Duration is given in microseconds (µs)
  • fixation_velocity_minimum_deg_per_sec - The minimal velocity to use as threshold for detecting onset and offset of saccades. Low noise in the preceding fixation can result in a low threshold for the saccade offset, preventing its detection. This setting safeguards against such effects by ensuring a minimum threshold.
  • early_peak_limit - If the velocity peak appears before this normalized time within the saccade, the saccade is discarded.
  • late_peak_limit - If the velocity peak appears after this normalized time within the saccade, the saccade is discarded.

Definition

class SmeetsHoogeFilterConfig(ctypes.Structure):

    _fields_ = [
        ("lower_threshold_deg_per_sec", ctypes.c_float),
        ("fixation_sigma_threshold", ctypes.c_float),
        ("fixation_velocity_window_start_us", ctypes.c_int64),
        ("fixation_velocity_window_size_us", ctypes.c_int64),
        ("fixation_velocity_minimum_deg_per_sec", ctypes.c_float),
        ("early_peak_limit", ctypes.c_float),
        ("late_peak_limit", ctypes.c_float),
    ]

    def __init__(self, lower_threshold_deg_per_sec: float = None, fixation_sigma_threshold: float = None, fixation_velocity_window_start_us: int = None, fixation_velocity_window_size_us: int = None, fixation_velocity_minimum_deg_per_sec: float = None, early_peak_limit: float = None, late_peak_limit: float = None):
        ...

SpectralRFFIPerEye

Output for Short-time Fourier transform for the gaze local velocities per eye

Fields

  • fft_magnitude_local_angular_speed - Magnitude for frequency components for local angular speed.
  • fft_local_angular_speed - Frequency components for local angular speed.

Definition

class SpectralRFFIPerEye(ctypes.Structure):

    _fields_ = [
        ("fft_magnitude_local_angular_speed", ctypes.c_float * 32),
        ("fft_local_angular_speed", Complexf32 * 32),
    ]

    def __init__(self, fft_magnitude_local_angular_speed = None, fft_local_angular_speed = None):
        ...

SpectralRFFIPerEyeExtended

Output for Short-time Fourier transform for the gaze local velocities with extended window per eye

Fields

  • fft_magnitude_local_angular_speed - Magnitude for frequency components for local angular speed.
  • fft_local_angular_speed - Frequency components for local angular speed.

Definition

class SpectralRFFIPerEyeExtended(ctypes.Structure):

    _fields_ = [
        ("fft_magnitude_local_angular_speed", ctypes.c_float * 256),
        ("fft_local_angular_speed", Complexf32 * 256),
    ]

    def __init__(self, fft_magnitude_local_angular_speed = None, fft_local_angular_speed = None):
        ...

SpectralSTFTConfig

Config for computing the Short-time Fourier transform for the gaze local velocities (STFT)

Fields

  • handle_missing_strategy - How to treat invalid data. Specific values can be provided in handle missing value field.
  • handle_missing_value - Value to use when handle missing strategy is ‘Value’. Ignore this if you’re using any other than ‘Value’ handle missing strategy.
  • windowing - The window function to use. By applying a window function, you can reduce spectral leakage, improve frequency resolution, and obtain a more accurate representation of the signal’s frequency. However, there is often a trade-off between frequency resolution and time resolution, so choosing the right window function and length depends on the specific needs.
  • stft_length - How many samples to include in the window, values must be powers of 2: [2, 4, 8, …, 256]). A longer window provides better frequency resolution but sacrifices time resolution, a shorter window offers better time resolution but reduces frequency resolution. Consider the properties of your signal and experiment with different window lengths to determine the best choice for your specific application.
  • sample_rate - Sample rate of the velocities array provided as input for the STFT.
  • scaling - Scaling for the results of the STFT with windowing functions. Scaling will be applied only when you’re using a windowing function and the result will be scaled with sqrt(1/(sum of applied window Hann/Hamming/Blackman)^2) Spectrum scaling can help you better understand the relative importance of different frequency components in your signal.
  • subtract_averages - Subtract averages for each window before performing RFFT. If velocity signal has an average different from zero, it contains a DC offset that can cause discontinuities at the edges when the signal is assumed to be periodic, which leads to spectral leakage. By subtracting the average we are removing the DC offset, ensuring that the periodic assumption holds. This leads to a cleaner and more accurate representation of the frequency content of the signal.

Definition

class SpectralSTFTConfig(ctypes.Structure):

    _fields_ = [
        ("handle_missing_strategy", ctypes.c_int),
        ("handle_missing_value", ctypes.c_float),
        ("windowing", ctypes.c_int),
        ("stft_length", ctypes.c_uint64),
        ("sample_rate", ctypes.c_float),
        ("scaling", ctypes.c_int),
        ("subtract_averages", ctypes.c_bool),
    ]

    def __init__(self, handle_missing_strategy: ctypes.c_int = None, handle_missing_value: float = None, windowing: ctypes.c_int = None, stft_length: int = None, sample_rate: float = None, scaling: ctypes.c_int = None, subtract_averages: bool = None):
        ...

SpectralSTFTOutput

Output for Short-time Fourier transform for the gaze local velocities

Fields

  • left - Left eye data.
  • right - Right eye data.

Definition

class SpectralSTFTOutput(ctypes.Structure):

    _fields_ = [
        ("left", OptionSpectralRFFIPerEye),
        ("right", OptionSpectralRFFIPerEye),
    ]

    def __init__(self, left: OptionSpectralRFFIPerEye = None, right: OptionSpectralRFFIPerEye = None):
        ...

SpectralSTFTOutputExtended

Output for Short-time Fourier transform for the gaze local velocities with extended window

Fields

  • left - Left eye data.
  • right - Right eye data.

Definition

class SpectralSTFTOutputExtended(ctypes.Structure):

    _fields_ = [
        ("left", OptionSpectralRFFIPerEyeExtended),
        ("right", OptionSpectralRFFIPerEyeExtended),
    ]

    def __init__(self, left: OptionSpectralRFFIPerEyeExtended = None, right: OptionSpectralRFFIPerEyeExtended = None):
        ...

TobiiIVTFilterConfig

Configuration for the Tobii I-VT filter.

Fields

  • detect_fixation_if_angle_speed_below_deg_per_sec - Threshold at which fixation won’t be detected anymore. The recommended value is 30°/s, the value is selected to be sufficient for recordings with various levels of noise. However, modifications to this setting might be necessary for recordings and projects with very noisy data.
  • discard_fixations_below_us - Fixations with a duration below this threshold will be discarded. Duration is given in microseconds (µs)
  • merge_adjacent_when_gap_below_us - Fixations separated by at most this interval that fulfill the angle threshold can be merged into one. Duration is given in microseconds (µs)
  • merge_adjacent_when_angle_below_deg - Fixations with angular differences below this angle that fulfill the time gap threshold can be merged into one.
  • gap_fill_in_interpolation_duration_below_us - Missing data gaps with duration below will be filled-in with interpolation data. This value should be chosen to not fill in blinks and other gaps caused by the participant or researcher. If set to 0 fill-in interpolation is disabled Duration is given in microseconds (µs)

Definition

class TobiiIVTFilterConfig(ctypes.Structure):

    _fields_ = [
        ("detect_fixation_if_angle_speed_below_deg_per_sec", ctypes.c_float),
        ("discard_fixations_below_us", ctypes.c_int64),
        ("merge_adjacent_when_gap_below_us", ctypes.c_int64),
        ("merge_adjacent_when_angle_below_deg", ctypes.c_float),
        ("gap_fill_in_interpolation_duration_below_us", ctypes.c_int64),
    ]

    def __init__(self, detect_fixation_if_angle_speed_below_deg_per_sec: float = None, discard_fixations_below_us: int = None, merge_adjacent_when_gap_below_us: int = None, merge_adjacent_when_angle_below_deg: float = None, gap_fill_in_interpolation_duration_below_us: int = None):
        ...

Vector3f32

A 3-dimensional vector.

Fields

  • x - x component.
  • y - y component.
  • z - z component.

Definition

class Vector3f32(ctypes.Structure):

    _fields_ = [
        ("x", ctypes.c_float),
        ("y", ctypes.c_float),
        ("z", ctypes.c_float),
    ]

    def __init__(self, x: float = None, y: float = None, z: float = None):
        ...

VelocityOutput

Output for left and right eye produced by velocity filters.

Fields

  • left - Velocity output for left eye. A value of none means that there was insufficient data to calculate velocity.
  • right - Velocity output for right eye. A value of none means that there was insufficient data to calculate velocity.

Definition

class VelocityOutput(ctypes.Structure):

    _fields_ = [
        ("left", OptionVelocityPerEye),
        ("right", OptionVelocityPerEye),
    ]

    def __init__(self, left: OptionVelocityPerEye = None, right: OptionVelocityPerEye = None):
        ...

VelocityPerEye

Per eye data of velocity filter output.

Fields

  • gaze_direction - Direction vector of gaze ray.
  • velocity_direction - Velocity direction vector of gaze ray.
  • local_angular_speed_deg - Shortest path (3D angle) instantaneous speed, degrees per second.

Definition

class VelocityPerEye(ctypes.Structure):

    _fields_ = [
        ("gaze_direction", Vector3f32),
        ("velocity_direction", Vector3f32),
        ("local_angular_speed_deg", ctypes.c_float),
    ]

    def __init__(self, gaze_direction: Vector3f32 = None, velocity_direction: Vector3f32 = None, local_angular_speed_deg: float = None):
        ...

VelocityWindowedIndicesConfig

Configuration for the windowed angular gaze velocities using indices for the window definition. Each output velocity is aggregated based on all neighboring pairs of velocities for elements between the given, relative time indices.

Fields

  • index_before - Index difference for the window start before currently calculated value. This value must be specified as a negative index relative to current value.
  • index_after - Index difference for the window end after currently calculated value. This value must be specified as a positive index relative to current value.
  • aggregation - The aggregation type for deltas within the window.

Definition

class VelocityWindowedIndicesConfig(ctypes.Structure):

    _fields_ = [
        ("index_before", ctypes.c_int64),
        ("index_after", ctypes.c_int64),
        ("aggregation", ctypes.c_int),
    ]

    def __init__(self, index_before: int = None, index_after: int = None, aggregation: ctypes.c_int = None):
        ...

VelocityWindowedTimesConfig

Configuration for the windowed angular gaze velocities using times for the window definition. Each output velocity is aggregated based on all neighboring pairs of velocities for elements between the given, relative time stamps

Fields

  • time_before_us - Time when the window starts before currently calculated value. This value must be specified as a negative duration in microseconds (µs).
  • time_after_us - Time when the window ends after currently calculated value. This value must be specified as a positive duration in microseconds (µs).
  • aggregation - The aggregation type for calculating values within the window.

Definition

class VelocityWindowedTimesConfig(ctypes.Structure):

    _fields_ = [
        ("time_before_us", ctypes.c_int64),
        ("time_after_us", ctypes.c_int64),
        ("aggregation", ctypes.c_int),
    ]

    def __init__(self, time_before_us: int = None, time_after_us: int = None, aggregation: ctypes.c_int = None):
        ...

VerifyDeltaOutput

Output from the verify delta filter.

Fields

  • count - Count of elements in time sequence that are outside of the threshold.
  • first_found_time_us - Timestamp in microseconds (µs) of the first element found outside of the threshold.

Definition

class VerifyDeltaOutput(ctypes.Structure):

    _fields_ = [
        ("count", ctypes.c_int64),
        ("first_found_time_us", Optioni64),
    ]

    def __init__(self, count: int = None, first_found_time_us: Optioni64 = None):
        ...

Version

Encodes a version number for our products, like 2.0.1.

Fields

  • major - Major component, e.g. 2.
  • minor - Minor component, e.g. 0.
  • patch - Patch component, e.g. 1.
  • build - Build ID.

Definition

class Version(ctypes.Structure):

    _fields_ = [
        ("major", ctypes.c_uint8),
        ("minor", ctypes.c_uint8),
        ("patch", ctypes.c_uint8),
        ("build", ctypes.c_int64),
    ]

    def __init__(self, major: int = None, minor: int = None, patch: int = None, build: int = None):
        ...

SliceBinocularGaze

A pointer to an array of data someone else owns which may not be modified.

Fields

  • data - Pointer to start of immutable data.
  • len - Number of elements.

Definition

class SliceBinocularGaze(ctypes.Structure):

    _fields_ = [
        ("data", ctypes.POINTER(BinocularGaze)),
        ("len", ctypes.c_uint64),
    ]

    def __init__(self, data: ctypes.POINTER(BinocularGaze) = None, len: int = None):
        ...

SliceBlinkState

A pointer to an array of data someone else owns which may not be modified.

Fields

  • data - Pointer to start of immutable data.
  • len - Number of elements.

Definition

class SliceBlinkState(ctypes.Structure):

    _fields_ = [
        ("data", ctypes.POINTER(BlinkState)),
        ("len", ctypes.c_uint64),
    ]

    def __init__(self, data: ctypes.POINTER(BlinkState) = None, len: int = None):
        ...

SliceCameraPose

A pointer to an array of data someone else owns which may not be modified.

Fields

  • data - Pointer to start of immutable data.
  • len - Number of elements.

Definition

class SliceCameraPose(ctypes.Structure):

    _fields_ = [
        ("data", ctypes.POINTER(CameraPose)),
        ("len", ctypes.c_uint64),
    ]

    def __init__(self, data: ctypes.POINTER(CameraPose) = None, len: int = None):
        ...

SliceEntrancePupilData

A pointer to an array of data someone else owns which may not be modified.

Fields

  • data - Pointer to start of immutable data.
  • len - Number of elements.

Definition

class SliceEntrancePupilData(ctypes.Structure):

    _fields_ = [
        ("data", ctypes.POINTER(EntrancePupilData)),
        ("len", ctypes.c_uint64),
    ]

    def __init__(self, data: ctypes.POINTER(EntrancePupilData) = None, len: int = None):
        ...

SliceFixationOutput

A pointer to an array of data someone else owns which may not be modified.

Fields

  • data - Pointer to start of immutable data.
  • len - Number of elements.

Definition

class SliceFixationOutput(ctypes.Structure):

    _fields_ = [
        ("data", ctypes.POINTER(FixationOutput)),
        ("len", ctypes.c_uint64),
    ]

    def __init__(self, data: ctypes.POINTER(FixationOutput) = None, len: int = None):
        ...

SlicePositionGuide

A pointer to an array of data someone else owns which may not be modified.

Fields

  • data - Pointer to start of immutable data.
  • len - Number of elements.

Definition

class SlicePositionGuide(ctypes.Structure):

    _fields_ = [
        ("data", ctypes.POINTER(PositionGuide)),
        ("len", ctypes.c_uint64),
    ]

    def __init__(self, data: ctypes.POINTER(PositionGuide) = None, len: int = None):
        ...

SlicePupilSizeAbsolute

A pointer to an array of data someone else owns which may not be modified.

Fields

  • data - Pointer to start of immutable data.
  • len - Number of elements.

Definition

class SlicePupilSizeAbsolute(ctypes.Structure):

    _fields_ = [
        ("data", ctypes.POINTER(PupilSizeAbsolute)),
        ("len", ctypes.c_uint64),
    ]

    def __init__(self, data: ctypes.POINTER(PupilSizeAbsolute) = None, len: int = None):
        ...

SliceVelocityOutput

A pointer to an array of data someone else owns which may not be modified.

Fields

  • data - Pointer to start of immutable data.
  • len - Number of elements.

Definition

class SliceVelocityOutput(ctypes.Structure):

    _fields_ = [
        ("data", ctypes.POINTER(VelocityOutput)),
        ("len", ctypes.c_uint64),
    ]

    def __init__(self, data: ctypes.POINTER(VelocityOutput) = None, len: int = None):
        ...

Slicei64

A pointer to an array of data someone else owns which may not be modified.

Fields

  • data - Pointer to start of immutable data.
  • len - Number of elements.

Definition

class Slicei64(ctypes.Structure):

    _fields_ = [
        ("data", ctypes.POINTER(ctypes.c_int64)),
        ("len", ctypes.c_uint64),
    ]

    def __init__(self, data: ctypes.POINTER(ctypes.c_int64) = None, len: int = None):
        ...

OptionPupilPerEye

Option type containing boolean flag and maybe valid data.

Fields

  • t - Element that is maybe valid.
  • is_some - Byte where 1 means element t is valid.

Definition

class OptionPupilPerEye(ctypes.Structure):

    _fields_ = [
        ("t", PupilPerEye),
        ("is_some", ctypes.c_uint8),
    ]

    def __init__(self, t: PupilPerEye = None, is_some: int = None):
        ...

OptionSpectralRFFIPerEye

Option type containing boolean flag and maybe valid data.

Fields

  • t - Element that is maybe valid.
  • is_some - Byte where 1 means element t is valid.

Definition

class OptionSpectralRFFIPerEye(ctypes.Structure):

    _fields_ = [
        ("t", SpectralRFFIPerEye),
        ("is_some", ctypes.c_uint8),
    ]

    def __init__(self, t: SpectralRFFIPerEye = None, is_some: int = None):
        ...

OptionSpectralRFFIPerEyeExtended

Option type containing boolean flag and maybe valid data.

Fields

  • t - Element that is maybe valid.
  • is_some - Byte where 1 means element t is valid.

Definition

class OptionSpectralRFFIPerEyeExtended(ctypes.Structure):

    _fields_ = [
        ("t", SpectralRFFIPerEyeExtended),
        ("is_some", ctypes.c_uint8),
    ]

    def __init__(self, t: SpectralRFFIPerEyeExtended = None, is_some: int = None):
        ...

OptionVelocityPerEye

Option type containing boolean flag and maybe valid data.

Fields

  • t - Element that is maybe valid.
  • is_some - Byte where 1 means element t is valid.

Definition

class OptionVelocityPerEye(ctypes.Structure):

    _fields_ = [
        ("t", VelocityPerEye),
        ("is_some", ctypes.c_uint8),
    ]

    def __init__(self, t: VelocityPerEye = None, is_some: int = None):
        ...

Optionbool

Option type containing boolean flag and maybe valid data.

Fields

  • t - Element that is maybe valid.
  • is_some - Byte where 1 means element t is valid.

Definition

class Optionbool(ctypes.Structure):

    _fields_ = [
        ("t", ctypes.c_bool),
        ("is_some", ctypes.c_uint8),
    ]

    def __init__(self, t: bool = None, is_some: int = None):
        ...

Optionf32

Option type containing boolean flag and maybe valid data.

Fields

  • t - Element that is maybe valid.
  • is_some - Byte where 1 means element t is valid.

Definition

class Optionf32(ctypes.Structure):

    _fields_ = [
        ("t", ctypes.c_float),
        ("is_some", ctypes.c_uint8),
    ]

    def __init__(self, t: float = None, is_some: int = None):
        ...

Optioni64

Option type containing boolean flag and maybe valid data.

Fields

  • t - Element that is maybe valid.
  • is_some - Byte where 1 means element t is valid.

Definition

class Optioni64(ctypes.Structure):

    _fields_ = [
        ("t", ctypes.c_int64),
        ("is_some", ctypes.c_uint8),
    ]

    def __init__(self, t: int = None, is_some: int = None):
        ...

Enums

Aggregation

Aggregation type for calculating values within a window.

Variants

  • Average -
  • Median -
  • Max -
  • Min -
  • AbsAverage -
  • AbsMax -
  • AbsMin -

Definition

class Aggregation:
    Average = 0
    Median = 1
    Max = 2
    Min = 3
    AbsAverage = 4
    AbsMax = 5
    AbsMin = 6

BlinkStatePerEye

Describes the openness of an eye in discrete steps. What exactly constitues and open or closed eye is hardware specific.

Variants

  • Invalid - Eye state was invalid, e.g., could not be measured.
  • Open - Eye is open.
  • Closed - Eye is closed.

Definition

class BlinkStatePerEye:
    Invalid = 0
    Open = 1
    Closed = 2

Eye

Which eye(s) to invalidate.

Variants

  • Left -
  • Right -
  • Both -

Definition

class Eye:
    Left = 0
    Right = 1
    Both = 2

FilterError

Error type returned from filter functions.

Variants

  • Ok - The function executed successfully.
  • LengthMismatch - Parameters of different lengths were passed to the function.
  • InvalidConfig - The configuration passed to the function is invalid.
  • InternalError - The function encountered an internal error.
  • InvalidTimeSequence - The time passed to the data contains an invalid sequence (e.g. not monotonic)
  • NotEnoughData - Not enough data for the function to process.
  • InvalidInputData - Invalid input data was passed to the function.

Definition

class FilterError:
    Ok = 0
    LengthMismatch = 1
    InvalidConfig = 2
    InternalError = 3
    InvalidTimeSequence = 4
    NotEnoughData = 5
    InvalidInputData = 6

LogLevel

Log level for Ocumen functions.

Variants

  • Off -
  • Error -
  • Warn -
  • Info -
  • Debug -
  • Trace -

Definition

class LogLevel:
    Off = 0
    Error = 1
    Warn = 2
    Info = 3
    Debug = 4
    Trace = 5

MissingValueStrategy

How to treat invalid data. Specific values can be provided in handle missing value field.

Variants

  • Value - Provide specific value to use when handling missing value field.
  • Average - Use window average to replace missing values.

Definition

class MissingValueStrategy:
    Value = 0
    Average = 1

ResampleMethod

Method used when resampling data.

Variants

  • TakeNearest - Takes the nearest value in time, or the one after if two identical.
  • TakeNearestBefore - Takes the nearest previous value.
  • TakeNearestAfter - Takes the nearest next value.
  • Interpolate - Interpolates previous and next value.

Definition

class ResampleMethod:
    TakeNearest = 0
    TakeNearestBefore = 1
    TakeNearestAfter = 2
    Interpolate = 3

Scaling

Scaling for the results of the STFT with windowing functions.

Variants

  • NoScaling - No scaling will be applied.
  • Spectrum - ‘Spectrum’ scaling allows results to be interpreted as a magnitude spectrum. The results are scaled to sqrt(1/(sum of applied window Hann/Hamming/Blackman)^2)

Definition

class Scaling:
    NoScaling = 0
    Spectrum = 1

SmoothGazeData

Which component of the gaze ray to apply smoothing to.

Variants

  • Direction - Applies smoothing only to direction.
  • Origin - Applies smoothing only to origin.
  • Both - Applies smoothing to both origin and direction.

Definition

class SmoothGazeData:
    Direction = 0
    Origin = 1
    Both = 2

WindowingFunction

Windowing function to use for STFT calculation.

Variants

  • NoFunction - No windowing function will be used
  • Hann - Hann windowing function
  • Hamming - Hamming windowing function
  • Blackman - Blackman windowing function

Definition

class WindowingFunction:
    NoFunction = 0
    Hann = 1
    Hamming = 2
    Blackman = 3

Functions

get_version

Returns an Ocumen Filters version.

Definition

def get_version() -> Version:
    ...

init_logging

Initializes logging.

If you want log messages this should be called exactly once, as early as possible. Otherwise log messages inside the library will not be recorded.

Definition

def init_logging(config: LoggerConfiguration):
    ...

process_log_messages

Process all outstanding log messages.

The provided callback will be invoked with all outstanding log messages that have occurred since the last invocation.

Definition

def process_log_messages(f):
    ...

Instantaneous Angular Gaze Velocities

Computes instantaneous angular gaze velocities.

The velocities are calculated to be the deltas between two adjacent frames. All angles are reported relative to the user’s ’nose vector'.

The function takes three arrays of matching timestamps, gaze and output. All arrays are required to be the same size. This function must not be used on data with non-monotonic time stamps. The result is written into the output array.

Notes

  • This filter must be used on data with monotonic time stamps.

Output

Definition

def velocity_instantaneous(times: Slicei64 | ctypes.Array[ctypes.c_int64], gaze: SliceBinocularGaze | ctypes.Array[BinocularGaze], output: SliceMutVelocityOutput | ctypes.Array[VelocityOutput]) -> ctypes.c_int:
    ...

Windowed angular gaze velocities (index-based)

Computes index-based windowed angular gaze velocities.

This filter computes relative velocities for-and-between a series of eye tracking samples. Each output velocity is aggregated based on all neighboring pairs of velocities for elements between the given, relative indices

The function takes three arrays of matching timestamps, gaze and output. All arrays are required to be the same size. This function must not be used on data with non-monotonic time stamps. The result is written into the output array.

Notes

  • This filter must be used on data with monotonic time stamps.

VelocityWindowedIndicesConfig

  • “aggregation” - Average
  • “index after” - 0
  • “index before” - -1

Output

Definition

def velocity_windowed_indices(config: VelocityWindowedIndicesConfig, times: Slicei64 | ctypes.Array[ctypes.c_int64], gaze: SliceBinocularGaze | ctypes.Array[BinocularGaze], output: SliceMutVelocityOutput | ctypes.Array[VelocityOutput]) -> ctypes.c_int:
    ...

Windowed angular gaze velocities (time-based)

Computes time-based windowed angular gaze velocities.

This filter computes relative velocities for-and-between a series of eye tracking samples. Each output velocity is aggregated based on all neighboring pairs of velocities for elements between the given, relative time stamps

The function takes three arrays of matching timestamps, gaze and output. All arrays are required to be the same size. This function must not be used on data with non-monotonic time stamps. The result is written into the output array.

Notes

  • This filter must be used on data with monotonic time stamps.

VelocityWindowedTimesConfig

  • “aggregation” - Average
  • “time after” - 20000 µs
  • “time before” - -20000 µs

Output

Definition

def velocity_windowed_times(config: VelocityWindowedTimesConfig, times: Slicei64 | ctypes.Array[ctypes.c_int64], gaze: SliceBinocularGaze | ctypes.Array[BinocularGaze], output: SliceMutVelocityOutput | ctypes.Array[VelocityOutput]) -> ctypes.c_int:
    ...

Saccade Smeets Hooge

Detects saccades, including onset and offset.

The algorithm uses absolute velocity for thresholding onset and offset of saccades and is therefore sensitive to glissades. Using a non up-sampled resolution of eye tracking data will impact accuracy of the onset and offset time of saccades.

The option to consider a direction change to signal the offset of a saccade is not part of the paper and was introduced to try to remedy this algorithms sensitivity to glissades.

The function takes a configuration for the filter, and three arrays of matching timestamps, velocities and output. All arrays are required to be the same size. This filter must not be used on data with non-monotonic time stamps. The output is written into the output array.

Notes

  • This filter must be used on data with monotonic time stamps.

SmeetsHoogeFilterConfig

  • “early peak limit” - 0.25
  • “fixation sigma threshold” - 3.0
  • “fixation velocity minimum” - 5.0 deg/s
  • “fixation velocity window size” - 100000 µs
  • “fixation velocity window start” - 200000 µs
  • “late peak limit” - 0.75
  • “lower threshold” - 75.0 deg/s

Output

References

Smeets and Hooge. Nature of Variability in Saccades. J Neurophysiol 90: 12-20, 2003.

Definition

def saccade_smeets_hooge(config: SmeetsHoogeFilterConfig, times: Slicei64 | ctypes.Array[ctypes.c_int64], velocities: SliceVelocityOutput | ctypes.Array[VelocityOutput], output: SliceMutSaccadeOutput | ctypes.Array[SaccadeOutput]) -> ctypes.c_int:
    ...

Saccade Non-Fixation

A simple detector that classifies everything a saccade that is not a fixation. Internally the filter invokes the given fixation filter and marks all outputs a saccade that were not marked as a fixation. This algorithm was sometimes used in slow desktop eye tracking systems, but unless you have a very special setting, you should probably not use this filter since there are many reasons why a non-fixation is not a saccade.

Notes

  • This filter must be used on data with monotonic time stamps.

Output

Definition

def saccade_non_fixation(fixations: SliceFixationOutput | ctypes.Array[FixationOutput], output: SliceMutSaccadeOutput | ctypes.Array[SaccadeOutput]) -> ctypes.c_int:
    ...

Saccade Simple

Simple filter to compute saccades. This filter will always point to the fastest, and simplest, unspecified saccade filter available. Although no guarantees are made, this filter should give a good out-of-the-box performance if you are only interested in “detecting saccades”. We only recommend to use this filter in cases where you do not need to control which algorithm runs, and if you are fine with changing behavior between versions.

This filter must not be used on data with non-monotonic time stamps.

Notes

  • This filter must be used on data with monotonic time stamps.

Output

Definition

def saccade_simple(times: Slicei64 | ctypes.Array[ctypes.c_int64], gaze: SliceBinocularGaze | ctypes.Array[BinocularGaze], output: SliceMutSaccadeOutput | ctypes.Array[SaccadeOutput]) -> ctypes.c_int:
    ...

Fixation Dispersion Angles

A white-label dispersion detector checking if gaze data is within certain thresholds.

This filter has a good balance between computational performance and accuracy and is suited for situations where eye tracking quality is good, and your primary concern is detecting periods of relative stillness. However, in situations where slow smooth pursuits dominate this filter may not produce optimal results.

The function takes a configuration for the filter, and three arrays of matching timestamps, velocities and output. The result is written into the output array. All arrays are required to be the same size.

Notes

  • This filter must be used on data with monotonic time stamps.
  • The output at position i reflects the interval between fused data i-1 and i.

DispersionAnglesFilterConfig

  • “max angle for fixations” - 3.0°
  • “max outliers” - 1
  • “min duration for fixation” - 100000 µs

Output

References

Holmqvist, K, Nyström, M, Andersson, R, Dewhurst, R, Halszka, J & van de Weijer, J 2011, Eye Tracking : A Comprehensive Guide to Methods and Measures. Oxford University Press.

Definition

def fixation_dispersion_angles(config: DispersionAnglesFilterConfig, times: Slicei64 | ctypes.Array[ctypes.c_int64], velocities: SliceVelocityOutput | ctypes.Array[VelocityOutput], output: SliceMutFixationOutput | ctypes.Array[FixationOutput]) -> ctypes.c_int:
    ...

Fixation Tobii IVT

Fixation classification filter based on the Tobii Velocity-Threshold Identification (I-VT) algorithm. The filter classifies eye movements based on the velocity of the directional shifts of the eye. If it is below a certain threshold the sample for which the velocity is calculated is classified as a part of a fixation. There is, in this filter, no distinction between fixations and smooth pursuit. Depending on the set velocity threshold, smooth pursuits are either classified as none-fixations or fixations.

The Tobii I-VT filter is suited for situations where eye tracking quality is good, and your primary concern is detecting periods in which the eye does not move.

The function takes a configuration for the filter, and three arrays of matching timestamps, gaze, velocities and output. All arrays are required to be the same size. This filter must not be used on data with non-monotonic time stamps. The result is written into the output array.

Notes

  • This filter must be used on data with monotonic time stamps.

TobiiIVTFilterConfig

  • “detect fixation if angle speed below” - 30.0 deg/s
  • “discard fixations below” - 100000 µs
  • “gap fill in interpolation duration below” - 75000 µs
  • “merge adjacent when angle below” - 3.0°
  • “merge adjacent when gap below” - 100000 µs

Output

References

Olsen, Anneli. The Tobii I-VT fixation filter. Tobii Technology (2012): 1-21.

Definition

def fixation_tobii_ivt(config: TobiiIVTFilterConfig, times: Slicei64 | ctypes.Array[ctypes.c_int64], velocities: SliceVelocityOutput | ctypes.Array[VelocityOutput], output: SliceMutFixationOutput | ctypes.Array[FixationOutput]) -> ctypes.c_int:
    ...

Fixation Simple

Simple filter to compute fixations. This filter will always point to the fastest, and simplest, unspecified fixation filter available. Although no guarantees are made, this filter should give a good out-of-the-box performance if you are only interested in “detecting fixations”. We only recommend to use this filter in cases where you do not need to control which algorithm runs, and if you are fine with changing behavior between versions.

Notes

  • This filter must be used on data with monotonic time stamps.
  • The output at position i reflects the interval between fused data i-1 and i.

Output

Definition

def fixation_simple(times: Slicei64 | ctypes.Array[ctypes.c_int64], gaze: SliceBinocularGaze | ctypes.Array[BinocularGaze], output: SliceMutFixationOutput | ctypes.Array[FixationOutput]) -> ctypes.c_int:
    ...

Pupil Lam Thompson Corbett 1987

Computes the size difference between pupils and related metrics.

The function takes a configuration for the filter, and an array of pupil sizes. The output is written into the output array. Both arrays are required to be the same size.

Notes

  • The output at position i reflects the fused measurement i.
  • This filter may be applied to unsorted data.

LamThompsonCorbett1987FilterConfig

  • “loewenfeld criterion” - 0.4 mm
  • “ltc criterion ratio” - 0.15

Output

References

Lam, B. L., Thompson, H. S., & Corbett, J. J. (1987). The Prevalence of Simple Anisocoria. American Journal of Ophthalmology, 104(1), 69–73.

10.1016/0002-9394(87)90296-0

Definition

def pupil_lam_thompson_corbett_1987(config: LamThompsonCorbett1987FilterConfig, pupil_size: SlicePupilSizeAbsolute | ctypes.Array[PupilSizeAbsolute], output: SliceMutPupilOutput | ctypes.Array[PupilOutput]) -> ctypes.c_int:
    ...

Short-time Fourier transform

Compute the Short-time Fourier transform for the gaze local velocities (STFT).

The data is be broken up into chunks or frames of stft_length which overlap each other. Each chunk is Fourier transformed, and the complex result is added to a matrix, which records complex result and power magnitude for each point in time and frequency.

The window size (stft_length) for this function ranges from 2 to 64. If you want to use a larger window, please use the spectral_stft_velocity_extended function.

The returned frequency component i depends on the sampling rate and stft_length and will also be returned. It can be estimated by freq[i] = i * sample_rate / stft_length.

Use resampling to make sure that the input velocity is sampled with sample rate specified in config.

Notes

  • The output at position i has special meaning.

Output

References

Smith, S. (2002). Digital signal processing. London: Newnes. ISBN: 075067444X. 10.1016/B978-0-7506-7444-7.X5036-5

Definition

def spectral_stft_velocity(config: SpectralSTFTConfig, velocities: SliceVelocityOutput | ctypes.Array[VelocityOutput], output: SliceMutSpectralSTFTOutput | ctypes.Array[SpectralSTFTOutput], output_frequencies: SliceMutf32 | ctypes.Array[ctypes.c_float]) -> ctypes.c_int:
    ...

Short-time Fourier transform (extended)

Compute the Short-time Fourier transform for the gaze local velocities (STFT) with extended window sizes.

The data is be broken up into chunks or frames of stft_length which overlap each other. Each chunk is Fourier transformed, and the complex result is added to a matrix, which records complex result and power magnitude for each point in time and frequency.

The window size (stft_length) for this function ranges from 128 to 512. Please note that using this function requires more memory, and we recommend only running it on machines with a high amount of RAM. If you want to use a smaller window, please use the spectral_stft_velocity function.

The returned frequency component i depends on the sampling rate and stft_length and will also be returned. It can be estimated by freq[i] = i * sample_rate / stft_length.

Use resampling to make sure that the input velocity is sampled with sample rate specified in config.

Notes

  • The output at position i has special meaning.

Output

References

Smith, S. (2002). Digital signal processing. London: Newnes. ISBN: 075067444X. 10.1016/B978-0-7506-7444-7.X5036-5

Definition

def spectral_stft_velocity_extended(config: SpectralSTFTConfig, velocities: SliceVelocityOutput | ctypes.Array[VelocityOutput], output: SliceMutSpectralSTFTOutputExtended | ctypes.Array[SpectralSTFTOutputExtended], output_frequencies: SliceMutf32 | ctypes.Array[ctypes.c_float]) -> ctypes.c_int:
    ...

Add Noise

Adds normally distributed noise to eye tracking gaze data.

This filter is useful for testing purposes to stress algorithms and computations under less-than-ideal conditions.

The function takes array of gaze data and configuration. The result is written directly into the gaze data array.

Notes

  • This filter may be applied to unsorted data.

NoiseConfig

  • “mean direction” - 0.0
  • “mean origin” - 0.0
  • “seed” - 0
  • “std dev direction” - 0.05
  • “std dev origin” - 0.02

Output

Definition

def add_noise(config: NoiseConfig, data: SliceMutBinocularGaze | ctypes.Array[BinocularGaze]) -> ctypes.c_int:
    ...

Time Shift

Shifts time by a supplied duration.

The function takes in an array of times and a duration which the array will be shifted by.

Notes

  • This filter may be applied to unsorted data.

Definition

def time_shift(times: SliceMuti64 | ctypes.Array[ctypes.c_int64], duration_us: int) -> ctypes.c_int:
    ...

Verify Delta Above

Checks whether all data has a time delta above a supplied duration.

The function takes in an array of times, as well as a duration in microseconds (µs) and writes the result in the last parameter.

Notes

  • This filter must be used on data with monotonic time stamps.

Definition

def verify_delta_above(times: Slicei64 | ctypes.Array[ctypes.c_int64], duration_us: int, output: ctypes.POINTER(VerifyDeltaOutput)) -> ctypes.c_int:
    ...

Verify Delta Below

Checks whether all data has a time delta below a supplied duration.

The function takes in an array of times, as well as a duration in microseconds (µs) and writes the result in the last parameter.

Notes

  • This filter must be used on data with monotonic time stamps.

Definition

def verify_delta_below(times: Slicei64 | ctypes.Array[ctypes.c_int64], duration_us: int, output: ctypes.POINTER(VerifyDeltaOutput)) -> ctypes.c_int:
    ...

Force Increasing Timestamp

Enforces that all timestamps are strictly increasing.

If non-strictly monotonic timestamps are found their value will be forced to be monotonic. This is done by setting them to a value larger than the previous timestamp, based on the given minimum delta parameter. Fails the pipeline if the time between two adjacent samples is lower than the given threshold.

This stage can be used if sensor data fails to time sync properly but is known to be ordered. In that case new time stamps are forced onto the data so subsequent stages (e.g., fusion) can still attempt to merge the data sensibly.

The function takes array of timestamps, delta parameter in microseconds (µs) and output array for rearranged timestamps. The result is written into the output timestamps array.

Definition

def force_increasing_timestamp(times: Slicei64 | ctypes.Array[ctypes.c_int64], min_delta_us: int, output: SliceMuti64 | ctypes.Array[ctypes.c_int64]) -> ctypes.c_int:
    ...

Sort By Time

Sorts data by timestamp in ascending order.

The function takes a pointer to the data, the length of the data, the size of each element in the data, and a array of timestamps.

The provided pointer is assumed to be a pointer where each element is of the provided size. The provided array of timestamps must be to be the same length of the data array.

Both the data and the timestamps are modified in place.

Notes

  • This filter may be applied to unsorted data.

Definition

def sort_data_by_timestamp(data_ptr: ctypes.c_void_p, data_len: int, data_elem_size: int, timestamps: SliceMuti64 | ctypes.Array[ctypes.c_int64]) -> ctypes.c_int:
    ...

Resample Binocular Gaze

Resamples binocular gaze data given a method and target times.

The data from the time and gaze arrays will be resampled to match the target times array in accordance with the supplied method. The resulting data will be written into the output array.

Output

Definition

def resample_binocular_gaze(method: ctypes.c_int, invalid_treshold: int, times: Slicei64 | ctypes.Array[ctypes.c_int64], data: SliceBinocularGaze | ctypes.Array[BinocularGaze], target_times: Slicei64 | ctypes.Array[ctypes.c_int64], output: SliceMutBinocularGaze | ctypes.Array[BinocularGaze]) -> ctypes.c_int:
    ...

Resample Position Guide Data

Resample position guide data given a method and target times.

The data from the time and position guide array will be resampled to match the target times array in accordance with the supplied method. The resulting data will be written into the output array.

Output

Definition

def resample_position_guide_data(method: ctypes.c_int, invalid_treshold: int, times: Slicei64 | ctypes.Array[ctypes.c_int64], data: SlicePositionGuide | ctypes.Array[PositionGuide], target_times: Slicei64 | ctypes.Array[ctypes.c_int64], output: SliceMutPositionGuide | ctypes.Array[PositionGuide]) -> ctypes.c_int:
    ...

Resample Entrance Pupil Data

Resample entrance pupil data given a method and target times.

The data from the time and entrance pupils array will be resampled to match the target times array in accordance with the supplied method. The resulting data will be written into the output array.

Output

Definition

def resample_entrance_pupil_data(method: ctypes.c_int, invalid_treshold: int, times: Slicei64 | ctypes.Array[ctypes.c_int64], data: SliceEntrancePupilData | ctypes.Array[EntrancePupilData], target_times: Slicei64 | ctypes.Array[ctypes.c_int64], output: SliceMutEntrancePupilData | ctypes.Array[EntrancePupilData]) -> ctypes.c_int:
    ...

Resample Pupil Size Data

Resample pupil size data given a method and target times.

The data from the time and pupil size array will be resampled to match the target times array in accordance with the supplied method. The resulting data will be written into the output array.

Output

Definition

def resample_pupil_size_absolute_data(method: ctypes.c_int, invalid_treshold: int, times: Slicei64 | ctypes.Array[ctypes.c_int64], data: SlicePupilSizeAbsolute | ctypes.Array[PupilSizeAbsolute], target_times: Slicei64 | ctypes.Array[ctypes.c_int64], output: SliceMutPupilSizeAbsolute | ctypes.Array[PupilSizeAbsolute]) -> ctypes.c_int:
    ...

Transform Binocular Gaze

Transforms binocular gaze from the local eye tracker coordinate system to world space given a matching head pose.

To read more about coordinate systems and transformations, see https://developer.tobii.com/xr/learn/technical-information/coordinate-systems/ Keep in mind that the eye tracking data and head pose needs to be synced, since they may be temporally shifted, read more at https://developer.tobii.com/xr/learn/technical-information/time-synchronization/

Output

Definition

def transform_binocular_gaze(gaze: SliceBinocularGaze | ctypes.Array[BinocularGaze], head_pose: SliceCameraPose | ctypes.Array[CameraPose], output: SliceMutBinocularGaze | ctypes.Array[BinocularGaze]) -> ctypes.c_int:
    ...

Detects near blinks.

Eye tracking data around blinks can sometimes exhibit what can best be described as “dipping”, a measurement of vertical movement. Since this dipping behavior can interfere with some algorithms this filter allows you to invalidate eye tracking samples around blinks more aggressively so that dipping won’t be detected.

Using this function you can get an array of boolean values indicating blink or near blink for both eyes and apply it later on any data type you need.

Notes

  • This filter must be used on data with monotonic time stamps.

InvalidateNearBlinkConfig

  • “after” - 20000 µs
  • “before” - 20000 µs
  • “min blink duration” - 50000 µs

Output

Definition

def detect_near_blinks(config: InvalidateNearBlinkConfig, times: Slicei64 | ctypes.Array[ctypes.c_int64], blinks: SliceBlinkState | ctypes.Array[BlinkState], output: SliceMutNearBlinkOutput | ctypes.Array[NearBlinkOutput]) -> ctypes.c_int:
    ...

Invalidates entrance pupil data before and after a blink.

Eye tracking data around blinks can sometimes exhibit what can best be described as “dipping”, a measurement of vertical movement. Since this dipping behavior can interfere with some algorithms this filter allows you to invalidate eye tracking samples around blinks more aggressively so that dipping won’t be detected.

Notes

  • This filter must be used on data with monotonic time stamps.

InvalidateNearBlinkConfig

  • “after” - 20000 µs
  • “before” - 20000 µs
  • “min blink duration” - 50000 µs

Output

Definition

def invalidate_near_blink_entrance_pupil(config: InvalidateNearBlinkConfig, times: Slicei64 | ctypes.Array[ctypes.c_int64], blinks: SliceBlinkState | ctypes.Array[BlinkState], data: SliceMutEntrancePupilData | ctypes.Array[EntrancePupilData]) -> ctypes.c_int:
    ...

Invalidates binocular gaze data before and after a blink.

Eye tracking data around blinks can sometimes exhibit what can best be described as “dipping”, a measurement of vertical movement. Since this dipping behavior can interfere with some algorithms this filter allows you to invalidate eye tracking samples around blinks more aggressively so that dipping won’t be detected.

Notes

  • This filter must be used on data with monotonic time stamps.

InvalidateNearBlinkConfig

  • “after” - 20000 µs
  • “before” - 20000 µs
  • “min blink duration” - 50000 µs

Output

Definition

def invalidate_near_blink_binocular_gaze(config: InvalidateNearBlinkConfig, times: Slicei64 | ctypes.Array[ctypes.c_int64], blinks: SliceBlinkState | ctypes.Array[BlinkState], data: SliceMutBinocularGaze | ctypes.Array[BinocularGaze]) -> ctypes.c_int:
    ...

Invalidates pupil size absolute data before and after a blink.

Eye tracking data around blinks can sometimes exhibit what can best be described as “dipping”, a measurement of vertical movement. Since this dipping behavior can interfere with some algorithms this filter allows you to invalidate eye tracking samples around blinks more aggressively so that dipping won’t be detected.

Notes

  • This filter must be used on data with monotonic time stamps.

InvalidateNearBlinkConfig

  • “after” - 20000 µs
  • “before” - 20000 µs
  • “min blink duration” - 50000 µs

Output

Definition

def invalidate_near_blink_pupil_size_absolute(config: InvalidateNearBlinkConfig, times: Slicei64 | ctypes.Array[ctypes.c_int64], blinks: SliceBlinkState | ctypes.Array[BlinkState], data: SliceMutPupilSizeAbsolute | ctypes.Array[PupilSizeAbsolute]) -> ctypes.c_int:
    ...

Invalidates position guide data before and after a blink.

Eye tracking data around blinks can sometimes exhibit what can best be described as “dipping”, a measurement of vertical movement. Since this dipping behavior can interfere with some algorithms this filter allows you to invalidate eye tracking samples around blinks more aggressively so that dipping won’t be detected.

Notes

  • This filter must be used on data with monotonic time stamps.

InvalidateNearBlinkConfig

  • “after” - 20000 µs
  • “before” - 20000 µs
  • “min blink duration” - 50000 µs

Output

Definition

def invalidate_near_blink_position_guide(config: InvalidateNearBlinkConfig, times: Slicei64 | ctypes.Array[ctypes.c_int64], blinks: SliceBlinkState | ctypes.Array[BlinkState], data: SliceMutPositionGuide | ctypes.Array[PositionGuide]) -> ctypes.c_int:
    ...

Invalidates the blink state data by eye.

InvalidateEyeConfig

  • “eye” - Both

Output

Definition

def invalidate_eye_for_blink_state(config: InvalidateEyeConfig, data: SliceMutBlinkState | ctypes.Array[BlinkState]) -> ctypes.c_int:
    ...

Invalidate Entrance Pupil Data

Invalidates the entrance pupil data by eye.

InvalidateEyeConfig

  • “eye” - Both

Output

Definition

def invalidate_eye_for_entrance_pupil(config: InvalidateEyeConfig, data: SliceMutEntrancePupilData | ctypes.Array[EntrancePupilData]) -> ctypes.c_int:
    ...

Invalidate Gaze Data

Invalidates the gaze data by eye

InvalidateEyeConfig

  • “eye” - Both

Output

Definition

def invalidate_eye_for_gaze(config: InvalidateEyeConfig, data: SliceMutBinocularGaze | ctypes.Array[BinocularGaze]) -> ctypes.c_int:
    ...

Invalidate Pupil Size Data

Invalidates the pupil size data by eye.

InvalidateEyeConfig

  • “eye” - Both

Output

Definition

def invalidate_eye_for_pupil_size(config: InvalidateEyeConfig, data: SliceMutPupilSizeAbsolute | ctypes.Array[PupilSizeAbsolute]) -> ctypes.c_int:
    ...

Invalidate Position Guide Data

Invalidates the position guide data by eye.

InvalidateEyeConfig

  • “eye” - Both

Output

Definition

def invalidate_eye_for_position_guide(config: InvalidateEyeConfig, data: SliceMutPositionGuide | ctypes.Array[PositionGuide]) -> ctypes.c_int:
    ...

Calculate Catmull-Rom Resampling length

Calculates count of the resampled items for Catmull-Rom resampling.

CatmullRomResamplingConfig

  • “output interval” - 4000 µs
  • “single eye resampling” - false

Definition

def calculate_catmull_rom_resampling_length(time_start_us: int, time_end_us: int, config: CatmullRomResamplingConfig, output_length: ctypes.POINTER(ctypes.c_uint64)) -> ctypes.c_int:
    ...

Catmull-Rom Resampling

Samples gaze angles by interpolation using a Catmull-Rom spline.

This processor will create a continuous Catmull-Rom spline over all samples and then sample the spline with the configured time interval.

The resulting data will have gaze angles interpolated.

Using this processor you can achieve higher resolution on eye tracking data and thereby getting higher precision on events produced by filters.

Since this processor will ignore invalid samples when creating the spline, it is highly recommended preceding this processor with a processor that handles invalid data.

The function takes in an array of times and corresponding gaze data, config and writes the result into output time array and output gaze parameters.

Make sure that the length of output parameters match resampled data length (end time - start time) / output interval + 1. You can use calculate resampling length function to get resampled data length.

Notes

  • This filter must be used on data with monotonic time stamps.

CatmullRomResamplingConfig

  • “output interval” - 4000 µs
  • “single eye resampling” - false

Output

References

Catmull, Edwin; Rom, Raphael (1974). A class of local interpolating splines. In Barnhill, Robert E.; Riesenfeld, Richard F. (eds.). Computer Aided Geometric Design. pp. 317–326. 10.1016/B978-0-12-079050-0.50020-5

Definition

def catmull_rom_resampling(config: CatmullRomResamplingConfig, times: Slicei64 | ctypes.Array[ctypes.c_int64], gaze_data: SliceBinocularGaze | ctypes.Array[BinocularGaze], output_times: SliceMuti64 | ctypes.Array[ctypes.c_int64], output_gaze: SliceMutBinocularGaze | ctypes.Array[BinocularGaze]) -> ctypes.c_int:
    ...

Savitzky-Golay Smoothing

Smooths gaze data by interpolation using fitted Savitzky-Golay polynomial functions.

This processor will create a polynomial function for every sample passed to this processor where it can fit a window and output sample this polynomial with the system_timestamp from the original sample.

This processor will try to create a polynomial for a window that contains invalid samples only if there is at least 2 valid samples. It is highly recommended preceding this processor with a processor that handles invalid data.

The function takes in an array of times and corresponding gaze data, config and writes the result into output gaze array. If smoothing is impossible due to lack of data, initial values are copied to the output gaze.

Notes

  • This filter must be used on data with monotonic time stamps.

SavitzkyGolaySmoothingConfig

  • “half window size” - 2
  • “polynomial degree” - 2
  • “smooth gaze” - Direction

Output

References

Savitzky, A. and Golay, M.J.E. (1964) Smoothing and Differentiation of Data by Simplified Least-Squares Procedures. Analytical Chemistry, 36, 1627-1639. 10.1021/ac60214a047

Definition

def savitzky_golay_smoothing(config: SavitzkyGolaySmoothingConfig, times: Slicei64 | ctypes.Array[ctypes.c_int64], gaze_data: SliceBinocularGaze | ctypes.Array[BinocularGaze], output_gaze: SliceMutBinocularGaze | ctypes.Array[BinocularGaze]) -> ctypes.c_int:
    ...