MiniToolkit 0.1.5

常用功能模块快速使用库.

MiniToolkit

一个实用的 Python 工具库，提供计算机视觉数据处理、标注格式转换和图像处理常用功能。

安装

pip install minitoolkit

或从源码以可编辑模式安装：

pip install -e .

需要 Python >= 3.10。

功能模块

图像加载与保存

便捷的 PIL 与 OpenCV 互转，支持 EXIF 自动修正和多格式保存。

from MiniToolkit.tools.image import just_load_image, just_save_image

# 以 BGR numpy 数组格式加载（OpenCV 格式）
img = just_load_image("photo.jpg")

# 保存图像
just_save_image(img, "output.png", save_format="PNG")

高级加载方式，支持 float 归一化或强制 RGB 模式：

from MiniToolkit.tools.image import load_image

img = load_image("photo.jpg", force_float=True, force_rgb=True)

滑窗裁剪

将大图切分为重叠的滑窗切片，适用于批量推理场景：

from MiniToolkit.tools.image import load_images_by_window

cropped_images, windows = load_images_by_window("large.jpg", window_size=1024)

掩码与多边形工具

支持二值掩码与多边形轮廓互转、边界框计算、IoU / iOS 指标计算。

from MiniToolkit.tools.mask import (
    polygon_to_mask, mask_to_polygons, mask_to_polygon,
    polygon_to_box,
    calculate_iou_by_mask, calculate_ios_by_mask,
    calculate_iou_by_box, calculate_iou_by_boxes,
)

# 多边形转二值掩码
mask = polygon_to_mask(polygon, height=480, width=640)

# 二值掩码转多边形列表（带面积过滤）
polygons = mask_to_polygons(mask, area_threshold=4000)

# 从掩码提取最大连通域多边形
polygon = mask_to_polygon(mask, strategy="largest")

# 计算两个掩码的 IoU
iou = calculate_iou_by_mask(mask_a, mask_b)

# 批量计算 N x M 组边界框的 IoU 矩阵
iou_matrix = calculate_iou_by_boxes(boxes1, boxes2)

标签格式转换

解析、转换并导出 LabelMe 格式的 JSON 标注文件。

from MiniToolkit.tools.label import (
    just_load_label, convert_label_to_instances,
    convert_instances_to_label, get_mask_from_label,
    get_polygons_from_label, save_label_to_json,
)

# 加载 LabelMe JSON 文件
label = just_load_label("annotation.json")

# 转换为结构化实例列表
instances = convert_label_to_instances(label, classes_name_to_id={"defect": 0})

# 将实例列表转回 LabelMe JSON
new_label = convert_instances_to_label(
    instances, classes_id_to_name={0: "defect"},
    image_name="photo.jpg", image_height=480, image_width=640,
)
save_label_to_json(new_label, "output.json")

# 从标注文件提取 one-hot 掩码
mask = get_mask_from_label(label_path, label_to_id={"defect": 0}, image_height=480, image_width=640)

实例可视化

在图像上绘制边界框、多边形以及类别/状态标签。

from MiniToolkit.tools.image import visualize_instances_on_image

result = visualize_instances_on_image(
    "photo.jpg",
    instances,
    class_mapper={0: "wanglei", 1: "molei"},
    state_mapper={0: "normal", 1: "defect"},
    show_filter=["class", "state", "box", "polygon"],
    title="Detection Result",
)
just_save_image(result, "visualized.jpg")

多线程进度条

基于 tqdm 的线程安全进度条，适合并发任务场景。

from MiniToolkit.tools.bar import Bar

bar = Bar(total_num=len(paths), desc="Processing", color="#CD8500")
bar(process_func, [(p,) for p in paths])

文件系统辅助

按后缀名递归查找、复制、移动、链接文件。

from MiniToolkit.tools.path import (
    find_files_in_dir, find_images_in_dir, find_labels_in_dir,
    find_label_path_from_image, copy_file,
)

# 递归查找所有图片
images = find_images_in_dir("./data", recurrence=True)

# 根据图片查找对应的标注文件
label_path = find_label_path_from_image("photo.jpg")

检测指标封装

将模型评估输出（AP、mAP、precision、recall）按类别封装，便于调用。

from MiniToolkit.tools.metric import Metric

m = Metric(metrics_dict)
print(m.map, m.map50, m.maps)  # mAP、mAP@50、各类别 mAP

标注转换脚本

• convert/labelme2coco.py — 将 LabelMe JSON 标注转换为 COCO 格式。
• convert/caculate_instances.py — 统计目录下各实例出现次数并导出为 Excel 表格。

项目结构

MiniToolkit/
├── tools/              # 可复用的工具模块
│   ├── image.py        # 图像加载/保存、滑窗裁剪、可视化
│   ├── mask.py         # 多边形与掩码互转、IoU/iOS
│   ├── label.py        # LabelMe JSON 解析与转换
│   ├── bar.py          # 多线程进度条
│   ├── metric.py       # 检测指标封装
│   └── path.py         # 文件系统辅助
└── convert/            # 独立转换脚本()
    ├── labelme2coco.py
    └── caculate_instances.py

依赖

• pillow >= 8.1.0 — 图像读写
• opencv-python >= 4.3.0 — 计算机视觉基础操作
• numpy — 数值计算
• tqdm — 进度条
• pandas — 实例统计脚本使用（可选）

开发说明

以可编辑模式安装并做快速冒烟测试：

pip install -e .
python -c "from MiniToolkit.tools.image import just_load_image; print('ok')"

构建分发包：

python -m build