images-dedup 0.1.0

基于感知哈希（imagehash）的图像去重工具，支持本地路径/URL/base64 输入

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

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

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

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

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

License

MIT