cvflair

Bilgisayarlı görü tespitlerini üç satırda, hazır temalarla ekrana çizen ince bir katman.

Kamera döngüsü, temalar ve çizim tek pakette; numpy ve opencv dışında bağımlılığı yok. Model bağımsızdır: kutu üreten her kaynak (YOLO, MediaPipe, InsightFace veya özel bir model) aynı temayla çizilir.

Aynı tespitler, dört tema. tools/make_demo_gif.py ile üretildi: docs/city.png üzerine çizilen kutular. Başka bir görsel için --background <yol>.

Sekiz çerçeve biçimi, dört hazır tema — hepsi tek Theme(...) satırıyla. Hiçbirini kurmadan denemek için: tema playground → Ayarları oynat, hazır Python kodunu kopyala; sayfa tamamen tarayıcıda çalışır.

Kurulum

Python 3.10 veya üzeri gerekir.

pip install cvflair

YOLO ile kullanmak için Ultralytics extra'sı — ayrıntı ve lisans notu için aşağıdaki Lisans bölümü:

pip install "cvflair[yolo]"

Depodan geliştirme kurulumu:

git clone https://github.com/kbycode/cvflair.git
cd cvflair
pip install -e ".[dev]"

Hızlı başlangıç

from cvflair import Camera

cam = Camera(source=0, theme="neon")
for frame in cam.stream():
    cam.show(frame)

Kamera açılır, kareler ayrı bir thread'de okunur, pencere q veya ESC ile kapanır — release() çağırmaya, while True kurmaya gerek yok.

Model verilmeyen bu akışta ekranda ham kare görünür: tema ancak ortada tespit varken çizim yapar. Temayı modelsiz, canlı görmek için: python examples/demo_fake_detections.py — kamera görüntüsü üzerine hareketli sahte kutular çizer ve temaları 3 saniyede bir değiştirir.

Modelle kullanım

stream()'e bir model verildiğinde her adım (kare, tespitler) çifti döndürür ve tema otomatik uygulanır:

from cvflair import Camera

cam = Camera(source=0, theme="neon")
for frame, detections in cam.stream(model="yolov8n.pt"):
    cam.show(frame, detections)

model üç şeyden biri olabilir:

Son seçenek kütüphaneyi model-agnostik yapan yer:

from cvflair import Camera, Detections

def detect(frame) -> Detections:
    ...  # özel model çağrısı
    return Detections(xyxy=[[10, 20, 120, 260]], class_id=[0], names=["kisi"])

cam = Camera(source=0, theme="pastel")
for frame, detections in cam.stream(model=detect):
    cam.show(frame, detections)

Çizim alan adlarına göre okuduğu için başka kütüphanelerin tespit nesneleri de (örneğin supervision.Detections) dönüştürülmeden verilebilir.

Çıkarım bu döngüde çalışır, okuma thread'inde değil: bir kare işlenirken okuyucu kuyruktaki kareyi tazelemeye devam eder, dolayısıyla bir sonraki tur birikmiş kareyle değil en güncel kareyle başlar.

Ultralytics'e ek ayar geçirmek için UltralyticsDetector doğrudan kullanılabilir:

from cvflair import Camera, UltralyticsDetector
from ultralytics import YOLO

detector = UltralyticsDetector(YOLO("yolov8n.pt"), conf=0.4, device="cpu", classes=[0])
cam = Camera(source=0, theme="neon")
for frame, detections in cam.stream(model=detector):
    cam.show(frame, detections)

Etiket metni doğrudan da verilebilir: cam.show(frame, detections, labels=[...]). Pencere yönetimi uygulamaya aitse cam.annotate(frame, detections) yalnızca çizim yapar.

Temalar

Tema	Görünüm
minimal	ince beyaz çerçeve, sade etiket — ekran kaydı ve profesyonel demo için
neon	sınıf başına canlı renk, yuvarlak köşe, koyu hâle ile parlama hissi
pastel	yumuşak tonlar, geniş yuvarlama, koyu etiket yazısı — atölye/projeksiyon
cyberpunk	ince çerçeve + kalın beyaz köşeler, yüksek kontrast — hedef kilitleme görünümü
hud	ince köşe çentikleri + köşede sayaç paneli — oyun ve robotik demoları

Çerçeve biçimleri

Görselleri yukarıda. box_style sekiz değerden birini alır:

