### Installing GazeTracking (Shell)

Source: https://github.com/antoinelame/gazetracking/blob/master/README.md

Clone the repository and set up dependencies using pip or conda environments. Requires NumPy, OpenCV, and Dlib; Dlib needs Boost, Boost.Python, CMake, and X11/XQuartz. Verify by running the example script.

```shell
git clone https://github.com/antoinelame/GazeTracking.git
pip install -r requirements.txt
python example.py
```

```shell
conda env create --file environment.yml
conda activate GazeTracking
```

--------------------------------

### GazeTracking API Methods (Python)

Source: https://github.com/antoinelame/gazetracking/blob/master/README.md

Provides methods to refresh frames, get pupil coordinates, check gaze directions (left/right/center), retrieve horizontal/vertical ratios (0.0-1.0), detect blinking, and obtain annotated frames. Requires a GazeTracking instance and input frames as numpy arrays; outputs coordinates, booleans, or ratios. Limitations include dependency on lighting and webcam quality for accuracy.

```python
gaze.refresh(frame)
```

```python
gaze.pupil_left_coords()
```

```python
gaze.pupil_right_coords()
```

```python
gaze.is_left()
```

```python
gaze.is_right()
```

```python
gaze.is_center()
```

```python
ratio = gaze.horizontal_ratio()
```

```python
ratio = gaze.vertical_ratio()
```

```python
gaze.is_blinking()
```

```python
frame = gaze.annotated_frame()
```

--------------------------------

### Get Horizontal Gaze Ratio with Python

Source: https://context7.com/antoinelame/gazetracking/llms.txt

This Python code captures webcam video and uses the GazeTracking library to calculate the horizontal gaze ratio, a value between 0.0 (extreme right) and 1.0 (extreme left). It visualizes the ratio and determined direction (RIGHT, CENTER, LEFT) on the frame. The script runs for a maximum of 10 seconds or until the ESC key is pressed, then prints the average ratio.

```python
import cv2
from gaze_tracking import GazeTracking
import time

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

gaze_history = []
start_time = time.time()

while True:
    _, frame = webcam.read()
    gaze.refresh(frame)

    h_ratio = gaze.horizontal_ratio()

    if h_ratio is not None:
        gaze_history.append(h_ratio)

        # Determine direction with precise ratio
        if h_ratio <= 0.35:
            direction = "RIGHT"
        elif h_ratio >= 0.65:
            direction = "LEFT"
        else:
            direction = "CENTER"

        # Create visual indicator bar
        bar_width = int(h_ratio * 400)
        cv2.rectangle(frame, (50, 150), (450, 180), (100, 100, 100), 2)
        cv2.rectangle(frame, (50, 150), (50 + bar_width, 180), (0, 255, 0), -1)

        cv2.putText(frame, f"H-Ratio: {h_ratio:.3f}", (50, 50),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.9, (255, 255, 255), 2)
        cv2.putText(frame, f"Direction: {direction}", (50, 100),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.9, (255, 255, 255), 2)
    else:
        cv2.putText(frame, "No gaze detected", (50, 50),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.9, (0, 0, 255), 2)

    cv2.imshow("Horizontal Gaze Ratio", frame)

    if cv2.waitKey(1) == 27 or time.time() - start_time > 10:
        break

webcam.release()
cv2.destroyAllWindows()

if gaze_history:
    avg_ratio = sum(gaze_history) / len(gaze_history)
    print(f"Average horizontal ratio: {avg_ratio:.3f}")
```

--------------------------------

### Get Right Pupil Coordinates

Source: https://context7.com/antoinelame/gazetracking/llms.txt

Returns absolute (x, y) pixel coordinates of the right pupil in the frame, or None if pupil is not detected. Includes visual feedback by drawing a blue circle at the detected position for verification.

```python
import cv2
from gaze_tracking import GazeTracking

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

while True:
    _, frame = webcam.read()
    gaze.refresh(frame)

    right_pupil = gaze.pupil_right_coords()

    if right_pupil is not None:
        x, y = right_pupil
        print(f"Right pupil position: X={x}, Y={y}")

        # Draw marker on right pupil
        cv2.circle(frame, (x, y), 3, (255, 0, 0), -1)
    else:
        print("Right pupil not detected")

    cv2.imshow("Right Pupil Tracking", frame)

    if cv2.waitKey(1) == 27:
        break

webcam.release()
cv2.destroyAllWindows()
```

