DeepGlance Quick Documentation

Version 1.0.0

Getting Started

Welcome to DeepGlance Quick! The only QML plugin that allows you to integrate and test eye tracking technology in an immediate and effortless way in your QT Quick application. Turning a traditional interface into a gaze-controlled interface.

This guide will show you how to install and use the DeepGlance Quick plugin.

System Requirements

Before you begin, make sure that your system has the minimum requirements.

Operating System

Currently, Windows and macOS operating systems are officially supported. Support for Linux is coming soon.

Eye Tracking Device

An eye tracking device is necessary to control the application, the first eye tracker to be supported is Tobii 4C, a low-cost high-performance consumer eye tracker.

DeepGlance Quick also integrates an eye tracker simulator that allows you to use the plugin even if you do not yet have an eye tracker and to develop in a more convenient and faster way.

Step 1: Download the DeepGlance Quick plugin

As a first step, contact us to obtain a copy of DeepGlance Quick package.

Step 2: Install the Tobii Stream Engine Library

The Tobii Stream Engine library is a dependency of the plugin and it is distributed in the plugin package.

You must be sure that the Qt Design Studio and your application can find the library.

Windows

Copy 3rdparty/tobii/tobii_stream_engine.dll to a folder in your system path. If you don’t know how to add a folder in your system path follow this guide. 

macOS 

cp 3rdparty/tobii/libtobii_stream_engine.dylib /usr/local/lib

Step 3: Copy the DgQuick plugin in your project

Copy the DgQuick folder in the imports directory of your Qt project.

EyeTracker Type

The EyeTracker type is used to instantiate and start the eye tracking device, this operation must be done only one time in your application.

ApplicationWindow {
    visible: true
    width: 1000
    height: 1000
    title: qsTr("Hello World")

    EyeTracker {
        model: EyeTracker.ModelTobii
        Component.onCompleted: start()
    }
}

The following example shows how to use the eye tracker simulator instead of the physical eye tracker.

ApplicationWindow {
    visible: true
    width: 1000
    height: 1000
    title: qsTr("Hello World")

    EyeTracker {
        model: EyeTracker.ModelSimulator
        Component.onCompleted: start()
    }
    EventHandler {
        anchors.fill: parent
    }
}

Using the simulator is like you are gazing on the mouse pointer, in this way you can reproduce exactly the behavior of a gaze-controlled application using your mouse instead of a physical eye tracker.

Public enums, properties, signals and methods

Enum {
    name: "EyeTrackerModel"
    values: {
        "ModelSimulator": 0,
        "ModelTobii": 1
    }
}
Property { name: "model"; type: "EyeTrackerModel" }
Method { name: "start" }

EyeArea Type

The EyeArea is an area that is sensitive to the eye and it provides the  eye tracking functionalities to the application. The EyeArea is the main component of the DeepGlance Quick plugin and it is used in a similar way to the MouseArea.

In the following example, if you look at the rectangle, after a while it turns red.

Rectangle {
    width: 100
    height: 100
    color: "green"
    EyeArea {
        anchors.fill: parent
        onAction: { parent.color = 'red' }
    }
}

eyeFocus

The eyeFocus property is true only for the currently observed area. In the following example the area changes its opacity using the eyeFocus flag.

Rectangle {
        width: 100
        height: 100
        color: "green"
        opacity: eyeArea.eyeFocus? 1: 0.5
        EyeArea {
            id: eyeArea
            anchors.fill: parent
            onAction: { parent.color = 'red' }
        }
    }

actionProgress

Indicates the progress [0-1] before the action takes place.
In the following example, the area becomes increasingly opaque until the action is triggered.

Rectangle {
    width: 100
    height: 100
    color: "green"
    opacity: eyeArea.eyeFocus? 0.5 + (0.5 * eyeArea.actionProgress): 0.5
    EyeArea {
        id: eyeArea
        anchors.fill: parent
        onAction: { parent.color = 'red' }
    }
}

focusActionMode

There are two ways to trigger an action on a button. The default is related to time, but you can also use the gaze to select the elements and a single physical button to trigger the actions. In the following example, we use the spacebar to confirm the actions.

ApplicationWindow {
    visible: true
    width: 1000
    height: 1000
    title: qsTr("Hello World")

    EyeTracker {
        model: EyeTracker.ModelTobii
        Component.onCompleted: start()
    }

    EventHandler {
        anchors.fill: parent
        focus: true
        Keys.onPressed: {
            if(event.key === Qt.Key_Space) {
                virtualButton.press();
            }
        }
        Keys.onReleased: {
            if(event.key === Qt.Key_Space) {
                virtualButton.release();
            }
        }
    }

    Rectangle {
        width: 100
        height: 100
        color: "green"
        EyeArea {
            anchors.fill: parent
            focusActionMode: EyeArea.ActionModeButton
            focusButtonName: "virtualButton"
            onAction: { parent.color = 'red' }
        }
    }

    VirtualButton {
        id: virtualButton
        objectName: "virtualButton"
    }
}

scrollEnabled

This flag enables the scroll events. In the following example, an image of a map contained in a Flickable is scrolled.

Item {
    readonly property int scrollSpeed: 3000
    width: 1000
    height: 1000
    Flickable {
        id: mapFlickable
        anchors.fill: parent
        clip: true
        contentX: mapImage.width / 2 - mapFlickable.width / 2
        contentY: mapImage.height / 2 - mapFlickable.height / 2
        contentWidth: mapImage.width
        contentHeight: mapImage.height
        Image {
            id: mapImage
            source: "assets/map.png"
        }
    }

    EyeArea {
        x: mapFlickable.x
        y: mapFlickable.y
        width: mapFlickable.width
        height: mapFlickable.height
        scrollEnabled: true
        onScroll: {
            mapFlickable.contentX = Math.max(0, Math.min(mapFlickable.contentWidth - mapFlickable.width, mapFlickable.contentX + (dx * scrollSpeed)))
            mapFlickable.contentY = Math.max(0, Math.min(mapFlickable.contentHeight - mapFlickable.height, mapFlickable.contentY - (dy * scrollSpeed)))
        }
    }
}

