kotoha 0.1.0b2

Image-processing utilities with geometry primitives, I/O helpers, visualization tools, and typed model outputs.

kotoha

kotoha 是一个面向计算机视觉工程的 Python 工具箱。它把几何数据、算法结果、文件读写和可视化能力收拢为一套轻量且类型明确的接口，让传统视觉、人工标注和模型推理可以使用相同的数据结构协作。

特性

• 不可变的二维几何类型：点、关键点、矩形、四边形、多边形、直线、圆和仿射变换。
• 统一的视觉任务结果：分类、检测、实例分割、姿态、旋转框和语义分割。
• 常用几何计算：面积、点线关系、线段相交、点在多边形内、旋转等。
• 面向工程的文件和图像工具：JSON、YAML、CSV、TXT、Pickle、XML、YOLO 标注及 Unicode 路径图像读写。
• OpenCV 绘制与视频读取工具。
• 可选的 ONNX YOLO 推理适配，包括检测、分割、姿态、分类和旋转框任务。

安装

需要 Python 3.12 或更高版本。

安装核心功能：

pip install kotoha

如需使用 ONNX 模型适配，安装 model 扩展：

pip install "kotoha[model]"

从源码开发时，推荐使用 uv：

uv sync --all-extras --dev

快速开始

用几何类型表达和变换区域

Rect、Polygon 和 KeyPoint 都支持平移、缩放、旋转和镜像变换。坐标以 (x, y) 表示；rotate_deg 的角度单位为度。

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()。

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 会直接在传入图像上绘制并返回该图像。

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 对象。

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 命名空间只导出稳定的值类型和标注类型；工具函数请从对应子模块导入：

from kotoha.geo import polygon_area, rotate_points
from kotoha.io import read_json, save_yaml
from kotoha.visual import draw_bbox, imread

开发与验证

安装开发依赖后运行测试：

uv run pytest

代码质量检查可使用：

uv run ruff check .
uv run ruff format --check .

兼容性说明

标注结果类型已统一移动到 kotoha.annotation。旧的模型或几何命名空间导入方式不再支持：

# 旧写法（不再支持）
from kotoha.model.typing import Detection
from kotoha.typing import PoseDetection

# 新写法
from kotoha.annotation import Detection, PoseDetection

为了兼容简洁用法，结果类型仍可从顶层导入：

from kotoha import Detection, PoseDetection