--------------------------------

### Get Left Pupil Coordinates

Source: https://context7.com/antoinelame/gazetracking/llms.txt

Returns absolute (x, y) pixel coordinates of the left pupil in the frame, or None if pupil is not detected. Includes visual feedback by drawing a red circle at the detected position for verification.

```python
import cv2
from gaze_tracking import GazeTracking

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

while True:
    _, frame = webcam.read()
    gaze.refresh(frame)

    left_pupil = gaze.pupil_left_coords()

    if left_pupil is not None:
        x, y = left_pupil
        print(f"Left pupil position: X={x}, Y={y}")

        # Draw marker on left pupil
        cv2.circle(frame, (x, y), 3, (0, 0, 255), -1)
    else:
        print("Left pupil not detected")

    cv2.imshow("Left Pupil Tracking", frame)

    if cv2.waitKey(1) == 27:
        break

webcam.release()
cv2.destroyAllWindows()
```

--------------------------------

### Initialize GazeTracking Instance

Source: https://context7.com/antoinelame/gazetracking/llms.txt

Creates a new gaze tracking object that handles face detection, eye isolation, and pupil tracking using Dlib's facial landmark predictor. Requires OpenCV for video capture functionality and proper webcam access.

```python
from gaze_tracking import GazeTracking
import cv2

# Initialize the gaze tracking system
gaze = GazeTracking()

# Open webcam connection
webcam = cv2.VideoCapture(0)

# Verify initialization
if not webcam.isOpened():
    print("Error: Could not access webcam")
else:
    print("GazeTracking initialized successfully")
```

--------------------------------

### Implement complete gaze tracking with pupil detection and statistics

Source: https://context7.com/antoinelame/gazetracking/llms.txt

This Python script demonstrates simultaneous use of all gaze tracking features including direction detection, pupil coordinates, gaze ratios, and blink detection. It uses OpenCV for video capture and the GazeTracking library for gaze analysis. The code captures real-time video, processes each frame to detect gaze direction and pupil positions, and displays comprehensive statistics including blink count and look direction percentages. Dependencies include cv2, gaze_tracking, and time modules.

```python
import cv2
from gaze_tracking import GazeTracking
import time

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

# Statistics tracking
stats = {
    "frames": 0,
    "blinks": 0,
    "left_looks": 0,
    "right_looks": 0,
    "center_looks": 0
}

start_time = time.time()
was_blinking = False

while True:
    success, frame = webcam.read()

    if not success:
        print("Failed to capture frame")
        break

    gaze.refresh(frame)
    stats["frames"] += 1

    # Get annotated frame as base
    display_frame = gaze.annotated_frame()

    if gaze.pupils_located:
        # Pupil coordinates
        left_pupil = gaze.pupil_left_coords()
        right_pupil = gaze.pupil_right_coords()

        # Gaze ratios
        h_ratio = gaze.horizontal_ratio()
        v_ratio = gaze.vertical_ratio()

        # Direction detection
        direction = "UNKNOWN"
        if gaze.is_blinking():
            direction = "BLINKING"
            if not was_blinking:
                stats["blinks"] += 1
            was_blinking = True
        else:
            was_blinking = False
            if gaze.is_left():
                direction = "LEFT"
                stats["left_looks"] += 1
            elif gaze.is_right():
                direction = "RIGHT"
                stats["right_looks"] += 1
            elif gaze.is_center():
                direction = "CENTER"
                stats["center_looks"] += 1

        # Display all information
        y_offset = 30
        cv2.putText(display_frame, f"Direction: {direction}", (10, y_offset),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 255, 0), 2)

        y_offset += 30
        cv2.putText(display_frame, f"H-Ratio: {h_ratio:.3f} | V-Ratio: {v_ratio:.3f}",
                    (10, y_offset), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 255, 255), 2)

        y_offset += 25
        cv2.putText(display_frame, f"Left: {left_pupil} | Right: {right_pupil}",
                    (10, y_offset), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (255, 255, 255), 1)

        # Statistics panel
        y_offset += 30
        cv2.putText(display_frame, f"Blinks: {stats['blinks']} | "
                                  f"L: {stats['left_looks']} | "
                                  f"C: {stats['center_looks']} | "
                                  f"R: {stats['right_looks']}",
                    (10, y_offset), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (200, 200, 200), 1)

        # Draw horizontal gaze indicator bar
        bar_x = int(h_ratio * 400)
        cv2.rectangle(display_frame, (100, 430), (500, 450), (100, 100, 100), 2)
        cv2.rectangle(display_frame, (100, 430), (100 + bar_x, 450), (0, 255, 0), -1)
        cv2.line(display_frame, (300, 425), (300, 455), (255, 0, 0), 2)  # Center mark

    else:
        cv2.putText(display_frame, "No face detected", (10, 30),
                    cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 0, 255), 2)

    # Show elapsed time and FPS
    elapsed = time.time() - start_time
    fps = stats["frames"] / elapsed if elapsed > 0 else 0
    cv2.putText(display_frame, f"Time: {elapsed:.1f}s | FPS: {fps:.1f}",
                (10, display_frame.shape[0] - 20),
                cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 255, 0), 2)

    cv2.imshow("Complete Gaze Tracking Demo", display_frame)

    if cv2.waitKey(1) == 27:  # ESC to exit
        break

webcam.release()
cv2.destroyAllWindows()

# Print final statistics
print("\n=== Session Statistics ===")
print(f"Total frames: {stats['frames']}")
print(f"Total blinks: {stats['blinks']}")
print(f"Left looks: {stats['left_looks']} ({stats['left_looks']/stats['frames']*100:.1f}%)")
print(f"Center looks: {stats['center_looks']} ({stats['center_looks']/stats['frames']*100:.1f}%)")
print(f"Right looks: {stats['right_looks']} ({stats['right_looks']/stats['frames']*100:.1f}%)")
print(f"Session duration: {elapsed:.2f} seconds")
print(f"Average FPS: {fps:.1f}")
```

