kotoha 0.1.0__tar.gz

kotoha-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: kotoha
+Version: 0.1.0
+Summary: Image-processing utilities with geometry primitives, I/O helpers, visualization tools, and typed model outputs.
+Keywords: image-processing
+Classifier: Development Status :: 5 - Production/Stable
+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: requests
+Requires-Dist: pillow
+Requires-Dist: tqdm
+Requires-Dist: matplotlib
+Provides-Extra: model
+Requires-Dist: onnx; extra == "model"
+Requires-Dist: onnxruntime; extra == "model"
+
+# kotoha
+
+`kotoha` 是一个面向计算机视觉工程的 Python 工具箱。它把几何数据、算法结果、文件读写和可视化能力收拢为一套轻量且类型明确的接口，让传统视觉、人工标注和模型推理可以使用相同的数据结构协作。
+
+## 特性
+
+- 不可变的二维几何类型：点、关键点、矩形、四边形、多边形、直线、圆和仿射变换。
+- 统一的视觉任务结果：分类、检测、实例分割、姿态、旋转框和语义分割。
+- 常用几何计算：面积、点线关系、线段相交、点在多边形内、旋转等。
+- 面向工程的文件和图像工具：JSON、YAML、CSV、TXT、Pickle、XML、YOLO 标注及 Unicode 路径图像读写。
+- OpenCV 绘制与视频读取工具。
+- 可选的 ONNX YOLO 推理适配，包括检测、分割、姿态、分类和旋转框任务。
+
+## 安装
+
+需要 Python 3.12 或更高版本。
+
+安装核心功能：
+
+```bash
+pip install kotoha
+```
+
+如需使用 ONNX 模型适配，安装 `model` 扩展：
+
+```bash
+pip install "kotoha[model]"
+```
+
+从源码开发时，推荐使用 `uv`：
+
+```bash
+uv sync --all-extras --dev
+```
+
+## 快速开始
+
+### 用几何类型表达和变换区域
+
+`Rect`、`Polygon` 和 `KeyPoint` 都支持平移、缩放、旋转和镜像变换。坐标以 `(x, y)` 表示；`rotate_deg` 的角度单位为度。
+
+```python
+from kotoha import Rect
+
+box = Rect.from_xyxy(10, 20, 110, 80)
+polygon = box.to_polygon()
+
+rotated = polygon.rotate_deg(30, pivot=(60, 50))
+print(rotated.to_list())
+```
+
+### 使用统一的检测结果
+
+模型输出、传统算法结果和人工标注都可以使用相同的标注对象。每种对象均提供 `to_dict()`，检测类结果还提供适合导出的 `to_numpy()`。
+
+```python
+from kotoha import Detection, Rect
+
+detection = Detection(
+    box=Rect.from_xyxy(10, 20, 110, 180),
+    score=0.95,
+    class_id=0,
+    label="person",
+)
+
+print(detection.to_dict())
+# {'box': {'pmin': [10, 20], 'pmax': [110, 180]}, ...}
+```
+
+可用的结果类型如下：
+
+| 类型 | 用途 |
+| --- | --- |
+| `Classification` | 图像分类的类别与置信度 |
+| `Detection` | 轴对齐目标框 |
+| `SegmentationDetection` | 目标框、二值掩码与可选轮廓 |
+| `PoseDetection` | 目标框与关键点 |
+| `ObbDetection` | 由四个顶点表示的旋转框 |
+| `SemanticSegmentation` | 整张图的语义类别图 |
+
+### 读写图像并绘制结果
+
+`imread` 和 `imwrite` 支持包含中文等非 ASCII 字符的本地路径。`draw_bbox` 会直接在传入图像上绘制并返回该图像。
+
+```python
+from kotoha.visual import draw_bbox, imread, imwrite
+
+image = imread("input.jpg")
+if image is None:
+    raise RuntimeError("无法读取 input.jpg")
+
+draw_bbox(
+    image,
+    box=[10, 20, 110, 180],
+    score=0.95,
+    obj_id="person",
+)
+imwrite("result.jpg", image)
+```
+
+### 运行 YOLO ONNX 检测
+
+安装 `model` 扩展后，传入已导出的 ONNX 模型文件即可推理。模型适配器接收 BGR 图像，返回标准的 `Detection` 对象。
+
+```python
+from kotoha.model.ultralytics import YOLOv8
+from kotoha.visual import imread, imwrite
+
+model = YOLOv8("yolov8n.onnx")
+image = imread("input.jpg")
+if image is None:
+    raise RuntimeError("无法读取 input.jpg")
+
+detections = model.detect(image, conf_thres=0.4)
+rendered = model.draw_bbox(image, detections)
+imwrite("result.jpg", rendered)
+```
+
+可用的适配器包括 `YOLOv5`、`YOLOv8`、`YOLOv8Cls`、`YOLOv8Seg`、`YOLOv8Pose`、`YOLOv8Obb` 和 `YOLO26Sem`。不同模型需要与对应任务和导出格式匹配的 ONNX 文件。
+
+## 模块一览
+
+| 模块 | 内容 |
+| --- | --- |
+| `kotoha` / `kotoha.typing` | 稳定的核心几何类型与标注类型 |
+| `kotoha.annotation` | 分类、检测、分割、姿态、旋转框等任务结果 |
+| `kotoha.geo` | 几何算法，如面积、相交判断和点集旋转 |
+| `kotoha.io` | 通用文件、标注文件的读写与文件枚举 |
+| `kotoha.visual` | 图像读写、框/关键点/掩码绘制和 `VideoReader` |
+| `kotoha.model.ultralytics` | ONNX YOLO 系列模型适配器 |
+| `kotoha.eval` | 分类、检测、姿态、重识别和文本任务的评估工具 |
+
+顶层 `kotoha` 命名空间只导出稳定的值类型和标注类型；工具函数请从对应子模块导入：
+
+```python
+from kotoha.geo import polygon_area, rotate_points
+from kotoha.io import read_json, save_yaml
+from kotoha.visual import draw_bbox, imread
+```
+
+## 开发与验证
+
+安装开发依赖后运行测试：
+
+```bash
+uv run pytest
+```
+
+代码质量检查可使用：
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## 兼容性说明
+
+标注结果类型已统一移动到 `kotoha.annotation`。旧的模型或几何命名空间导入方式不再支持：
+
+```python
+# 旧写法（不再支持）
+from kotoha.model.typing import Detection
+from kotoha.typing import PoseDetection
+
+# 新写法
+from kotoha.annotation import Detection, PoseDetection
+```
+
+为了兼容简洁用法，结果类型仍可从顶层导入：
+
+```python
+from kotoha import Detection, PoseDetection
+```

