cvflair 0.14.0

Gizlenen alan artık oval olabiliyor.

pip install -U cvflair

Theme(hide="pixelate", hide_shape="ellipse")

Dikdörtgen gizleme, yuvarlak çerçeve biçimlerinde köşelerden taşıyor ve
özellikle yüzlerin üstünde uyumsuz duruyordu. "ellipse" kutuya içten teğet
ovali gizler, köşeler el değmemiş kalır.

Tema geneli yerine belirli tespitleri gizlemek için BlurAnnotator doğrudan
çağrılabilir; Theme(hide=...) bütün kutulara uygulanır:

from cvflair.annotators import BlurAnnotator

BlurAnnotator(mode="pixelate", shape="ellipse").annotate(frame, gizlenecekler)

Aynı boyuttaki maskeler saklanıyor: her karede ve her gizlenen yüz için yeniden
elips çizmek, gizlenen yüz sayısıyla çarpılan gereksiz bir maliyetti.

Bu özellik, kütüphaneyi gerçek bir yüz tanıma uygulamasında kullanırken çıktı.

Tüm değişiklikler:
CHANGELOG

cvflair 0.13.0

Yüz tespiti yolu açıldı. Çizim tarafı zaten çalışıyordu; sürtünme, yüz
modellerinin kutuyu farklı bir biçimde vermesindeydi.

pip install -U cvflair

Kutu biçimi

cvflair xyxy okur; yüz ve cascade modellerinin çoğu bir köşe ve bir boyut
verir. from_xywh dönüşümü üstlenir:

faces = cascade.detectMultiScale(gray)          # OpenCV: (x, y, w, h)
detections = Detections.from_xywh(faces)

Model 0-1 aralığında veriyorsa kare boyutu da geçilir:
Detections.from_xywh(kutular, *frame.shape[1::-1]).

MediaPipe'ın yüz ve nesne tespiti için ayrı bir okuyucu var; iki API sürümünü de
tanır (eski solutions oranlı kutu verir, yeni tasks piksel):

detections = Detections.from_mediapipe(sonuc, *frame.shape[1::-1])

Model	Çıktısı	Yol
YOLO / Ultralytics	xyxy	Detections.from_ultralytics(...)
InsightFace	face.bbox xyxy	Doğrudan Detections(...)
OpenCV cascade	(x, y, w, h)	Detections.from_xywh(...)
MediaPipe	oranlı ya da piksel kutu	Detections.from_mediapipe(...)

Hiçbiri kurulu olmak zorunda değil: alanlar adlarıyla okunur, cvflair bu
kütüphaneleri import etmez.

FACE_5

Yüz modellerinin ortak beş noktası — iki göz, burun, iki ağız köşesi.
InsightFace'in kps alanı, RetinaFace ve MediaPipe aynı sırayı kullanır.

from cvflair import FACE_5, KeyPoints

points = KeyPoints(xy=[face.kps for face in faces])
cam.show(frame, detections, keypoints=points, skeleton=FACE_5)

skeleton="face" de aynı topolojiyi verir. Gözler arasına çizgi çekilmez: yüzü
ortadan bölüp işareti okunmaz hale getiriyor. Kalabalıkta 20 piksele inen
yüzlerde de çizildiği sınandı.

Playground

İskelet önizlemesine yüz eklendi ve üç çizimin de altına silüet kondu; kutu
kipinde çizim bir figürün üstünde duruyor, iskelet kipinde çizgiler boşluktaydı.
Çizimlerin kendisi değişmedi.

Tüm değişiklikler:
CHANGELOG

cvflair 0.12.0

Playground'da ayarladığın görünüm artık komut satırına da taşınıyor.

pip install -U cvflair

Tema dosyası

Bir tema JSON olarak yazılıp okunabiliyor; --theme hazır bir ad ya da bir
.json yolu alıyor:

cvflair 0 --theme theme.json --model yolov8n.pt

from cvflair import Theme, get_theme

Theme(box_style="sketch", palette=["#39FF14"], glow=True).save("theme.json")
theme = get_theme("theme.json")

Dosyaya yalnızca varsayılandan farklı ayarlar yazılıyor, yani paylaşılan dosya
neyin seçildiğini anlatıyor. Aynı biçimi Theme.to_dict() ve
Theme.from_dict() sözlük olarak veriyor; get_theme sözlüğü de kabul ediyor.