Hepsi cvflair.annotators içinde, OpenCV çizim çağrılarıyla tanımlıdır; renk paleti ve ColorLookup davranışı sekizinde de aynıdır.

dashed_corner, bracket, crosshair ve target ikinci bir renk kabul eder; köşe ayraçları, dirsekler ve merkez artısı o renge geçer — hibrit biçimlerin iki katmanı böyle ayrışır:

theme = Theme(
    palette=["#00F0FF"],
    accent_palette="#FF206E",
    box_style="target",
    thickness=3,
)

Sayaç paneli

hud teması köşeye küçük bir panel çizer. Sayılar kutulardan değil döngüden gelir, bu yüzden ayrı bir yoldan veriliyor — Camera kare hızını ve tespit sayısını kendisi dolduruyor:

cam = Camera(source=0, theme="hud")
for frame, detections in cam.stream(model="yolov8n.pt"):
    cam.show(frame, detections)          # FPS ve Objects panelde

Kendi satırlarını eklemek için stats; aynı anahtar verilirse seninki kazanır:

cam.show(frame, detections, stats={"Skor": score, "Tur": lap})

Panel her temaya açılabilir: Theme(hud=True, hud_position="bottom_right", hud_opacity=0.5). Konumlar cvflair.HUD_POSITIONS içinde. Ölçülen kare hızına cam.measured_fps ile doğrudan da erişilebilir — cihazdan istenen fps değil, döngünün gerçekte ulaştığı hız.

Özel bir tema, Theme doğrudan kurulup Camera'ya verilerek tanımlanır:

from cvflair import Camera, Theme

my_theme = Theme(
    name="my-theme",
    palette=["#39FF14", "#FF00E5"],
    box_style="corner",     # bkz. Çerçeve biçimleri
    thickness=2,
    glow=True,
    text_scale=0.6,
)
cam = Camera(source=0, theme=my_theme)

Ayarları tarayıcıda deneyip hazır Theme(...) kodunu kopyalamak için: tema playground — kurulum gerektirmez, tamamen istemci tarafında çalışır, ayarlar bağlantıda taşınır.

Playground İngilizce açılır, sağ üstteki TR düğmesiyle Türkçeye geçer.

Temaları yerelde görmek ve kendi modelini bağlamak için sekiz örnek var — örnek galerisi:

python examples/motion_detection.py       # gerçek tespit, sinir ağı yok
python examples/hud_stats.py              # sayaç panelini kendi verinle besle
python examples/theme_preview.py          # kamerasız, her temayı bir PNG'ye çizer

API özeti

Camera bağlam yöneticisi olarak da kullanılabilir: with Camera() as cam: ...

Nasıl çalışıyor

• Kareler ayrı thread'de okunur. Okuyucu, tüketiciyi beklemez.
• Kuyruk tek slotlu. Yeni kare gelince bekleyen eski kare düşürülür (frames_dropped ile sayılır). Böylece işleme yavaşladığında gecikme birikmez; ekranda hep en güncel kare olur.
• Annotator'lar bir kere kurulur. Theme nesnesi oluşturulurken çizim nesneleri hazırlanır ve her karede yeniden kullanılır — döngü içinde annotator kurmak bu tür işlerde en sık görülen gereksiz maliyettir.
• Bağımlılık yüzeyi kasten dar. Yalnızca numpy ve opencv. import cvflair ~0.3 saniye sürüyor; kurulum ~170 MB (neredeyse tamamı opencv + numpy).
• Model paketin dışında. stream(model=...) verilen şeyi bir çağrılabilire çevirir; ağırlıklar ilk yinelemede yüklenir. Hiçbir model kodu veya ağırlığı pakete gömülü değil.

Geliştirme

python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
pytest
ruff check .

Testler kamera gerektirmez: Camera'ya capture_factory üzerinden sahte bir VideoCapture verilir, temalar da sentetik kareler üzerinde doğrulanır.

Dokümantasyon görselleri de kamerasız üretilir:

python tools/make_demo_gif.py    # docs/demo.gif
python examples/theme_preview.py # examples/output/theme-*.png

Lisans

MIT — bkz. LICENSE. Bağımlılıkların ikisi de izin verici lisanslı (opencv-python Apache 2.0, numpy BSD).

YOLO ağırlıkları veya Ultralytics kodu bu pakete gömülü değildir; Ultralytics'in kullanılması hâlinde AGPL-3.0 koşulları onu kullanan projenin sorumluluğundadır.