### Install EyeGestures

Source: https://github.com/nativesensors/eyegestures/blob/main/README.md

Use pip to install the library. If dependencies like mediapipe, scikit-learn, or opencv fail to install, install them manually.

```bash
python3 -m pip install eyeGestures
```

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

### Run EyeGestures Examples

Source: https://github.com/nativesensors/eyegestures/blob/main/README.md

Execute provided example scripts to test the tracker. The legacy tracker is marked for obsolescence.

```bash
python3 examples/simple_example_v2.py
```

```bash
python3 examples/simple_example.py [legacy tracker, will become obsolete]
```

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

### Bufferless VideoCapture Initialization

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Demonstrates initializing the bufferless VideoCapture utility for real-time camera access. Shows examples for webcam, video files, and pickle files.

```python
from eyeGestures.utils import VideoCapture
import cv2

cap = VideoCapture(0, bufforless=True)

# cap = VideoCapture("video.mp4", bufforless=False)
# cap = VideoCapture("frames.pkl")

while True:
    ret, frame = cap.read()
    if not ret:
        print("Failed to get frame")
        break

    cv2.imshow("Camera", frame)

    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.close()
cv2.destroyAllWindows()
```

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

### Install EyeGestures via Pip

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Install the EyeGestures library using pip. If dependencies are missing, install them separately.

```bash
python3 -m pip install eyeGestures
```

```bash
pip install mediapipe scikit-learn opencv-contrib-python
```

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

### Integrate EyeGestures with Pygame

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Full implementation example showing initialization, calibration, and the main tracking loop within a Pygame environment.

```python
import cv2
import pygame
import numpy as np
from eyeGestures.utils import VideoCapture
from eyeGestures import EyeGestures_v3

# Initialize Pygame
pygame.init()
screen_info = pygame.display.Info()
screen_width = screen_info.current_w
screen_height = screen_info.current_h
screen = pygame.display.set_mode((screen_width, screen_height))
pygame.display.set_caption("EyeGestures Demo")
clock = pygame.time.Clock()

# Initialize eye tracking
gestures = EyeGestures_v3()
cap = VideoCapture(0)

# Calibration setup
x = np.arange(0, 1.1, 0.2)
y = np.arange(0, 1.1, 0.2)
xx, yy = np.meshgrid(x, y)
calibration_map = np.column_stack([xx.ravel(), yy.ravel()])
np.random.shuffle(calibration_map)
gestures.uploadCalibrationMap(calibration_map, context="pygame")

# Colors
RED = (255, 0, 100)
BLUE = (100, 0, 255)
GREEN = (0, 255, 0)
WHITE = (255, 255, 255)

n_points = 25
iterator = 0
running = True

while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        elif event.type == pygame.KEYDOWN:
            if event.key == pygame.K_q:
                running = False

    ret, frame = cap.read()
    if not ret:
        continue

    frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
    calibrate = iterator <= n_points

    gaze_event, calib_event = gestures.step(
        frame, calibrate, screen_width, screen_height, context="pygame"
    )

    screen.fill((0, 0, 0))

    if gaze_event:
        # Draw camera feed
        if gaze_event.sub_frame is not None:
            face_surf = pygame.surfarray.make_surface(
                np.rot90(gaze_event.sub_frame)
            )
            screen.blit(face_surf, (0, 0))

        # Draw gaze cursor
        gaze_color = GREEN if gaze_event.saccades else RED
        pygame.draw.circle(screen, gaze_color,
                          (int(gaze_event.point[0]), int(gaze_event.point[1])), 30)

        # Draw calibration target during calibration
        if calibrate and calib_event:
            pygame.draw.circle(screen, BLUE,
                             tuple(calib_event.point.astype(int)),
                             calib_event.acceptance_radius, 3)
            font = pygame.font.Font(None, 36)
            text = font.render(f"Calibration: {iterator}/{n_points}", True, WHITE)
            screen.blit(text, (10, screen_height - 40))
            iterator += 1

        # Display tracking info
        font = pygame.font.Font(None, 24)
        info_text = f"Fixation: {gaze_event.fixation:.2f} | Blink: {gaze_event.blink}"
        text_surf = font.render(info_text, True, WHITE)
        screen.blit(text_surf, (10, 10))

    pygame.display.flip()
    clock.tick(60)

cap.close()
pygame.quit()
```

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

