cv4 0.0.1__py3-none-any.whl

cv4/__init__.py

@@ -0,0 +1,14 @@
+"""cv4 is a Python library for computer vision.""" # TODO: Update description
+
+__version__ = "0.0.1"
+try:
+    import cv2  # pyright: ignore[reportUnusedImport]  # noqa: F401
+except ImportError as e:
+    raise ImportError(
+        "cv4 requires OpenCV. Install it with `pip install cv4[opencv]`, or provide your own cv2 build."
+    ) from e
+
+from .main import *  # noqa: F401,F403
+
+def hello() -> str:
+    return "Hello from cv4!"

cv4/main.py

@@ -0,0 +1,242 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Final
+
+import cv2
+import numpy as np
+
+
+@dataclass
+class HSV:
+    hue: float
+    saturation: float
+    value: float
+
+    def as_tuple(self) -> tuple[float, float, float]:
+        return (self.hue, self.saturation, self.value)
+
+    @property
+    def np_array(self) -> np.ndarray[np.float64, np.dtype[np.float64]]:
+        return np.array(self.as_tuple())
+
+
+@dataclass
+class RGB:
+    red: float
+    green: float
+    blue: float
+
+    def as_tuple(self) -> tuple[float, float, float]:
+        return (self.red, self.green, self.blue)
+
+    def as_bgr(self) -> "BGR":
+        return BGR(self.blue, self.green, self.red)
+
+
+@dataclass
+class Point:
+    x: float
+    y: float
+
+    def as_tuple(self) -> tuple[float, float]:
+        return (self.x, self.y)
+
+    def as_cv2_point(self) -> "cv2.typing.Point":
+        return (int(self.x), int(self.y))
+
+
+@dataclass
+class BGR:
+    blue: float
+    green: float
+    red: float
+
+    def as_tuple(self) -> tuple[float, float, float]:
+        return (self.blue, self.green, self.red)
+
+    def as_rgb(self) -> RGB:
+        return RGB(self.red, self.green, self.blue)
+
+
+@dataclass
+class HSVRange:
+    lower: HSV
+    upper: HSV
+
+
+class Image:
+    def __init__(self, image: "cv2.typing.MatLike"):
+        self.cv2_image: cv2.typing.MatLike = image
+
+    def copy(self) -> "Image":
+        return self.__class__(self.cv2_image.copy())
+
+
+class DrawableImage(Image):
+    def draw_contours(self, contours: list["Contour"], color: RGB, thickness: int = 2):
+        _ = cv2.drawContours(
+            self.cv2_image,
+            [contour.cv2_image for contour in contours],
+            -1,
+            color.as_bgr().as_tuple(),
+            thickness,
+        )
+        return self
+
+    def draw_circle(self, center: Point, radius: int, color: RGB, thickness: int = -1):
+        _ = cv2.circle(
+            self.cv2_image,
+            center.as_cv2_point(),
+            radius,
+            color.as_bgr().as_tuple(),
+            thickness,
+        )
+        return self
+
+    def draw_marker(  # noqa: PLR0913, PLR0917  # just replicating cv2 API
+        self,
+        position: Point,
+        color: RGB,
+        markerType: int = cv2.MARKER_CROSS,
+        markerSize: int = 10,
+        thickness: int = 2,
+        lineType: int = cv2.LINE_AA,
+    ):
+        _ = cv2.drawMarker(
+            self.cv2_image,
+            position.as_cv2_point(),
+            color.as_bgr().as_tuple(),
+            markerType,
+            markerSize,
+            thickness,
+            lineType,
+        )
+        return self
+
+
+class BGRImage(DrawableImage):
+    def __init__(self, image: "cv2.typing.MatLike"):
+        super().__init__(image)
+
+    @property
+    def height(self) -> int:
+        return self.cv2_image.shape[0]
+
+    @property
+    def width(self) -> int:
+        return self.cv2_image.shape[1]
+
+    def as_grayscale(self) -> "GrayscaleImage":
+        return GrayscaleImage(cv2.cvtColor(self.cv2_image, cv2.COLOR_BGR2GRAY))
+
+    def as_hsv(self) -> "HSVImage":
+        return HSVImage(cv2.cvtColor(self.cv2_image, cv2.COLOR_BGR2HSV))
+
+    def as_rgb(self) -> "RGBImage":
+        return RGBImage(cv2.cvtColor(self.cv2_image, cv2.COLOR_BGR2RGB))
+
+
+class HSVImage(Image):
+    def __init__(self, image: "cv2.typing.MatLike"):
+        super().__init__(image)
+
+    def as_bgr(self) -> "BGRImage":
+        return BGRImage(cv2.cvtColor(self.cv2_image, cv2.COLOR_HSV2BGR))
+
+    def as_rgb(self) -> "RGBImage":
+        return RGBImage(cv2.cvtColor(self.cv2_image, cv2.COLOR_HSV2RGB))
+
+    def mask(self, range: HSVRange) -> "HSVMask":
+        return HSVMask(
+            cv2.inRange(self.cv2_image, range.lower.np_array, range.upper.np_array),
+            range,
+        )
+
+
+class HSVMask(Image):
+    def __init__(self, image: "cv2.typing.MatLike", range: HSVRange | None = None):
+        super().__init__(image)
+
+    def bitwise_or(self, other: "HSVMask") -> "HSVMask":
+        self.cv2_image = cv2.bitwise_or(self.cv2_image, other.cv2_image)
+        return self
+
+    def clean(self, kernel_size: int) -> "HSVMask":
+        kernel = np.ones((kernel_size, kernel_size), np.uint8)
+        self.cv2_image = cv2.morphologyEx(self.cv2_image, cv2.MORPH_OPEN, kernel)
+        self.cv2_image = cv2.morphologyEx(self.cv2_image, cv2.MORPH_CLOSE, kernel)
+        return self
+
+    def find_contours(self) -> "Contours":
+        contours, _ = cv2.findContours(
+            self.cv2_image, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
+        )
+        return Contours([Contour(contour) for contour in contours])
+
+
+class Contours(list["Contour"]):
+    def __init__(self, contours: list["Contour"]):
+        super().__init__(contours)
+
+    def filter(self, function: Callable[["Contour"], bool]) -> "Contours":
+        return Contours([contour for contour in self if function(contour)])
+
+
+class Contour(Image):
+    def __init__(self, image: "cv2.typing.MatLike"):
+        super().__init__(image)
+        self._moments: Final = cv2.moments(self.cv2_image)
+
+    @property
+    def area(self) -> float:
+        return self._moments["m00"]
+
+    @property
+    def moments(self) -> "cv2.typing.Moments":
+        return self._moments
+
+    @property
+    def cx(self) -> float:
+        return self.centroid.x
+
+    @property
+    def cy(self) -> float:
+        return self.centroid.y
+
+    @property
+    def centroid(self) -> Point:
+        m00 = self._moments["m00"]
+        if abs(m00) > 1e-9:  # noqa: PLR2004
+            return Point(self._moments["m10"] / m00, self._moments["m01"] / m00)
+        # degenerate contour (point / line) the mean of its vertices should be close enough.
+        x, y = self.cv2_image.reshape(-1, 2).mean(axis=0)
+        return Point(float(x), float(y))
+
+    @property
+    def base_y(self) -> float:
+        return float(self.cv2_image[:, :, 1].max())  # pyright: ignore[reportAny]
+
+
+class RGBImage(DrawableImage):
+    def __init__(self, image: "cv2.typing.MatLike"):
+        super().__init__(image)
+
+    def as_bgr(self) -> "BGRImage":
+        return BGRImage(cv2.cvtColor(self.cv2_image, cv2.COLOR_RGB2BGR))
+
+    def as_hsv(self) -> "HSVImage":
+        return HSVImage(cv2.cvtColor(self.cv2_image, cv2.COLOR_RGB2HSV))
+
+    def as_grayscale(self) -> "GrayscaleImage":
+        return GrayscaleImage(cv2.cvtColor(self.cv2_image, cv2.COLOR_RGB2GRAY))
+
+
+class GrayscaleImage(Image):
+    def __init__(self, image: "cv2.typing.MatLike"):
+        super().__init__(image)
+
+    def as_bgr(self) -> "BGRImage":
+        return BGRImage(cv2.cvtColor(self.cv2_image, cv2.COLOR_GRAY2BGR))
+
+    def as_rgb(self) -> "RGBImage":
+        return RGBImage(cv2.cvtColor(self.cv2_image, cv2.COLOR_GRAY2RGB))

