omnicrop 1.0.3

High-performance iterative cropping engine based on C++ and DIoU.

OmniCrop

OmniCrop 是一个基于 C++ 核心和 DIoU (Distance-IoU) 聚类算法的高性能智能图像裁剪引擎。它能够自动分析图像中多目标（如行人）的分布，通过全路径迭代优化逻辑，在保持高分辨率（像素利用率）与减少裁剪框数量之间自动寻找全局最优平衡点。

---

🚀 核心特性

• 全路径迭代 (Iterative Best Fit)：算法会遍历从“完全分散”到“完全合并”的所有演化状态，并根据评分函数自动选择最优布局。
• DIoU 聚类权重：综合考虑边界框的重叠度、中心点距离以及合并后的面积扩张率 (Expansion)，使聚类结果更符合视觉直观。
• C++ 引擎加速：核心算法逻辑由 C++ 实现，通过 pybind11 提供极低开销的 Python 接口调用。
• 广泛版本支持：原生支持 Python 3.8 - 3.13，涵盖主流操作系统（Linux, Windows, macOS）。

---

🛠️ 参数详细说明

你可以通过调整 omnicrop.Config() 中的参数来精细控制裁剪逻辑：

1. 核心评估参数 (Core Optimization)

参数名	类型	默认值	调整方向与影响
crop_count_penalty	float	50.0	最重要的平衡参数。值越大，引擎越倾向于减少 Crop 数量（强力合并）；值越小，引擎越倾向于保留独立的小框以提高分辨率。
w_diou	float	10.0	距离权重。增加此值会使物理距离接近的目标更容易被聚类到一起。
w_expansion	float	5.0	扩张惩罚。增加此值会抑制生成带有大量空白的大框，强制算法保持裁剪的紧凑性。

2. 硬约束与后处理 (Constraints & Post-processing)

参数名	类型	默认值	描述
max_crop_size	int	1280	物理上限。单个裁剪框的宽度或高度尽可能不会超过此值。
padding	int	30	在目标边缘留出的白边像素，确保目标不贴边。
nms_threshold	float	0.3	迭代完成后的最后融合阈值，用于合并重叠较大的 Crop。

3. 画面适配 (Layout)

参数名	类型	默认值	描述
enable_aspect_ratio_fix	bool	False	是否强制裁剪框符合特定的宽高比。
target_aspect_ratio	float	1.0	目标宽高比 (宽/高)。例如 1.77 代表 16:9。

---

💡 调优建议 (Tuning Guide)

场景 A：追求极致清晰度（监控/质检）

• 目标：每个目标都要尽可能大。
• 策略：
  • 将 crop_count_penalty 调低 (例如 10.0 ~ 20.0)。
  • 减小 max_crop_size。
• 效果：算法会为分散的目标生成独立的高分辨率裁剪框。

---

效果展示

📦 安装与构建

1. 从源码编译

需要系统中安装了 C++ 编译器和 pybind11。

git clone [https://github.com/your-repo/omnicrop.git](https://github.com/your-repo/omnicrop.git)
cd omnicrop
pip install .