--------------------------------

### Simple Gaze Detection Demo (Python)

Source: https://github.com/antoinelame/gazetracking/blob/master/README.md

Captures webcam frames, processes them with GazeTracking for gaze direction, and annotates the frame with text indicating left, right, or center gaze. Uses OpenCV for video capture and display; exits on ESC key. Depends on GazeTracking instance and webcam access.

```python
import cv2
from gaze_tracking import GazeTracking

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

while True:
    _, frame = webcam.read()
    gaze.refresh(frame)

    new_frame = gaze.annotated_frame()
    text = ""

    if gaze.is_right():
        text = "Looking right"
    elif gaze.is_left():
        text = "Looking left"
    elif gaze.is_center():
        text = "Looking center"

    cv2.putText(new_frame, text, (60, 60), cv2.FONT_HERSHEY_DUPLEX, 2, (255, 0, 0), 2)
    cv2.imshow("Demo", new_frame)

    if cv2.waitKey(1) == 27:
        break
```

--------------------------------

### Annotate gaze tracking frame in Python

Source: https://context7.com/antoinelame/gazetracking/llms.txt

Generates annotated frames with pupil crosshairs and gaze direction indicators. Displays pupil coordinates and frame count. Requires OpenCV and GazeTracking library with webcam input.

```python
import cv2
from gaze_tracking import GazeTracking

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

frame_count = 0

while True:
    _, frame = webcam.read()
    gaze.refresh(frame)

    # Get frame with pupil annotations
    annotated_frame = gaze.annotated_frame()

    # Add additional information overlay
    if gaze.pupils_located:
        left = gaze.pupil_left_coords()
        right = gaze.pupil_right_coords()

        info_text = f"Frame: {frame_count} | Left: {left} | Right: {right}"
        cv2.putText(annotated_frame, info_text, (10, 30),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 255, 255), 2)

        # Add gaze direction indicator
        if gaze.is_left():
            direction = "LEFT"
        elif gaze.is_right():
            direction = "RIGHT"
        elif gaze.is_center():
            direction = "CENTER"
        else:
            direction = "UNKNOWN"

        cv2.putText(annotated_frame, f"Gaze: {direction}", (10, 60),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.9, (0, 255, 0), 2)
    else:
        cv2.putText(annotated_frame, "No face detected", (10, 30),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 0, 255), 2)

    cv2.imshow("Annotated Gaze Tracking", annotated_frame)
    frame_count += 1

    if cv2.waitKey(1) == 27:
        break

webcam.release()
cv2.destroyAllWindows()
```

