cvflair 0.2.0__py3-none-any.whl

cvflair/__init__.py

@@ -0,0 +1,33 @@
+"""
+cvflair -- theme-based visualisation for computer vision detections.
+
+The package draws nothing itself: it configures ``supervision`` annotators and
+wraps the camera loop, so the everyday case fits in three lines::
+
+    from cvflair import Camera
+
+    cam = Camera(source=0, theme="neon")
+    for frame in cam.stream():
+        cam.show(frame)
+"""
+
+from __future__ import annotations
+
+from .camera import Camera, CameraError
+from .models import Detector, UltralyticsDetector, load_ultralytics, resolve_detector
+from .themes import Theme, available_themes, get_theme
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Camera",
+    "CameraError",
+    "Detector",
+    "Theme",
+    "UltralyticsDetector",
+    "available_themes",
+    "get_theme",
+    "load_ultralytics",
+    "resolve_detector",
+    "__version__",
+]

cvflair/camera.py

@@ -0,0 +1,266 @@
+"""
+Webcam capture on a background thread, with a one-slot latest-frame queue.
+
+The reader thread never blocks on the consumer: before publishing a new frame
+it drops the pending one, so ``read()`` always returns the most recent frame
+and latency does not build up when annotation is slower than the camera.
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+from collections.abc import Callable, Iterator, Sequence
+from typing import Any, overload
+
+import cv2
+import numpy as np
+import supervision as sv
+
+from .models import ModelLike, resolve_detector
+from .themes import Theme, get_theme
+
+__all__ = ["Camera", "CameraError"]
+
+QUIT_KEYS = (ord("q"), ord("Q"), 27)  # 27 == ESC
+
+
+class CameraError(RuntimeError):
+    """The capture device could not be opened, or died while streaming."""
+
+
+class Camera:
+    """
+    A threaded video source with a theme attached.
+
+    ::
+
+        cam = Camera(source=0, theme="neon")
+        for frame in cam.stream():
+            cam.show(frame, detections)
+
+    ``stream()`` starts the reader thread on first use and releases the device
+    when the generator ends, so the loop above needs no explicit teardown.
+    Pressing ``q`` or ``ESC`` in the preview window ends the stream.
+
+    Any object with OpenCV's ``VideoCapture`` interface can be injected through
+    ``capture_factory``; that is how the test suite runs without a camera.
+    """
+
+    def __init__(
+        self,
+        source: int | str = 0,
+        theme: str | Theme = "minimal",
+        *,
+        width: int | None = None,
+        height: int | None = None,
+        fps: int | None = None,
+        window_name: str = "cvflair",
+        capture_factory: Callable[[Any], Any] = cv2.VideoCapture,
+    ) -> None:
+        self.source = source
+        self.window_name = window_name
+        self.width = width
+        self.height = height
+        self.fps = fps
+
+        self._theme = get_theme(theme)
+        self._capture_factory = capture_factory
+        self._capture: Any | None = None
+        self._thread: threading.Thread | None = None
+        self._queue: queue.Queue[np.ndarray] = queue.Queue(maxsize=1)
+        self._stop_event = threading.Event()
+        self._window_open = False
+        self._frames_read = 0
+        self._frames_dropped = 0
+
+    # -- configuration ---------------------------------------------------
+
+    @property
+    def theme(self) -> Theme:
+        return self._theme
+
+    @theme.setter
+    def theme(self, theme: str | Theme) -> None:
+        self._theme = get_theme(theme)
+
+    @property
+    def is_running(self) -> bool:
+        return self._thread is not None and self._thread.is_alive()
+
+    @property
+    def frames_read(self) -> int:
+        """Frames pulled off the device since :meth:`start`."""
+        return self._frames_read
+
+    @property
+    def frames_dropped(self) -> int:
+        """Frames discarded because the consumer was still busy."""
+        return self._frames_dropped
+
+    # -- lifecycle -------------------------------------------------------
+
+    def start(self) -> Camera:
+        """Open the device and start the reader thread. Safe to call twice."""
+        if self.is_running:
+            return self
+
+        capture = self._capture_factory(self.source)
+        if not capture.isOpened():
+            capture.release()
+            raise CameraError(
+                f"Could not open video source {self.source!r}. "
+                "Check that the device index is right and no other application is using it."
+            )
+        self._apply_properties(capture)
+
+        self._capture = capture
+        self._stop_event.clear()
+        self._thread = threading.Thread(
+            target=self._read_loop, name=f"cvflair-reader-{self.source}", daemon=True
+        )
+        self._thread.start()
+        return self
+
+    def _apply_properties(self, capture: Any) -> None:
+        if self.width is not None:
+            capture.set(cv2.CAP_PROP_FRAME_WIDTH, self.width)
+        if self.height is not None:
+            capture.set(cv2.CAP_PROP_FRAME_HEIGHT, self.height)
+        if self.fps is not None:
+            capture.set(cv2.CAP_PROP_FPS, self.fps)
+
+    def _read_loop(self) -> None:
+        capture = self._capture
+        while not self._stop_event.is_set():
+            ok, frame = capture.read()
+            if not ok or frame is None:
+                break  # end of file, or the device went away
+            self._frames_read += 1
+            self._publish(frame)
+        self._stop_event.set()
+
+    def _publish(self, frame: np.ndarray) -> None:
+        """Put ``frame`` in the one-slot queue, discarding whatever was there."""
+        try:
+            self._queue.get_nowait()
+            self._frames_dropped += 1
+        except queue.Empty:
+            pass
+        try:
+            self._queue.put_nowait(frame)
+        except queue.Full:  # pragma: no cover - single producer, cannot happen
+            self._frames_dropped += 1
+
+    def close(self) -> None:
+        """Stop the thread, release the device, close the preview window."""
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+            self._thread = None
+        if self._capture is not None:
+            self._capture.release()
+            self._capture = None
+        if self._window_open:
+            cv2.destroyWindow(self.window_name)
+            self._window_open = False
+
+    def __enter__(self) -> Camera:
+        return self.start()
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        state = "running" if self.is_running else "stopped"
+        return f"Camera(source={self.source!r}, theme={self._theme.name!r}, {state})"
+
+    # -- reading ---------------------------------------------------------
+
+    def read(self, timeout: float = 5.0) -> np.ndarray | None:
+        """
+        Return the latest frame, or ``None`` if the source ended or stalled.
+
+        A frame is never returned twice: the queue slot is consumed here.
+        """
+        try:
+            return self._queue.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    @overload
+    def stream(self, timeout: float = ..., *, model: None = ...) -> Iterator[np.ndarray]: ...
+
+    @overload
+    def stream(
+        self, timeout: float = ..., *, model: ModelLike
+    ) -> Iterator[tuple[np.ndarray, sv.Detections]]: ...
+
+    def stream(self, timeout: float = 5.0, *, model: ModelLike | None = None):
+        """
+        Yield frames until the source ends, ``q``/``ESC`` is pressed, or no
+        frame arrives within ``timeout`` seconds. Releases the device on exit.
+
+        Without ``model`` the frames come through bare. With one -- a weights
+        path, an Ultralytics model, or any callable returning ``sv.Detections``
+        -- each item is a ``(frame, detections)`` pair::
+
+            for frame, detections in cam.stream(model="yolov8n.pt"):
+                cam.show(frame, detections)
+
+        Inference runs in this loop, not in the reader thread: while a frame is
+        being processed the reader keeps replacing the queued frame, so the next
+        iteration gets the newest one rather than a backlog.
+        """
+        detector = resolve_detector(model)
+        self.start()
+        try:
+            while not self._stop_event.is_set():
+                frame = self.read(timeout=timeout)
+                if frame is None:
+                    break
+                yield frame if detector is None else (frame, detector(frame))
+        finally:
+            self.close()
+
+    # -- output ----------------------------------------------------------
+
+    def annotate(
+        self,
+        frame: np.ndarray,
+        detections: sv.Detections | None = None,
+        labels: Sequence[str] | None = None,
+    ) -> np.ndarray:
+        """Apply the active theme in place. Useful when not using :meth:`show`."""
+        if detections is None:
+            return frame
+        return self._theme.annotate(frame, detections, labels=labels)
+
+    def show(
+        self,
+        frame: np.ndarray,
+        detections: sv.Detections | None = None,
+        labels: Sequence[str] | None = None,
+        *,
+        wait: int = 1,
+    ) -> bool:
+        """
+        Annotate and display ``frame``.
+
+        Returns ``False`` once the user asks to quit (``q``, ``ESC``, or the
+        window's close button), which also ends an active :meth:`stream`.
+        """
+        self.annotate(frame, detections, labels=labels)
+        cv2.imshow(self.window_name, frame)
+        self._window_open = True
+
+        if (cv2.waitKey(wait) & 0xFF) in QUIT_KEYS or self._window_closed():
+            self._stop_event.set()
+            return False
+        return True
+
+    def _window_closed(self) -> bool:
+        try:
+            return cv2.getWindowProperty(self.window_name, cv2.WND_PROP_VISIBLE) < 1
+        except cv2.error:  # pragma: no cover - headless build without HighGUI
+            return False

cvflair/models.py

@@ -0,0 +1,140 @@
+"""
+Optional model binding.
+
+cvflair ships no model and depends on none. This module only turns whatever was
+passed as ``model`` into a callable that maps a frame to ``sv.Detections``:
+
+* a weights path (``"yolov8n.pt"``) -- loaded through Ultralytics, which is an
+  extra (``pip install "cvflair[yolo]"``), never a hard dependency;
+* an already constructed Ultralytics model -- its results are converted;
+* any callable returning ``sv.Detections`` -- used as it is.
+
+Keeping Ultralytics out of the dependency list is deliberate: it is AGPL-3.0,
+and pulling it in would push that licence onto every cvflair user.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+import numpy as np
+import supervision as sv
+
+__all__ = [
+    "Detector",
+    "ModelLike",
+    "UltralyticsDetector",
+    "load_ultralytics",
+    "resolve_detector",
+]
+
+#: Weight file suffixes Ultralytics can load.
+WEIGHT_SUFFIXES = frozenset({".pt", ".onnx", ".engine", ".torchscript", ".mlpackage"})
+
+
+@runtime_checkable
+class Detector(Protocol):
+    """Anything that turns one frame into detections."""
+
+    def __call__(self, frame: np.ndarray) -> sv.Detections: ...
+
+
+ModelLike = str | Path | Detector | Any
+
+
+class UltralyticsDetector:
+    """
+    Runs an Ultralytics model and converts its output to ``sv.Detections``.
+
+    ``predict_kwargs`` is forwarded to every call (``conf``, ``iou``, ``device``,
+    ``classes`` ...). ``verbose`` defaults to ``False`` so the capture loop is
+    not drowned in per-frame logging.
+    """
+
+    def __init__(
+        self,
+        model: Any,
+        *,
+        convert: Callable[[Any], sv.Detections] | None = None,
+        **predict_kwargs: Any,
+    ) -> None:
+        self.model = model
+        self.predict_kwargs = {"verbose": False, **predict_kwargs}
+        self._convert = convert or sv.Detections.from_ultralytics
+
+    def __call__(self, frame: np.ndarray) -> sv.Detections:
+        results = self.model(frame, **self.predict_kwargs)
+        return self._convert(results[0])
+
+    def __repr__(self) -> str:
+        return f"UltralyticsDetector({type(self.model).__name__})"
+
+
+class _CallableDetector:
+    """Wraps a user callable so a wrong return type fails with a clear message."""
+
+    def __init__(self, function: Callable[[np.ndarray], sv.Detections]) -> None:
+        self.function = function
+
+    def __call__(self, frame: np.ndarray) -> sv.Detections:
+        detections = self.function(frame)
+        if not isinstance(detections, sv.Detections):
+            raise TypeError(
+                f"model returned {type(detections).__name__}, expected supervision.Detections. "
+                "Convert the model output first, e.g. sv.Detections.from_ultralytics(result)."
+            )
+        return detections
+
+    def __repr__(self) -> str:
+        name = getattr(self.function, "__name__", type(self.function).__name__)
+        return f"_CallableDetector({name})"
+
+
+def load_ultralytics(weights: str | Path, **predict_kwargs: Any) -> UltralyticsDetector:
+    """Load Ultralytics weights. Raises ``ImportError`` when the extra is missing."""
+    try:
+        from ultralytics import YOLO
+    except ImportError as exc:
+        raise ImportError(
+            f"Loading {str(weights)!r} needs the ultralytics package: "
+            'pip install "cvflair[yolo]". It is an optional extra because Ultralytics '
+            "is AGPL-3.0 licensed; cvflair itself stays MIT."
+        ) from exc
+    return UltralyticsDetector(YOLO(str(weights)), **predict_kwargs)
+
+
+def _is_ultralytics_model(model: Any) -> bool:
+    return type(model).__module__.split(".")[0] == "ultralytics"
+
+
+def resolve_detector(model: ModelLike | None) -> Detector | None:
+    """
+    Turn ``model`` into a detector callable, or ``None`` when nothing was given.
+
+    Weights are loaded here, so calling this is what triggers the (slow) model
+    load -- ``Camera.stream()`` does it on the first iteration, not before.
+    """
+    if model is None:
+        return None
+
+    if isinstance(model, (str, Path)):
+        suffix = Path(model).suffix.lower()
+        if suffix not in WEIGHT_SUFFIXES:
+            raise ValueError(
+                f"Unrecognised weights file {str(model)!r}. "
+                f"Expected one of: {', '.join(sorted(WEIGHT_SUFFIXES))}."
+            )
+        return load_ultralytics(model)
+
+    if _is_ultralytics_model(model):
+        return UltralyticsDetector(model)
+
+    if callable(model):
+        return _CallableDetector(model)
+
+    raise TypeError(
+        f"model must be a weights path, an Ultralytics model, or a callable returning "
+        f"supervision.Detections; got {type(model).__name__}."
+    )

cvflair/themes.py

@@ -0,0 +1,232 @@
+"""
+Visual themes -- a thin configuration layer over ``supervision`` annotators.
+
+A :class:`Theme` holds nothing but presentation settings plus the annotator
+instances built from them. Annotators are created once, when the theme is
+constructed, and reused for every frame; rebuilding them inside the capture
+loop is the most common avoidable cost in this kind of pipeline.
+
+No drawing maths lives here. Every pixel is still produced by ``supervision``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Literal
+
+import numpy as np
+import supervision as sv
+
+__all__ = ["Theme", "get_theme", "available_themes", "BoxStyle"]
+
+BoxStyle = Literal["box", "round", "corner"]
+
+
+def _dim(color: sv.Color, factor: float) -> sv.Color:
+    """Return a darker copy of ``color`` (used for the neon halo pass)."""
+    return sv.Color(
+        r=int(color.r * factor),
+        g=int(color.g * factor),
+        b=int(color.b * factor),
+    )
+
+
+def _dim_palette(palette: sv.ColorPalette, factor: float) -> sv.ColorPalette:
+    return sv.ColorPalette([_dim(color, factor) for color in palette.colors])
+
+
+@dataclass
+class Theme:
+    """
+    A named bundle of annotator settings.
+
+    The defaults describe a plain white box with a plain label; the shipped
+    presets (see :func:`get_theme`) are just different field values, which is
+    also how a user-defined theme is written::
+
+        Theme(name="my-theme", palette=sv.ColorPalette.from_hex(["#39FF14"]),
+              box_style="round", thickness=3)
+
+    Attributes are read at construction time only. Changing a field afterwards
+    does not rebuild the annotators -- construct a new theme instead.
+    """
+
+    name: str = "custom"
+    palette: sv.ColorPalette = field(default_factory=lambda: sv.ColorPalette.DEFAULT)
+    box_style: BoxStyle = "box"
+    thickness: int = 2
+    #: Corner rounding for ``box_style="round"``, in (0, 1].
+    roundness: float = 0.5
+    #: Corner arm length in pixels for ``box_style="corner"``.
+    corner_length: int = 20
+    #: Draw a dimmed, thicker box behind the main one to fake a glow.
+    glow: bool = False
+    glow_thickness: int = 5
+    glow_dim: float = 0.45
+    labels: bool = True
+    text_color: sv.Color = field(default_factory=lambda: sv.Color.BLACK)
+    text_scale: float = 0.5
+    text_thickness: int = 1
+    text_padding: int = 6
+    label_radius: int = 0
+    color_lookup: sv.ColorLookup = sv.ColorLookup.CLASS
+
+    def __post_init__(self) -> None:
+        if self.box_style not in ("box", "round", "corner"):
+            raise ValueError(
+                f"Unknown box_style {self.box_style!r}. Use 'box', 'round' or 'corner'."
+            )
+        if self.thickness < 1:
+            raise ValueError(f"thickness must be >= 1, got {self.thickness}.")
+        if not 0.0 < self.roundness <= 1.0:
+            raise ValueError(f"roundness must be in (0, 1], got {self.roundness}.")
+
+        self._glow_annotator = (
+            self._build_box_annotator(
+                palette=_dim_palette(self.palette, self.glow_dim),
+                thickness=self.thickness + self.glow_thickness,
+            )
+            if self.glow
+            else None
+        )
+        self._box_annotator = self._build_box_annotator(
+            palette=self.palette,
+            thickness=self.thickness,
+        )
+        self._label_annotator = (
+            sv.LabelAnnotator(
+                color=self.palette,
+                text_color=self.text_color,
+                text_scale=self.text_scale,
+                text_thickness=self.text_thickness,
+                text_padding=self.text_padding,
+                border_radius=self.label_radius,
+                color_lookup=self.color_lookup,
+            )
+            if self.labels
+            else None
+        )
+
+    def _build_box_annotator(self, palette: sv.ColorPalette, thickness: int):
+        if self.box_style == "round":
+            return sv.RoundBoxAnnotator(
+                color=palette,
+                thickness=thickness,
+                roundness=self.roundness,
+                color_lookup=self.color_lookup,
+            )
+        if self.box_style == "corner":
+            return sv.BoxCornerAnnotator(
+                color=palette,
+                thickness=thickness,
+                corner_length=self.corner_length,
+                color_lookup=self.color_lookup,
+            )
+        return sv.BoxAnnotator(
+            color=palette,
+            thickness=thickness,
+            color_lookup=self.color_lookup,
+        )
+
+    def annotate(
+        self,
+        scene: np.ndarray,
+        detections: sv.Detections,
+        labels: Sequence[str] | None = None,
+    ) -> np.ndarray:
+        """
+        Draw ``detections`` onto ``scene`` in place and return the same array.
+
+        ``labels`` is passed straight through to ``supervision``: when it is
+        ``None`` the label text falls back to the detections' ``class_name``
+        data field, then to the class id.
+        """
+        if len(detections) == 0:
+            return scene
+        if self._glow_annotator is not None:
+            self._glow_annotator.annotate(scene=scene, detections=detections)
+        self._box_annotator.annotate(scene=scene, detections=detections)
+        if self._label_annotator is not None:
+            self._label_annotator.annotate(scene=scene, detections=detections, labels=labels)
+        return scene
+
+
+def _minimal() -> Theme:
+    """Thin single-colour box, plain label. Reads well in a screen recording."""
+    return Theme(
+        name="minimal",
+        palette=sv.ColorPalette([sv.Color.WHITE]),
+        box_style="box",
+        thickness=1,
+        text_color=sv.Color.BLACK,
+        text_scale=0.45,
+        text_padding=4,
+    )
+
+
+def _neon() -> Theme:
+    """Saturated per-class colours, rounded box, dimmed halo behind it."""
+    return Theme(
+        name="neon",
+        palette=sv.ColorPalette.from_hex(
+            ["#39FF14", "#FF00E5", "#00E5FF", "#FFE600", "#FF2D55", "#7B5CFF"]
+        ),
+        box_style="round",
+        thickness=3,
+        roundness=0.6,
+        glow=True,
+        glow_thickness=6,
+        glow_dim=0.4,
+        text_color=sv.Color.BLACK,
+        text_scale=0.5,
+        text_padding=8,
+        label_radius=6,
+    )
+
+
+def _pastel() -> Theme:
+    """Soft tones, generous rounding, dark text. Easy on a projector."""
+    return Theme(
+        name="pastel",
+        palette=sv.ColorPalette.from_hex(
+            ["#FFADAD", "#A0C4FF", "#B9FBC0", "#FFD6A5", "#CDB4DB", "#9BF6FF"]
+        ),
+        box_style="round",
+        thickness=2,
+        roundness=0.8,
+        text_color=sv.Color.from_hex("#2E2E2E"),
+        text_scale=0.45,
+        text_padding=8,
+        label_radius=10,
+    )
+
+
+_THEMES: dict[str, Callable[[], Theme]] = {
+    "minimal": _minimal,
+    "neon": _neon,
+    "pastel": _pastel,
+}
+
+
+def available_themes() -> list[str]:
+    """Names accepted by :func:`get_theme` and by ``Camera(theme=...)``."""
+    return sorted(_THEMES)
+
+
+def get_theme(theme: str | Theme) -> Theme:
+    """
+    Resolve a theme name to a fresh :class:`Theme`; pass instances through.
+
+    Each call builds a new instance, so two cameras never share annotators.
+    """
+    if isinstance(theme, Theme):
+        return theme
+    if not isinstance(theme, str):
+        raise TypeError(f"theme must be a name or a Theme instance, got {type(theme).__name__}.")
+    try:
+        return _THEMES[theme.strip().lower()]()
+    except KeyError:
+        raise ValueError(
+            f"Unknown theme {theme!r}. Available: {', '.join(available_themes())}."
+        ) from None

cvflair-0.2.0.dist-info/METADATA

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: cvflair
+Version: 0.2.0
+Summary: Theme-based, model-agnostic visualisation layer for computer vision detections, built on supervision.
+Author: kbycode
+License: MIT
+Project-URL: Homepage, https://github.com/kbycode/cvflair
+Project-URL: Documentation, https://github.com/kbycode/cvflair#readme
+Project-URL: Repository, https://github.com/kbycode/cvflair
+Project-URL: Issues, https://github.com/kbycode/cvflair/issues
+Project-URL: Changelog, https://github.com/kbycode/cvflair/blob/main/CHANGELOG.md
+Keywords: computer-vision,opencv,supervision,annotation,visualization,webcam,yolo,bounding-box,themes
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Multimedia :: Video :: Display
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: opencv-python>=4.8
+Requires-Dist: supervision<0.30,>=0.28
+Provides-Extra: yolo
+Requires-Dist: ultralytics>=8.2; extra == "yolo"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: pillow>=10.0; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=5.0; extra == "release"
+Dynamic: license-file
+
+# cvflair
+
+Bilgisayarlı görü tespitlerini üç satırda, hazır temalarla ekrana çizen ince bir katman.
+
+Çizim işini [supervision](https://github.com/roboflow/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.
+
+![cvflair demo](https://raw.githubusercontent.com/kbycode/cvflair/main/docs/demo.gif)
+
+*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).
+
+```bash
+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](#lisans) bölümü).
+
+## Hızlı başlangıç
+
+```python
+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:
+
+```python
+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:
+
+| Değer | Anlamı |
+|---|---|
+| `"yolov8n.pt"` (ağırlık yolu) | Ultralytics ile yüklenir — `cvflair[yolo]` gerekir |
+| Hazır bir Ultralytics modeli | `YOLO(...)` nesnesi doğrudan verilebilir, çıktısı dönüştürülür |
+| Herhangi bir çağrılabilir | `sv.Detections` döndüren kendi fonksiyonun — MediaPipe, InsightFace, özel model |
+
+Son seçenek kütüphaneyi model-agnostik yapan yer:
+
+```python
+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:
+
+```python
+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 | ![minimal](https://raw.githubusercontent.com/kbycode/cvflair/main/docs/theme-minimal.png) |
+| `neon` | sınıf başına canlı renk, yuvarlak köşe, koyu hâle ile parlama hissi | ![neon](https://raw.githubusercontent.com/kbycode/cvflair/main/docs/theme-neon.png) |
+| `pastel` | yumuşak tonlar, geniş yuvarlama, koyu etiket yazısı — atölye/projeksiyon | ![pastel](https://raw.githubusercontent.com/kbycode/cvflair/main/docs/theme-pastel.png) |
+
+Yol haritasındaki `cyberpunk` ve `hud` temaları Faz 2'de gelecek.
+
+Özel bir tema, `Theme` doğrudan kurulup `Camera`'ya verilerek tanımlanır:
+
+```python
+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:
+
+```bash
+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
+
+| Üye | Ne yapar |
+|---|---|
+| `Camera(source, theme, width, height, fps, window_name, capture_factory)` | Kaynağı ve temayı bağlar; kamerayı henüz açmaz |
+| `cam.start()` / `cam.close()` | Cihazı açar ve okuma thread'ini başlatır / her şeyi bırakır |
+| `cam.stream(timeout, model=None)` | Kareleri üretir; model verilirse `(kare, tespitler)` çifti. İlk kullanımda `start()`, bitince `close()` eder |
+| `cam.read(timeout)` | En güncel tek kareyi döndürür, kaynak bittiyse `None` |
+| `cam.show(frame, detections, labels)` | Temayı uygular, pencerede gösterir; çıkış istendiğinde `False` döner |
+| `cam.annotate(frame, detections, labels)` | Sadece çizer, pencere açmaz |
+| `cam.theme` | Okunur/yazılır; `cam.theme = "minimal"` çalışır |
+| `cam.frames_read` / `cam.frames_dropped` | Okunan ve tüketici yetişemediği için atılan kare sayısı |
+| `get_theme(ad)` / `available_themes()` | Tema adını çözer / mevcut adları listeler |
+| `UltralyticsDetector(model, **kwargs)` | Ultralytics çıktısını `sv.Detections`'a çevirir; `conf`, `iou`, `device` gibi ayarları taşır |
+| `resolve_detector(model)` | Ağırlık yolu / model / çağrılabilir → detektör; `stream()` bunu kullanır |
+
+`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
+
+```bash
+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:
+
+```bash
+python tools/make_demo_gif.py    # docs/demo.gif
+python examples/theme_preview.py # examples/output/theme-*.png
+```
+
+## Yol haritası
+
+| Faz | İçerik | Durum |
+|---|---|---|
+| Faz 1 | Kamera döngüsü, `minimal`/`neon`/`pastel` temaları, README, demo GIF, testler | tamam |
+| Faz 2 | Model bağlama (`stream(model=...)`) | tamam |
+| Faz 2 | PyPI paketi, Türkçe dokümantasyon sitesi, tema playground, `cyberpunk`/`hud` | sırada |
+| Faz 3 | GitHub Actions (lint + test), issue şablonları, örnek galerisi | planlandı |
+
+## Lisans
+
+MIT — bkz. [LICENSE](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.

cvflair-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+cvflair/__init__.py,sha256=JFOK3FPvkLiY-yM9De81mRCwdj_YYZho1ZPVHfQTbrM,805
+cvflair/camera.py,sha256=Tpkwd98ecRFoBcsCKiomH-Z7n75GEVDenL60XN5oTbk,8984
+cvflair/models.py,sha256=gfoUBFEsozY5l0NbJJ5XYo-GWhwX84CpLBbAHzF0x8Y,4731
+cvflair/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cvflair/themes.py,sha256=r4EmV1DneFP5-c5ioccXdPoqM4YnSMf-Yw9y_DSb5c8,7650
+cvflair-0.2.0.dist-info/licenses/LICENSE,sha256=0Tnxs_G4BvM4usmyYt-fIEogX96duNa_QmLJelQzb0w,1064
+cvflair-0.2.0.dist-info/METADATA,sha256=LgVHZilD4jgaP-B3U_345z-pTTbx7N3ROFI1A8SniuY,10382
+cvflair-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+cvflair-0.2.0.dist-info/top_level.txt,sha256=lPrkOHgpDfjoyb4I-sPatny-icHdTZjAtpb81IGQLXM,8
+cvflair-0.2.0.dist-info/RECORD,,

cvflair-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cvflair-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kbycode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cvflair-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cvflair