pixpick 0.1.0__py3-none-any.whl

pixpick/__init__.py

@@ -0,0 +1,106 @@
+"""
+pixpick
+-------
+Interactive coordinate picker for Computer Vision frameworks.
+
+Quick start
+-----------
+    import pixpick
+
+    # Box
+    region = pixpick.box("frame.jpg")
+    model.predict("frame.jpg", **region.yolo_region())
+    print(region.xyxy)          # [x1, y1, x2, y2]
+    print(region.norm)    # [0.12, 0.08, 0.64, 0.48]
+
+    # Polygon
+    zone = pixpick.polygon("frame.jpg")
+    sv.PolygonZone(**zone.to_supervision())
+    print(zone.points)          # [(x0,y0), (x1,y1), ...]
+
+    # Save and reload either type
+    region.save("zone.json")
+    region = pixpick.load("zone.json")
+"""
+
+from pixpick.selectors.box import BoxSelector
+from pixpick.selectors.polygon import PolygonSelector, SelectionCancelled
+from pixpick.core.selection import Box, Polygon
+from pixpick.utils import ImageSource
+
+
+def box(source: ImageSource, title: str = "pixpick") -> Box:
+    """
+    Open an interactive window on `source`, drag a rectangle, return a Box.
+
+    Parameters
+    ----------
+    source : str | Path | np.ndarray
+        Image file path or BGR numpy array.
+    title : str
+        Window title shown to the user.
+
+    Returns
+    -------
+    Box
+
+    Raises
+    ------
+    SelectionCancelled
+        If the user pressed Esc.
+    """
+    return BoxSelector().select(source, title=title)
+
+
+def polygon(source: ImageSource, title: str = "pixpick") -> Polygon:
+    """
+    Open an interactive window on `source`, click vertices, return a Polygon.
+
+    Controls: LMB=add point  RMB=undo last  Enter=confirm  Z=clear  Esc=cancel
+
+    Parameters
+    ----------
+    source : str | Path | np.ndarray
+        Image file path or BGR numpy array.
+    title : str
+        Window title shown to the user.
+
+    Returns
+    -------
+    Polygon
+
+    Raises
+    ------
+    SelectionCancelled
+        If the user pressed Esc.
+    """
+    return PolygonSelector().select(source, title=title)
+
+
+def load(path: str) -> Box | Polygon:
+    """
+    Load a previously saved selection from a JSON file.
+    Dispatches to Box.load or Polygon.load based on the 'type' field.
+    """
+    import json
+    from pathlib import Path
+    data = json.loads(Path(path).read_text())
+    sel_type = data.get("type")
+    if sel_type == "box":
+        return Box.load(path)
+    elif sel_type == "polygon":
+        return Polygon.load(path)
+    else:
+        raise ValueError(f"Unknown selection type in JSON: '{sel_type}'")
+
+
+__all__ = [
+    "box",
+    "polygon",
+    "load",
+    "Box",
+    "Polygon",
+    "BoxSelector",
+    "PolygonSelector",
+    "SelectionCancelled",
+]

pixpick/backends/base.py

@@ -0,0 +1,46 @@
+from abc import ABC, abstractmethod
+import numpy as np
+
+
+class BaseBackend(ABC):
+    """
+    A backend owns the UI layer — it opens a window (or widget),
+    captures user interactions, and returns raw pixel coordinates.
+
+    It knows nothing about Selection objects or adapters.
+    The selector calls the backend and wraps the raw result in the
+    appropriate Selection type.
+
+    Adding a new environment (Jupyter, Gradio, …) means adding a new
+    backend — zero changes to selectors or adapters.
+    """
+
+    @abstractmethod
+    def select_box(
+        self,
+        image: np.ndarray,
+        title: str = "pixpick",
+    ) -> tuple[int, int, int, int] | None:
+        """
+        Let the user drag a rectangle on the image.
+
+        Returns
+        -------
+        (x1, y1, x2, y2) in absolute pixels, or None if cancelled.
+        """
+        ...
+
+    @abstractmethod
+    def select_polygon(
+        self,
+        image: np.ndarray,
+        title: str = "pixpick",
+    ) -> list[tuple[int, int]] | None:
+        """
+        Let the user click polygon vertices on the image.
+
+        Returns
+        -------
+        List of (x, y) tuples (≥ 3 points), or None if cancelled.
+        """
+        ...

pixpick/backends/cv2_backend.py

