Metadata-Version: 2.4
Name: kotoha
Version: 0.1.4
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: tqdm
Provides-Extra: model
Requires-Dist: onnx; extra == "model"
Requires-Dist: onnxruntime; extra == "model"

# kotoha

`kotoha` 是一个面向计算机视觉工程的 Python 工具库，提供统一的几何类型、标注结果类型、文件读写、图像可视化和评估工具。它适合用在数据处理脚本、标注转换、模型推理后处理，以及日常的视觉算法开发中。

## 核心能力

- 统一的二维几何类型：`Rect`、`Polygon`、`KeyPoint`、`Line`、`Circle`、`Affine2D`
- 统一的视觉任务结果：`Classification`、`Detection`、`SegmentationDetection`、`PoseDetection`、`ObbDetection`、`SemanticSegmentation`
- 常用几何计算：面积、旋转、点与线段关系、线段相交、点在多边形内
- 工程向 I/O 工具：`JSON`、`YAML`、`CSV`、`TXT`、`Pickle`、`XML`、YOLO 标注读写
- OpenCV 图像与视频工具：`imread`、`imwrite`、`draw_bbox`、`draw_keypoints`、`draw_masks`、`VideoReader`
- 评估能力：分类、检测、姿态、重识别和文本任务的常用指标
- 可选的 ONNX 模型适配：内置 Ultralytics YOLO 系列推理封装

## 安装

需要 `Python 3.12` 或更高版本。

安装基础功能：

```bash
pip install kotoha
```

安装 ONNX 模型相关功能：

```bash
pip install "kotoha[model]"
```

如果你在本地参与开发，可以安装完整依赖：

```bash
uv sync --all-extras --dev
```

## 快速开始

### 1. 使用几何类型描述区域

```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(box.to_list())
print(rotated.to_list())
```

### 2. 使用统一的检测结果结构

```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())
print(detection.to_numpy())
```

### 3. 读取图像并绘制检测框

```python
from kotoha import draw_bbox, imread, imwrite

image = imread("input.jpg")
if image is None:
    raise RuntimeError("failed to read input.jpg")

draw_bbox(
    image,
    box=[10, 20, 110, 180],
    score=0.95,
    obj_id="person",
)
imwrite("result.jpg", image)
```

### 4. 读写标注和配置文件

```python
from kotoha import read_json, read_yaml, save_json

dataset = read_json("annotations.json")
config = read_yaml("config.yaml")

save_json("preview.json", dataset)
print(type(config))
```

### 5. 运行 YOLO ONNX 推理

安装 `model` 扩展后，可以直接加载导出的 ONNX 模型：

```python
from kotoha.model.ultralytics import YOLOv8
from kotoha import imread, imwrite

model = YOLOv8("yolov8n.onnx")
image = imread("input.jpg")
if image is None:
    raise RuntimeError("failed to read 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`

## 常用模块

| 模块 | 说明 |
| --- | --- |
| `kotoha` | 顶层导出，适合直接导入常用类型和工具函数 |
| `kotoha.annotation` | 分类、检测、分割、姿态、旋转框等结果类型 |
| `kotoha.geo` | 几何计算、坐标变换、栅格和多边形处理 |
| `kotoha.io` | 文件读写、标注格式转换、文件枚举 |
| `kotoha.visual` | 图像读写、结果绘制、颜色工具、视频读取 |
| `kotoha.eval` | 分类、检测、姿态、重识别、文本评估指标 |
| `kotoha.model.ultralytics` | YOLO ONNX 推理适配 |
| `kotoha.image_filter` | 感知哈希与图像去重过滤 |
| `kotoha.experiments` | 一些实验性或任务型工具 |

## 顶层导入示例

顶层 `kotoha` 已经导出了大部分常用接口，适合在业务脚本中直接使用：

```python
from kotoha import Detection, Rect, draw_bbox, imread, polygon_area, read_json
```

如果你希望按功能拆分导入，也可以使用对应子模块：

```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 .
```

## License

项目许可证见 `license` 文件。