kotoha-0.1.0/README.md

@@ -0,0 +1,173 @@
+# kotoha
+
+`kotoha` 是一个面向计算机视觉工程的 Python 工具箱。它把几何数据、算法结果、文件读写和可视化能力收拢为一套轻量且类型明确的接口，让传统视觉、人工标注和模型推理可以使用相同的数据结构协作。
+
+## 特性
+
+- 不可变的二维几何类型：点、关键点、矩形、四边形、多边形、直线、圆和仿射变换。
+- 统一的视觉任务结果：分类、检测、实例分割、姿态、旋转框和语义分割。
+- 常用几何计算：面积、点线关系、线段相交、点在多边形内、旋转等。
+- 面向工程的文件和图像工具：JSON、YAML、CSV、TXT、Pickle、XML、YOLO 标注及 Unicode 路径图像读写。
+- OpenCV 绘制与视频读取工具。
+- 可选的 ONNX YOLO 推理适配，包括检测、分割、姿态、分类和旋转框任务。
+
+## 安装
+
+需要 Python 3.12 或更高版本。
+
+安装核心功能：
+
+```bash
+pip install kotoha
+```
+
+如需使用 ONNX 模型适配，安装 `model` 扩展：
+
+```bash
+pip install "kotoha[model]"
+```
+
+从源码开发时，推荐使用 `uv`：
+
+```bash
+uv sync --all-extras --dev
+```
+
+## 快速开始
+
+### 用几何类型表达和变换区域
+
+`Rect`、`Polygon` 和 `KeyPoint` 都支持平移、缩放、旋转和镜像变换。坐标以 `(x, y)` 表示；`rotate_deg` 的角度单位为度。
+
+```python
+from kotoha import Rect
+
+box = Rect.from_xyxy(10, 20, 110, 80)
+polygon = box.to_polygon()
+
+rotated = polygon.rotate_deg(30, pivot=(60, 50))
+print(rotated.to_list())
+```
+
+### 使用统一的检测结果
+
+模型输出、传统算法结果和人工标注都可以使用相同的标注对象。每种对象均提供 `to_dict()`，检测类结果还提供适合导出的 `to_numpy()`。
+
+```python
+from kotoha import Detection, Rect
+
+detection = Detection(
+    box=Rect.from_xyxy(10, 20, 110, 180),
+    score=0.95,
+    class_id=0,
+    label="person",
+)
+
+print(detection.to_dict())
+# {'box': {'pmin': [10, 20], 'pmax': [110, 180]}, ...}
+```
+
+可用的结果类型如下：
+
+| 类型 | 用途 |
+| --- | --- |
+| `Classification` | 图像分类的类别与置信度 |
+| `Detection` | 轴对齐目标框 |
+| `SegmentationDetection` | 目标框、二值掩码与可选轮廓 |
+| `PoseDetection` | 目标框与关键点 |
+| `ObbDetection` | 由四个顶点表示的旋转框 |
+| `SemanticSegmentation` | 整张图的语义类别图 |
+
+### 读写图像并绘制结果
+
+`imread` 和 `imwrite` 支持包含中文等非 ASCII 字符的本地路径。`draw_bbox` 会直接在传入图像上绘制并返回该图像。
+
+```python
+from kotoha.visual import draw_bbox, imread, imwrite
+
+image = imread("input.jpg")
+if image is None:
+    raise RuntimeError("无法读取 input.jpg")
+
+draw_bbox(
+    image,
+    box=[10, 20, 110, 180],
+    score=0.95,
+    obj_id="person",
+)
+imwrite("result.jpg", image)
+```
+
+### 运行 YOLO ONNX 检测
+
+安装 `model` 扩展后，传入已导出的 ONNX 模型文件即可推理。模型适配器接收 BGR 图像，返回标准的 `Detection` 对象。
+
+```python
+from kotoha.model.ultralytics import YOLOv8
+from kotoha.visual import imread, imwrite
+
+model = YOLOv8("yolov8n.onnx")
+image = imread("input.jpg")
+if image is None:
+    raise RuntimeError("无法读取 input.jpg")
+
+detections = model.detect(image, conf_thres=0.4)
+rendered = model.draw_bbox(image, detections)
+imwrite("result.jpg", rendered)
+```
+
+可用的适配器包括 `YOLOv5`、`YOLOv8`、`YOLOv8Cls`、`YOLOv8Seg`、`YOLOv8Pose`、`YOLOv8Obb` 和 `YOLO26Sem`。不同模型需要与对应任务和导出格式匹配的 ONNX 文件。
+
+## 模块一览
+
+| 模块 | 内容 |
+| --- | --- |
+| `kotoha` / `kotoha.typing` | 稳定的核心几何类型与标注类型 |
+| `kotoha.annotation` | 分类、检测、分割、姿态、旋转框等任务结果 |
+| `kotoha.geo` | 几何算法，如面积、相交判断和点集旋转 |
+| `kotoha.io` | 通用文件、标注文件的读写与文件枚举 |
+| `kotoha.visual` | 图像读写、框/关键点/掩码绘制和 `VideoReader` |
+| `kotoha.model.ultralytics` | ONNX YOLO 系列模型适配器 |
+| `kotoha.eval` | 分类、检测、姿态、重识别和文本任务的评估工具 |
+
+顶层 `kotoha` 命名空间只导出稳定的值类型和标注类型；工具函数请从对应子模块导入：
+
+```python
+from kotoha.geo import polygon_area, rotate_points
+from kotoha.io import read_json, save_yaml
+from kotoha.visual import draw_bbox, imread
+```
+
+## 开发与验证
+
+安装开发依赖后运行测试：
+
+```bash
+uv run pytest
+```
+
+代码质量检查可使用：
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## 兼容性说明
+
+标注结果类型已统一移动到 `kotoha.annotation`。旧的模型或几何命名空间导入方式不再支持：
+
+```python
+# 旧写法（不再支持）
+from kotoha.model.typing import Detection
+from kotoha.typing import PoseDetection
+
+# 新写法
+from kotoha.annotation import Detection, PoseDetection
+```
+
+为了兼容简洁用法，结果类型仍可从顶层导入：
+
+```python
+from kotoha import Detection, PoseDetection
+```