cv4-0.0.1.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: cv4
+Version: 0.0.1
+Summary: A type-safe, builder-pattern, pythonic wrapper for OpenCV
+Author: kytpbs
+Author-email: kytpbs <email@example.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: opencv-contrib-python>=5.0.0.93 ; extra == 'contrib'
+Requires-Dist: opencv-contrib-python-headless>=5.0.0.93 ; extra == 'contrib-headless'
+Requires-Dist: opencv-python>=5.0.0.93 ; extra == 'opencv'
+Requires-Dist: opencv-python-headless>=5.0.0.93 ; extra == 'opencv-headless'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/kytpbs/cv4
+Provides-Extra: contrib
+Provides-Extra: contrib-headless
+Provides-Extra: opencv
+Provides-Extra: opencv-headless
+Description-Content-Type: text/markdown
+
+# Type Safe OpenCV
+
+A simple wrapper around opencv to make it type-safe and also follow pythonic syntax
+using builder pattern and similar systems.
+
+## Example
+
+<table>
+<tr>
+<th>The old way: raw <code>cv2</code></th>
+<th>The builder pattern: <code>cv4</code></th>
+</tr>
+<tr>
+<td>
+
+```python
+hsv = cv2.cvtColor(image, cv2.COLOR_BGR2HSV)
+mask = cv2.inRange(hsv, lower, upper)
+
+kernel = np.ones((5, 5), np.uint8)
+mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)
+mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
+
+# nothing stops you passing the HSV image here
+# by mistake it runs, but the result is very wrong
+contours, _ = cv2.findContours(
+    hsv, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+for c in contours:
+    if cv2.contourArea(c) < MIN_AREA:
+        continue
+    m = cv2.moments(c)
+    cx = m["m10"] / m["m00"]  # can divide by zero
+```
+
+</td>
+<td>
+
+```python
+contours = (
+    hsv.mask(BLUE)
+       .clean(5)
+       .find_contours()
+       .filter(lambda c: c.area > MIN_AREA)
+       .filter(lambda c: c.base_y >= MIN_Y)
+)
+
+# find_contours() lives ONLY on HSVMask.
+# hsv.find_contours() does not exist: the
+# editor won't autocomplete it, and the type
+# checker rejects it before you ever run.
+
+for c in contours:
+    cx = c.cx        # centroid, typed
+    base = c.base_y  # ground contact
+```
+
+</td>
+</tr>
+</table>
+
+Where `hsv` and `BLUE` come from:
+
+```python
+from cv4 import BGRImage, HSV, HSVRange
+
+BLUE = HSVRange(lower=HSV(100, 150, 50), upper=HSV(130, 255, 255))
+hsv = BGRImage(frame).as_hsv()  # frame: a BGR image from cv2
+```

cv4-0.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+cv4/__init__.py,sha256=vyvmbNJ-6Zbxn5LXH3B1ymObsLkanrC5Z6xNYMzGATY,430
+cv4/main.py,sha256=u2Vx_G5i0ehiV6bjaiQnWd8MxVuV6j5U8Xe3ppJX3x4,6682
+cv4/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cv4-0.0.1.dist-info/licenses/LICENSE,sha256=Tsif_IFIW5f-xYSy1KlhAy7v_oNEU4lP2cEnSQbMdE4,1086
+cv4-0.0.1.dist-info/WHEEL,sha256=1dD_GoEqEIxQ7VnrUExgdj_eExY4b4UgfR0iBlGKVac,80
+cv4-0.0.1.dist-info/METADATA,sha256=Nwm8RjyMIeZKi56HG4hybvQKwb0JdaGaHAYCLcLcyXc,2319
+cv4-0.0.1.dist-info/RECORD,,

cv4-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.4
+Root-Is-Purelib: true
+Tag: py3-none-any

cv4-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Sebastián Ramírez
+
+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.