Metadata-Version: 2.1
Name: kotoha
Version: 0.1.0b1
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: 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
```