### Clone and Navigate Repository

Source: https://github.com/nativesensors/eyegestures/blob/main/CONTRIBUTING.md

Commands to download the forked repository and enter the project directory.

```sh
git clone https://github.com/YOUR-USERNAME/EyeGestures.git
```

```sh
cd EyeGestures
```

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

### Core Eye Tracking with EyeGestures_v3

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Initialize and use the V3 engine for real-time eye tracking, including calibration, gaze estimation, fixation, saccade, and blink detection. Requires screen dimensions for coordinate scaling.

```python
import cv2
import numpy as np
from eyeGestures.utils import VideoCapture
from eyeGestures import EyeGestures_v3

# Initialize the eye tracking engine
gestures = EyeGestures_v3(calibration_radius=1000)

# Initialize video capture from webcam
cap = VideoCapture(0)

# Screen dimensions for coordinate scaling
screen_width = 1920
screen_height = 1080

# Create calibration map (grid of points from 0.0 to 1.0)
x = np.arange(0, 1.1, 0.2)
y = np.arange(0, 1.1, 0.2)
xx, yy = np.meshgrid(x, y)
calibration_map = np.column_stack([xx.ravel(), yy.ravel()])
np.random.shuffle(calibration_map)

# Upload custom calibration points
gestures.uploadCalibrationMap(calibration_map, context="main")
gestures.setFixation(1.0)

n_calibration_points = 25
iterator = 0

while True:
    ret, frame = cap.read()
    if not ret:
        break

    # Calibrate for first 25 points, then track
    calibrate = iterator <= n_calibration_points

    # Process frame and get gaze event
    event, cevent = gestures.step(
        frame,
        calibrate,
        screen_width,
        screen_height,
        context="main"
    )

    if event is not None:
        # Get gaze position (screen coordinates)
        cursor_x, cursor_y = event.point[0], event.point[1]

        # Fixation detection (0.0 to 1.0, higher = more fixated)
        fixation = event.fixation

        # Saccade detection (rapid eye movement)
        is_saccade = event.saccades

        # Blink detection
        is_blinking = event.blink

        # Get face sub-frame for debugging
        face_image = event.sub_frame

        print(f"Gaze: ({cursor_x:.0f}, {cursor_y:.0f}), "
              f"Fixation: {fixation:.2f}, "
              f"Saccade: {is_saccade}, Blink: {is_blinking}")

        # Track calibration progress
        if cevent and calibrate:
            current_calibration_point = cevent.point
            iterator += 1
            print(f"Calibrating point {iterator}/{n_calibration_points}")

    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.close()
```

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

### Save and Load Calibration Models

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Persist calibrated models to disk to avoid re-calibration in future sessions.

```python
from eyeGestures import EyeGestures_v3
from eyeGestures.utils import VideoCapture

gestures = EyeGestures_v3()
cap = VideoCapture(0)

# ... perform calibration ...
for i in range(100):
    ret, frame = cap.read()
    gestures.step(frame, True, 1920, 1080, context="user_john")

# Save the calibrated model
model_bytes = gestures.saveModel(context="user_john")
if model_bytes:
    with open("calibration_user_john.pkl", "wb") as f:
        f.write(model_bytes)
    print("Model saved successfully")

# Later, load the model for instant tracking without calibration
gestures_new = EyeGestures_v3()
with open("calibration_user_john.pkl", "rb") as f:
    model_bytes = f.read()
gestures_new.loadModel(model_bytes, context="user_john")

# Now track without calibration
ret, frame = cap.read()
event, cevent = gestures_new.step(frame, False, 1920, 1080, context="user_john")
if event:
    print(f"Loaded model tracking: {event.point}")

cap.close()
```

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

### Manage Multi-Context Tracking

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Track multiple users or scenarios simultaneously by assigning unique contexts to calibration maps and step calls.

