minor patch

Author: Eaglearn Developer

README.md

@@ -14,6 +14,7 @@ Eaglearn adalah sistem monitoring fokus real-time untuk aktivitas belajar/kerja
 - Head pose (yaw/pitch/roll) + rule-based stress/confusion/drowsiness
 - Focus score + time tracking (focused/unfocused time)
 - Calibration gaze (wizard) + kompensasi head pose sederhana
+- Opsi pembalikan sumbu Y gaze (`eye_tracking.invert_y`) untuk device tertentu
 - Logging metrik sesi (JSONL) + tombol “Simpan Log”
 - Mode pause (privacy)
 
@@ -43,6 +44,12 @@ Skenario pre-release beta memakai `.venv_gpu` untuk menghindari mismatch environ
 Aplikasi berjalan di:
 - Web: `http://localhost:8080`
 
+Alternatif minimal:
+
+```powershell
+.\run_app.bat
+```
+
 ## Instalasi Lengkap
 
 Lihat [INSTALL.md](file:///d:/Eaglearn-Project/INSTALL.md).
@@ -52,6 +59,10 @@ Lihat [INSTALL.md](file:///d:/Eaglearn-Project/INSTALL.md).
 - Konfigurasi utama: [config.yaml](file:///d:/Eaglearn-Project/config.yaml)
 - Contoh env: [.env.example](file:///d:/Eaglearn-Project/.env.example)
 
+Pengaturan penting:
+- Jika arah top/bottom terbalik: ubah `eye_tracking.invert_y` (default: `true`)
+- Threshold fokus: `focus.focused_threshold` dan `focus.distracted_threshold`
+
 ## API (Ringkas)
 
 - `POST /api/session/start`
@@ -64,6 +75,15 @@ WebSocket:
 - `state_update`
 - `frame_update`
 
+## Logging
+
+File yang disimpan di folder `logs/`:
+- `app_YYYYMMDD.log`: log aplikasi Flask (rotating)
+- `metrics_<session_id>.jsonl`: snapshot metrik per ~1 detik (bisa diunduh via `GET /api/logs/metrics/download`)
+
+File non-log yang relevan:
+- `calibrations/<user_id>.json`: data kalibrasi gaze
+
 ## Panduan Darurat (Troubleshooting Flow)
 
 ```text
@@ -93,62 +113,25 @@ Dokumen operasional VLM: [docs/VLM_OPERATIONAL.md](file:///d:/Eaglearn-Project/d
 - TensorFlow GPU di Windows sering tidak tersedia (gpus: `[]`), sementara PyTorch CUDA tetap bisa aktif.
 - VLM bersifat opsional dan membutuhkan dependency tambahan (`transformers`).
 
-## Kontribusi
-
-- PR dan issue diterima. Sertakan langkah reproduksi, log, dan spesifikasi perangkat.
-
-## Lisensi
-
-Lihat [LICENSE](file:///d:/Eaglearn-Project/LICENSE).
-- Check confidence threshold in config
-- See logs for error messages
-
-## Requirements
-
-### Core Dependencies
-
-- Python 3.11+
-- Flask 3.0+
-- Flask-SocketIO 5.3+
-- OpenCV 4.8+
-- MediaPipe 0.10+
-
-### ML Dependencies
-
-- DeepFace 0.0.79+ (emotion detection)
-- TensorFlow 2.15+ (DeepFace backend)
-- PyTorch + torchvision (EfficientNet)
-
-### Optional
-
-- CUDA-capable GPU (for acceleration)
-- POSTER++ weights (for 90% accuracy emotion detection)
-
 ## Development
 
 ### Running Tests
 
 ```bash
-pytest tests/
+pytest -q
 ```
 
 ### Code Quality
 
 ```bash
-# Format code
-black app.py mediapipe_processors/
-
-# Lint code
-pylint app.py
+ruff check .
+mypy app.py improved_webcam_processor.py state_manager.py mediapipe_processors/face_mesh_processor.py
 ```
 
-## License
+## Kontribusi
 
-See LICENSE file.
+- PR dan issue diterima. Sertakan langkah reproduksi, log, dan spesifikasi perangkat.
 
-## Acknowledgments
+## Lisensi
 
-- [MediaPipe](https://google.github.io/mediapipe/) - Face & pose detection
-- [DeepFace](https://github.com/serengil/deepface) - Emotion recognition
-- [PyTorch](https://pytorch.org/) - EfficientNet models
-- [POSTER++](https://github.com/AnnamTk/POSTER) - SOTA emotion detection (optional)
+Lihat [LICENSE](file:///d:/Eaglearn-Project/LICENSE).

calibration.py

@@ -168,6 +168,7 @@ def calculate_calibration(self) -> Dict:
             "scale_factor": scale_factor,
             "screen_width": expected_screen_width,
             "screen_height": expected_screen_height,
+            "invert_y": bool(self.config.get("eye_tracking", "invert_y", default=False)),
             "user_id": getattr(self, "current_user", "default"),
             "calibrated_at": datetime.now().isoformat(),
             "num_points": len(self.calibration_points),

config.yaml

@@ -146,6 +146,7 @@ eye_tracking:
   gaze_scale_x: 800  # Pixels per gaze unit
   gaze_scale_y: 450  # Pixels per gaze unit
   sensitivity_threshold: 0.18  # Lower = more sensitive
+  invert_y: true
 
   # Gaze Smoothing (reduce jitter)
   enable_smoothing: true

improved_webcam_processor.py

@@ -72,14 +72,19 @@ def __init__(self, state, socketio=None):
         try:
             existing_calibration = self.calibration.load_calibration("default")
             if isinstance(existing_calibration, dict):
+                invert_y = bool(config.get("eye_tracking", "invert_y", default=False))
+                calibration_invert_y = bool(existing_calibration.get("invert_y", False))
                 with self.state.lock:
                     self.state.calibration_applied = True
                     self.state.calibration_gaze_offset_x = float(
                         existing_calibration.get("gaze_offset_x", 0.0) or 0.0
                     )
-                    self.state.calibration_gaze_offset_y = float(
+                    offset_y = float(
                         existing_calibration.get("gaze_offset_y", 0.0) or 0.0
                     )
+                    if invert_y and (not calibration_invert_y):
+                        offset_y = -offset_y
+                    self.state.calibration_gaze_offset_y = offset_y
                     self.state.calibration_scale_factor = float(
                         existing_calibration.get("scale_factor", 1.0) or 1.0
                     )
@@ -98,13 +103,31 @@ def __init__(self, state, socketio=None):
                     self.state.calibration_head_compensation_yaw_gain = (
                         existing_calibration.get("head_compensation_yaw_gain", None)
                     )
-                    self.state.calibration_head_compensation_pitch_gain = (
-                        existing_calibration.get("head_compensation_pitch_gain", None)
-                    )
+                    pitch_gain = existing_calibration.get("head_compensation_pitch_gain", None)
+                    if invert_y and (not calibration_invert_y) and pitch_gain is not None:
+                        try:
+                            pitch_gain = -float(pitch_gain)
+                        except Exception:
+                            pass
+                    self.state.calibration_head_compensation_pitch_gain = pitch_gain
                     mapping = existing_calibration.get("screen_mapping") or {}
                     if isinstance(mapping, dict) and "x" in mapping and "y" in mapping:
                         self.state.calibration_screen_mapping_x = mapping.get("x")
-                        self.state.calibration_screen_mapping_y = mapping.get("y")
+                        mapping_y = mapping.get("y")
+                        if (
+                            invert_y
+                            and (not calibration_invert_y)
+                            and isinstance(mapping_y, list)
+                            and len(mapping_y) >= 3
+                        ):
+                            try:
+                                ay = float(mapping_y[0])
+                                by = float(mapping_y[1])
+                                cy = float(mapping_y[2])
+                                mapping_y = [ay, -by, cy]
+                            except Exception:
+                                pass
+                        self.state.calibration_screen_mapping_y = mapping_y
         except Exception:
             pass
 

mediapipe_processors/face_mesh_processor.py

@@ -472,6 +472,9 @@ def _extract_face_metrics(self, landmarks, state):
                 else 0.0
             )
 
+            if bool(self.config.get("eye_tracking", "invert_y", default=False)):
+                raw_gaze_y = -raw_gaze_y
+
             if hasattr(state, "calibration_applied") and state.calibration_applied:
                 try:
                     base_yaw = float(getattr(state, "calibration_head_yaw", 0.0) or 0.0)