pixpick 0.1.0__tar.gz

pixpick-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,143 @@
+<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/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-0.1.0/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.
+        """
+        ...