```python
from eyeGestures import EyeGestures_v3
from eyeGestures.utils import VideoCapture
import numpy as np

gestures = EyeGestures_v3()

# Different calibration maps for different users
user1_calibration = np.array([[0.2, 0.2], [0.8, 0.2], [0.5, 0.5], [0.2, 0.8], [0.8, 0.8]])
user2_calibration = np.array([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [1.0, 1.0]])

gestures.uploadCalibrationMap(user1_calibration, context="user1")
gestures.uploadCalibrationMap(user2_calibration, context="user2")

cap1 = VideoCapture(0)  # Camera for user 1
cap2 = VideoCapture(1)  # Camera for user 2

while True:
    ret1, frame1 = cap1.read()
    ret2, frame2 = cap2.read()

    if ret1:
        event1, _ = gestures.step(frame1, True, 1920, 1080, context="user1")
        if event1:
            print(f"User1 gaze: {event1.point}")

    if ret2:
        event2, _ = gestures.step(frame2, True, 1920, 1080, context="user2")
        if event2:
            print(f"User2 gaze: {event2.point}")

    # Reset specific user's calibration
    # gestures.reset(context="user1")

cap1.close()
cap2.close()
```

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

### Initialize and Process Frames with EyeGesture Engine V2

Source: https://github.com/nativesensors/eyegestures/blob/main/README.md

Initializes the EyeGesture Engine V2 and VideoCapture, then processes each frame to detect events and gaze points. Ensure calibration is set appropriately for your use case.

```python
from eyeGestures.utils import VideoCapture
from eyeGestures import EyeGestures_v2

# Initialize gesture engine and video capture
gestures = EyeGestures_v2()
cap = VideoCapture(0)  
calibrate = True
screen_width = 500
screen_height= 500

# Process each frame
while True:
  ret, frame = cap.read()
  event, cevent = gestures.step(frame,
    calibrate,
    screen_width,
    screen_height,
    context="my_context")

  if event:
    cursor_x, cursor_y = event.point[0], event.point[1]
    fixation = event.fixation
    # calibration_radius: radius for data collection during calibration
```

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

### Real-time Gaze Tracking with EyeGestures_v3

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Demonstrates real-time gaze tracking using the EyeGestures_v3 engine. Requires calibration map upload and processes video frames to detect gaze events.

```python
import numpy as np
import cv2
from eyeGestures import EyeGestures_v3
from eyeGestures.utils import VideoCapture

calibration_map = np.array([
    [0.0, 0.0], [0.5, 0.0], [1.0, 0.0],
    [0.0, 0.5], [0.5, 0.5], [1.0, 0.5],
    [0.0, 1.0], [0.5, 1.0], [1.0, 1.0]
])
gestures = EyeGestures_v3()
gestures.uploadCalibrationMap(calibration_map, context="session1")

cap = VideoCapture(0)
screen_width, screen_height = 1920, 1080

while True:
    ret, frame = cap.read()
    if not ret:
        break

    event, cevent = gestures.step(
        frame,
        calibration=True,
        width=screen_width,
        height=screen_height,
        context="session1"
    )

    if event:
        gaze_x, gaze_y = event.point[0], event.point[1]
        fixation = event.fixation
        blink = event.blink

        algorithm = gestures.whichAlgorithm(context="session1")
        print(f"Using {algorithm}: Gaze at ({gaze_x:.0f}, {gaze_y:.0f})")

    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.close()
```

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

### Implement EyeGesture Engine V3

Source: https://github.com/nativesensors/eyegestures/blob/main/README.md

Initialize the EyeGestures_v3 engine and process video frames to detect eye movements and cursor coordinates.

```python
from eyeGestures.utils import VideoCapture
from eyeGestures import EyeGestures_v3

# Initialize gesture engine and video capture
gestures = EyeGestures_v3()
cap = VideoCapture(0)
calibrate = True
screen_width = 500
screen_height= 500

# Process each frame
while True:
  ret, frame = cap.read()
  event, cevent = gestures.step(frame,
    calibrate,
    screen_width,
    screen_height,
    context="my_context")

  if event:
    cursor_x, cursor_y = event.point[0], event.point[1]
    fixation = event.fixation
    saccades = event.saccadess # saccadess movement detector
    # calibration_radius: radius for data collection during calibration
```

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

### Create a Feature Branch

Source: https://github.com/nativesensors/eyegestures/blob/main/CONTRIBUTING.md

Command to initialize a new branch for feature development or bug fixes.

```sh
git checkout -b your-branch-name
```

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

### Access Calibration Event Data

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Use the Cevent class to retrieve calibration state information and draw UI elements based on target points.