Playground'da komut satırı

Playground'da üretilen Python kodunun
altında artık aynı görünümü veren cvflair komutu duruyor. Hazır bir temada
--theme neon yetiyor; özel görünüm bir bayrağa sığmadığı için theme.json
indir düğmesi dosyayı üretiyor ve komut onu kullanıyor.

Depo

Playground sayfası CI'da denetleniyor: betik node --check ile ayrıştırılıyor,
sayfadaki çerçeve biçimi / panel konumu / tema listeleri kütüphanedekilerle
karşılaştırılıyor, sayfanın ürettiği tema alanlarının Theme'de gerçekten
bulunduğu doğrulanıyor. Sayfanın derleme adımı yok: bozuk bir sözdizimi hiçbir
yerde hata vermeden yayınlanıyor ve sayfa sessizce boş açılıyordu.

Tüm değişiklikler:
CHANGELOG

cvflair 0.11.0

Bu sürüm çizime değil, kütüphaneye ulaşma yollarına bakıyor. Şimdiye kadar
cvflair'i kullanmanın tek yolu Python yazıp bir OpenCV penceresi açmaktı.

pip install -U cvflair

Komut satırı

Paketle birlikte cvflair komutu geliyor. Kamera, video, tek görsel ya da bir
klasör dolusu görsel — kod yazmadan:

cvflair 0 --theme neon --model yolov8n.pt
cvflair girdi.mp4 --model yolov8n.pt -o cikti.mp4 --theme cyberpunk
cvflair fotograflar/ --model yolov8n.pt -o isaretli/

python -m cvflair de aynı komut. Ayrıntı:
komut satırı belgesi.

Video yazma

VideoWriter kütüphaneden de kullanılabiliyor. Dosya ilk kareyle açılıyor, yani
boyutu önceden bilmek gerekmiyor:

from cvflair import Camera, VideoWriter

cam = Camera(source="girdi.mp4", drop_frames=False, theme="neon")
with VideoWriter("cikti.mp4", fps=cam.source_fps or 25) as writer:
    for frame, detections in cam.stream(model="yolov8n.pt"):
        writer.write(cam.annotate(frame, detections))

Sonraki kareler farklı boyutta gelirse hata veriyor: OpenCV bunları sessizce
düşürüyor ve dosya nedeni görünmeden eksik çıkıyor.

Not defteri

cv2.imshow Jupyter ve Colab'da çalışmıyor; matplotlib'e geçmek ise BGR/RGB
takasını kullanıcıya bırakıyordu.

import cvflair

theme.annotate(frame, detections)
cvflair.notebook.show(frame)

IPython bağımlılık değil, yalnızca çağrıldığında import ediliyor. Not defteri
dışında çizmiyor, nesneyi döndürüyor — aynı betik iki yerde de çalışıyor.

MediaPipe

points = KeyPoints.from_mediapipe(sonuc, *frame.shape[1::-1])
cam.show(frame, keypoints=points, skeleton=HAND_21)

Eski solutions ve yeni tasks API'leri ile düz nokta listesi kabul ediliyor;
ölçekleme burada yapılıyor. MediaPipe import edilmiyor, alanlar adlarıyla
okunuyor.

Düzeltildi

Video dosyasının son karesi kayboluyordu. Okuyucu thread tüketiciden bir
adım önde bittiği için, kaynak tükendiğinde kuyrukta bekleyen kare işlenmeden
döngü kapanıyordu: 40 karelik bir dosya 39 kare olarak yazılıyordu. Artık kaynak
bittiğinde kuyruk boşaltılıyor, kullanıcı çıktığında ise boşaltılmıyor.

Belgeler

README İngilizceye çevrildi; Türkçesi
README.tr.md olarak
duruyor. Ayrıntılı belgeler Türkçe kalıyor.

Tüm değişiklikler:
CHANGELOG

cvflair 0.10.0

Bu sürüm çizim tarafını genişletiyor: kutunun kendisinden başka, kutunun
üstüne binen ve kare kare biriken çizimler de var.

pip install -U cvflair

theme = Theme(box_style="sketch", pulse=True, trace=True, trace_length=32)

Bu sürümde

