images-dedup

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

安装

pip install images-dedup

快速开始

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，表示两张图像相似度超过此值即视为重复。

API

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

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

License

MIT