melek-eyes 0.1.0

Melek (Jarvis) için ultra hafif ve GPU gerektirmeyen gelişmiş ekran tarama kütüphanesi

Melek Gözleri (Melek Eyes) 👁️👋

Melek Gözleri (Melek Eyes), bilgisayarınızın ekranını tarayarak metinleri, butonları, form alanlarını ve pencereleri algılayabilen ve bu elemanlar üzerinde tıklama, yazı yazma gibi fiziksel aksiyonlar alabilen hafif, GPU gerektirmeyen (CPU-dostu) ve çoklu monitör uyumlu bir ekran görme kütüphanesidir.

Bu kütüphane, kendi kişisel yapay zeka asistanınızın (örn. Jarvis/Melek) ekrandaki öğeleri "görmesini" ve insan gibi "tıklayıp yazmasını" sağlayan bir göz ve el motoru (eyes & hands engine) olarak tasarlanmıştır.

---

🚀 Öne Çıkan Özellikler

• 🖥️ Çoklu Monitör & DPI Desteği: Sistemdeki tüm fiziksel monitörleri tek tek veya sanal ekran olarak tarar. Monitörlerin DPI ölçeklendirmelerinden ve konumlandırmalarından (left, top) bağımsız olarak, elemanların koordinatlarını mutlak sanal ekran koordinatlarına dönüştürerek hatasız tıklamalar yapar.
• ⚡ Hafif ve GPU-Free OCR Motoru:
  • RapidOCR (Varsayılan): CPU üzerinde son derece hızlı çalışan ve Türkçe/İngilizce karakterleri hatasız tanıyan ONNX tabanlı PaddleOCR motoru.
  • Windows Native OCR: Windows'un dahili C++ OCR motorunu kullanarak sıfır ek kütüphane ve sıfır bellek tüketimiyle hızlı okuma.
  • EasyOCR: PyTorch tabanlı yedek motor.
• 🎨 Akıllı Arayüz Nesnesi Tespiti (Contour Detector): OpenCV kontur analizini kullanarak butonları, input alanlarını, pencereleri ve ikonları milisaniyeler içinde tespit eder.
• 🏷️ Etiket-Önce (Label-First) Stratejisi & Sentetik Girdiler: Borderless (çerçevesiz/modern) web formlarında kontur algılayıcıların göremediği input alanlarını, ilişkili metin etiketlerini ("Username", "Email" vb.) bulup hemen altına veya sağ tarafına otomatik olarak sentetik tıklama hedefi oluşturarak doldurur.
• 🛡️ Canlı Sentinel (Ekran Bekçisi): Frame-diffing (kare farkı) algoritması ile ekranı canlı izler. Sadece ekranda bir değişiklik (yeni pencere açılması, kaydırma yapılması vb.) olduğunda taramayı tetikler; video izlenirken veya ekran sabitken CPU yormaz.
• 🔄 Doğrulamalı Doldurma Döngüsü: Ajanın ekrana yazı yazarken başarısız olmasını (odağın kayması, UI gecikmesi vb.) önlemek için yazılan metni ekranda okuyarak doğrular, başarısızlık durumunda otomatik olarak tekrar dener.

---

📁 Proje Klasör Yapısı

melek_eyes/
│
├── melek_eyes/                   # Ana Kütüphane Paketi
│   ├── ocr/                      # OCR Motorları
│   │   ├── __init__.py           # OCR Fabrikası (RapidOCR, WindowsOCR, EasyOCR seçimi)
│   │   ├── base.py               # Soyut OCR taban sınıfı
│   │   ├── easy_ocr.py           # EasyOCR sarmalayıcısı
│   │   ├── paddle_ocr.py         # RapidOCR ONNX sarmalayıcısı
│   │   └── windows_ocr.py        # Windows Media OCR sarmalayıcısı
│   │
│   ├── __init__.py               # Ana MelekEyes sınıfı (Koordinasyon & Arama Motoru)
│   ├── capture.py                # Çoklu monitör ve pencere yakalama motoru (MSS)
│   ├── controller.py             # Klavye & Fare aksiyon motoru (PyAutoGUI)
│   ├── detector.py               # UI Elemanı tespit motoru (OpenCV Kontur Fallback)
│   ├── layout.py                 # Ekran Haritası ve Eleman Eşleme modeli (ScreenMap)
│   └── sentinel.py               # Değişiklik algılayıcı Ekran Bekçisi
│
├── examples/                     # Örnek ve Demo Kodları
│   ├── basic_capture.py          # Ekran yakalama ve çözünürlük testi
│   ├── browser_login_demo.py     # Tarayıcıda doğrulamalı giriş yapma demosu (Önerilen)
│   ├── detect_ui_elements.py     # Kontur tespiti görselleştirme demosu
│   ├── get_screen_map.py         # Ekrandaki metinleri JSON ve Metin haritasına dökme
│   ├── live_sentinel_demo.py     # Canlı ekran izleme ve değişim tetikleyici test
│   ├── test_agent_actions.py     # Tıklama, taşıma ve klavye kısayol testi
│   └── test_paddleocr.py         # PaddleOCR okuma testi
│
├── requirements.txt              # Bağımlılıklar listesi
└── setup.py                      # pip kurulum yapılandırması

---

⚙️ Kurulum

Kütüphaneyi yerel olarak kurmak veya diğer Python projelerinizde doğrudan kullanmak için aşağıdaki adımları takip edebilirsiniz.

