cvflair

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

Çizim işini supervision yapar; cvflair kamera döngüsünü ve tema ayarlarını üstlenir. Model bağımsızdır: supervision'ın Detections nesnesini üreten her kaynak (YOLO, MediaPipe, InsightFace veya özel bir model) tema tarafından çizilebilir.

Aynı tespitler, üç tema. Animasyon tools/make_demo_gif.py ile üretildi — sentetik sahne, kamera gerekmiyor.

Durum: Faz 1 tamam (kamera döngüsü, üç tema, testler), Faz 2 başladı (model bağlama). Paket henüz PyPI'da yayınlanmadı.

Kurulum

Python 3.10 veya üzeri gerekir (bu alt sınır supervision'dan geliyor).

git clone https://github.com/kbycode/cvflair.git
cd cvflair
pip install -e .

Yayınlandıktan sonra: pip install cvflair

YOLO ile kullanmak için Ultralytics extra'sı: pip install -e ".[yolo]" (ayrıntı ve lisans notu için aşağıdaki Lisans bölümü).

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:

import supervision as sv
from cvflair import Camera

def detect(frame) -> sv.Detections:
    ...  # kendi modelin
    return sv.Detections(xyxy=..., class_id=..., confidence=...)

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

Çı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

Yol haritasındaki cyberpunk ve hud temaları Faz 2'de gelecek.

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

import supervision as sv
from cvflair import Camera, Theme

my_theme = Theme(
    name="my-theme",
    palette=sv.ColorPalette.from_hex(["#39FF14", "#FF00E5"]),
    box_style="corner",     # "box" | "round" | "corner"
    thickness=2,
    glow=True,
    text_scale=0.6,
)
cam = Camera(source=0, theme=my_theme)

Temaları görmenin iki yolu:

python examples/demo_fake_detections.py   # canlı kamera + hareketli sahte tespitler
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 supervision annotator'ları 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.
• Çizim matematiği yeniden yazılmadı. Her piksel supervision tarafından çiziliyor; cvflair sadece yapılandırma ve akış katmanı.
• 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

Yol haritası

Lisans

MIT — bkz. LICENSE. Bağımlılıkların hepsi izin verici lisanslı (supervision MIT, 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.