Çizim

• sketch çerçeve biçimi — elle çizilmiş gibi titrek, iki kere üstünden
  geçilmiş dikdörtgen. Titreşim kutunun konumundan türetilen tohumla üretilir:
  aynı nesne her karede aynı çizilir, desen ekranda kaynamaz. Böylece biçim
  sayısı dokuza çıktı.
• Nabız — Theme(pulse=True) kutunun çevresinde açılıp sönen bir halka
  çizer. Evre saatten okunur; kaydedilen videoda ya da testte tekrarlanabilir
  olması için annotate(..., moment=...) verilebilir.
• Takip izi — Theme(trace=True) takip edilen nesnelerin geçtiği yolu
  çizer, iz geriye doğru incelip solar. Yalnızca tracker_id taşıyan
  tespitlerde çalışır: cvflair takip etmez, takip edicinin verdiği kimlikleri
  çizer. Görünmeyen kimlikler unutulur; theme.reset_trace() hepsini siler.
• Segmentasyon maskesi — Detections.mask maskeleri taşır,
  Theme(masks=..., mask_opacity=..., mask_outline=...) çizer.
• Kutu içini gizleme — Theme(hide="blur") ya da "pixelate". Çerçeveden
  önce uygulanır, kutu çizgisi ve etiket üstünde net kalır.
• Bölge çizimi — theme.annotate_zone(scene, points, fill_opacity=...)
  poligon ya da açık çizgi çizer. Yalnızca çizim: bir tespitin bölgenin içinde
  olup olmadığına cvflair karar vermez.
• Etiket çakışması çözülüyor: üst üste binen kutularda plakalar boş bir yere
  kaydırılıyor ve uzaklaşan plakaya kutuya giden ince bir işaretçi çizgisi
  çekiliyor. Theme(avoid_label_overlap=False) ile kapatılabilir.
• Güven barı — Theme(confidence_bar=True) kutunun altına skorla orantılı
  ince bir çubuk çizer.

Hız

1280x720, 8 kutu; düz kutu 0,74 ms üzerine: pulse +0,24 ms, trace +1,1 ms,
sketch +3,7 ms. Maske 46 ms'den 10,4 ms'ye indi — iş tüm kare yerine nesnenin
penceresine indirildi ve dizin atama yerine OpenCV'nin maskeli kopyası
kullanıldı. Eskiz 9,4 ms'den 4,4 ms'ye indi: kutunun bütün kenarları tek dizide
üretilip tek OpenCV çağrısıyla çiziliyor.

Ölçüm tablosu yenilendi ve ölçüt en iyi kare süresine çevrildi; ortanca, arka
plan yüküyle koşudan koşuya %20 oynuyordu.

Playground

Eskiz, nabız ve iz playground'da da
denenebiliyor; üretilen Python kodu ve paylaşım bağlantısı yeni ayarları
taşıyor.

Tüm değişiklikler: CHANGELOG

cvflair 0.9.0

Kutuların yanına ikinci bir aile geldi: el ve poz iskeleti. Aynı temalar,
aynı palet, aynı parlama — yalnızca çizilen şey değişiyor.

pip install -U cvflair

from cvflair import HAND_21, Camera, KeyPoints

cam = Camera(source=0, theme="neon")
for frame in cam.stream():
    points = KeyPoints(xy=el_noktalarini_bul(frame))   # senin modelin
    cam.show(frame, keypoints=points, skeleton=HAND_21)

Kutu ve iskelet aynı karede birlikte de çizilebilir:
cam.show(frame, detections, keypoints=points, skeleton="pose")

Bu sürümde

• KeyPoints taşıyıcısı, EdgeAnnotator (kemikler) ve VertexAnnotator
  (eklemler). Kemikler paletin rengini, eklemler vurgu rengini alır; glow
  kemiklerin arkasına koyu bir geçiş çizer.
• Hazır topolojiler: HAND_21 (MediaPipe Hands sırası) ve POSE_17
  (COCO / YOLO-pose). Ad olarak da verilebilir (skeleton="hand"), farklı bir
  düzen için kendi kenar listen geçilebilir.
• Theme.annotate_keypoints(...) ve Camera.show(..., keypoints=...);
  yeni tema alanları pose_thickness, pose_radius, pose_confidence.
