kotoha 0.1.0a1__tar.gz

kotoha-0.1.0a1/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.1
+Name: kotoha
+Version: 0.1.0a1
+Summary: Image-processing utilities with geometry primitives, I/O helpers, visualization tools, and typed model outputs.
+Keywords: image-processing
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: opencv-python
+Requires-Dist: numpy
+Requires-Dist: pyyaml
+Requires-Dist: xmltodict
+Requires-Dist: shapely>=2.1.2
+Requires-Dist: requests
+Requires-Dist: pillow
+Requires-Dist: tqdm
+Provides-Extra: model
+Requires-Dist: onnx; extra == "model"
+Requires-Dist: onnxruntime; extra == "model"
+
+# kotoha
+
+`kotoha` is a small image-processing toolbox built around a stable set of geometry types, file helpers, visualization utilities, and typed model outputs.
+
+## What Lives Where
+
+- `kotoha`: minimal public API for stable geometry and detection result types
+- `kotoha.typing`: geometry primitives and typed detection data structures
+- `kotoha.io`: file and annotation helpers
+- `kotoha.geo`: small geometry utilities
+- `kotoha.visual`: drawing and display helpers
+- `kotoha.model`: typed model outputs and Ultralytics-style ONNX wrappers
+
+## Installation
+
+Install the core toolbox:
+
+```bash
+pip install kotoha
+```
+
+Install model-related extras as well:
+
+```bash
+pip install "kotoha[model]"
+```
+
+## Quick Examples
+
+### Geometry Types
+
+```python
+from kotoha import Point2f, Polygon, Rect
+
+rect = Rect.from_xyxy(10, 20, 30, 40)
+polygon = rect.to_polygon()
+rotated = polygon.rotate_deg(90)
+```
+
+### File Helpers
+
+```python
+from kotoha.io import read_json, save_yaml
+
+data = read_json("sample.json")
+save_yaml("sample.yaml", data)
+```
+
+### Typed Model Results
+
+```python
+from kotoha import Detection, Rect
+
+detection = Detection(
+    box=Rect.from_xyxy(10, 20, 30, 40),
+    score=0.95,
+    class_id=1,
+    label="person",
+)
+```
+
+## Public API Policy
+
+The top-level `kotoha` namespace is intentionally minimal. Import utility functions from their submodules, for example:
+
+- `from kotoha.io import imread`
+- `from kotoha.geo import rotate_points`
+- `from kotoha.visual import draw_bbox`
+
+This keeps the stable API surface small and makes module boundaries explicit.

kotoha-0.1.0a1/README.md

@@ -0,0 +1,70 @@
+# kotoha
+
+`kotoha` is a small image-processing toolbox built around a stable set of geometry types, file helpers, visualization utilities, and typed model outputs.
+
+## What Lives Where
+
+- `kotoha`: minimal public API for stable geometry and detection result types
+- `kotoha.typing`: geometry primitives and typed detection data structures
+- `kotoha.io`: file and annotation helpers
+- `kotoha.geo`: small geometry utilities
+- `kotoha.visual`: drawing and display helpers
+- `kotoha.model`: typed model outputs and Ultralytics-style ONNX wrappers
+
+## Installation
+
+Install the core toolbox:
+
+```bash
+pip install kotoha
+```
+
+Install model-related extras as well:
+
+```bash
+pip install "kotoha[model]"
+```
+
+## Quick Examples
+
+### Geometry Types
+
+```python
+from kotoha import Point2f, Polygon, Rect
+
+rect = Rect.from_xyxy(10, 20, 30, 40)
+polygon = rect.to_polygon()
+rotated = polygon.rotate_deg(90)
+```
+
+### File Helpers
+
+```python
+from kotoha.io import read_json, save_yaml
+
+data = read_json("sample.json")
+save_yaml("sample.yaml", data)
+```
+
+### Typed Model Results
+
+```python
+from kotoha import Detection, Rect
+
+detection = Detection(
+    box=Rect.from_xyxy(10, 20, 30, 40),
+    score=0.95,
+    class_id=1,
+    label="person",
+)
+```
+
+## Public API Policy
+
+The top-level `kotoha` namespace is intentionally minimal. Import utility functions from their submodules, for example:
+
+- `from kotoha.io import imread`
+- `from kotoha.geo import rotate_points`
+- `from kotoha.visual import draw_bbox`
+
+This keeps the stable API surface small and makes module boundaries explicit.

kotoha-0.1.0a1/kotoha/__init__.py

@@ -0,0 +1,33 @@
+from .typing import (
+    Affine2D,
+    Circle,
+    Detection,
+    KeyPoint,
+    Line,
+    ObbDetection,
+    Point2f,
+    PointGeometryMixin,
+    PointLike,
+    Polygon,
+    PoseDetection,
+    Rect,
+    SegmentationDetection,
+    Vector2,
+)
+
+__all__ = [
+    "Affine2D",
+    "Circle",
+    "Detection",
+    "KeyPoint",
+    "Line",
+    "ObbDetection",
+    "Point2f",
+    "PointGeometryMixin",
+    "PointLike",
+    "Polygon",
+    "PoseDetection",
+    "Rect",
+    "SegmentationDetection",
+    "Vector2",
+]