@@ -0,0 +1,269 @@
+import cv2
+import numpy as np
+from pixpick.backends.base import BaseBackend
+
+
+class CV2Backend(BaseBackend):
+    """
+    OpenCV imshow backend.
+
+    Controls
+    --------
+    Left-click + drag  : draw the box
+    Enter / Space      : confirm selection
+    R                  : reset and redraw
+    Esc                : cancel — returns None
+
+    The live rubber-band rect is drawn on a scratch copy of the image
+    so the original is never mutated.
+    """
+
+    # Internal mouse state — kept on the instance so the callback has access.
+    _drawing: bool
+    _start:   tuple[int, int]
+    _end:     tuple[int, int]
+    _confirmed: bool
+    _cancelled: bool
+
+    def select_box(
+        self,
+        image: np.ndarray,
+        title: str = "pixpick  |  drag to select  |  Enter=confirm  R=reset  Esc=cancel",
+    ) -> tuple[int, int, int, int] | None:
+
+        self._reset_state()
+        canvas = image.copy()   # scratch copy for live drawing
+
+        cv2.namedWindow(title, cv2.WINDOW_AUTOSIZE)
+        cv2.setMouseCallback(title, self._mouse_callback, param={"image": image, "title": title})
+        cv2.imshow(title, canvas)
+
+        while True:
+            # Redraw every frame so the rubber-band rect updates.
+            canvas = self._draw_rect(image)
+            cv2.imshow(title, canvas)
+
+            key = cv2.waitKey(20) & 0xFF
+
+            if self._cancelled or key == 27:        # Esc
+                cv2.destroyWindow(title)
+                return None
+
+            # Backspace or Delete -> clear current selection
+            if key in (ord("z"), 8, 127):
+                self._reset_state()
+                continue
+
+            if key in (13, 32) or self._confirmed:  # Enter / Space
+                if self._start == self._end:
+                    # User hit confirm without completing a drag — ignore.
+                    continue
+                cv2.destroyWindow(title)
+                x1 = min(self._start[0], self._end[0])
+                y1 = min(self._start[1], self._end[1])
+                x2 = max(self._start[0], self._end[0])
+                y2 = max(self._start[1], self._end[1])
+                return x1, y1, x2, y2
+
+
+    def select_polygon(
+            self, 
+            image: np.ndarray,
+            title: str = "pixpick | polygon | LMB=add RMB=undo Enter=confirm Z=clear Esc=cancel",
+            ) -> list[tuple[int, int]] | None:
+
+        self._points = []
+
+        cv2.namedWindow(title, cv2.WINDOW_AUTOSIZE)
+        cv2.setMouseCallback(title, self._polygon_callback)
+
+        while True:
+            canvas = self._draw_polygon(image)
+            cv2.imshow(title, canvas)
+
+            key = cv2.waitKey(20) & 0xFF
+
+            # Esc
+            if key == 27:
+                cv2.destroyWindow(title)
+                return None
+
+            # Z / Backspace / Delete
+            if key in (ord("z"), 8, 127):
+                self._points.clear()
+                continue
+
+            # Enter / Space
+            if key in (13, 32):
+
+                if len(self._points) < 3:
+                    continue
+
+                cv2.destroyWindow(title)
+
+                return self._points
+
+
+    # ------------------------------------------------------------------ #
+    # Mouse callback                                                       #
+    # ------------------------------------------------------------------ #
+
+    def _mouse_callback(self, event: int, x: int, y: int, flags: int, param: dict) -> None:
+        if event == cv2.EVENT_LBUTTONDOWN:
+            self._drawing = True
+            self._start   = (x, y)
+            self._end     = (x, y)
+
+        elif event == cv2.EVENT_MOUSEMOVE and self._drawing:
+            self._end = (x, y)
+
+        elif event == cv2.EVENT_LBUTTONUP:
+            self._drawing   = False
+            self._end       = (x, y)
+            # self._confirmed = True   # auto-confirm on mouse release
+
+
+    def _polygon_callback(
+        self,
+        event: int,
+        x: int,
+        y: int,
+        flags: int,
+        param,
+    ) -> None:
+
+        # Add point
+        if event == cv2.EVENT_LBUTTONDOWN:
+            self._points.append((x, y))
+
+        # Remove last point
+        elif event == cv2.EVENT_RBUTTONDOWN:
+            if self._points:
+                self._points.pop()
+
+
+    # ------------------------------------------------------------------ #
+    # Helpers                                                              #
+    # ------------------------------------------------------------------ #
+
+    def _reset_state(self) -> None:
+        self._drawing = False
+        self._start = (0, 0)
+        self._end = (0, 0)
+        self._confirmed = False
+        self._cancelled = False
+        self._points = []
+
+    def _draw_rect(self, image: np.ndarray) -> np.ndarray:
+        """Return a copy of image with the current rubber-band rect drawn."""
+        canvas = image.copy()
+        if self._start != self._end:
+            # Semi-transparent fill
+            overlay = canvas.copy()
+            cv2.rectangle(overlay, self._start, self._end, (0, 255, 0), -1)
+            cv2.addWeighted(overlay, 0.15, canvas, 0.85, 0, canvas)
+            # Solid border
+            cv2.rectangle(canvas, self._start, self._end, (0, 255, 0), 2)
+            # Corner coords label
+            x1 = min(self._start[0], self._end[0])
+            y1 = min(self._start[1], self._end[1])
+            x2 = max(self._start[0], self._end[0])
+            y2 = max(self._start[1], self._end[1])
+            label = f"({x1},{y1}) ({x2},{y2})  w={x2-x1} h={y2-y1}"
+            cv2.putText(canvas, label, (x1, max(y1 - 8, 12)),
+                        cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 1, cv2.LINE_AA)
+        return canvas
+    
+
+    def _draw_polygon(self, image: np.ndarray) -> np.ndarray:
+        """
+        Draw current polygon preview.
+        """
+
+        canvas = image.copy()
+
+        if not self._points:
+            return canvas
+
+        # Draw filled polygon
+        if len(self._points) >= 3:
+
+            overlay = canvas.copy()
+
+            pts = np.array(self._points, dtype=np.int32)
+
+            cv2.fillPoly(
+                overlay,
+                [pts],
+                (0, 255, 0),
+            )
+
+            cv2.addWeighted(
+                overlay,
+                0.15,
+                canvas,
+                0.85,
+                0,
+                canvas,
+            )
+
+        # Draw edges
+        if len(self._points) > 1:
+
+            pts = np.array(self._points, dtype=np.int32)
+
+            cv2.polylines(
+                canvas,
+                [pts],
+                isClosed=False,
+                color=(0, 255, 0),
+                thickness=2,
+            )
+
+        # Preview closing edge
+        if len(self._points) >= 3:
+
+            cv2.line(
+                canvas,
+                self._points[-1],
+                self._points[0],
+                (0, 255, 0),
+                1,
+                cv2.LINE_AA,
+            )
+
+        # Draw vertices + indices
+        for idx, pt in enumerate(self._points):
+
+            cv2.circle(
+                canvas,
+                pt,
+                4,
+                (0, 255, 0),
+                -1,
+            )
+
+            cv2.putText(
+                canvas,
+                str(idx),
+                (pt[0] + 5, pt[1] - 5),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                0.5,
+                (0, 255, 0),
+                1,
+                cv2.LINE_AA,
+            )
+
+        # Info text
+        cv2.putText(
+            canvas,
+            f"Points: {len(self._points)}",
+            (10, 25),
+            cv2.FONT_HERSHEY_SIMPLEX,
+            0.7,
+            (0, 255, 0),
+            2,
+            cv2.LINE_AA,
+        )
+
+        return canvas