• KeyPoints.from_normalized(...) — MediaPipe gibi 0-1 aralığında veren
  kütüphaneler için ölçekleme.
• Kutulardaki dayanıklılık burada da geçerli: NaN, sonsuz ya da güven eşiğinin
  altındaki noktalar çizilmez, iskeletin geri kalanı çizilmeye devam eder.
• Playground önizlemesine iskelet kipi
  eklendi; kutu ve iskelet ayarları birbirine karışmıyor, üretilen kod da seçilen
  aileyi anlatıyor.

Kapsam notu: cvflair poz tahmini yapmaz ve MediaPipe'a bağımlı değildir.
Noktalar senin çalıştırdığın modelden gelir; burada olan şey taşıyıcı, topoloji
ve çizim. Sınır bilinçli: nokta ve kenar evet, segmentasyon maskesi ve takip
mantığı hayır.

Belgeler: nokta ve iskelet çizimi ·
örnek ·
CHANGELOG

Gereksinim: Python 3.10+ — bağımlılıklar yalnızca numpy ve opencv.

cvflair 0.8.1

Dayanıklılık düzeltmesi: modelden gelen bozuk bir kutu artık akışı düşürmüyor.

pip install -U cvflair

Bozuk kutular

Model çıktısı her zaman temiz gelmez — sıfıra bölen bir güven hesabı NaN üretir,
ıraksayan bir takipçi sonsuz koordinat verir. Bu değerlerde OpenCV hata fırlatıyordu
ve tek bir bozuk tespit bütün döngüyü durduruyordu; üstelik yığın izi modeli
değil cvflair'i işaret ediyordu.

Girdi	Önce	Şimdi
NaN koordinat	cv2.error, akış durur	tespit atlanır, diğerleri çizilir
Sonsuz koordinat	cv2.error, akış durur	atlanır
int32'yi aşan değer	cv2.error, akış durur	güvenli aralığa kırpılır, çizilir

Kırpma kadraja değil OpenCV'nin sınırına yapılıyor: kadrajı taşan bir kutu kısmen
görünmeye devam etmeli. Çizilemeyen kutu sessizce atlanıyor — bir çizim katmanının
işi akışı ayakta tutmak.

72 yeni test bunu sekiz çerçeve biçiminin hepsinde ve etiket plakasında doğruluyor.

Belgeler

README vitrine indirildi (304 → 119 satır); ayrıntı docs/ altında üç dosyaya
bölündü — temalar,
modeller,
api. Site üreteci
eklenmedi. README'deki bağlantılar mutlak GitHub adresine çevrildi; göreli yollar
aynı dosya PyPI sayfası olarak kullanıldığında kırılıyordu.

Ayrıntılı liste: CHANGELOG.md

Gereksinim: Python 3.10+ — bağımlılıklar yalnızca numpy ve opencv.

cvflair 0.8.0

show() artık basılan tuşu yutmuyor: demolar klavyeye cevap verebiliyor.
Bu sürüm ayrıca PyPI'a otomatik yayınlandı — etiket push edildi, paket
GitHub Actions'ta derlendi ve token yerine kısa ömürlü OIDC kimliğiyle yüklendi.

pip install -U cvflair

Klavye

cam.show(frame, detections)
if cam.pressed("1"):
    cam.theme = "neon"

• cam.key — son karede basılan tuş kodu, basılmadıysa -1
• cam.pressed("1") / cam.pressed(27) — hem karakter hem kod kabul eder
• Çıkış tuşları (q, Q, ESC) ve pencere kapatma aynen çalışıyor

Yeni örnek theme_switcher.py:
rakam tuşlarıyla beş tema arasında geçiş, b ile sayaç panelini açıp kapama —
playground'da fareyle yapılanın kamera karşısındaki hâli.

Düzeltildi

• Camera.close() pencere kapatılamadığında hata fırlatıyordu (başsız ortamda
  veya pencere zaten kapanmışsa). Kapanış artık sessizce geçiyor.

Depo

• Yayın otomatikleşti: v* etiketi push edilince paket derlenip PyPI'a yükleniyor.
  Depoda ve diskte saklanan bir token yok; PyPI, GitHub'ın imzaladığı kimliği
  doğruluyor ve paketler için köken belgesi (attestation) üretiliyor.