```python
from eyeGestures import EyeGestures_v3
from eyeGestures.utils import VideoCapture

gestures = EyeGestures_v3(calibration_radius=1000)
cap = VideoCapture(0)

ret, frame = cap.read()
event, cevent = gestures.step(frame, True, 1920, 1080, context="main")

if cevent:
    # Current calibration target point [x, y] in screen coordinates
    calibration_point = cevent.point  # np.ndarray

    # Radius within which gaze is accepted as "on target"
    acceptance_radius = cevent.acceptance_radius  # int (pixels)

    # Radius for data collection around calibration point
    calibration_radius = cevent.calibration_radius  # int (pixels)

    # Draw calibration UI
    import cv2
    screen = frame.copy()
    cv2.circle(screen, tuple(calibration_point.astype(int)),
               acceptance_radius, (0, 255, 0), 2)
    cv2.circle(screen, tuple(calibration_point.astype(int)),
               calibration_radius, (255, 0, 0), 1)

cap.close()
```

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

### Legacy Eye Tracking with EyeGestures_v2

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Initialize and configure the V2 engine, a legacy two-stage tracker that blends V1 and V2 models. Allows setting the blending ratio, fixation sensitivity, and enabling background calibration.

```python
import cv2
import numpy as np
from eyeGestures.utils import VideoCapture
from eyeGestures import EyeGestures_v2

# Initialize V2 engine
gestures = EyeGestures_v2(calibration_radius=1000)

# Configure V1/V2 blending ratio
# N=2 means output is: (V2_sample + 2*V1_sample) / 3
gestures.setClassicImpact(2)

# Set fixation sensitivity threshold (0.0 to 1.0)
gestures.setFixation(0.8)

# Enable hidden V1 calibration (runs in background)
gestures.enableCNCalib()
```

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

### Commit and Push Changes

Source: https://github.com/nativesensors/eyegestures/blob/main/CONTRIBUTING.md

Commands to stage, commit, and push local changes to the remote repository.

```sh
git add .
git commit -m "Description of the changes made"
```

```sh
git push origin your-branch-name
```

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

### Initialize and Estimate Gaze with EyeGesture Engine V1

Source: https://github.com/nativesensors/eyegestures/blob/main/README.md

Initializes the legacy EyeGesture Engine V1 with RoI parameters and estimates gaze points from camera frames. Calibration can be enabled or disabled.

```python
from eyeGestures.utils import VideoCapture
from eyeGestures import EyeGestures_v1

# Initialize gesture engine with RoI parameters
gestures = EyeGestures_v1()

cap = VideoCapture(0)  
ret, frame = cap.read()
calibrate = True
screen_width = 500
screen_height= 500

# Obtain estimations from camera frames
event, cevent = gestures.estimate(
    frame,
    "main",
    calibrate,  # set calibration - switch to False to stop calibration
    screen_width,
    screen_height,
    0, 0, 0.8, 10
)

if event:
  cursor_x, cursor_y = event.point[0], event.point[1]
  fixation = event.fixation
  # calibration_radius: radius for data collection during calibration
```

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

### Detect Gaze Fixation

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Initialize the Fixation tracker to monitor if gaze remains stable within a specific radius.

```python
from eyeGestures.Fixation import Fixation

# Initialize fixation tracker with center point and detection radius
fixation_tracker = Fixation(x=500, y=300, radius=100)
```

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

### Customize Calibration Map for EyeGesture Engine V2

Source: https://github.com/nativesensors/eyegestures/blob/main/README.md

Uploads a custom calibration map to the EyeGesture Engine V2. The points should be on x,y planes from 0.0 to 1.0 and will be automatically scaled to your display.

```python
gestures = EyeGestures_v2()
gestures.uploadCalibrationMap([[0,0],[0,1],[1,0],[1,1]])
```

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

### Enable Hidden Calibration for EyeGesture Engine V1/V2

Source: https://github.com/nativesensors/eyegestures/blob/main/README.md

Enables hidden calibration for the EyeGesture Engine, providing V1 calibration behavior that is invisible to the user.

```python
gestures.enableCNCalib()
```

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

### Gevent Data Structure for Gaze Events

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Illustrates accessing various attributes from the Gevent object returned by the step() method, including gaze point, blink status, fixation level, and eye details.

