# ImageLibrary

**Repository Path**: cnscj/ImageLibrary

## Basic Information

- **Project Name**: ImageLibrary
- **Description**: 多路径图库，上传截图找相似图片
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-06
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图片图书馆

为多个路径下的图片建立「图书馆」，上传截图即可按相似度查找相似图片，支持 Web 界面管理路径与搜索。

## 功能

- **多路径图库**：添加多个文件夹路径，一键扫描建立索引
- **相似度搜索**：上传一张图片（如截图），按相似度阈值（滑块）返回结果
- **结果展示**：预览图 + 相似度百分比 + 完整路径（点击可复制）
- **随时增删**：可增删监听路径，随时重新扫描（适合夜间全量刷新）

## 环境要求

- Python 3.10+（含 3.13）
- 使用 **imagehash** 做感知哈希相似度，无需 PyTorch / GPU

## 安装

```bash
cd ImageLibrary
pip install -r requirements.txt
# 或: pip3 install -r requirements.txt
```

## 启动

在项目根目录执行：

```bash
python3 -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8765
```

或直接运行：`python3 run.py`

浏览器打开：<http://localhost:8765>

## 使用

1. **图书馆管理**
   - 在「监听文件夹」中输入绝对路径（如 `/Users/xxx/Pictures`），点击「添加」
   - 点击「开始扫描」全量构建索引（首次或增删路径后执行）
   - 状态区显示已收录图片数和上次扫描时间

2. **相似搜索**
   - 切换到「相似搜索」，拖拽或选择一张图片
   - 调节「相似度阈值」滑块（越高结果越严格）
   - 点击「搜索相似图片」，下方会列出预览与路径，点击结果可复制路径

## 数据与索引

- 索引与配置默认存放在项目下 `data/` 目录（可通过环境变量 `IMAGE_LIBRARY_DATA` 指定）
- 支持格式：jpg、jpeg、png、gif、bmp、webp

## 规模与配置（单文件夹 2w+、总规模几十万）

- **搜索**：索引在首次搜索或重建后缓存在内存，相似度用向量化汉明距离（numpy）计算，避免每次请求重读 JSON 和逐条算哈希。
- **构建**：路径数超过阈值（默认 1000，即单文件夹 2w 张必走并行）时多进程并行算哈希，参数在 `app/config.py` 中，均可通过环境变量覆盖：

| 环境变量 | 含义 | 默认（2w～几十万建议） |
|----------|------|------------------------|
| `IMAGE_LIBRARY_BUILD_PARALLEL_THRESHOLD` | 超过此路径数才启用多进程 | 1000 |
| `IMAGE_LIBRARY_BUILD_CHUNK_SIZE` | 每进程一次处理的图片数（块越大 IPC 越少） | 1000 |
| `IMAGE_LIBRARY_BUILD_MAX_WORKERS` | 并行进程数；设为 0 表示用满全部 CPU | CPU 数 -1 |

## 夜间全量刷新

可配合系统定时任务（如 cron、launchd）在夜间执行「扫描」：  
先调用 `POST /api/scan` 触发后台扫描，或直接在本机打开 Web 页面点击「开始扫描」即可。