pixpick/core/selection.py

@@ -0,0 +1,362 @@
+from __future__ import annotations
+import cv2
+import json
+import numpy as np
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+
+# ======================================================================== #
+# Box                                                                        #
+# ======================================================================== #
+
+@dataclass
+class Box:
+    """
+    Immutable result of a box selection.
+
+    All coordinate math lives here.
+    Adapters are thin — they just re-package what this class already holds.
+
+    Attributes
+    ----------
+    x1, y1, x2, y2 : int
+        Absolute pixel coordinates (top-left → bottom-right).
+    image_width, image_height : int
+        Dimensions of the source image — needed for normalisation.
+    """
+
+    x1: int
+    y1: int
+    x2: int
+    y2: int
+    image_width: int
+    image_height: int
+
+    # ------------------------------------------------------------------ #
+    # Validation                                                           #
+    # ------------------------------------------------------------------ #
+
+    def __post_init__(self):
+        # Normalise so x1 < x2 and y1 < y2 regardless of drag direction.
+        self.x1, self.x2 = sorted([self.x1, self.x2])
+        self.y1, self.y2 = sorted([self.y1, self.y2])
+
+        if self.x1 == self.x2 or self.y1 == self.y2:
+            raise ValueError("Box has zero area — did the drag complete?")
+
+        if not (0 <= self.x1 < self.x2 <= self.image_width):
+            raise ValueError(
+                f"x coords out of bounds: {self.x1}, {self.x2} (image width={self.image_width})"
+            )
+        if not (0 <= self.y1 < self.y2 <= self.image_height):
+            raise ValueError(
+                f"y coords out of bounds: {self.y1}, {self.y2} (image height={self.image_height})"
+            )
+
+    # ------------------------------------------------------------------ #
+    # Core format properties                                               #
+    # ------------------------------------------------------------------ #
+
+    @property
+    def xyxy(self) -> list[int]:
+        """[x1, y1, x2, y2] — absolute pixels."""
+        return [self.x1, self.y1, self.x2, self.y2]
+
+    @property
+    def xywh(self) -> list[int]:
+        """[x, y, width, height] — top-left origin, absolute pixels."""
+        return [self.x1, self.y1, self.x2 - self.x1, self.y2 - self.y1]
+
+    @property
+    def cxcywh(self) -> list[float]:
+        """[cx, cy, width, height] — centre + size, absolute pixels."""
+        w, h = self.x2 - self.x1, self.y2 - self.y1
+        return [self.x1 + w / 2, self.y1 + h / 2, float(w), float(h)]
+
+    @property
+    def norm(self) -> list[float]:
+        """[x1, y1, x2, y2] — values in [0, 1]."""
+        return [
+            self.x1 / self.image_width,
+            self.y1 / self.image_height,
+            self.x2 / self.image_width,
+            self.y2 / self.image_height,
+        ]
+
+    @property
+    def norm_xywh(self) -> list[float]:
+        """[x, y, w, h] normalised — YOLO label format."""
+        x1n, y1n, x2n, y2n = self.norm
+        return [x1n, y1n, x2n - x1n, y2n - y1n]
+
+    @property
+    def center(self) -> tuple[int, int]:
+        """(cx, cy) in absolute pixels."""
+        return (self.x1 + self.x2) // 2, (self.y1 + self.y2) // 2
+
+    @property
+    def area(self) -> int:
+        """Area in pixels²."""
+        return (self.x2 - self.x1) * (self.y2 - self.y1)
+
+    @property
+    def as_numpy(self) -> np.ndarray:
+        """Shape (4,) int32 array — [x1, y1, x2, y2]."""
+        return np.array(self.xyxy, dtype=np.int32)
+
+    # ------------------------------------------------------------------ #
+    # Adapter shortcuts                                                    #
+    # ------------------------------------------------------------------ #
+
+    def yolo_region(self) -> list[float]:
+        """[(point1), (point2), (point3), (point4)] """
+        return [
+            (self.x1, self.y1),
+            (self.x2, self.y1),
+            (self.x2, self.y2),
+            (self.x1, self.y2)
+        ]
+
+    def yolo_prompt(self) -> np.ndarray:
+        """[(point1), (point2), (point3), (point4)] """
+        return np.array([
+            [self.x1, self.y1, self.x2, self.y2]
+        ])
+
+    def sam(self) -> np.ndarray:
+        """[(point1), (point2), (point3), (point4)] """
+        return np.array([self.x1, self.y1, self.x2, self.y2])
+
+    def raw(self) -> dict:
+        """All formats at once — handy for debugging."""
+        return {
+            "xyxy":            self.xyxy,
+            "xywh":            self.xywh,
+            "cxcywh":          self.cxcywh,
+            "normalized":      self.norm,
+            "normalized_xywh": self.norm_xywh,
+            "numpy":           self.as_numpy.tolist(),
+        }
+
+    # ------------------------------------------------------------------ #
+    # Persistence                                                          #
+    # ------------------------------------------------------------------ #
+
+    def save(self, path: str | Path) -> None:
+        """Serialise to JSON."""
+        data = {
+            "type": "box",
+            "image_size": [self.image_width, self.image_height],
+            "coordinates": {
+                "xyxy":       self.xyxy,
+                "xywh":       self.xywh,
+                "normalized": self.norm,
+            },
+        }
+        Path(path).write_text(json.dumps(data, indent=2))
+
+    @classmethod
+    def load(cls, path: str | Path) -> "Box":
+        """Reconstruct from a saved JSON file."""
+        data = json.loads(Path(path).read_text())
+        if data["type"] != "box":
+            raise ValueError(f"Expected type 'box', got '{data['type']}'")
+        w, h = data["image_size"]
+        x1, y1, x2, y2 = data["coordinates"]["xyxy"]
+        return cls(x1=x1, y1=y1, x2=x2, y2=y2, image_width=w, image_height=h)
+
+    # ------------------------------------------------------------------ #
+    # Visualisation                                                        #
+    # ------------------------------------------------------------------ #
+
+    def visualize(
+        self,
+        image: np.ndarray,
+        color: tuple = (0, 255, 0),
+        thickness: int = 2,
+    ) -> np.ndarray:
+        """Draw the box on a copy of image and return it."""
+        canvas = image.copy()
+        cv2.rectangle(canvas, (self.x1, self.y1), (self.x2, self.y2), color, thickness)
+        label = f"({self.x1},{self.y1}) -> ({self.x2},{self.y2})"
+        cv2.putText(
+            canvas, label, (self.x1, max(self.y1 - 8, 12)),
+            cv2.FONT_HERSHEY_SIMPLEX, 0.5, color, 1, cv2.LINE_AA,
+        )
+        return canvas
+
+    def __repr__(self) -> str:
+        return (
+            f"Box(xyxy={self.xyxy}, "
+            f"size={self.image_width}x{self.image_height}, "
+            f"area={self.area}px²)"
+        )
+
+
+# ======================================================================== #
+# Polygon                                                                    #
+# ======================================================================== #
+
+@dataclass
+class Polygon:
+    """
+    Immutable result of a polygon selection.
+
+    Attributes
+    ----------
+    points : list[tuple[int, int]]
+        Ordered list of (x, y) vertices in absolute pixels.
+    image_width, image_height : int
+        Dimensions of the source image — needed for normalisation.
+    """
+
+    points: list[tuple[int, int]]
+    image_width: int
+    image_height: int
+
+    # ------------------------------------------------------------------ #
+    # Validation                                                           #
+    # ------------------------------------------------------------------ #
+
+    def __post_init__(self):
+        if len(self.points) < 3:
+            raise ValueError(
+                f"Polygon needs at least 3 points, got {len(self.points)}"
+            )
+        for i, pt in enumerate(self.points):
+            x, y = pt
+            if not (0 <= x <= self.image_width and 0 <= y <= self.image_height):
+                raise ValueError(
+                    f"Point {i} ({x},{y}) is outside image "
+                    f"({self.image_width}x{self.image_height})"
+                )
+
+    # ------------------------------------------------------------------ #
+    # Core format properties                                               #
+    # ------------------------------------------------------------------ #
+
+    @property
+    def as_numpy(self) -> np.ndarray:
+        """Shape (N, 2) int32 array — [[x0,y0], [x1,y1], ...]."""
+        return np.array(self.points, dtype=np.int32)
+
+    @property
+    def norm(self) -> list[tuple[float, float]]:
+        """Points normalised to [0, 1]."""
+        return [
+            (x / self.image_width, y / self.image_height)
+            for x, y in self.points
+        ]
+
+    @property
+    def norm_numpy(self) -> np.ndarray:
+        """Shape (N, 2) float32 array of normalised points."""
+        return np.array(self.norm, dtype=np.float32)
+
+    @property
+    def bbox(self) -> Box:
+        """Tight axis-aligned Box that encloses this polygon."""
+        xs = [p[0] for p in self.points]
+        ys = [p[1] for p in self.points]
+        x1, y1, x2, y2 = min(xs), min(ys), max(xs), max(ys)
+        xyxy = [x1, y1, x2, y2]
+        return xyxy
+
+    @property
+    def npoints(self) -> int:
+        return len(self.points)
+
+    # ------------------------------------------------------------------ #
+    # Adapter shortcuts                                                    #
+    # ------------------------------------------------------------------ #
+
+    def supervision(self) -> dict:
+        """
+        Ready to unpack into sv.PolygonZone().
+
+        Usage
+        -----
+        zone = sv.PolygonZone(**polygon.to_supervision())
+        """
+        return {"polygon": self.as_numpy}
+
+    def raw(self) -> dict:
+        """All formats at once."""
+        return {
+            "points":            self.points,
+            "numpy":             self.as_numpy.tolist(),
+            "normalized":        self.norm,
+            "normalized_numpy":  self.norm_numpy.tolist(),
+            "bbox_xyxy":         self.bbox,
+        }
+
+    # ------------------------------------------------------------------ #
+    # Persistence                                                          #
+    # ------------------------------------------------------------------ #
+
+    def save(self, path: str | Path) -> None:
+        """Serialise to JSON."""
+        data = {
+            "type": "polygon",
+            "image_size": [self.image_width, self.image_height],
+            "coordinates": {
+                "points":     self.points,
+                "normalized": self.norm,
+            },
+        }
+        Path(path).write_text(json.dumps(data, indent=2))
+
+    @classmethod
+    def load(cls, path: str | Path) -> "Polygon":
+        """Reconstruct from a saved JSON file."""
+        data = json.loads(Path(path).read_text())
+        if data["type"] != "polygon":
+            raise ValueError(f"Expected type 'polygon', got '{data['type']}'")
+        w, h = data["image_size"]
+        points = [tuple(p) for p in data["coordinates"]["points"]]
+        return cls(points=points, image_width=w, image_height=h)
+
+    # ------------------------------------------------------------------ #
+    # Visualisation                                                        #
+    # ------------------------------------------------------------------ #
+
+    def visualize(
+        self,
+        image: np.ndarray,
+        color: tuple = (0, 255, 0),
+        thickness: int = 2,
+        fill_alpha: float = 0.15,
+    ) -> np.ndarray:
+        """Draw the polygon (filled + border + vertex dots) on a copy of image."""
+        canvas = image.copy()
+        pts = self.as_numpy.reshape((-1, 1, 2))
+
+        # Semi-transparent fill
+        if fill_alpha > 0:
+            overlay = canvas.copy()
+            cv2.fillPoly(overlay, [self.as_numpy], color)
+            cv2.addWeighted(overlay, fill_alpha, canvas, 1 - fill_alpha, 0, canvas)
+
+        # Border
+        cv2.polylines(canvas, [pts], isClosed=True, color=color, thickness=thickness)
+
+        # Vertex dots + index labels
+        for i, (x, y) in enumerate(self.points):
+            cv2.circle(canvas, (x, y), 4, color, -1)
+            cv2.putText(
+                canvas, str(i), (x + 5, y - 5),
+                cv2.FONT_HERSHEY_SIMPLEX, 0.45, color, 1, cv2.LINE_AA,
+            )
+
+        return canvas
+
+    def __repr__(self) -> str:
+        return (
+            f"Polygon(npoints={self.npoints}, "
+            f"size={self.image_width}x{self.image_height})"
+        )