Ayrıntılı liste: CHANGELOG.md

Gereksinim: Python 3.10+ — bağımlılıklar yalnızca numpy ve opencv.

cvflair 0.7.0

Bu sürümün konusu ölçüm: çizim maliyeti ilk kez ölçüldü, çıkan sonuca göre
neon teması hızlandırıldı ve playground'daki bir belirsizlik giderildi.

pip install -U cvflair

neon %42 hızlandı

7,1 ms/kare yerine 4,1 ms (1280x720, 8 kutu). Sebep basit: kenar yumuşatmalı
yay, düz çizgiye göre dört kat pahalı ve her yuvarlak kutuda dört tane var.
neon bunun üstüne bir de hâle geçişi ekliyordu. Hâle sönük ve ana çizginin
altında kaldığı için orada yumuşatma kapatıldı — belirgin farklı piksel oranı
%0,4, yani gözle görünmüyor.

Tema	ms/kare	30 fps bütçesinin
minimal	0,35	%1
hud	0,51	%2
cyberpunk	0,64	%2
pastel	2,8	%8
neon	4,1	%12

Karşılaştırma tabanı, elle yazılmış bir OpenCV kutu+etiket döngüsü: 0,34 ms.
minimal onunla aynı hızda — katmanın kendi ek yükü ölçülebilir düzeyde değil.
Tabloyu tools/benchmark.py üretiyor.

Playground: hangi renk neye ait

Palet artık kendini açıklıyor — her renk kutusunun altında önizlemedeki nesnenin
adı yazıyor, kullanılmayan renkler soluk gösteriliyor ve dağıtım kuralı bir
satırla anlatılıyor. Kamera önizlemesi ise kaldırıldı: tarayıcıda tespit
çalışmadığı için kutular sahte kalıyor, ayarları görmeye katkısı yoktu.

→ https://kbycode.github.io/cvflair/

Depo

• Tip denetimi CI'ya eklendi (mypy). Paket py.typed gönderiyordu ama iddia
  denetlenmiyordu; ilk koşuda üç gerçek sorun çıktı ve düzeltildi.
• Issue ve PR şablonları, CONTRIBUTING.md.

Ayrıntılı liste: CHANGELOG.md

Gereksinim: Python 3.10+ — bağımlılıklar yalnızca numpy ve opencv.

cvflair 0.6.0

Bu sürüm kütüphaneyi denemeyi kolaylaştırmaya odaklandı: çalışan örnekler,
video dosyalarında kare kaybını bitiren bir kip ve iki dilli playground.

pip install -U cvflair

Örnek galerisi

Sekiz örnek, hangisinin kamera veya ek kurulum istediğiyle birlikte:
examples/README.md

Öne çıkanı motion_detection.py:
sinir ağı olmadan gerçek tespit. Arka plan çıkarımı ve konturlarla hareket eden
bölgeleri bulur — indirilecek ağırlık, torch, ek paket yok. cvflair'in model
bağımsızlığının çalışan hâli; diğer örnekler de bunu detektör olarak kullanıyor.

from cvflair import Camera
from motion_detection import MotionDetector

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

Yeni örnekler: motion_detection.py, hud_stats.py (sayaç panelini kendi verinle
beslemek), video_file.py (dosyayı işleyip işaretlenmiş kopyasını yazmak),
image_folder.py (toplu görsel işaretleme).

Camera(drop_frames=False)

Canlı kamerada bekleyen kareyi düşürmek doğru: gecikme birikmez, ekranda hep en
güncel kare olur. Video dosyasında ise bunun karşılığı kare kaybı. Yeni kipte
okuyucu tüketiciyi bekler, dolayısıyla dosya işlerken hiçbir kare atlanmaz.

cam = Camera(source="girdi.mp4", theme="neon", drop_frames=False)

Playground artık iki dilli

Varsayılan İngilizce, sağ üstteki TR düğmesiyle Türkçe. Seçim tarayıcıda
saklanıyor, ?lang=tr ile de verilebiliyor; sayfa başlığı her zaman İngilizce.
→ https://kbycode.github.io/cvflair/

Ayrıntılı liste: CHANGELOG.md

Gereksinim: Python 3.10+ — bağımlılıklar yalnızca numpy ve opencv.