kotoha-0.1.0/kotoha/__init__.py

@@ -0,0 +1,163 @@
+from .annotation import (
+    Classification,
+    Detection,
+    ObbDetection,
+    PoseDetection,
+    SegmentationDetection,
+    SemanticSegmentation,
+)
+from .common import (
+    FuzzyMatchingSet,
+    is_url,
+    is_valid_image,
+    parallel_process,
+    scale_bbox_xyxy,
+    url_to_image,
+)
+from .dataset_info import CocoConfig
+from .eval import (
+    average_precision,
+    bleu,
+    confusion,
+    edit_distance,
+    evaluate_detection,
+    evaluate_reid_market1501,
+    evaluate_reid_roc,
+    f1_score,
+    match_detections,
+    mean_average_precision,
+    pairwise_box_iou,
+    pck_accuracy,
+    rouge,
+    safe_divide,
+    topk_accuracy,
+)
+from .geo import (
+    circle_from_three_points,
+    fit_line,
+    intersect_lines,
+    is_point_in_polygon,
+    is_point_on_segment,
+    polygon_area,
+    rotate_points,
+    segment_intersection,
+)
+from .image_filter import ImageFilter
+from .io import (
+    list_files,
+    read_csv,
+    read_json,
+    read_pkl,
+    read_txt,
+    read_xml,
+    read_yaml,
+    read_yolo_txt,
+    save_csv,
+    save_json,
+    save_pkl,
+    save_txt,
+    save_xml,
+    save_yaml,
+    save_yolo_txt,
+)
+from .typing import (
+    Affine2D,
+    Circle,
+    KeyPoint,
+    Line,
+    Point2f,
+    PointGeometryMixin,
+    PointLike,
+    PointSet,
+    Polygon,
+    PolygonLike,
+    Rect,
+    Vector2,
+)
+from .visual import (
+    VideoReader,
+    draw_bbox,
+    draw_keypoints,
+    draw_masks,
+    generate_distinct_colors,
+    get_color,
+    imread,
+    imwrite,
+)
+
+__all__ = [
+    "Affine2D",
+    "Circle",
+    "Classification",
+    "CocoConfig",
+    "Detection",
+    "FuzzyMatchingSet",
+    "ImageFilter",
+    "KeyPoint",
+    "Line",
+    "ObbDetection",
+    "Point2f",
+    "PointGeometryMixin",
+    "PointLike",
+    "PointSet",
+    "Polygon",
+    "PolygonLike",
+    "PoseDetection",
+    "Rect",
+    "SegmentationDetection",
+    "SemanticSegmentation",
+    "Vector2",
+    "VideoReader",
+    "average_precision",
+    "bleu",
+    "circle_from_three_points",
+    "confusion",
+    "draw_bbox",
+    "draw_keypoints",
+    "draw_masks",
+    "edit_distance",
+    "evaluate_detection",
+    "evaluate_reid_market1501",
+    "evaluate_reid_roc",
+    "f1_score",
+    "fit_line",
+    "generate_distinct_colors",
+    "get_color",
+    "imread",
+    "imwrite",
+    "intersect_lines",
+    "is_point_in_polygon",
+    "is_point_on_segment",
+    "is_url",
+    "is_valid_image",
+    "list_files",
+    "match_detections",
+    "mean_average_precision",
+    "pairwise_box_iou",
+    "parallel_process",
+    "pck_accuracy",
+    "polygon_area",
+    "read_csv",
+    "read_json",
+    "read_pkl",
+    "read_txt",
+    "read_xml",
+    "read_yaml",
+    "read_yolo_txt",
+    "rotate_points",
+    "rouge",
+    "safe_divide",
+    "save_csv",
+    "save_json",
+    "save_pkl",
+    "save_txt",
+    "save_xml",
+    "save_yaml",
+    "save_yolo_txt",
+    "scale_bbox_xyxy",
+    "segment_intersection",
+    "topk_accuracy",
+    "url_to_image",
+]
+
+__version__ = "0.1.0"

