Metadata-Version: 2.4
Name: kotoha
Version: 0.2.2
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: scipy
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())
```

使用带离群点的关键点对估计仿射变换：

```python
from kotoha import Affine2D

affine = Affine2D.from_points(
    source_points,
    target_points,
    ransac_reproj_threshold=2.0,
)
aligned_points = affine.transform_points(source_points)
```

默认估计器是 RANSAC；也可以选择 `method="lmeds"` 或在确认没有离群点时使用
`method="least_squares"`。完整示例见 `examples/affine2d_ransac.py`。

### 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.experiments.geo3d` | 基础三维测量、点云清洗、局部配准、已标定投影与评估 |
| `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.experiments.geo3d import calibration, measure3d, metrics3d, pointcloud, reconstruction, registration, stereo
from kotoha.io import read_json, save_yaml
from kotoha.visual import draw_bbox, imread
```

三维工具统一放在 `kotoha.experiments.geo3d` 下，按上述路径导入。
保留平面/圆/球拟合、AABB/PCA 包围盒、体素降采样、离群点过滤、分批法线估计、
Kabsch/局部 ICP、点云指标、相机射线与世界平面求交，以及已校正双目的反投影。
相机标定、位姿估计和双目校正使用 OpenCV；本库不提供全局配准、稠密视差求解或教学重建算法。

视差转深度统一使用 `stereo.depth_from_disparity(disparity, focal, baseline)`，
必须显式提供像素焦距与基线；非有限或不大于 `1e-6` 的视差返回 `NaN`。
反投影假定校正后的两相机主点一致且 `fx=fy`，深度与基线同单位；
单点和稀疏转换保留无效点为 `NaN`，稠密点云输出省略无效点。
已知单应矩阵的平面映射使用 `Projective2D.transform_points`。
ICP 需要合适初值，PCA 包围盒不保证最小体积，最小二乘拟合前应清理离群点。

缺陷生成工具通过 `from kotoha.experiments import defects` 使用，
可视化示例见 `examples/defects_visualization.py`。

## 开发与验证

运行测试：

```bash
uv run pytest
```

运行代码检查：

```bash
uv run ruff check .
uv run ruff format --check .
```

## License

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