Metadata-Version: 2.4
Name: images-dedup
Version: 0.1.0
Summary: 基于感知哈希（imagehash）的图像去重工具，支持本地路径/URL/base64 输入
Author: images-dedup contributors
License: MIT
Project-URL: Homepage, https://github.com/example/images-dedup
Project-URL: Repository, https://github.com/example/images-dedup
Keywords: image,deduplication,perceptual-hash,imagehash
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: imagehash>=4.3
Requires-Dist: Pillow>=9.0
Requires-Dist: numpy>=1.21
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: matplotlib>=3.5; extra == "dev"

# images-dedup

基于感知哈希（[imagehash](https://github.com/JohannesBuchner/imagehash)）的图像去重工具。支持三种输入方式：本地路径、URL、base64，使用归一化相似度阈值，直觉友好。

## 安装

```bash
pip install images-dedup
```

## 快速开始

```python
from images_dedup import dedup_images

images = [
    "photo1.jpg",
    "https://example.com/photo2.png",
    "data:image/png;base64,iVBORw0KGgo...",
]

result = dedup_images(images, threshold=0.97)

print(f"{result.original_count} 张 → 去重后 {result.unique_count} 张 "
      f"(移除 {result.removed_count}, {result.reduction_rate:.1%})")

for item in result.unique_images:
    print(item.index, item.source[:60], item.hash_hex)

# 重复关系: {保留索引: [被移除的索引列表]}
print(result.duplicates)
```

## 阈值说明

`threshold` 取值范围 0~1，表示两张图像相似度超过此值即视为重复。

| threshold | 含义（phash, hash_size=8） |
|:---------:|----------------------------|
| 1.00 | 只去完全相同的图像 |
| 0.97 | 相似度 ≥ 98.4% 视为重复 |
| 0.95 | 相似度 ≥ 95.3% 视为重复（默认） |
| 0.90 | 相似度 ≥ 90.6% 视为重复 |
| 0.80 | 相似度 ≥ 81.2% 视为重复 |

## API

```python
dedup_images(
    images,                  # List[str] — 路径 / URL / base64
    threshold=0.95,          # float — 归一化相似度阈值
    hash_method="phash",     # phash | ahash | dhash | whash | colorhash
    hash_size=8,             # int — 哈希尺寸
    max_workers=8,           # int — 并发数
    retries=1,               # int — URL 下载失败重试次数
    verbose=False,           # bool — 是否打印进度
) -> DedupResult
```

### DedupResult

| 属性 | 说明 |
|------|------|
| `images` | 全部条目（含失败），用于诊断 |
| `unique_images` | 去重后保留的图像列表 |
| `duplicates` | `{保留索引: [重复索引...]}` |
| `input_count` | 输入总数 |
| `original_count` | 成功加载的数量（参与去重） |
| `unique_count` | 去重后数量 |
| `removed_count` | 被移除的重复图像数 |
| `error_count` | 加载失败的数量 |
| `reduction_rate` | 去重率 = removed / original |

> 加载失败的图像不参与去重，不计入 `original_count` 和去重率。

## License

MIT