kotoha-0.1.0/kotoha/annotation.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+import numpy as np
+
+from kotoha.geo._types import KeyPoint, Polygon, Rect
+
+__all__ = [
+    "Classification",
+    "Detection",
+    "ObbDetection",
+    "PoseDetection",
+    "SegmentationDetection",
+    "SemanticSegmentation",
+]
+
+
+@dataclass(slots=True)
+class Classification:
+    """One ranked category prediction for an image."""
+
+    score: float
+    class_id: int
+    label: str | None = None
+
+    def to_numpy(self) -> np.ndarray:
+        return np.array([self.score, self.class_id], dtype=np.float32)
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class SemanticSegmentation:
+    """Dense semantic class map for one image."""
+
+    mask: np.ndarray
+
+    def to_numpy(self) -> np.ndarray:
+        return self.mask
+
+    def to_dict(self) -> dict[str, object]:
+        return {"mask": self.mask.tolist()}
+
+
+@dataclass(slots=True)
+class Detection:
+    box: Rect
+    score: float
+    class_id: int
+    label: str | None = None
+
+    def to_numpy(self) -> np.ndarray:
+        return np.array(
+            [*self.box.to_list(), self.score, self.class_id],
+            dtype=np.float32,
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        data = asdict(self)
+        data["box"] = self.box.to_dict()
+        return data
+
+
+@dataclass(slots=True)
+class SegmentationDetection:
+    box: Rect
+    score: float
+    class_id: int
+    mask: np.ndarray
+    polygon: Polygon | None = None
+    label: str | None = None
+
+    def to_numpy(self) -> np.ndarray:
+        return np.array(
+            [*self.box.to_list(), self.score, self.class_id],
+            dtype=np.float32,
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        data = asdict(self)
+        data["box"] = self.box.to_dict()
+        data["mask"] = self.mask.tolist()
+        if self.polygon is not None:
+            data["polygon"] = self.polygon.to_dict()
+        return data
+
+
+@dataclass(slots=True)
+class PoseDetection:
+    box: Rect
+    score: float
+    class_id: int
+    keypoints: list[KeyPoint]
+    label: str | None = None
+
+    def to_numpy(self) -> np.ndarray:
+        values: list[float] = [*self.box.to_list(), self.score, float(self.class_id)]
+        for keypoint in self.keypoints:
+            values.extend([keypoint.p.x, keypoint.p.y, keypoint.score or 0.0])
+        return np.array(values, dtype=np.float32)
+
+    def to_dict(self) -> dict[str, object]:
+        data = asdict(self)
+        data["keypoints"] = [keypoint.to_dict() for keypoint in self.keypoints]
+        data["box"] = self.box.to_dict()
+        return data
+
+
+@dataclass(slots=True)
+class ObbDetection:
+    quad: Polygon
+    score: float
+    class_id: int
+    label: str | None = None
+
+    def to_numpy(self) -> np.ndarray:
+        values = [coord for point in self.quad.vertices for coord in (point.x, point.y)]
+        values.extend([self.score, float(self.class_id)])
+        return np.array(values, dtype=np.float32)
+
+    def to_dict(self) -> dict[str, object]:
+        data = asdict(self)
+        data["quad"] = self.quad.to_dict()
+        return data