```python
from eyeGestures import EyeGestures_v3
from eyeGestures.utils import VideoCapture
import numpy as np

gestures = EyeGestures_v3()
cap = VideoCapture(0)

ret, frame = cap.read()
event, cevent = gestures.step(frame, True, 1920, 1080, context="main")

if event:
    gaze_point = event.point  # np.ndarray([x, y])
    is_blinking = event.blink  # True/False
    fixation_level = event.fixation  # float 0.0-1.0
    is_saccade = event.saccades  # True/False
    face_frame = event.sub_frame  # cv2 image or None
    left_eye = event.l_eye   # Eye object or None
    right_eye = event.r_eye  # Eye object or None

cap.close()
```

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

### Perform Detailed Eye Analysis

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Access eye landmarks, pupil position, and blink status using the Eye class.

```python
from eyeGestures import EyeGestures_v1
from eyeGestures.utils import VideoCapture

gestures = EyeGestures_v1()
cap = VideoCapture(0)

ret, frame = cap.read()
event, _ = gestures.step(frame, "main", True, 1920, 1080)

if event and event.l_eye:
    left_eye = event.l_eye

    # Get eye center coordinates
    center_x, center_y = left_eye.getCenter()

    # Get eye position in frame
    pos_x, pos_y = left_eye.getPos()

    # Get pupil position
    pupil = left_eye.getPupil()  # np.ndarray or None

    # Check if eye is closed (blink)
    is_blinking = left_eye.getBlink()

    # Get eye openness (vertical size)
    openness = left_eye.getOpenness()

    # Get bounding box (x, y, width, height)
    bbox = left_eye.getBoundingBox()

    # Get all eye landmarks
    landmarks = left_eye.getLandmarks()  # np.ndarray of landmark points

    # Get cropped eye image
    eye_image = left_eye.getImage()

    print(f"Eye center: ({center_x}, {center_y})")
    print(f"Blinking: {is_blinking}")
    print(f"Openness: {openness}")

cap.close()
```

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

### EyeGestures_v1 Model-Based Gaze Tracking

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Initializes and uses the deprecated EyeGestures_v1 engine for gaze tracking. This version uses a pure model-based approach without machine learning.

```python
import cv2
from eyeGestures.utils import VideoCapture
from eyeGestures import EyeGestures_v1

gestures = EyeGestures_v1(
    roi_x=225,
    roi_y=105,
    roi_width=80,
    roi_height=15
)

cap = VideoCapture(0)
screen_width, screen_height = 1920, 1080

while True:
    ret, frame = cap.read()
    if not ret:
        break

    event, cevent = gestures.step(
        frame,
        context="main",
        calibration=True,
        display_width=screen_width,
        display_height=screen_height,
        display_offset_x=0,
        display_offset_y=0,
        fixation_freeze=0.7,
        freeze_radius=20
    )

    if event:
        cursor_x, cursor_y = event.point[0], event.point[1]
        fixation = event.fixation
        blink = event.blink

        left_eye = event.l_eye
        right_eye = event.r_eye

        if left_eye:
            left_landmarks = left_eye.getLandmarks()
            left_blink = left_eye.getBlink()
            left_pupil = left_eye.getPupil()

        print(f"V1 Gaze: ({cursor_x:.0f}, {cursor_y:.0f})")

    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.close()
```

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

### Set Classic Impact for EyeGesture Engine V2

Source: https://github.com/nativesensors/eyegestures/blob/main/README.md

Controls the influence of the V1 model on the V2 gaze point estimation by averaging V2 samples with N copies of V1 samples. A value of N=2 is recommended for testing.

```python
gestures.setClassicImpact(N) # setting N = 2 is working best for my testing 
```

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

### Process Gaze Fixation Points

Source: https://context7.com/nativesensors/eyegestures/llms.txt

Iterate through gaze coordinates to determine fixation levels using the fixation_tracker.

```python
gaze_points = [
    (500, 300), (502, 298), (498, 302), (501, 299),  # Stable gaze
    (700, 400), (705, 398), (698, 402),  # Moved to new position
    (700, 400), (701, 399), (699, 401),  # Fixating at new position
]

for x, y in gaze_points:
    fixation_value = fixation_tracker.process(x, y)
    # fixation_value: 0.0 (just moved) to 1.0 (fully fixated)

    if fixation_value > 0.5:
        print(f"Fixating at ({x}, {y}): {fixation_value:.2f}")
    else:
        print(f"Moving/unstable at ({x}, {y}): {fixation_value:.2f}")
```

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