kotoha-0.1.0a1/kotoha/_geometry_types.py

@@ -0,0 +1,353 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+import math
+from dataclasses import dataclass, replace
+from typing import NamedTuple, Self, overload, override
+
+import numpy as np
+
+type PointLike = Sequence[float] | Point2f
+type Vector2 = PointLike
+
+
+class Line(NamedTuple):
+    # Line in the form ax + by + c = 0
+    a: float
+    b: float
+    c: float
+
+@dataclass(slots=True)
+class Circle:
+    x: float
+    y: float
+    radius: float
+
+
+
+class Point2f(NamedTuple):
+    x: float
+    y: float
+
+    @staticmethod
+    def transformed(
+        point: PointLike,
+        M: Sequence[Sequence[float]],
+    ) -> Point2f:
+        return Point2f(
+            M[0][0] * point[0] + M[0][1] * point[1] + M[0][2],
+            M[1][0] * point[0] + M[1][1] * point[1] + M[1][2],
+        )
+
+    def __add__(self, other):
+        if not isinstance(other, Point2f):
+            raise NotImplementedError
+        return Point2f(
+            self.x + other.x,
+            self.y + other.y,
+        )
+
+    def __sub__(self, other):
+        if not isinstance(other, Point2f):
+            raise NotImplementedError
+        return Point2f(
+            self.x - other.x,
+            self.y - other.y,
+        )
+
+    @overload
+    def __mul__(self, other: float) -> "Point2f": ...
+
+    @overload
+    def __mul__(self, other: PointLike) -> float: ...
+
+    def __mul__(self, other):
+        if isinstance(other, (int, float)):
+            return Point2f(
+                self.x * other,
+                self.y * other,
+            )
+
+        return self.x * other[0] + self.y * other[1]
+
+
+class Affine2D:
+    def __init__(self, M=None):
+        self.M = np.eye(3) if M is None else np.array(M, dtype=float)
+
+    def apply_matrix(self, M: Sequence[Sequence[float]]) -> Self:
+        self.M = self.M @ np.array(M, dtype=float)
+        return self
+
+    def translate(self, dx: float, dy: float) -> Self:
+        M = [
+            [1, 0, dx],
+            [0, 1, dy],
+            [0, 0, 1],
+        ]
+        return self.apply_matrix(M)
+
+    def scale(self, sx: float, sy: float | None = None, pivot=(0, 0)) -> Self:
+        if sy is None:
+            sy = sx
+
+        px, py = pivot
+
+        return (
+            self.translate(px, py)
+            .apply_matrix(
+                [
+                    [sx, 0, 0],
+                    [0, sy, 0],
+                    [0, 0, 1],
+                ]
+            )
+            .translate(-px, -py)
+        )
+
+    def rotate_deg(self, theta: float, pivot=(0, 0)) -> Self:
+        px, py = pivot
+        angle = math.radians(theta % 360)
+        c, s = math.cos(angle), math.sin(angle)
+
+        return (
+            self.translate(px, py)
+            .apply_matrix(
+                [
+                    [c, -s, 0],
+                    [s, c, 0],
+                    [0, 0, 1],
+                ]
+            )
+            .translate(-px, -py)
+        )
+
+    def reflect_line(self, theta: float):
+        c, s = math.cos(theta), math.sin(theta)
+
+        return self.apply_matrix(
+            [
+                [c * c - s * s, 2 * c * s, 0],
+                [2 * c * s, s * s - c * c, 0],
+                [0, 0, 1],
+            ]
+        )
+
+    def reflect_x(self) -> Self:
+        return self.apply_matrix(
+            [
+                [1, 0, 0],
+                [0, -1, 0],
+                [0, 0, 1],
+            ]
+        )
+
+    def reflect_y(self) -> Self:
+        return self.apply_matrix(
+            [
+                [-1, 0, 0],
+                [0, 1, 0],
+                [0, 0, 1],
+            ]
+        )
+
+    def shear(self, kx=0.0, ky=0.0) -> Self:
+        return self.apply_matrix(
+            [
+                [1, kx, 0],
+                [ky, 1, 0],
+                [0, 0, 1],
+            ]
+        )
+
+    def matrix(self):
+        return self.M
+
+
+class PointGeometryMixin(ABC):
+    @abstractmethod
+    def transformed(
+        self,
+        M: Sequence[Sequence[float]],
+    ) -> Self:
+        raise NotImplementedError
+
+    def translate(self, dx: float, dy: float) -> Self:
+        M = [
+            [1, 0, dx],
+            [0, 1, dy],
+            [0, 0, 1],
+        ]
+        return self.transformed(M)
+
+    def scale(
+        self, sx: float, sy: float | None = None
+    ) -> Self:
+        if sy is None:
+            sy = sx
+
+        M = [
+            [sx, 0, 0],
+            [0, sy, 0],
+            [0, 0, 1],
+        ]
+        return self.transformed(M)
+
+    def rotate_deg(
+        self,
+        theta: float,
+        pivot: PointLike = (0.0, 0.0),
+    ):
+        px, py = pivot
+
+        theta = theta % 360
+        match theta:
+            case 0:
+                c, s = 1.0, 0.0
+            case 90:
+                c, s = 0.0, 1.0
+            case 180:
+                c, s = -1.0, 0.0
+            case 270:
+                c, s = 0.0, -1.0
+            case _:
+                angle = math.radians(theta)
+                c, s = np.cos(angle), np.sin(angle)
+
+        R = np.array([[c, -s, 0], [s, c, 0], [0, 0, 1]])
+        T1 = np.array([[1, 0, -px], [0, 1, -py], [0, 0, 1]])
+        T2 = np.array([[1, 0, px], [0, 1, py], [0, 0, 1]])
+
+        M = (T2 @ R @ T1).tolist()
+        return self.transformed(M)
+
+    def reflect_x(self) -> Self:
+        M = [
+            [1, 0, 0],
+            [0, -1, 0],
+            [0, 0, 1],
+        ]
+        return self.transformed(M)
+
+    def reflect_y(self) -> Self:
+        M = [
+            [-1, 0, 0],
+            [0, 1, 0],
+            [0, 0, 1],
+        ]
+        return self.transformed(M)
+
+    def reflect(
+        self,
+        direction: PointLike,
+    ):
+        vx, vy = direction
+
+        length = math.hypot(vx, vy)
+        if length == 0:
+            raise ValueError("direction vector cannot be zero")
+
+        ux = vx / length
+        uy = vy / length
+
+        M = [
+            [2 * ux * ux - 1, 2 * ux * uy, 0],
+            [2 * ux * uy, 2 * uy * uy - 1, 0],
+            [0, 0, 1],
+        ]
+
+        return self.transformed(M)
+
+
+@dataclass(slots=True, frozen=True)
+class KeyPoint(PointGeometryMixin):
+    p: Point2f
+    score: float | None = None
+
+    @override
+    def transformed(
+        self,
+        M: Sequence[Sequence[float]],
+    ) -> Self:
+        point = Point2f.transformed(self.p, M)
+        return replace(self, p=point)
+
+    def to_list(self) -> list[float]:
+        return list(self.p)+([self.score] if self.score is not None else [])
+    
+    def to_dict(self) -> dict:
+        return {"p": list(self.p), "score": self.score}
+
+
+@dataclass(slots=True, frozen=True)
+class Rect(PointGeometryMixin):
+    pmin: Point2f
+    pmax: Point2f
+
+    @classmethod
+    def from_xyxy(
+        cls,
+        xmin: float,
+        ymin: float,
+        xmax: float,
+        ymax: float,
+    ) -> Rect:
+        return cls(
+            Point2f(xmin, ymin),
+            Point2f(xmax, ymax),
+        )
+
+    def to_list(self) -> list[float]:
+        return list(self.pmin) + list(self.pmax)
+ 
+    def to_dict(self) -> dict:
+        return {"pmin": list(self.pmin), "pmax": list(self.pmax)}
+
+    def to_polygon(self) -> Polygon:
+        return Polygon(
+            [
+                self.pmin,
+                Point2f(self.pmax.x, self.pmin.y),
+                self.pmax,
+                Point2f(self.pmin.x, self.pmax.y),
+            ]
+        )
+
+    @override
+    def transformed(
+        self,
+        M: Sequence[Sequence[float]],
+    ) -> Self:
+        rect = self.to_polygon().transformed(M).to_rect()
+        return self.__class__(rect.pmin, rect.pmax)
+
+
+@dataclass(slots=True, frozen=True)
+class Polygon(PointGeometryMixin):
+    vertices: list[Point2f]
+
+    @override
+    def transformed(
+        self,
+        M: Sequence[Sequence[float]],
+    ) -> Self:
+        vertices: list[Point2f] = []
+        for vertex in self.vertices:
+            vertices.append(Point2f.transformed(vertex, M))
+
+        return replace(self, vertices=vertices)
+
+    def to_rect(self) -> Rect:
+        xs = [vertex.x for vertex in self.vertices]
+        ys = [vertex.y for vertex in self.vertices]
+        return Rect.from_xyxy(min(xs), min(ys), max(xs), max(ys))
+
+    def __iter__(self):
+        yield from self.vertices
+
+    def to_list(self) -> list[list[float]]:
+        return [list(v) for v in self.vertices]
+
+    def to_dict(self) -> dict:
+        return {"vertices": self.to_list()}