1. Bağımlılıkları ve Kütüphaneyi Kurun

Proje ana dizininde (setup.py dosyasının bulunduğu klasör) bir terminal açın ve şu komutla kütüphaneyi kurulabilir (editable) modda yükleyin:

pip install -e .

Bu komut; mss, opencv-python, pyautogui, onnxruntime, numpy ve rapidocr-onnxruntime paketlerini otomatik olarak kuracaktır.

2. GitHub Üzerinden Kurulum (Diğer Projeler İçin)

Kütüphaneyi herhangi bir projede doğrudan GitHub'dan indirmek için:

pip install git+https://github.com/TearsFearsxf/melek_eyes.git

---

⚡ Hızlı Başlangıç

1. Tek Seferlik Ekran Taraması (Screen Mapping)

Aşağıdaki kod ekranı tarar ve ekranda bulunan tüm metin ve etkileşimli elemanları hiyerarşik bir metin olarak konsola döker:

from melek_eyes import MelekEyes

# Gözleri uyandır (Varsayılan olarak RapidOCR kullanılır)
with MelekEyes() as eyes:
    # 0. monitörü (varsayılan) tarar
    screen_map = eyes.scan_once()
    
    # Ekranın insan ve LLM tarafından okunabilir haritasını yazdır
    print(screen_map.to_text())

2. Akıllı Aksiyon Alma (Tıklama ve Yazma)

Melek, elemanların koordinatlarını kendi hesaplar. Sizin tek yapmanız gereken ekranda ne gördüğünüzü söylemektir:

from melek_eyes import MelekEyes
import time

with MelekEyes() as eyes:
    # 1. Giriş kutusuna veri yaz (Label-First yöntemiyle 'Username' etiketinin altındaki alana yazar)
    eyes.type_in("Username", "tomsmith")
    
    # 2. Şifre alanına yaz
    eyes.type_in("Password", "SuperSecretPassword!")
    
    # 3. 'Login' yazan butona tıkla
    eyes.click_on("Login")

3. Canlı Sentinel İzleme (Screen Sentinel)

Ekranda bir değişiklik olduğunda (yeni bir buton belirdiğinde veya pencere taşındığında) asistanınızı uyarmak için Sentinel modunu kullanabilirsiniz:

from melek_eyes import MelekEyes
import time

def ekran_degisti_callback(yeni_harita):
    print("🔔 Ekran değişti! Güncel butonlar:")
    for el in yeni_harita.buttons:
        print(f" - {el.text} (Konum: {el.center})")

with MelekEyes() as eyes:
    # Callback fonksiyonunu kaydet
    eyes.sentinel.register_callback(ekran_degisti_callback)
    
    # Canlı izlemeyi başlat (arka planda çalışır)
    eyes.sentinel.start()
    print("👁️ Ekran Bekçisi aktif. Ekranda bir şeyleri hareket ettirin...")
    
    time.sleep(10) # 10 saniye boyunca gözlemle
    
    # İzlemeyi durdur
    eyes.sentinel.stop()

---

🧪 Detaylı Demolar ve Testler

examples/ klasörü altındaki demoları çalıştırarak kütüphaneyi canlı test edebilirsiniz:

1. Tarayıcı Giriş Demosu (Önerilen test):
   • Öncelikle tarayıcınızda şu test adresini açın: http://the-internet.herokuapp.com/login
   • Sayfa açıkken şu komutu çalıştırın:

     python examples/browser_login_demo.py
     

   • Ajanımız sayfayı görecek, girdileri dolduracak ve doğrulamayı yapıp giriş yapacaktır.
2. Arayüz Eleman Tespiti Testi:
   • Aşağıdaki komut ekran görüntüsünü alır ve tespit ettiği buton/input kutularını yeşil çerçeve içine alarak annotated_screen.png adıyla kaydeder:

     python examples/detect_ui_elements.py
     

3. Ekran Değişim Bekçisi Testi:
   • Aşağıdaki komut ekranı canlı izler ve pencere açtığınızda veya kapattığınızda konsola bildirim gönderir:

     python examples/live_sentinel_demo.py
     

---

🧠 Yapay Zeka (LLM / Brain) Entegrasyonu İçin İpuçları

Bu kütüphane bir yapay zeka beyninin (Gemini, GPT vb.) ekranı kontrol etmesini kolaylaştırmak üzere tasarlanmıştır.

Aşağıdaki şablonu kullanarak ekran haritasını JSON formatında LLM'e gönderebilir ve LLM'den gelen komutları (click_on, type_in) yürütebilirsiniz:

import json
from melek_eyes import MelekEyes

with MelekEyes() as eyes:
    # 1. Ekran haritasını çıkar
    screen_map = eyes.scan_once()
    
    # 2. LLM'e göndermek için temiz bir JSON çıktısı oluşturun
    ekran_verisi = {
        "elements": [
            {
                "category": el.category, 
                "text": el.text, 
                "associated_label": el.associated_label,
                "center": el.center
            } 
            for el in screen_map.elements
        ],
        "standalone_texts": screen_map.standalone_texts
    }
    
    json_payload = json.dumps(ekran_verisi, ensure_ascii=False, indent=2)
    # Bu json_payload'u doğrudan LLM sistem promptuna veya chat geçmişine ekleyebilirsiniz.

---

🛡️ Lisans

Bu proje MIT lisansı ile lisanslanmıştır. Dilediğiniz gibi kullanabilir, değiştirebilir ve dağıtabilirsiniz.