pixpick/selectors/box.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+import numpy as np
+from pixpick.backends.base import BaseBackend
+from pixpick.backends.cv2_backend import CV2Backend
+from pixpick.core.selection import Box
+from pixpick.utils import load_image, image_size, ImageSource
+
+
+class BoxSelector:
+    """
+    Orchestrates: load image → open backend → capture drag → return Box.
+
+    This is the only class that knows about both the backend and the
+    Box result object. Backends know nothing about Box; Box knows nothing
+    about backends. BoxSelector is the glue.
+
+    Parameters
+    ----------
+    backend : BaseBackend | None
+        Pass a backend instance to override auto-detection.
+        None → CV2Backend (the only backend implemented in v0.1).
+    """
+    
+    def __init__(self, backend: BaseBackend | None = None):
+        self.backend = backend or CV2Backend()
+
+
+    def select(self, source: ImageSource, 
+               title: str = "pixpick | drag to select | Enter=confirm | Backspace=clear | Esc=cancel") -> Box:
+        """
+        Open an interactive window on `source` and return a Box.
+
+        Parameters
+        ----------
+        source : str | Path | np.ndarray
+            File path or BGR numpy array.
+        title : str
+            Window title.
+
+        Returns
+        -------
+        Box
+            A fully populated Box with all format properties and adapter methods.
+
+        Raises
+        ------
+        SelectionCancelled
+            If the user pressed Esc or closed the window.
+        """
+        print(f"Opening interactive selection window for: {source}")
+        image = load_image(source)
+        w, h  = image_size(image)
+
+        raw = self.backend.select_box(image, title=title)
+
+        if raw is None:
+            raise SelectionCancelled("Box selection was cancelled by the user.")
+
+        x1, y1, x2, y2 = raw
+        return Box(x1=x1, y1=y1, x2=x2, y2=y2, image_width=w, image_height=h)
+
+
+class SelectionCancelled(Exception):
+    """Raised when the user cancels an interactive selection (Esc)."""