Public enums, properties, signals and methods

Enum {
    name: "ActionMode"
    values: {
        "ActionModeDwell": 0,
        "ActionModeButton": 1
    }
}
Property { name: "enabled"; type: "bool" }
Property { name: "eyeFocusDwellTime"; type: "int" }
Property { name: "actionDwellTime"; type: "int" }
Property { name: "croppingEnabled"; type: "bool" }
Property { name: "dragAndDropButtonName"; type: "string" }
Property { name: "dragAndDropEnabled"; type: "bool" }
Property { name: "focusGroup"; type: "int" }
Property { name: "focusActionMode"; type: "ActionMode" }
Property { name: "focusButtonName"; type: "string" }
Property { name: "scrollDeadSubArea"; type: "QRectF" }
Property { name: "scrollEnabled"; type: "bool" }
Property { name: "zoomEnabled"; type: "bool" }
Property { name: "horizontalMagnification"; type: "double" }
Property { name: "verticalMagnification"; type: "double" }
Property { name: "actionProgress"; type: "double" }
Property { name: "eyeFocus"; type: "bool" }
Signal { name: "action" }
Signal {
    name: "dragAndDrop"
    Parameter { name: "eventToNotify"; type: "int" }
    Parameter { name: "dx"; type: "double" }
    Parameter { name: "dy"; type: "double" }
}
Signal {
    name: "actionProgressChanged"
}
Signal {
    name: "eyeFocusChanged"
}
Signal {
    name: "scroll"
    Parameter { name: "dx"; type: "double" }
    Parameter { name: "dy"; type: "double" }
}
Signal {
    name: "zoom"
    Parameter { name: "dz"; type: "double" }
}

TrackStatus Type

The TrackStatus is a real-time graphical representation of the tracking status of the user’s eyes. Below is an example.

TrackStatus {
    id: trackstatus
    width: 400
    height: 240
}

Public enums, properties, signals and methods

Property { name: "backgroundColor"; type: "QColor" }
Property { name: "correctlyPositioned"; type: "bool"; isReadonly: true }
Property { name: "correctPositionEyeColor"; type: "QColor" }
Property { name: "correctPositionOutlineFeedbackEnabled"; type: "bool" }
Property { name: "distanceBarEnabled"; type: "bool" }
Property { name: "eyeRelativeSize"; type: "double" }
Property { name: "eyeValidMinX"; type: "double" }
Property { name: "eyeValidMaxX"; type: "double" }
Property { name: "eyeValidMinY"; type: "double" }
Property { name: "eyeValidMaxY"; type: "double" }
Property { name: "eyeValidMinZ"; type: "double" }
Property { name: "eyeValidMaxZ"; type: "double" }
Property { name: "faceOutlineEnabled"; type: "bool" }
Property { name: "faceReferenceOutlineEnabled"; type: "bool" }
Signal { name: "eyeValidRectChanged" }
Signal { name: "completed" }

EventHandler Type

The EventHandler intercepts mouse and keyboard events and forwards them to the eye tracking engine and makes them available to the application. It should be the size of the entire window.

Public enums, properties, signals and methods

Signal {
    name: "mousePositionChanged"
    Parameter { name: "x"; type: "float" }
    Parameter { name: "y"; type: "float" }
}
Signal {
    name: "mouseWheelChanged"
    Parameter { name: "y"; type: "float" }
}
Signal {
    name: "keyPress"
    Parameter { name: "key"; type: "int" }
}
Signal {
    name: "keyRelease"
    Parameter { name: "key"; type: "int" }
}

ErrorHandler Type

The Errorhandler forwards the errors to the application. The following example shows a dialog when an error is received.

ApplicationWindow {
    visible: true
    width: 1000
    height: 1000
    title: qsTr("Hello World")

    EyeTracker {
        model: EyeTracker.ModelTobii
        Component.onCompleted: start()
    }
    ErrorHandler {
        objectName: "errorHandler"
        id: errorHandler
        anchors.fill: parent
        focus: true
        onError: {
            if (error === ErrorHandler.ErrorEyeTrackerSoftwareNotInstalled) {
                errorDialog.message = "Tobii software not installed"
                errorDialog.visible = true
            } else if (error === ErrorHandler.ErrorEyeTrackerNotConnected) {
                errorDialog.message = "Tobii eye tracker not connected"
                errorDialog.visible = true
            }
        }
    }
    Dialog {
        id: errorDialog
        property alias message: message.text
        title: "Error"
        x: (parent.width - width) / 2
        y: (parent.height - height) / 2
        width: 300
        height: 150
        standardButtons: DialogButtonBox.Ok
        Text {
            id: message
        }
    }
}

Public enums, properties, signals and methods

Enum {
    name: "Error"
    values: {
        "ErrorEyeTrackerSoftwareNotInstalled": 0,
        "ErrorEyeTrackerNotConnected": 1
    }
}
Signal {
    name: "error"
    Parameter { name: "error"; type: "ErrorHandler::Error" }
}

Virtual Button Type

Used to trigger actions in the EyeArea if it is set to ActionModeButton.

Public enums, properties, signals and methods

Method { name: "press" }
Method { name: "release" }

Support

If you need assistance or you use an operating system, a Qt version or an eye tracker not yet supported do not hesitate to contact us.