--------------------------------

### Detect eye blinking in Python

Source: https://context7.com/antoinelame/gazetracking/llms.txt

Identifies eye blinks using eye aspect ratio (threshold > 3.8). Tracks blink count and time since last blink. Visual feedback shows blinking status in red/green. Requires webcam and time modules.

```python
import cv2
from gaze_tracking import GazeTracking
import time

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

blink_count = 0
last_blink_time = 0
was_blinking = False

while True:
    _, frame = webcam.read()
    gaze.refresh(frame)

    is_blinking = gaze.is_blinking()
    current_time = time.time()

    # Detect blink event (transition from not blinking to blinking)
    if is_blinking and not was_blinking:
        blink_count += 1
        last_blink_time = current_time
        print(f"Blink detected! Total: {blink_count}")

    was_blinking = is_blinking

    if is_blinking:
        status = "BLINKING"
        color = (0, 0, 255)  # Red
    else:
        status = "Eyes Open"
        color = (0, 255, 0)  # Green

    # Calculate time since last blink
    time_since_blink = current_time - last_blink_time if last_blink_time > 0 else 0

    cv2.putText(frame, status, (50, 50),
                cv2.FONT_HERSHEY_SIMPLEX, 1.5, color, 3)
    cv2.putText(frame, f"Blink Count: {blink_count}", (50, 100),
                cv2.FONT_HERSHEY_SIMPLEX, 0.8, (255, 255, 255), 2)
    cv2.putText(frame, f"Last blink: {time_since_blink:.1f}s ago", (50, 140),
                cv2.FONT_HERSHEY_SIMPLEX, 0.8, (255, 255, 255), 2)

    cv2.imshow("Blink Detection", frame)

    if cv2.waitKey(1) == 27:
        break

webcam.release()
cv2.destroyAllWindows()
print(f"Session summary: {blink_count} blinks detected")
```

--------------------------------

### Calculate vertical gaze ratio in Python

Source: https://context7.com/antoinelame/gazetracking/llms.txt

Measures vertical gaze direction (0.0-1.0) using OpenCV and GazeTracking library. Outputs categorized positions (TOP/CENTER/BOTTOM) with visual indicator bar. Requires webcam input.

```python
import cv2
from gaze_tracking import GazeTracking

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

vertical_positions = {"top": 0, "center": 0, "bottom": 0}

while True:
    _, frame = webcam.read()
    gaze.refresh(frame)

    v_ratio = gaze.vertical_ratio()

    if v_ratio is not None:
        # Categorize vertical position
        if v_ratio < 0.4:
            v_position = "TOP"
            vertical_positions["top"] += 1
            color = (255, 0, 0)
        elif v_ratio > 0.6:
            v_position = "BOTTOM"
            vertical_positions["bottom"] += 1
            color = (0, 0, 255)
        else:
            v_position = "CENTER"
            vertical_positions["center"] += 1
            color = (0, 255, 0)

        # Create vertical indicator bar
        bar_height = int(v_ratio * 300)
        cv2.rectangle(frame, (550, 50), (580, 350), (100, 100, 100), 2)
        cv2.rectangle(frame, (550, 50), (580, 50 + bar_height), color, -1)

        cv2.putText(frame, f"V-Ratio: {v_ratio:.3f}", (50, 50),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.9, (255, 255, 255), 2)
        cv2.putText(frame, f"Position: {v_position}", (50, 100),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.9, color, 2)
        cv2.putText(frame, f"T:{vertical_positions['top']} "
                          f"C:{vertical_positions['center']} "
                          f"B:{vertical_positions['bottom']}",
                    (50, 150), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (255, 255, 255), 2)

    cv2.imshow("Vertical Gaze Ratio", frame)

    if cv2.waitKey(1) == 27:
        break

webcam.release()
cv2.destroyAllWindows()
```

--------------------------------

### Refresh Frame for Analysis

Source: https://context7.com/antoinelame/gazetracking/llms.txt

Processes a new video frame to update pupil positions and gaze direction. Must be called in a loop for continuous tracking. Uses OpenCV to capture frames and handles connection failures gracefully.