pixpick/selectors/polygon.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+import numpy as np
+from pixpick.backends.base import BaseBackend
+from pixpick.backends.cv2_backend import CV2Backend
+from pixpick.core.selection import Polygon
+from pixpick.utils import load_image, image_size, ImageSource
+
+
+class PolygonSelector:
+    """
+    Orchestrates: load image → open backend → capture clicks → return Polygon.
+
+    Mirrors BoxSelector exactly — same pattern, different backend method
+    and different Selection type returned.
+
+    Parameters
+    ----------
+    backend : BaseBackend | None
+        Pass a backend instance to override auto-detection.
+        None → CV2Backend.
+    """
+
+    def __init__(self, backend: BaseBackend | None = None):
+        self.backend = backend or CV2Backend()
+
+    def select(self, source: ImageSource, title: str = "pixpick") -> Polygon:
+        """
+        Open an interactive window on `source`, let the user click polygon
+        vertices, and return a Polygon.
+
+        Parameters
+        ----------
+        source : str | Path | np.ndarray
+            Image file path or BGR numpy array.
+        title : str
+            Window title.
+
+        Returns
+        -------
+        Polygon
+
+        Raises
+        ------
+        SelectionCancelled
+            If the user pressed Esc or closed the window.
+        """
+        image = load_image(source)
+        w, h  = image_size(image)
+
+        raw = self.backend.select_polygon(image, title=title)
+
+        if raw is None:
+            raise SelectionCancelled("Polygon selection was cancelled by the user.")
+
+        # raw is list[tuple[int, int]] coming straight from the backend
+        return Polygon(points=raw, image_width=w, image_height=h)
+
+
+class SelectionCancelled(Exception):
+    """Raised when the user cancels an interactive selection (Esc)."""

