Metadata-Version: 2.2
Name: omnicrop
Version: 1.0.3
Summary: High-performance iterative cropping engine based on C++ and DIoU.
Author: Leon
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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`。
* **效果**：算法会为分散的目标生成独立的高分辨率裁剪框。

---

## 效果展示
![alt text](assert/01_Perspective_Mix.png)
![alt text](assert/02_Sparse_Corners.png)
![alt text](assert/03_Dense_Crowd.png)
![alt text](assert/04_Edge_Boundary.png)
![alt text](assert/05_Random_Stress.png)

## 📦 安装与构建

### 1. 从源码编译
需要系统中安装了 C++ 编译器和 `pybind11`。
```bash
git clone [https://github.com/your-repo/omnicrop.git](https://github.com/your-repo/omnicrop.git)
cd omnicrop
pip install .
```