```python
import cv2
from gaze_tracking import GazeTracking

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

while True:
    success, frame = webcam.read()

    if not success:
        print("Failed to capture frame")
        break

    # Analyze the current frame
    gaze.refresh(frame)

    # Frame is now processed and ready for queries
    if gaze.pupils_located:
        print("Face and pupils detected successfully")

    if cv2.waitKey(1) == 27:  # ESC to exit
        break

webcam.release()
cv2.destroyAllWindows()
```

--------------------------------

### Detect Center Gaze Direction with Python

Source: https://context7.com/antoinelame/gazetracking/llms.txt

This Python script utilizes the GazeTracking library and OpenCV to determine if the user is looking towards the center. It continuously monitors webcam frames, counts the number of frames where the gaze is centered, and provides visual feedback. The program terminates upon pressing the ESC key.

```python
import cv2
from gaze_tracking import GazeTracking

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

center_look_duration = 0

while True:
    _, frame = webcam.read()
    gaze.refresh(frame)

    if gaze.is_center():
        center_look_duration += 1
        status = "LOOKING CENTER"
        color = (255, 0, 0)  # Blue
    else:
        status = "Not centered"
        color = (200, 200, 200)  # Gray

    cv2.putText(frame, status, (50, 50),
                cv2.FONT_HERSHEY_SIMPLEX, 1.2, color, 2)
    cv2.putText(frame, f"Center frames: {center_look_duration}", (50, 100),
                cv2.FONT_HERSHEY_SIMPLEX, 0.8, (255, 255, 255), 2)

    cv2.imshow("Center Gaze Detection", frame)

    if cv2.waitKey(1) == 27:
        break

webcam.release()
cv2.destroyAllWindows()
print(f"Total center gaze frames: {center_look_duration}")
```

--------------------------------

### Detect Left Gaze Direction

Source: https://context7.com/antoinelame/gazetracking/llms.txt

Returns True when user is looking left (horizontal ratio >= 0.65), False otherwise. Provides visual feedback with color-coded text and tracks cumulative left gaze instances using OpenCV for real-time display.

```python
import cv2
from gaze_tracking import GazeTracking

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

left_look_count = 0

while True:
    _, frame = webcam.read()
    gaze.refresh(frame)

    if gaze.is_left():
        left_look_count += 1
        status = "LOOKING LEFT"
        color = (0, 255, 255)  # Yellow
    else:
        status = "Not looking left"
        color = (200, 200, 200)  # Gray

    cv2.putText(frame, status, (50, 50),
                cv2.FONT_HERSHEY_SIMPLEX, 1.2, color, 2)
    cv2.putText(frame, f"Left looks: {left_look_count}", (50, 100),
                cv2.FONT_HERSHEY_SIMPLEX, 0.8, (255, 255, 255), 2)

    cv2.imshow("Left Gaze Detection", frame)

    if cv2.waitKey(1) == 27:
        break

webcam.release()
cv2.destroyAllWindows()
print(f"Total left looks detected: {left_look_count}")
```

--------------------------------

### Detect Right Gaze Direction with Python

Source: https://context7.com/antoinelame/gazetracking/llms.txt

This Python script uses the GazeTracking library and OpenCV to detect when the user is looking to the right. It processes frames from a webcam, updates a counter for rightward gazes, and displays the status on the video feed. The script exits when the ESC key is pressed.

```python
import cv2
from gaze_tracking import GazeTracking

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

right_look_count = 0

while True:
    _, frame = webcam.read()
    gaze.refresh(frame)

    if gaze.is_right():
        right_look_count += 1
        status = "LOOKING RIGHT"
        color = (0, 255, 0)  # Green
    else:
        status = "Not looking right"
        color = (200, 200, 200)  # Gray

    cv2.putText(frame, status, (50, 50),
                cv2.FONT_HERSHEY_SIMPLEX, 1.2, color, 2)
    cv2.putText(frame, f"Right looks: {right_look_count}", (50, 100),
                cv2.FONT_HERSHEY_SIMPLEX, 0.8, (255, 255, 255), 2)

    cv2.imshow("Right Gaze Detection", frame)

    if cv2.waitKey(1) == 27:
        break

webcam.release()
cv2.destroyAllWindows()
print(f"Total right looks detected: {right_look_count}")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.