pixpick/utils.py

@@ -0,0 +1,33 @@
+import numpy as np
+import cv2
+from pathlib import Path
+from typing import Union
+
+ImageSource = Union[str, Path, np.ndarray]
+
+
+def load_image(source: ImageSource) -> np.ndarray:
+    """
+    Accept a file path (str / Path) or a raw numpy array.
+    Always returns a BGR uint8 np.ndarray, which is what cv2 expects.
+    """
+    if isinstance(source, np.ndarray):
+        if source.ndim != 3 or source.shape[2] != 3:
+            raise ValueError(f"Array must be (H, W, 3) BGR, got shape {source.shape}")
+        return source.copy()
+
+    path = Path(source)
+    if not path.exists():
+        raise FileNotFoundError(f"Image not found: {path}")
+
+    img = cv2.imread(str(path))
+    if img is None:
+        raise ValueError(f"cv2 could not read image: {path}")
+
+    return img
+
+
+def image_size(img: np.ndarray) -> tuple[int, int]:
+    """Return (width, height) from a cv2 BGR array."""
+    h, w = img.shape[:2]
+    return w, h

pixpick-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: pixpick
+Version: 0.1.0
+Summary: Interactive coordinate picker for Computer Vision frameworks
+License: MIT
+Project-URL: Homepage, https://github.com/K-saif/pixpick
+Project-URL: Documentation, https://github.com/K-saif/pixpick/tree/main/docs
+Project-URL: Bug Tracker, https://github.com/K-saif/pixpick/issues
+Keywords: computer-vision,yolo,sam2,supervision,roi,annotation
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python>=4.5
+Requires-Dist: numpy>=1.21
+Dynamic: license-file
+
+<div align="center">
+
+# pixpick 🎯
+
+**Interactive coordinate picker for Computer Vision — no external tools needed.**
+
+[![PyPI version](https://badge.fury.io/py/pixpick.svg)](https://badge.fury.io/py/pixpick)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+---
+
+## The problem
+
+Every major CV framework needs coordinates before it can run.
+
+```python
+regioncounter = RegionCounter(region=[120, 80, 640, 480])    # YOLO   — where does this region come from?
+predictor.predict(box=np.array([120, 80, 640, 480]))         # SAM2   — same problem
+```
+
+The standard workflow: open CVAT or Roboflow → grab coordinates → paste them back into code. Every. Single. Time.
+
+## The fix
+
+```python
+import pixpick
+
+region = pixpick.box("frame.jpg")      # drag a box on the image
+zone   = pixpick.polygon("frame.jpg")  # click polygon vertices
+
+# coordinates are ready — unpack directly into any framework
+# YOLO:
+regioncounter = RegionCounter(
+     region=region.yolo_region,  # pass region points
+     model="yolo26n.pt",
+ )
+
+# same for YOLOE
+model.predict("frame.jpg", visual_prompt= region.yolo_prompt())
+
+# SAM1/SAM2:
+predictor.predict(box=region.sam())
+```
+
+A window opens on your image. You interact. You get framework-ready coordinates back in Python. No round-trips.
+
+---
+
+## Install
+
+```bash
+pip install pixpick
+```
+
+---
+
+## Selectors
+
+| Selector | How to use | Returns |
+|---|---|---|
+| `pixpick.box()` | Left-click + drag | `Box` |
+| `pixpick.polygon()` | Click vertices → `Enter` to confirm | `Polygon` |
+
+**Box controls** — `drag` to draw · `R` to reset · `Esc` to cancel
+
+**Polygon controls** — `LMB` add point · `RMB` undo · `Z` clear · `Enter` confirm · `Esc` cancel
+
+---
+
+## Output formats
+
+Every selection object carries all the formats you'll ever need.
+
+```python
+# ── Box ──────────────────────────────────────────────────────
+region = pixpick.box("frame.jpg")
+
+region.xyxy              # [x1, y1, x2, y2]            absolute pixels
+region.xywh              # [x, y, w, h]                absolute pixels
+region.norm_xywh         # [x, y, w, h]                0.0 – 1.0  ← YOLO label format
+region.center            # (cx, cy)
+region.area              # pixels²
+
+
+# ── Polygon ───────────────────────────────────────────────────
+zone = pixpick.polygon("frame.jpg")
+
+zone.points              # [(x0,y0), (x1,y1), ...]     absolute pixels
+zone.as_numpy            # np.array shape (N, 2)
+zone.norm                # [(x0n,y0n), ...]             0.0 – 1.0
+zone.bbox                # → Box   tight bbox around the polygon
+zone.npoints             # int
+```
+For more details, see [Selectors](docs/selectors.md).
+---
+
+## Framework integration
+
+| Framework | Selector | Method |
+|---|---|---|
+| Ultralytics YOLOE — visual prompt | `Box` | `region.yolo_prompt()` |
+| Ultralytics YOLO — region | `Box` | `region.yolo_region()` |
+| SAM / SAM2 — box prompt | `Box` | `region.sam()` |
+| Any other format | `Box` / `Polygon` | `region.to_raw()` |
+
+---
+
+## Persistence
+
+Pick once, reuse forever.
+
+```python
+region.save("zone.json")
+region = pixpick.load("zone.json")   # Box and Polygon both work
+```
+
+Production pattern — pick interactively the first time, load on every subsequent run:
+
+```python
+from pathlib import Path
+import pixpick
+
+ZONE = "config/count_zone.json"
+
+zone = pixpick.load(ZONE) if Path(ZONE).exists() else pixpick.polygon("frame.jpg")
+zone.save(ZONE)
+```
+
+---
+
+## Docs
+
+| | |
+|---|---|
+| 🚀 [Getting Started](docs/getting-started.md) | Installation, first selection, controls |
+| 🎯 [Selectors](docs/selectors.md) | All properties and methods for Box and Polygon |
+| 🔌 [Framework Integration](docs/frameworks.md) | YOLO, SAM2 and more |
+| 💾 [Persistence](docs/persistence.md) | Save, load, JSON schema |
+| 🏗️ [Architecture](docs/architecture.md) | How it's built and how to extend it |
+| 🗺️ [Roadmap](docs/roadmap.md) | What's coming next |

pixpick-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pixpick/__init__.py,sha256=4SGFAS950rNiToQv6NTIc4EOLn87juU0jI4iuJ0jiPw,2537
+pixpick/utils.py,sha256=YJo4fNMHDrF-Sox6q4VBN4j1VdprD6RqlwyTZb0STxk,920
+pixpick/backends/base.py,sha256=wyWVQQvDqw1D7LufLp8orW6F97GZmVEYsup1TrOcTio,1212
+pixpick/backends/cv2_backend.py,sha256=4PafUoRO6tksxHK1PTvXJ_OeOi3x9Lqha2ogmylwGO4,7740
+pixpick/core/selection.py,sha256=Nh540mEN5ocrgJI7o-uyRxry5tH0e6rR11om8H3FZtI,12800
+pixpick/selectors/box.py,sha256=JMbZr1t6jAd3CrAOsE_SkRDRTTPzEJujMn-kqZPG3-I,2038
+pixpick/selectors/polygon.py,sha256=5b7vevc6X6wmyK9IFlO9cPbWpu8T18Rw-M1mnM4kMkg,1810
+pixpick-0.1.0.dist-info/licenses/LICENSE,sha256=7xVUULIVw6C8NnD9Eq6htNix3pST38jkkvD5lQq44bA,1066
+pixpick-0.1.0.dist-info/METADATA,sha256=LRdO8yHwKyzn0bnLAW1ZzsZUK0s_kIS-lCAxev1qd5E,5155
+pixpick-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pixpick-0.1.0.dist-info/top_level.txt,sha256=EGQWHYVK7lv1e_xz0LMcF_GANTdu3RlDxQbaOo_hz_k,8
+pixpick-0.1.0.dist-info/RECORD,,

pixpick-0.1.0.dist-info/WHEEL

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

pixpick-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saif Khan
+
+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.

pixpick-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pixpick