Publish NMM data preprocessing v0.3.0 with Chinese tutorials

.dockerignore

@@ -0,0 +1,8 @@
+.venv
+__pycache__
+*.egg-info
+runs
+release
+.git
+.env*
+*.token

.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+runs/
+.env
+.env.*
+*.token
+release/
+*.log

README.md

@@ -1,10 +1,281 @@
 ---
-title: NMM Data Preprocess
-emoji: 👁
+title: NMM-data-preprocess
+emoji: 🧹
 colorFrom: blue
-colorTo: indigo
+colorTo: green
 sdk: static
+app_file: index.html
 pinned: false
+short_description: 图片文本初筛：代码、参数、部署、分布统计与清洗教程
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# NMM-data-preprocess：图片—文本数据初筛
+
+版本 **0.3.0**。面向原生图片—文本模型训练前的数据初筛。Space 提供中文教程、参数查询、命令生成和源码下载；数据处理在本地或服务器通过 CLI 执行。静态 Space 不接收图片、不运行后台清洗作业。
+
+| 入口 | 内容 |
+| --- | --- |
+| [新手逐步教程](docs/QUICKSTART.md) | 下载、安装、合成示例、先统计再筛选再导出 |
+| [完整使用与评测手册](docs/USAGE.md) | 每个阶段的操作、指标公式、宽高比规则、报告解读 |
+| [参数参考](docs/PARAMETERS.md) | 所有 CLI 参数与 JSON 配置字段、默认值、边界和优先级 |
+| [部署指南](docs/DEPLOYMENT.md) | Windows、Linux、Docker、多机、断点续跑、HF Space 发布 |
+| [代码与功能说明](docs/ARCHITECTURE.md) | 模块职责、数据流、文件格式、功能矩阵、能力边界 |
+
+下载：`git clone https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess multimodal_training`，或在 Space 首页下载源码 ZIP。所有命令均在下载后的项目根目录执行。
+
+Python 3.10+，Windows / Linux。支持文件夹递归导入和 JSONL 图文清单；单机多进程和多机静态分片；SQLite 断点续跑、全局去重、原始/保留分布报告，以及标准化图片导出。原始图片不修改、不删除。
+
+详细的逐阶段指标、公式、配置字段、单机/多机命令和评测方法见 **[完整使用手册](docs/USAGE.md)**。
+
+## 统计后按宽高比桶筛选
+
+支持八个宽:高预设桶 `1:1,2:3,3:2,3:4,4:3,9:16,16:9,21:9`，可多选或使用 `all`。默认不启用桶筛选；启用后默认严格匹配。宽松模式偏差默认 5%，用 `--aspect-tolerance 0.03` 等参数调整。完整规则和评测指标见 [宽高比筛选说明](docs/USAGE.md#36-宽高比桶筛选)。
+
+```powershell
+# 严格筛选三个桶，同时要求短边至少 256 像素。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_strict --resolution 256p --aspect-buckets "1:1,2:3,3:2" --aspect-mode strict
+
+# 全部八个桶，允许包含边界的 5% 对称偏差；无须重新解码图片。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_loose --aspect-buckets all --aspect-mode loose --aspect-tolerance 0.05
+```
+
+## 统计后按分辨率筛选
+
+```powershell
+# 第一次全量统计，不启用可选阈值和去重。
+.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\images" --output runs/statistics --config configs/statistics_only.json --workers 8
+
+# 查看 runs/statistics/curated/report.html 后，保留短边大于或等于 256 像素的图片。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_256p --resolution 256p
+
+# 或只保留方向校正后的宽=256、高=256；其他尺寸全部进入 rejected.jsonl。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_256_square --resolution 256x256
+
+# 导出筛选后的图片与文本。
+.\.venv\Scripts\python.exe -m image_cleaner export --curated runs/only_256p --output runs/export_256p --workers 8
+```
+
+`filter` 是 `merge` 的别名；它从全部分析分片重新筛选，复用已保存的尺寸与质量指标，不重新读图，也不会把不匹配的图片缩放到目标尺寸。
+
+`256p` 在本工具中明确指 **短边大于或等于 256**：256×256、384×256、256×384、257×384、512×512 均符合；255×384 不符合。256 本身包含在内。`384x256` 指精确宽高，与 `256x384` 不同。尺寸取 EXIF 校正后的方向，筛选在导出缩放之前执行。`--resolution any` 关闭分辨率条件。
+
+配置文件也可写 `"resolution": "256p"`；命令行覆盖该字段。所有其他启用规则继续取交集。使用 `statistics_only.json` 做第一轮后，单独传 `--resolution` 就只做尺寸筛选；需要加去重时同时指定 `--config configs/audit.json`。
+
+`configs/above_256p.json` 可直接一键筛选。旧文件名 `configs/exact_256p.json` 保留为兼容配置，但其中的 `256p` 也采用大于或等于的新规则。
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\images" --output runs/direct_256p --config configs/above_256p.json --workers 8 --export
+```
+
+## 安装与第一次运行
+
+当前 Windows 工作区已建立 `.venv`。首次在另一台机器使用时：
+
+```powershell
+cd C:\Users\Administrator\.codex\tmp\multimodal_training
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e .
+```
+
+推荐第一次使用审计配置：先了解分布、查看重复样本，再设置质量阈值。输出必须在输入图片目录之外。
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\images" --output "runs\first_audit" --config configs/audit.json --workers 8
+```
+
+如果每张图片有同名 UTF-8 文本，如 `001.jpg` 与 `001.txt`，加 `--sidecar-text`。同一目录递归支持 JPG、PNG、WebP、BMP、TIFF、GIF、AVIF；实际解码格式支持取决于 Pillow。默认拒绝动画和多页文件，不会悄悄把所有帧当成一张图。
+
+若需要输出 RGB 标准化图片，加 `--export`。只导出保留样本，默认无损 PNG；默认不缩放、不裁剪、不去噪。配置 `export_max_edge` 后保持宽高比缩小，不放大。固定方形裁剪和图像张量均值/标准差归一化应由模型训练的数据加载器负责。
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\images" --output "runs\first_audit" --config configs/audit.json --workers 8 --export --resume
+```
+
+`--resume` 必须使用相同输入、配置和分片规模。清单固定后请保持原始文件不变；分析续跑会跳过已记录样本，导出时另行校验源文件 SHA-256，发现变更会报告失败。
+
+## 图文 JSONL 导入
+
+大规模多机处理最适合使用固定 JSONL 清单。每行至少有 `path`；`text`、原始 `id` 和任意元数据可选：
+
+```json
+{"id":"origin-001","path":"animals/001.jpg","text":"一只猫坐在窗边。","metadata":{"source":"dataset-a","license":"your-source-license"}}
+{"id":"origin-002","path":"charts/002.png","text":"柱状图显示不同月份的销量。"}
+```
+
+`path` 可以是绝对路径，或相对于 `--root` 的路径。为了跨机器迁移，推荐相对路径。同图多个描述/问答可使用多条记录；工具生成内部唯一 ID，原始 ID 存入 `source_id`，其他输入字段放入 `metadata`。
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\pairs.jsonl" --root "D:\datasets\images" --output runs/pairs --config configs/audit.json --workers 8
+```
+
+不自动下载 URL、不解压任意压缩包；请先将图片落到本地磁盘、共享文件系统或对象存储挂载目录。
+
+## 已实现的方法
+
+| 方法 | 实现与输出 |
+|---|---|
+| 分辨率分布 | 宽、高、短边、长边、总像素数的直方图、均值、标准差、分位数；清洗前后对比 |
+| 宽高比分布 | W/H 分桶，以及横图/竖图/近方图占比；可设置最小/最大比例 |
+| 图片规范化 | EXIF 方向校正、ICC 转 sRGB（有配置文件时）、RGB 转换、透明背景合成；可选等比例缩小 |
+| 文本规范化 | NFC 或 NFKC Unicode 规范化、换行统一、清除行末及首尾空白；保留段落；字符数和正则表达式筛选 |
+| 解码与容量检查 | 损坏、截断、缺失文件、动画/多页图片，以及最大解码像素数检查 |
+| 清晰度 | 原生像素区域上的拉普拉斯方差 `blur_score`；越低通常越模糊，但依赖图片内容 |
+| 噪声估计 | 低梯度区域高通残差 MAD 估计 `noise_sigma`，像素范围 0–255 |
+| 信噪比代理 | `snr_proxy_db = 20 log10(contrast / noise_sigma)`，无参考估计，不是真实 SNR 或 PSNR |
+| 压缩块效应 | 在 8 像素网格不同相位上测量边界与非边界的梯度差 `blockiness`；是代理指标 |
+| 完全重复 | 文件 SHA-256，以及方向/颜色/透明度规范化后的 RGB 像素 SHA-256 |
+| 近似重复 | 64 位 pHash 候选检索 + dHash + 宽高比 + RGB 缩略图 RMSE 复核 |
+| 可追溯筛选 | 每条记录保存指标、筛选原因、重复类型、代表样本 ID；配置及版本写入报告 |
+| 标准化输出 | 独立 PNG/JPEG 图片及对应文本清单；支持导出续跑、源文件与输出完整性校验 |
+
+此处“正则化”实施为数据规范化和文本正则筛选。Dropout、weight decay 等模型正则化属于训练代码，未混入清洗过程。
+
+这版实现的是图片技术质量与基础文本清洗，**未实现 CLIP 图文语义对齐、VLM 事实核验、审美模型、OCR、水印分类器和语义 embedding 去重**。统计/感知指标不能替代这些模型的判断。
+
+## 指标解释与阈值配置
+
+`configs/audit.json` 默认只统计技术质量，开启去重与格式有效性检查；不设置模糊、噪声、信噪比和块效应阈值。`configs/generation_example.json` 是示例，采用短边至少 512、宽高比 0.25–4、文本非空；不要将示例当成适用于所有领域的标准。
+
+可选字段如下，未列出的字段使用代码默认值；未知字段和非法范围会报错：
+
+```json
+{
+  "min_short_edge": 512,
+  "max_long_edge": null,
+  "min_pixels": null,
+  "max_pixels": null,
+  "min_aspect_ratio": 0.25,
+  "max_aspect_ratio": 4.0,
+  "min_blur_score": null,
+  "max_noise_sigma": null,
+  "min_snr_proxy_db": null,
+  "max_blockiness": null,
+  "min_text_chars": 1,
+  "max_text_chars": null,
+  "forbidden_text_patterns": [],
+  "duplicate_scope": "image_text",
+  "deduplicate": true,
+  "near_deduplicate": true,
+  "phash_distance": 4,
+  "dhash_distance": 4,
+  "near_rgb_rmse": 8.0,
+  "near_aspect_log_tolerance": 0.03,
+  "metric_patch_size": 256,
+  "max_decode_pixels": 100000000,
+  "reject_animated": true,
+  "alpha_background": [255, 255, 255],
+  "convert_icc": true,
+  "text_unicode_form": "NFC",
+  "export_max_edge": null,
+  "export_format": "png",
+  "export_jpeg_quality": 95
+}
+```
+
+质量指标使用最多五个原生像素区域（四角和中心，默认 256×256），取区域指标中位数。不会先缩图再估计噪声，但采样可能漏掉局部缺陷。高通噪声估计仍会受纹理、边缘、非高斯噪声影响；锐化、噪声也可能抬高清晰度分数。
+
+信噪比代理的“信号”是局部亮度标准差。纯色、低对比图或噪声估计为零时结果为 `null`，附带 `snr_proxy_undefined`；缺失指标不触发对应阈值筛选。极小图片的部分质量指标也为 `null`。报告包含各指标缺失数，避免将未测到的指标误当成高质量。
+
+ICC 转换失败会记录处理错误；16 位/浮点等输入最终转为 8 位 RGB，工具主要面向常规网页图像，不适合需要保留原始动态范围的科学影像。
+
+建议查看 `report.html`，抽查保留和删除样本后再设置质量阈值。清洗前后直方图、计数、均值和标准差是全量计算；分位数在不超过 20,000 条时精确，更多时使用固定随机种子的蓄水池抽样，报告明确标记近似。
+
+## 去重策略
+
+默认 `duplicate_scope=image_text`：仅当规范化文本也相同时删除重复记录，保留同图的不同有效描述/问答；只导入图片时文本为空，等价于按图片去重。改为 `image` 则不区分文本，图片重复记录都会归并。
+
+先应用质量阈值，再从合格样本选择代表，按 `像素数降序 → 噪声升序 → 清晰度降序 → 清单序号升序` 排序。被质量规则拒绝的样本不会压掉合格样本。每个近重复都直接匹配一个保留代表，不通过长链相似关系无限扩大分组。
+
+近重复候选通过 SQLite 多索引哈希分带检索：将 64 位 pHash 分成 r+1 段，汉明距离不超过 r 的候选必然共享至少一个段。之后严格复核 pHash、dHash、宽高比和 RGB 缩略图误差。允许 pHash 半径 0–8。pHash 抑制相对于最大 AC 系数极小的系数，减少平滑/纯色图片重编码后的数值波动；它与普通 pHash 分数不可直接互换。
+
+近重复仍是启发式，可能误合并细节仅有微小差异的图片，也可能漏掉大裁剪、翻转、文字覆盖或强颜色变化。先抽查 `duplicate.jsonl`；如只需要确定重复，设置 `near_deduplicate=false`。重复清单不会被删除，方便重新评估。
+
+若后续划分训练/验证集，需要把同图及其变体放在同一侧；本工具尚未自动做数据集划分。
+
+## 多机分布式处理
+
+采用静态 map/reduce 分片，无需 Ray、Redis 或 GPU。每台机器独立运行多进程 worker；每条清单按 `seq % world_size` 分配到唯一 rank。所有机器必须使用同一份冻结后的清单、元数据和配置。
+
+1. 在协调节点准备清单：
+
+```bash
+python -m image_cleaner prepare --input /data/images --manifest /jobs/input.jsonl --sidecar-text
+```
+
+将 `input.jsonl` 与 `input.jsonl.meta.json` 分发到节点。
+
+2. 以下两条命令分别在两台机器上运行（也可用于同一机器模拟两节点）：
+
+```bash
+# 节点 0，本机目录可以不同；相对路径须对应同一份图片内容。
+python -m image_cleaner analyze --manifest /jobs/input.jsonl --root /node0/images --output /jobs/shards --config configs/audit.json --workers 8 --world-size 2 --rank 0
+
+# 节点 1
+python -m image_cleaner analyze --manifest /jobs/input.jsonl --root /node1/images --output /jobs/shards --config configs/audit.json --workers 8 --world-size 2 --rank 1
+```
+
+每个节点也可以写本地目录。任务完成、进程退出后，把各自 `shard-*.sqlite` 收集到一个协调节点的目录。不要让多个机器写同一个 SQLite 文件；共享文件系统上不同 rank 的文件互不重叠，但更推荐节点本地磁盘后收集。
+
+3. 在协调节点执行全局合并：
+
+```bash
+python -m image_cleaner merge --shards /jobs/shards --output /jobs/curated
+```
+
+缺少任一 rank、未完成分片、不同清单/配置/版本、重复序号都会报错。去重是在所有分片合并后完成，因此能找到跨节点重复。
+
+4. 如需要物理输出标准化图片：
+
+```bash
+python -m image_cleaner export --curated /jobs/curated --root /data/images --output /jobs/normalized --workers 8
+```
+
+分析和导出均支持 `--resume`。中断后如果遗留 `.lock`，只有确认相关进程已经退出，才可删除对应锁文件后续跑。分析每 100 条提交 SQLite，最多重新分析尚未提交的记录。全局合并暂不支持中途续跑；合并失败时在新的输出目录重新执行，分析结果可复用。
+
+静态分片不包含自动调度、节点故障迁移或动态负载均衡。多机分析可并行，最终全局合并去重由单个协调节点执行；索引、排序与中间结果落磁盘，不在内存保存全部样本，也不做全量两两比较。大量相似/纯色图片或过宽的哈希半径会增加候选复核成本。每个节点需读取整份清单来选择自己的 rank；超大清单可预先拆分调度，但当前 CLI 不接受不同清单直接合并。
+
+并发任务队列最多约 `2 × workers`；统计抽样大小固定；SQLite 页缓存约 32 MiB。图片解码仍需原图大小的内存，因此高分辨率数据请适当降低 `--workers` 与 `max_decode_pixels`。这里提供的是规模化处理机制，没有宣称已完成百万/亿级性能基准。
+
+## 输出文件
+
+```text
+runs/first_audit/
+  input.jsonl                       # 固定清单
+  input.jsonl.meta.json             # 清单 SHA-256、数量、默认数据根目录
+  shards/
+    shard-00000-of-00001.sqlite     # 分析结果与续跑检查点
+    shard-00000-of-00001.jsonl      # 分片分析结果，方便查看
+  curated/
+    curation.sqlite                # 全局最终结果与哈希索引
+    kept.jsonl                     # 保留记录，包含源路径与文本
+    rejected.jsonl                 # 技术质量/文本规则拒绝记录
+    duplicate.jsonl                # 重复类型、代表 ID、近重复距离
+    error.jsonl                    # 解码或文件处理错误
+    report.json                    # 配置、计数、前后分布
+    report.html                    # 无外部依赖的 SVG 分布图
+  normalized/                      # 仅 --export 时生成
+    images/000000/sample-....png
+    exported.jsonl                 # 图片相对路径与文本，可用于后续训练
+    export_errors.jsonl
+    export.meta.json
+```
+
+导出 `exported.jsonl` 的顺序可能随 worker 完成时间变化；每条 ID 和输出路径稳定。最终筛选清单均按固定输入序号输出。导出失败会写错误清单并返回非零退出码；单张图片分析失败记录到错误清单，不中止整批分析。
+
+修改阈值后不必重复解码：
+
+```bash
+python -m image_cleaner merge --shards runs/first_audit/shards --output runs/filtered_v2 --config configs/generation_example.json
+```
+
+必须输出到新目录，图片预处理与质量测量设置不能更改；更改这些设置需要重新分析。
+
+## 验证
+
+```powershell
+.\.venv\Scripts\python.exe -m unittest discover -s tests -v
+```
+
+测试涵盖多进程/两分片与单机一致性、跨分片重复、缺失分片拒绝、断点续跑、源文件变更、像素重复与近重复、同图多文本、EXIF/透明度、噪声估计、模糊指标、筛选后再统计，以及超过一批次的全局去重。
+
+技术参考：[Pillow ImageOps](https://pillow.readthedocs.io/en/stable/reference/ImageOps.html)、[Python ProcessPoolExecutor](https://docs.python.org/3/library/concurrent.futures.html)。本工具的噪声实现采用原生像素高通残差估计，未调用 `skimage.estimate_sigma`，两者分数不可直接互换。

assets/app.js

@@ -0,0 +1,94 @@
+"use strict";
+// Use integer rational comparisons in the browser calculator, like the CLI.
+function decimalFraction(value) {
+  const parts = String(value).toLowerCase().split("e");
+  const mantissa = parts[0].split(".");
+  let numerator = BigInt(mantissa.join(""));
+  const exponent = Number(parts[1] || 0) - (mantissa[1] || "").length;
+  let denominator = 1n;
+  if (exponent >= 0) numerator *= 10n ** BigInt(exponent);
+  else denominator = 10n ** BigInt(-exponent);
+  return [numerator, denominator];
+}
+function bucketAssessment(width, height, buckets, mode, percent) {
+  let best = null;
+  const [tn, td] = decimalFraction(percent);
+  for (const bucket of buckets) {
+    const [n, d] = bucket.split(":").map(BigInt);
+    const a = BigInt(width) * d, b = BigInt(height) * n;
+    const difference = a >= b ? a - b : b - a, base = a <= b ? a : b;
+    const matched = mode === "strict" ? difference === 0n : difference * td * 100n <= base * tn;
+    if (best === null || difference * best.base < best.difference * base) {
+      best = {bucket, difference, base, matched};
+    }
+  }
+  return best;
+}
+function buildFilterCommand(platform, resolution, buckets, mode, percent) {
+  if (!/^(?:[1-9][0-9]*p|[1-9][0-9]*x[1-9][0-9]*|any|none)$/.test(resolution)) {
+    throw new Error("分辨率请填写 256p、384x256 或 any；数字需为正整数。");
+  }
+  if (mode === "loose" && (!Number.isFinite(Number(percent)) || Number(percent) < 0 || String(percent).trim() === "")) {
+    throw new Error("宽松偏差需为有限非负数，例如 5 表示 5%。");
+  }
+  const python = platform === "windows" ? ".\\.venv\\Scripts\\python.exe" : ".venv/bin/python";
+  const selected = buckets.length === 8 ? "all" : buckets.length ? '"' + buckets.join(",") + '"' : "none";
+  let command = `${python} -m image_cleaner filter --shards runs/statistics/shards --output runs/filtered --resolution ${resolution} --aspect-buckets ${selected}`;
+  if (buckets.length) {
+    command += ` --aspect-mode ${mode}`;
+    if (mode === "loose") command += ` --aspect-tolerance ${Number(percent) / 100}`;
+  }
+  return command;
+}
+if (typeof module !== "undefined") module.exports = {bucketAssessment, buildFilterCommand};
+if (typeof document !== "undefined") {
+  document.querySelectorAll("table").forEach(table => {
+    const wrapper = document.createElement("div"); wrapper.className = "table-scroll";
+    table.parentNode.insertBefore(wrapper, table); wrapper.appendChild(table);
+  });
+  document.querySelectorAll("pre").forEach(pre => {
+    const button = document.createElement("button"); button.className = "copy-code";
+    button.type = "button"; button.textContent = "复制";
+    button.addEventListener("click", async () => {
+      const value = pre.querySelector("code") ? pre.querySelector("code").textContent : pre.textContent.replace(/复制$/, "");
+      try {
+        await navigator.clipboard.writeText(value); button.textContent = "已复制";
+      } catch (_) { button.textContent = "请选中后复制"; }
+      setTimeout(() => {button.textContent = "复制";}, 2000);
+    });
+    pre.appendChild(button);
+  });
+  if (document.getElementById("command")) {
+    const ids = ["platform", "resolution", "mode", "tolerance", "width", "height"];
+    const controls = Object.fromEntries(ids.map(id => [id, document.getElementById(id)]));
+    const buckets = [...document.querySelectorAll('input[name="bucket"]')];
+    const update = () => {
+      const selected = buckets.filter(x => x.checked).map(x => x.value);
+      const mode = controls.mode.value, percent = controls.tolerance.value;
+      controls.tolerance.disabled = mode === "strict";
+      const error = document.getElementById("command-error"), output = document.getElementById("command");
+      try {
+        output.textContent = buildFilterCommand(controls.platform.value, controls.resolution.value.trim().toLowerCase(), selected, mode, percent);
+        error.textContent = "";
+      } catch (e) { output.textContent = "请先修正参数。"; error.textContent = e.message; }
+      const result = document.getElementById("ratio-result"), w = Number(controls.width.value), h = Number(controls.height.value);
+      if (!Number.isSafeInteger(w) || !Number.isSafeInteger(h) || w < 1 || h < 1) {
+        result.textContent = "请输入大于零的整数宽高。"; return;
+      }
+      if (error.textContent) { result.textContent = "请先修正筛选参数。"; return; }
+      const best = bucketAssessment(w, h, selected, mode, mode === "strict" ? "0" : percent);
+      const resolution = controls.resolution.value.trim().toLowerCase();
+      let sizeMatched = true;
+      if (resolution.endsWith("p")) sizeMatched = Math.min(w, h) >= Number(resolution.slice(0, -1));
+      else if (resolution.includes("x")) {
+        const [rw, rh] = resolution.split("x").map(Number); sizeMatched = w === rw && h === rh;
+      }
+      const bucketMessage = best ? `${best.matched ? "桶条件通过" : "桶条件未通过"}；最近桶 ${best.bucket}，偏差 ${(Number(best.difference) / Number(best.base) * 100).toFixed(3)}%` : "桶条件已关闭";
+      result.textContent = `${w}×${h}：${bucketMessage}；分辨率条件${sizeMatched ? "通过" : "未通过"}。`;
+    };
+    [...Object.values(controls), ...buckets].forEach(x => x.addEventListener("input", update));
+    document.getElementById("select-all").addEventListener("click", () => {buckets.forEach(x => x.checked = true); update();});
+    document.getElementById("select-none").addEventListener("click", () => {buckets.forEach(x => x.checked = false); update();});
+    update();
+  }
+}

assets/style.css

@@ -0,0 +1 @@
+:root{--ink:#12273b;--muted:#596c7a;--teal:#087d70;--line:#d9e3e8;--surface:#f3f7f9;--paper:#fff}*{box-sizing:border-box}html{scroll-behavior:smooth;scroll-padding-top:88px}body{margin:0;background:var(--paper);color:var(--ink);font-family:Inter,"Microsoft YaHei",system-ui,sans-serif;line-height:1.8}a{color:var(--teal);text-decoration:none}a:hover{text-decoration:underline}.topbar{position:sticky;top:0;z-index:20;min-height:72px;display:flex;justify-content:space-between;gap:20px;align-items:center;padding:15px max(24px,calc((100vw - 1180px)/2));border-bottom:1px solid var(--line);background:rgba(255,255,255,.97)}.brand{font-weight:750;letter-spacing:-.5px;color:var(--ink);white-space:nowrap}.brand span{color:var(--teal)}nav{display:flex;gap:24px;font-size:14px}nav a{color:var(--muted)}.landing{max-width:1180px;margin:auto;padding:0 28px}.hero{padding:75px 0 58px;max-width:900px}.eyebrow{font-size:12px;letter-spacing:1.5px;font-weight:700;color:var(--teal)}h1{font-size:clamp(36px,5.2vw,64px);line-height:1.24;letter-spacing:-1.8px;margin:22px 0}h2{font-size:26px;line-height:1.45;letter-spacing:-.5px}h3{font-size:19px;line-height:1.5}.lead{font-size:19px;max-width:740px;color:var(--muted)}.actions{display:flex;gap:12px;flex-wrap:wrap;margin:30px 0 17px}.button{display:inline-block;padding:11px 22px;border:1px solid var(--line);border-radius:7px;font-weight:600;color:var(--ink);font-size:14px}.primary{background:var(--teal);border-color:var(--teal);color:#fff}.button:hover{text-decoration:none;filter:brightness(.95)}.note{font-size:13px;color:var(--muted)}.pipeline{display:grid;grid-template-columns:repeat(4,1fr);border-top:1px solid var(--line);border-bottom:1px solid var(--line);padding:23px 0;gap:20px}.pipeline div{display:grid;grid-template-columns:36px 1fr;column-gap:12px}.pipeline b{grid-row:span 2;color:var(--teal);font-size:14px}.pipeline strong{font-size:17px}.pipeline span{font-size:12px;color:var(--muted)}.intro,.features{padding:48px 0 20px}.intro>p,.generator>p{color:var(--muted)}.guide-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:16px;margin-top:24px}.guide{border:1px solid var(--line);border-radius:9px;padding:23px;color:var(--ink);transition:background .15s}.guide:hover{background:var(--surface);text-decoration:none}.guide small{color:var(--teal);font-size:12px}.guide h3{margin:8px 0}.guide p{font-size:14px;color:var(--muted);margin:8px 0 20px}.guide span{font-size:13px;font-weight:600;color:var(--teal)}.generator{margin-top:38px;padding:30px;background:var(--surface);border:1px solid var(--line);border-radius:10px}.section-heading{display:flex;justify-content:space-between;gap:16px;align-items:center}.section-heading h2{margin:5px 0}.section-heading .eyebrow{margin:0}.tag{font-size:11px;border:1px solid #bbd9d2;border-radius:40px;padding:4px 11px;color:var(--teal)}.form-grid{display:grid;grid-template-columns:repeat(4,1fr);gap:16px;margin:24px 0}.form-grid label{display:flex;flex-direction:column;font-size:13px;gap:7px;font-weight:600}input,select,button{font:inherit}input[type=text],input[type=number],select{width:100%;border:1px solid #bdcdd6;background:white;padding:10px;border-radius:5px;color:var(--ink);font-size:14px}input:focus,select:focus,button:focus-visible,a:focus-visible{outline:2px solid var(--teal);outline-offset:3px}.buckets{padding:14px 0;border:0;display:flex;flex-wrap:wrap;gap:12px}.buckets legend{font-size:13px;font-weight:600}.buckets label{padding:6px 10px;border:1px solid var(--line);border-radius:5px;background:white;font-size:13px;cursor:pointer}.buckets input{accent-color:var(--teal);margin-right:6px}.buckets button{border:0;color:var(--teal);background:transparent;cursor:pointer;font-size:12px;padding:5px}pre{background:#142a3b;color:#e5edf2;border-radius:7px;padding:22px 24px;white-space:pre-wrap;overflow-wrap:anywhere;overflow-x:auto;position:relative;font-size:13px;line-height:1.75}pre code{background:transparent;color:inherit;padding:0}code{font-family:"Cascadia Code",Consolas,monospace;font-size:.88em;background:#eaf0f3;padding:2px 5px;border-radius:4px}.copy-code{position:absolute;right:7px;top:6px;cursor:pointer;color:#d6eee8;background:#294759;border:1px solid #537180;border-radius:4px;font-size:11px;padding:3px 8px}.error{color:#aa302b;font-size:13px}.error:empty{display:none}details{margin-top:20px;border-top:1px solid var(--line);padding-top:16px}summary{cursor:pointer;font-size:14px;font-weight:600}details .form-grid{grid-template-columns:repeat(2,minmax(120px,200px))}#ratio-result{font-size:14px;font-weight:600;color:var(--teal)}.feature-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:20px}.feature-grid article{border-top:2px solid var(--line);padding:12px 0}.feature-grid p{color:var(--muted);font-size:14px}.callout{border-left:3px solid var(--teal);padding:5px 26px;margin:30px 0 64px;background:var(--surface)}.callout h2{font-size:22px;padding-top:18px}.callout p{font-size:15px;max-width:900px}.callout a{display:inline-block;font-size:14px;margin-bottom:20px}footer{max-width:1180px;margin:auto;padding:24px 28px;border-top:1px solid var(--line);color:var(--muted);font-size:12px;display:flex;justify-content:space-between;gap:20px}.manual-layout{display:grid;grid-template-columns:240px minmax(0,1fr);gap:48px;max-width:1230px;margin:0 auto;padding:38px 28px 65px}.sidebar{position:sticky;top:108px;align-self:start;font-size:13px;max-height:calc(100vh - 135px);overflow:auto}.sidebar>a{display:block;margin-bottom:10px;padding:7px 11px;border-left:2px solid transparent;color:var(--muted)}.sidebar>a.active{color:var(--teal);border-color:var(--teal);background:var(--surface)}.sidebar h2{font-size:13px;color:var(--muted);margin:25px 0 10px}.toc ul{list-style:none;padding-left:0}.toc ul ul{padding-left:13px}.toc a{color:var(--muted);font-size:12px;display:block;line-height:1.6;margin-bottom:9px}.manual{min-width:0;font-size:15px}.manual h1{font-size:34px;margin:8px 0 27px;letter-spacing:-1px}.manual h2{margin:45px 0 18px;padding-top:12px;border-top:1px solid var(--line);font-size:24px}.manual h3{font-size:18px;margin-top:28px}.manual li{margin-bottom:5px}.manual pre{font-size:12px}.table-scroll{overflow:auto;margin:22px 0}.manual table{border-collapse:collapse;width:100%;font-size:13px}.manual td,.manual th{padding:12px;text-align:left;vertical-align:top;border:1px solid var(--line)}.manual th{background:var(--surface);font-weight:600}.manual blockquote{padding:5px 20px;border-left:3px solid var(--teal);margin:20px 0;color:var(--muted)}@media(max-width:900px){.guide-grid,.feature-grid{grid-template-columns:repeat(2,1fr)}.form-grid{grid-template-columns:repeat(2,1fr)}.tag{display:none}.topbar{padding:15px 20px}nav{gap:14px}.manual-layout{grid-template-columns:185px minmax(0,1fr);gap:24px}}@media(max-width:620px){.topbar{position:relative;flex-direction:column;align-items:flex-start;gap:6px}.brand{font-size:16px}nav{font-size:12px;flex-wrap:wrap}.landing{padding:0 20px}.hero{padding:40px 0 35px}h1{font-size:40px}.lead{font-size:16px}.pipeline{grid-template-columns:repeat(2,1fr);gap:20px}.guide-grid,.feature-grid{grid-template-columns:1fr}.generator{padding:22px 16px}.form-grid{gap:12px}.form-grid label{font-size:12px}.manual-layout{display:block;padding:22px 16px}.sidebar{position:relative;top:0;max-height:none;border-bottom:1px solid var(--line);margin-bottom:28px}.sidebar .toc,.sidebar h2{display:none}.sidebar>a{display:inline-block;font-size:12px;margin:3px;padding:4px 8px}.manual h1{font-size:29px}.manual h2{font-size:22px}footer{flex-direction:column;gap:4px}.section-heading h2{font-size:23px}}

configs/above_256p.json

@@ -0,0 +1,7 @@
+{
+  "resolution": "256p",
+  "deduplicate": false,
+  "near_deduplicate": false,
+  "text_unicode_form": "NFC",
+  "reject_animated": true
+}

configs/aspect_loose.json

@@ -0,0 +1,7 @@
+{
+  "aspect_buckets": ["1:1", "2:3", "3:2", "3:4", "4:3", "9:16", "16:9", "21:9"],
+  "aspect_mode": "loose",
+  "aspect_tolerance": 0.05,
+  "deduplicate": false,
+  "near_deduplicate": false
+}

configs/aspect_strict.json

@@ -0,0 +1,7 @@
+{
+  "aspect_buckets": ["1:1", "2:3", "3:2"],
+  "aspect_mode": "strict",
+  "aspect_tolerance": 0.05,
+  "deduplicate": false,
+  "near_deduplicate": false
+}

configs/audit.json

@@ -0,0 +1,10 @@
+{
+  "duplicate_scope": "image_text",
+  "phash_distance": 4,
+  "dhash_distance": 4,
+  "near_rgb_rmse": 8.0,
+  "near_aspect_log_tolerance": 0.03,
+  "reject_animated": true,
+  "text_unicode_form": "NFC",
+  "export_format": "png"
+}

configs/exact_256p.json

@@ -0,0 +1,7 @@
+{
+  "resolution": "256p",
+  "deduplicate": false,
+  "near_deduplicate": false,
+  "text_unicode_form": "NFC",
+  "reject_animated": true
+}

configs/generation_example.json

@@ -0,0 +1,14 @@
+{
+  "min_short_edge": 512,
+  "min_aspect_ratio": 0.25,
+  "max_aspect_ratio": 4.0,
+  "min_blur_score": null,
+  "max_noise_sigma": null,
+  "min_snr_proxy_db": null,
+  "max_blockiness": null,
+  "min_text_chars": 1,
+  "forbidden_text_patterns": [],
+  "duplicate_scope": "image_text",
+  "export_max_edge": 2048,
+  "export_format": "png"
+}

configs/statistics_only.json

@@ -0,0 +1,7 @@
+{
+  "resolution": null,
+  "deduplicate": false,
+  "near_deduplicate": false,
+  "text_unicode_form": "NFC",
+  "reject_animated": true
+}

docker/Dockerfile

@@ -0,0 +1,9 @@
+FROM python:3.12-slim
+RUN useradd --create-home --uid 1000 curator
+WORKDIR /app
+COPY pyproject.toml README.md ./
+COPY image_cleaner ./image_cleaner
+RUN python -m pip install --no-cache-dir .
+USER curator
+ENTRYPOINT ["python", "-m", "image_cleaner"]
+CMD ["--help"]

docs/ARCHITECTURE.md

@@ -0,0 +1,106 @@
+# 代码结构、功能与实现边界
+
+## 1. 当前版本与数据流
+
+当前清洗库版本 0.3.0，面向图片—文本对。主要流程：
+
+```text
+图片文件夹 / 图文 JSONL
+        │ prepare：稳定编号、固定清单与 SHA-256
+        ▼
+input.jsonl + input.jsonl.meta.json
+        │ analyze：rank 分片、本机进程池、规范化、测量
+        ▼
+各 rank 的 SQLite + JSONL
+        │ merge/filter：重算规则、全局去重、流式统计
+        ▼
+kept / rejected / duplicate / error + HTML/JSON 报告
+        │ export：源哈希校验、输出规范化 RGB
+        ▼
+标准化图片 + exported.jsonl → 训练数据加载器
+```
+
+`run` 将单机 prepare、analyze、merge 顺序串联，可选 export。静态 Space 仅展示文档与命令，算法在用户机器运行。
+
+## 2. 功能矩阵
+
+| 环节 | 已实现 | 输出/限制 |
+| --- | --- | --- |
+| 批量导入 | 递归图片目录、同名 txt、图文 JSONL | 固定清单，路径和原始 ID 可追溯 |
+| 解码检查 | 坏文件、截断、像素容量、动画/多页 | 单图失败进入 error，不删除源图 |
+| 标准化 | EXIF、ICC→sRGB、RGB、透明合成、Unicode/空白 | 无模型推理，无默认裁剪 |
+| 尺寸统计 | 宽高、短/长边、像素、比例、方向分类 | 全量直方图，最多 20000 样本估计分位数 |
+| 尺寸筛选 | 短边 >=Np、精确 WxH、其他尺寸阈值 | 条件取交集，包含边界 |
+| 宽高比桶 | 八桶、多选/全选、严格/宽松、可调容差 | 固定桶，不做桶均衡采样 |
+| 技术质量 | 模糊、噪声、SNR、块效应代理 | 最多五个原生像素区域，不是人工质量结论 |
+| 文本检查 | 长度、Unicode、广告等正则 | 不评估图文语义一致性 |
+| 精确去重 | 原字节、规范化像素 | 跨全部分片全局处理 |
+| 近重复 | pHash、dHash、比例、RGB RMSE 联合 | 启发式，不是 embedding 语义去重 |
+| 并行/续跑 | 本机进程池、多机静态 rank、SQLite 检查点 | 合并由单协调节点，无自动调度 |
+| 导出 | 独立 RGB PNG/JPEG、缩小长边、清单、续跑校验 | 原图不改动，固定裁剪由训练端完成 |
+
+用户提到的“正则化”在此实现中是数据规范化和规则校验；不包含训练损失正则化、数据增强或张量标准化。
+
+## 3. 源码文件说明
+
+| 文件 | 主要职责 |
+| --- | --- |
+| `image_cleaner/cli.py` | argparse 子命令、CLI 覆盖、run 串联与返回码 |
+| `image_cleaner/config.py` | 不可变 Config、JSON 加载、字段与数值校验、配置指纹 |
+| `image_cleaner/io.py` | 目录导入、JSONL、清单身份、原子写入、锁、SQLite、限流进程池 |
+| `image_cleaner/images.py` | EXIF/色彩/透明度/文本规范化、单图分析与筛选原因 |
+| `image_cleaner/aspect.py` | 精确分数比较、对称偏差、确定性桶分配 |
+| `image_cleaner/metrics.py` | 原生区域质量测量、pHash/dHash、缩略图与 RMSE |
+| `image_cleaner/jobs.py` | 分片分析、全局过滤、落盘去重索引、导出与续跑 |
+| `image_cleaner/stats.py` | 增量统计、蓄水池分位数、内嵌 SVG HTML 报告 |
+| `tests/test_pipeline.py` | 导入/清洗/去重/导出/分片/续跑/容量等测试 |
+| `tests/test_aspect.py` | 容差边界、横竖桶、重叠分配、CLI、缓存重筛选 |
+| `configs/` | 统计、尺寸、桶、去重、生成数据示例配置 |
+| `examples/` | 生成合成演示样本 |
+| `docker/Dockerfile` | CLI 容器部署，不启动 Web 服务 |
+| `tools/build_space.py` | 文档转换、静态页面、源码 ZIP、发布文件校验清单 |
+| `tools/publish_space.py` | 从环境变量读取 Token，检查账号并发布白名单文件 |
+| `web/` | Space 首页模板、样式与交互脚本 |
+
+`index.html`、`manual/*.html` 与 `downloads/*.zip` 是发布构建产物。运行结果在 runs，虚拟环境在 .venv，两者不发布。
+
+## 4. 记录格式与状态
+
+外部 JSONL 每条必须有字符串 path；text 为字符串或 null，metadata 为对象。输入 id 会保存为 source_id，程序生成稳定 `sample-000000000000` 等 ID 与 seq。其他外部字段放入 metadata，避免覆盖计算指标。
+
+分析记录包含源路径、规范化文本、原始/校正宽高、文件/像素哈希、质量指标、预处理元数据、警告和筛选原因。最终状态：
+
+| 状态 | 含义 |
+| --- | --- |
+| kept | 所有规则通过，且没有归并到其他代表 |
+| rejected | 至少一个尺寸/桶/质量/文本规则不通过 |
+| duplicate | 规则通过，但精确或近重复判定归并到代表 |
+| error | 无法成功解码、规范化或测量 |
+
+最终满足 `input_count=kept+rejected+duplicate+error`。同一拒绝记录可以有多个原因，原因计数不可当成样本数相加。
+
+## 5. 为什么统计后能反复筛选
+
+analyze 保存成功处理的完整指标，即使当时被阈值拒绝也写入 SQLite。filter 从全部记录重新计算规则，而不是仅读���上一次 kept。因此放宽阈值能恢复以前被拒绝的记录，收紧阈值也无需读源图片。
+
+六项测量设置（reject_animated、max_decode_pixels、metric_patch_size、alpha_background、convert_icc、text_unicode_form）不允许在重筛选中改变。变化会使缓存指标不再对应新处理逻辑，需要重新分析。
+
+## 6. 并行、去重和内存
+
+进程池并发队列约为 workers 的两倍，结果逐条写入 SQLite。rank 使用 `seq % world_size`，每个 rank 写单独数据库。全局 merge 校验完整分片并按稳定优先级处理候选。
+
+精确去重索引基于哈希，近重复使用 pHash 的 r+1 分段索引召回候选，再复核联合条件。索引和排序主要落磁盘，不将全量图片或全量指标载入内存；没有全数据两两比较。
+
+合并批量处理 500 条候选，SQLite 缓存约 32 MiB，分位数抽样上限 20000。图片解码内存仍随原图像素与 workers 增长。大量相似图片、纯色图或高半径设置会增加复核成本，不能据此承诺百万/亿级吞吐量。
+
+## 7. 当前没有覆盖的训练前审核
+
+当前不包含 OCR、水印/人脸/隐私识别、NSFW/版权判定、CLIP 语义一致性、美学模型、语义 embedding 去重、训练/验证集防泄漏、WebDataset/Parquet 输入、视频/音频、训练采样配额、动态集群调度。
+
+初筛保留仅代表通过已配置规则；训练前仍应按来源、内容类别和任务需求抽查，确认图文对齐及样本可用性。若后续扩展，应保留现有 source_id、稳定清单和每条决策原因便于追溯。
+
+## 8. 验证与版本
+
+现有 21 项清洗测试覆盖正好 5% 边界、零容差、桶重叠、源文件删除后的缓存筛选、多进程/双分片一致性、去重、多文本、断点续跑、导出校验、分辨率包含边界等。发布时另核验文档参数与代码、ZIP 白名单和页面链接。
+
+恢复分析要求软件版本与配置指纹一致。合并旧分片需要同一批分片身份一致且当前代码能够读取其字段；不要混用不同软件版本、不同清单或不同 world-size 的分片。版本号不代表数据清洗标准或模型效果保证。

docs/DEPLOYMENT.md

@@ -0,0 +1,198 @@
+# 部署、分布式运行与发布指南
+
+## 1. 部署形式如何选择
+
+| 场景 | 方式 |
+| --- | --- |
+| 初次使用、少量验证 | Windows / Linux 虚拟环境 + CLI |
+| 单台服务器大批量 | Linux CLI，多进程 analyze，磁盘上的 SQLite |
+| 环境一致性与隔离 | Docker CLI 容器，挂载原图与任务目录 |
+| 多机数据分析 | 同一 manifest，静态 rank/world-size，汇总完整分片 |
+| 在线共享代码和教程 | Hugging Face 静态 Space；不执行清洗后台 |
+
+清洗不依赖 GPU，也不加载大模型。核心依赖 Python>=3.10、NumPy>=1.26,<3、Pillow>=10.4,<13。实际解码格式取决于 Pillow 构建与可用编解码器，文件扩展名支持不保证所有格式均能解码。
+
+## 2. Windows 部署
+
+```powershell
+git clone https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess multimodal_training
+cd multimodal_training
+py -3.12 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --upgrade pip
+.\.venv\Scripts\python.exe -m pip install -e .
+.\.venv\Scripts\python.exe -m image_cleaner --help
+.\.venv\Scripts\python.exe -m unittest discover -s tests -v
+```
+
+不需要激活虚拟环境或修改 PowerShell 执行策略。路径有空格时加双引号。不要把 output 放到图片输入树中，以免后续重新导入导出文件。
+
+默认 workers 为 min(8,CPU 数量)，大图先设 2 或 4，观察内存与吞吐量再上调。配置 max_decode_pixels 控制解码容量；降低上限会把超限图片记入 error，不能替代缩图。
+
+## 3. Linux 部署
+
+```bash
+git clone https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess multimodal_training
+cd multimodal_training
+python3 -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install -e .
+.venv/bin/python -m image_cleaner --help
+.venv/bin/python -m unittest discover -s tests -v
+```
+
+```bash
+.venv/bin/python -m image_cleaner run --input /data/images --output /jobs/statistics --config configs/statistics_only.json --workers 8 --sidecar-text
+.venv/bin/python -m image_cleaner filter --shards /jobs/statistics/shards --output /jobs/filtered --config configs/audit.json --resolution 256p --aspect-buckets all --aspect-mode loose --aspect-tolerance 0.05
+.venv/bin/python -m image_cleaner export --curated /jobs/filtered --output /jobs/normalized --workers 8
+```
+
+离线运行前应在对应平台准备 Python、包安装文件和代码。可以执行 `pip download . --dest wheels` 收集核心依赖；打包方式和平台不同，应在目标环境验证。原图、任务文件建议放在可靠本地盘或受控共享存储，优先使用快盘承载 SQLite。
+
+## 4. Docker CLI 部署
+
+从项目根目录构建：
+
+```bash
+docker build -f docker/Dockerfile -t nmm-data-preprocess:0.3.0 .
+docker run --rm nmm-data-preprocess:0.3.0 --help
+```
+
+以下为 Linux 主机路径示例。先创建输出目录，并确保容器 UID 1000 对其有写权限；数据目录只读挂载：
+
+```bash
+mkdir -p /jobs/nmm
+docker run --rm \
+  -v /data/images:/data/images:ro \
+  -v /jobs/nmm:/jobs \
+  -v "$PWD/configs:/configs:ro" \
+  nmm-data-preprocess:0.3.0 \
+  run --input /data/images --output /jobs/statistics --config /configs/statistics_only.json --workers 4 --sidecar-text
+
+docker run --rm \
+  -v /jobs/nmm:/jobs \
+  -v "$PWD/configs:/configs:ro" \
+  nmm-data-preprocess:0.3.0 \
+  filter --shards /jobs/statistics/shards --output /jobs/filtered --config /configs/audit.json --resolution 256p --aspect-buckets all --aspect-mode loose
+
+docker run --rm \
+  -v /data/images:/data/images:ro \
+  -v /jobs/nmm:/jobs \
+  nmm-data-preprocess:0.3.0 \
+  export --curated /jobs/filtered --output /jobs/normalized --workers 4
+```
+
+第二条仅使用缓存分片，无须挂载源图；第三条 export 必须能访问原图，路径保持与分析时相同，或通过 `--root` 改写。容器不是 HF Docker Space 应用，没有监听 Web 端口。
+
+Windows Docker Desktop 中将 Linux 主机路径替换为实际 Windows 路径；PowerShell 多行续行用反引号，或把命令写成一行，不使用 Bash 的反斜线续行。Dockerfile 是提供的部署方案，Docker 是否可用需在用户环境实际构建验证。
+
+## 5. 两台服务器的完整流程
+
+### 5.1 制作一份全局清单
+
+在协调机器运行：
+
+```bash
+.venv/bin/python -m image_cleaner prepare --input /data/images --manifest /jobs/input.jsonl --sidecar-text
+```
+
+把 `input.jsonl`、`input.jsonl.meta.json`、同一代码版本和统计配置分发到所有分析节点。每台节点都要能访问属于其 rank 的图片，图片根目录可以不同；相对路径结构必须保持一致。
+
+### 5.2 各节点分析
+
+节点 0：
+
+```bash
+.venv/bin/python -m image_cleaner analyze --manifest /jobs/input.jsonl --root /mnt/images --output /jobs/node0 --config configs/statistics_only.json --rank 0 --world-size 2 --workers 8
+```
+
+节点 1：
+
+```bash
+.venv/bin/python -m image_cleaner analyze --manifest /jobs/input.jsonl --root /dataset/images --output /jobs/node1 --config configs/statistics_only.json --rank 1 --world-size 2 --workers 8
+```
+
+每条记录按 `seq % 2` 分配。不要让两个节点使用同一 rank，也不要向同一个 SQLite 并发写入。节点失败后在原节点增加 `--resume`，其余参数不变。
+
+### 5.3 收集分片
+
+分析进程正常退出后，将各节点的 `shard-00000-of-00002.sqlite` 与 `shard-00001-of-00002.sqlite` 放到协调节点 `/jobs/all_shards`；JSONL 可同时保留用于检查，但 merge 读取 SQLite。必须等分析完成再复制，避免只复制仍依赖 WAL 的数据库。
+
+先形成统计报告，然后全局筛选去重：
+
+```bash
+.venv/bin/python -m image_cleaner merge --shards /jobs/all_shards --output /jobs/global_statistics
+.venv/bin/python -m image_cleaner filter --shards /jobs/all_shards --output /jobs/global_filtered --config configs/audit.json --resolution 256p --aspect-buckets all --aspect-mode loose --aspect-tolerance 0.05
+```
+
+两轮都不需要原图。协调节点会验证所有 rank 完整、配置/清单/身份一致、总记录数匹配；缺失 rank 时拒绝合并，不能把局部去重当全局去重。
+
+### 5.4 统一导出
+
+协调节点必须能访问全部保留原图，以统一根目录覆盖各节点不同的绝对 source_path：
+
+```bash
+.venv/bin/python -m image_cleaner export --curated /jobs/global_filtered --root /coordinator/images --output /jobs/global_export --workers 8
+```
+
+相对图片路径依据原清单保持不变。当前 CLI 不把导出任务再分配到多个 rank，多机能力主要在 analyze 阶段。
+
+## 6. 续跑、重筛选与故障处理
+
+| 情况 | 操作 |
+| --- | --- |
+| analyze 正常中断 | 相同命令加 --resume；同 manifest/config/version/rank |
+| run 需要继续 | 相同命令加 --resume，不改输入、配置、root、sidecar 设置 |
+| export 中断 | 相同命令加 --resume；会检查源和已有输出哈希 |
+| 想调整尺寸、桶或质量阈值 | 从原 shards filter 到新的输出目录 |
+| 想调整颜色、测量区域等 | 新输出目录重新 analyze，再 merge |
+| merge 中途失败 | 无中途续跑支持；选新输出目录重新 merge，复用 shards |
+| 出现 .lock | 先确认对应进程已退出，才删除该特定锁；运行中不能删 |
+| 源文件在分析后变更 | export 拒绝哈希不一致的样本；重新制作/分析数据 |
+| 缺少 rank | 补齐原任务的分片，不修改 world-size 去掩盖缺失 |
+
+analyze 每 100 条提交一次检查点，异常退出最多重算尚未提交的记录。改变软件版本会影响 resume 身份，生产作业应固定版本与配置，保存元数据。
+
+代码读取整个 manifest 再挑选本 rank，不是自动调度器；超大清单、偏斜大图、共享盘拥塞可能限制速度。建议先测 1–10 万代表性图片，记录图片/秒、CPU、峰值内存、磁盘占用、错误率和各规则保留率，再确定节点与进程数。已有测试不等于百万级吞吐量基准。
+
+## 7. Hugging Face Space 的发布方式
+
+本项目使用静态 Space：根 README YAML 指定 `sdk: static` 与 `app_file: index.html`。页面包含教程、参数、代码下载、命令生成器和比例匹配演示；不连接用户文件系统、不提交训练图片、不运行服务器清洗。
+
+选择静态托管使文档入口无需清洗计算资源。官方规则参见 [Static HTML Spaces](https://huggingface.co/docs/hub/spaces-sdks-static) 和 [配置参考](https://huggingface.co/docs/hub/spaces-config-reference)。
+
+构建发布文件：
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install -e ".[publish]"
+.\.venv\Scripts\python.exe tools/build_space.py
+```
+
+本地预览：
+
+```powershell
+.\.venv\Scripts\python.exe -m http.server 8000 --bind 127.0.0.1
+```
+
+打开 `http://127.0.0.1:8000/index.html`。这是预览服务器，不是清洗 API。终端 Ctrl+C 停止。
+
+发布脚本仅从当前进程的 `HF_TOKEN` 读取认证，不使用账号密码，不调用持久化 login，不把 Token 写到任何文件。可在安全终端设置环境变量，或从秘密管理器注入；不要在脚本和配置中硬编码真实 Token。
+
+```bash
+# HF_TOKEN 已通过环境或秘密管理器注入。
+.venv/bin/python tools/publish_space.py --repo-id HanWangTJU/NMM-data-preprocess
+```
+
+脚本检查登录身份与仓库命名空间；创建不存在的 public static Space，或更新已有 static Space。它不删除远端文件、不变更现有私有性，也不申请付费硬件。先构建再发布，使用 release/publish-manifest.json 指定白名单与 SHA-256；发布前校验哈希、路径和凭据模式。
+
+发布内容包括库、测试、配置、示例、教程、页面、Dockerfile 和源码 ZIP；排除 .venv、runs、个人原图、运行日志、认证信息与系统路径。README 和 ZIP 保持同一版本，发布收据保存 repo ID、提交 ID、文件数量和页面地址。
+
+如果网络直连失败，可按实际网络环境设置 HTTPS_PROXY 连接官方 huggingface.co；不要为上传将认证 Token 发给未经确认的镜像站。权限不足时需要具有目标 Space 写入/创建权限的 Token。
+
+## 8. 部署后的验收
+
+1. `--help` 可用，测试通过，合成样例能统计/筛选/导出。
+2. 报告四类数量守恒，错误清单包含合成坏文件。
+3. 256p 和宽高比 5% 临界行为符合说明。
+4. 双 rank 与单机结果一致，源图删除后的缓存 filter 正常。
+5. 在线文档和源码 ZIP 可打开，远端文件没有凭据或个人数据。
+6. 实际数据上再做人工抽查与性能试运行，确认阈值和资源设置合适。

docs/PARAMETERS.md

@@ -0,0 +1,201 @@
+# 参数参考与设置方法
+
+## 1. 如何设置参数
+
+运行形式是 `python -m image_cleaner <子命令> ...`；安装后也可用 `image-cleaner <子命令> ...`。Windows 下建议直接使用虚拟环境的 `.\.venv\Scripts\python.exe`，Linux 使用 `.venv/bin/python`。
+
+CLI 提供流程与常用尺寸条件；质量、文本、去重、导出等设置集中在 JSON 配置文件中，由 `--config` 加载。配置采用 UTF-8，不能写注释；布尔值用 `true/false`，关闭可选阈值用 `null`。所有未知字段会报错，避免拼写错误被静默忽略。
+
+优先级：
+
+1. `analyze/run`：Config 默认值 → JSON 配置 → 显式 CLI 尺寸/宽高比参数。
+2. `filter/merge` 未传配置：继承分析分片完整配置 → 显式 CLI 参数。
+3. `filter/merge` 传配置：Config 默认值 → 新 JSON 配置 → 显式 CLI 参数；不与分片字段逐项合并。
+4. `export`：使用 curated/report.json 中的配置；不接受另一个 `--config`。
+
+例如统计分片使用 `statistics_only.json` 时去重关闭，仅加 `--resolution 256p` 不会开启去重；添加 `--config configs/audit.json` 才切换到该配置中的去重设置。
+
+## 2. 所有 CLI 参数
+
+### prepare：固定输入清单
+
+| 参数 | 必填/默认 | 说明 |
+| --- | --- | --- |
+| `--input` | 必填 | 图片目录或 UTF-8 JSONL |
+| `--manifest` | 必填 | 写入固定清单，同时生成 `.meta.json`；不能覆盖已有清单 |
+| `--root` | 自动推断 | 相对图片路径的根目录；目录输入默认自身，JSONL 默认其父目录 |
+| `--sidecar-text` | false | 文件夹输入时读取同名 UTF-8 `.txt`；JSONL 文本直接来自 text |
+
+### analyze：分析一个分片
+
+| 参数 | 必填/默认 | 说明 |
+| --- | --- | --- |
+| `--manifest` | 必填 | prepare 生成的清单，必须有配套 `.meta.json` |
+| `--output` | 必填 | 分片输出目录 |
+| `--config` | Config 默认值 | JSON 配置文件 |
+| `--root` | 清单元数据 root | 当前节点的图片根目录，可与制作清单的机器不同 |
+| `--workers` | min(8, CPU 数量) | 本机分析进程数，正整数 |
+| `--rank` | 0 | 当前分片编号，0 开始 |
+| `--world-size` | 1 | 总分片数，正整数，rank 必须小于该值 |
+| `--resume` | false | 使用相同清单、配置、版本和分片参数恢复已有 SQLite |
+| 尺寸/桶参数 | 见下表 | 支持 resolution 与三个 aspect 参数 |
+
+### filter / merge：重筛选与全局去重
+
+两个名称调用同一实现。
+
+| 参数 | 必填/默认 | 说明 |
+| --- | --- | --- |
+| `--shards` | 必填 | 同一 manifest、版本和分析配置的全部 rank SQLite 所在目录 |
+| `--output` | 必填 | 一个新的输出目录，不接受覆盖已有合并结果 |
+| `--config` | 继承分析配置 | 新筛选配置；不能改变预处理/测量设置 |
+| 尺寸/桶参数 | 见下表 | 覆盖有效配置对应字段 |
+
+### 共用尺寸与宽高比参数
+
+适用于 `analyze`、`run`、`filter/merge`。
+
+| 参数 | Config 默认值 | 取值与规则 |
+| --- | --- | --- |
+| `--resolution` | null | `256p` 短边 >=256；`384x256` 精确宽高；`any/none` 关闭；必须为正整数尺寸 |
+| `--aspect-buckets` | null | 多选例如 `"1:1,2:3"`；`all` 八桶并集；`none` 关闭；空选择报错 |
+| `--aspect-mode` | strict | strict 精确整数比例；loose 容差模式 |
+| `--aspect-tolerance` | 0.05 | 有限非负数，只作用于 loose；0.05=5%，0=不允许偏差 |
+
+八桶固定为 `1:1,2:3,3:2,3:4,4:3,9:16,16:9,21:9`，不支持自定义。所有尺寸条件基于 EXIF 校正后的宽和高；不自动互换横竖桶。严格模式忽略容差参数；未选择桶时模式和容差不会启用过滤。
+
+### export：标准化输出
+
+| 参数 | 必填/默认 | 说明 |
+| --- | --- | --- |
+| `--curated` | 必填 | filter/merge 输出目录，或 run 的 curated 子目录 |
+| `--output` | 必填 | 独立导出目录 |
+| `--root` | 记录 source_path | 图片移动后覆盖源图片根目录 |
+| `--workers` | min(8, CPU 数量) | 本机导出进程数，正整数 |
+| `--resume` | false | 使用相同配置和输出目录续跑，校验源文件和已导出文件哈希 |
+
+### run：单机完整流程
+
+| 参数 | 必填/默认 | 说明 |
+| --- | --- | --- |
+| `--input` | 必填 | 图片文件夹或 JSONL |
+| `--output` | 必填 | 工作目录，下设 input、shards、curated 等 |
+| `--root` | 自动推断 | 图片根目录 |
+| `--config` | Config 默认值 | 分析与筛选配置 |
+| `--workers` | min(8, CPU 数量) | 本机多进程数量 |
+| `--sidecar-text` | false | 文件夹输入读取同名文本 |
+| `--export` | false | 合并后导出到 normalized 子目录 |
+| `--resume` | false | 恢复同输入、配置、根目录和 sidecar 设置的已有任务 |
+| 尺寸/桶参数 | 见上表 | CLI 覆盖相应 JSON 字段 |
+
+每个子命令均支持 `--help`。没有 CLI 参数直接设置质量阈值，也没有 `--workers` 控制 merge：最终合并由单进程协调。
+
+## 3. 全部 JSON 配置字段
+
+### 尺寸与比例
+
+| 字段 | 默认值 | 单位/范围与行为 |
+| --- | --- | --- |
+| resolution | null | Np / WxH / any / none；语义同 CLI |
+| aspect_buckets | null | 数组、逗号字符串、all、none 或 null；规范化成固定顺序，重复值合并 |
+| aspect_mode | strict | strict / loose |
+| aspect_tolerance | 0.05 | 非负有限数，包含边界；不得为 null；设置很大将显著放宽筛选 |
+| min_short_edge | null | 非负整数像素，下限 |
+| max_long_edge | null | 非负整数像素，上限 |
+| min_pixels | null | 非负整数像素总数，下限 |
+| max_pixels | null | 非负整数像素总数，上限，不小于 min_pixels |
+| min_aspect_ratio | null | 非负有限数 W/H，下限 |
+| max_aspect_ratio | null | 非负有限数 W/H，上限，不小于 min_aspect_ratio |
+
+所有下限用 `>=`、上限用 `<=`，条件取交集。选择多个桶只在桶之间取并集，不会放宽其他规则。
+
+### 质量与文字
+
+| 字段 | 默认值 | 单位/范围与行为 |
+| --- | --- | --- |
+| min_blur_score | null | 非负有限数；拉普拉斯方差下限 |
+| max_noise_sigma | null | 非负有限数；灰度 0–255 尺度噪声估计上限 |
+| min_snr_proxy_db | null | 有限数，允许负数；SNR 代理 dB 下限 |
+| max_blockiness | null | 非负有限数；块效应代理上限 |
+| min_text_chars | null | 非负整数，规范化文本字符数量下限 |
+| max_text_chars | null | 非负整数，字符上限，不小于 min_text_chars |
+| forbidden_text_patterns | [] | 字符串数组；任意 Python 正则命中则拒绝；忽略大小写可用 (?i) |
+
+质量指标缺失时不会触发对应阈值，应另行审计报告 missing 与 warnings。所有质量阈值都需要在目标数据域校准，不能将默认 null 理解为“自动判断质量”。SNR 是代理指标，不是真实 SNR/PSNR。
+
+### 预处理与测量
+
+| 字段 | 默认值 | 单位/范围与行为 |
+| --- | --- | --- |
+| reject_animated | true | 布尔值；拒绝动画/多页；false 时只处理所读首帧/第一页 |
+| max_decode_pixels | 100000000 | 正整数；单图解码像素上限，超限记录为错误 |
+| metric_patch_size | 256 | 整数 >=16；角落和中心的原生像素测量区域边长上限 |
+| alpha_background | [255,255,255] | 三个 0–255 整数；透明区域合成背景 |
+| convert_icc | true | 有 ICC 时转 sRGB；无 ICC 时按 Pillow 的 RGB 转换处理 |
+| text_unicode_form | NFC | NFC / NFKC / none；仍执行换行与首尾空白规范化 |
+
+这六项会改变解码、标准化或指标，重筛选时必须与源分片一致；改变它们需重新 analyze。EXIF 校正与 RGB 转换始终执行。设置 max_decode_pixels 是容量限制，不会缩小超限原图。
+
+### 去重
+
+| 字段 | 默认值 | 范围与行为 |
+| --- | --- | --- |
+| deduplicate | true | 去重总开关，关闭后所有去重均关闭 |
+| near_deduplicate | true | 开启近重复，须同时开启 deduplicate；false 仍做精确去重 |
+| duplicate_scope | image_text | image_text：图片与规范化文字都满足；image：忽略文字差异 |
+| phash_distance | 4 | 整数 0–8，64 位 pHash 汉明距离上限 |
+| dhash_distance | 4 | 整数 0–64，64 位 dHash 汉明距离上限 |
+| near_rgb_rmse | 8.0 | 非负有限数；16×16 RGB 缩略图 RMSE 上限 |
+| near_aspect_log_tolerance | 0.03 | 非负有限数；abs(log(r1/r2)) 上限，与桶容差是不同参数 |
+
+近重复条件全部满足才归并。代表优先级为像素多、噪声低、清晰度高、清单 seq 小；不依赖 worker 完成顺序。精确去重检查原文件哈希和标准化像素哈希，作用域包含文本规则。
+
+### 导出
+
+| 字段 | 默认值 | 范围与行为 |
+| --- | --- | --- |
+| export_max_edge | null | 正整数像素；导出时限制长边，只缩小，不放大 |
+| export_format | png | png / jpeg |
+| export_jpeg_quality | 95 | 整数 1–100；JPEG 无色度子采样，仍为有损输出 |
+
+导出参数不修改统计阶段尺寸。缩图可能因整数取整产生微小比例变化，报告桶归属针对导出前的规范化原尺寸。修改导出设置先重新 filter 到新 curated 目录再 export。
+
+## 4. 典型配置组合
+
+### 只做第一轮统计
+
+```json
+{"deduplicate":false,"near_deduplicate":false}
+```
+
+### 尺寸、比例、文字与去重
+
+```json
+{
+  "resolution": "256p",
+  "aspect_buckets": ["1:1","2:3","3:2","9:16","16:9"],
+  "aspect_mode": "loose",
+  "aspect_tolerance": 0.05,
+  "min_text_chars": 1,
+  "deduplicate": true,
+  "near_deduplicate": true,
+  "duplicate_scope": "image_text",
+  "export_format": "png"
+}
+```
+
+### 原图规范化并限制导出长边
+
+```json
+{"resolution":"256p","export_max_edge":1024,"export_format":"jpeg","export_jpeg_quality":95}
+```
+
+`generation_example.json` 的 512 下限和比例范围是演示配置，不是通用训练推荐。`exact_256p.json` 是兼容旧文件名，内容实际为短边 >=256，请优先使用含义清晰的 `above_256p.json`。
+
+## 5. 无效设置与返回码
+
+常见非法值：`resolution=256`、`aspect_buckets=[]`、`aspect_tolerance=5%`、数值 NaN/Infinity、负容差、拼错字段、质量阈值写成字符串、正则语法错误。容差 CLI 只能写数值，5% 写 0.05。
+
+正常完成返回 0；CLI 捕获的配置/文件/SQLite 错误返回 2；export 存在导出失败，或 run 的导出环节存在失败，返回 1。单图分析失败会记入 error，通常整个分析仍返回 0，应核对报告。非法正则等未统一捕获的异常可能显示 Python traceback 并返回非零。
+
+完整算法公式与各字段的评测解释见 [使用手册](USAGE.md)，故障恢复见 [部署指南](DEPLOYMENT.md)。

docs/QUICKSTART.md

@@ -0,0 +1,139 @@
+# 从下载到第一轮图片—文本初筛
+
+## 1. 下载代码
+
+安装 Python 3.10 或更新版本，建议 Python 3.12。使用 Git 下载，或者在 Space 首页下载源码 ZIP，解压到 `multimodal_training`。
+
+```bash
+git clone https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess multimodal_training
+cd multimodal_training
+```
+
+后续命令都在此目录运行。安装过程需要联网下载 NumPy 和 Pillow；实际清洗不需要联网或 GPU。
+
+## 2. Windows 安装
+
+在 PowerShell 执行，无需激活环境或修改执行策略：
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --upgrade pip
+.\.venv\Scripts\python.exe -m pip install -e .
+.\.venv\Scripts\python.exe -m image_cleaner --help
+```
+
+如果没有 Python 3.12，将第一条改为 `python -m venv .venv`，并先确认 `python --version` 至少为 3.10。
+
+## 3. Linux 安装
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install -e .
+.venv/bin/python -m image_cleaner --help
+```
+
+后文 Windows 命令中的 `.\.venv\Scripts\python.exe` 在 Linux 替换为 `.venv/bin/python`，路径也换成实际 Linux 路径。
+
+## 4. 先用合成样例跑通
+
+```powershell
+.\.venv\Scripts\python.exe examples/make_demo.py
+.\.venv\Scripts\python.exe -m image_cleaner run --input runs/demo_input --output runs/tutorial_statistics --config configs/statistics_only.json --workers 2 --sidecar-text
+```
+
+合成示例包括重压缩、同像素不同格式、模糊、噪声、低分辨率、透明图、极端宽高比和坏文件。示例不是真实训练数据。生成脚本发现目标目录已存在时会停止，避免覆盖。
+
+预期输入 12 条，成功处理 11 条、错误 1 条；统计配置关闭可选阈值和去重，所以 11 条成功记录全部保留。打开 `runs/tutorial_statistics/curated/report.html`，查看原始分布与质量代理指标。坏文件应出现在 `error.jsonl`，不会使全批分析终止。
+
+## 5. 实际数据怎样输入
+
+最直接的方式是递归扫描图片文件夹：
+
+```text
+D:/datasets/images/
+  animal/cat.jpg
+  animal/cat.txt
+  scene/road.png
+  scene/road.txt
+```
+
+添加 `--sidecar-text` 会读取同名 `.txt` 文本（UTF-8）。没有文本的图片仍可导入；后续可用 `min_text_chars` 条件筛掉。
+
+已有图文配对时更推荐 JSONL，一行一条，路径相对 `--root`：
+
+```json
+{"id":"cat-001","path":"animal/cat.jpg","text":"一只猫坐在窗边。","metadata":{"source":"my_corpus"}}
+{"id":"road-002","path":"scene/road.png","text":"雨后的城市道路。"}
+```
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\pairs.jsonl" --root "D:\datasets\images" --output runs/my_statistics --config configs/statistics_only.json --workers 8
+```
+
+输出目录应位于原始图片文件夹之外。工具不修改或删除原始图片。文件夹导入未显式启用 `--sidecar-text` 时，不会自动配对文本。
+
+## 6. 在统计后筛选尺寸与宽高比
+
+```powershell
+# 短边 >=256；宽高比在八桶内，允许 5% 对称偏差。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/tutorial_statistics/shards --output runs/tutorial_filtered --resolution 256p --aspect-buckets all --aspect-mode loose --aspect-tolerance 0.05
+
+# 严格只留方图或 3:2 横图，输出到另一个目录。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/tutorial_statistics/shards --output runs/tutorial_strict --resolution 256p --aspect-buckets "1:1,3:2" --aspect-mode strict
+```
+
+`256p` 的定义是 `min(width,height)>=256`，包括正好 256；不要求短边必须等于 256。`256x256` 才是精确尺寸。宽高比始终按方向校正后的宽:高计算。
+
+宽松偏差为 `max(r/b,b/r)-1`，`0.05` 表示 5%。参数说明和完整边界例子见 [完整手册](USAGE.md)。重筛选读取原分析分片，不重复解码；规则取交集。
+
+## 7. 再加入文本与去重规则
+
+在项目根目录新建 `my_rules.json`：
+
+```json
+{
+  "resolution": "256p",
+  "aspect_buckets": "all",
+  "aspect_mode": "loose",
+  "aspect_tolerance": 0.05,
+  "min_text_chars": 1,
+  "deduplicate": true,
+  "near_deduplicate": true,
+  "duplicate_scope": "image_text"
+}
+```
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/tutorial_statistics/shards --output runs/tutorial_dedup --config my_rules.json
+```
+
+显式提供 JSON 配置文件时，未写字段使用 Config 默认值，而不是与分析分片逐项合并。默认开启精确与近重复去重；纯统计配置特意关闭了它们。同图不同规范化文本默认保留；改为 `duplicate_scope=image` 会忽略文本差异。
+
+质量阈值如 `min_blur_score`、`max_noise_sigma`、`min_snr_proxy_db`、`max_blockiness` 应先在代表性样本上校准，再写入配置；没有跨数据域通用的推荐数值。
+
+## 8. 查看报告、导出训练清单
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner export --curated runs/tutorial_dedup --output runs/tutorial_export --workers 2
+```
+
+清洗目录有 `kept/rejected/duplicate/error.jsonl`、`report.json`、`report.html`、`curation.sqlite`。导出目录有 RGB 图片、相对路径与文本组成的 `exported.jsonl`、失败清单和续跑元数据。
+
+优先核对以下项目：
+
+1. 输入数等于保留、拒绝、重复、错误四类数量之和。
+2. 错误数及错误原因；质量缺失指标并不等于通过人工质量检验。
+3. 分辨率与桶的独立通过率，以及全部规则通过率。
+4. 各桶前后样本数量；抽查被拒绝的临界图片和近重复判定。
+5. 最终图文是否对应。当前工具没有图文语义一致性模型。
+
+导出的文本已做 Unicode 与空白规范化；图片做 EXIF、色彩、透明度与 RGB 标准化。训练时的张量归一化、裁剪和多模态对齐仍由训练数据加载器负责。
+
+## 9. 测试和后续阅读
+
+```powershell
+.\.venv\Scripts\python.exe -m unittest discover -s tests -v
+```
+
+基础版本包含 21 项清洗测试。详细参数见 [参数参考](PARAMETERS.md)，多机与续跑见 [部署指南](DEPLOYMENT.md)，逐阶段指标见 [完整手册](USAGE.md)，实现细节见 [代码说明](ARCHITECTURE.md)。

docs/USAGE.md

@@ -0,0 +1,504 @@
+# 图片—文本数据清洗：完整操作与指标手册
+
+## 1. 工具范围和运行环境
+
+本工具处理本地图片与可选文本，完成导入、规范化测量、分布统计、分辨率/质量筛选、去重和独立导出。源文件不修改、不删除。保留/拒绝/重复/错误的判断通过输出清单表达。
+
+Python 3.10+；Windows 与 Linux；基础处理不需要 GPU。先下载仓库，以下以安装目录为例：
+
+```text
+D:\projects\multimodal_training
+```
+
+Windows 首次安装需要建立 `.venv`，完成后进入项目目录使用：
+
+```powershell
+cd D:\projects\multimodal_training
+.\.venv\Scripts\python.exe -m image_cleaner --help
+```
+
+新机器首次安装：
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e .
+```
+
+Linux 对应安装与命令前缀：
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+.venv/bin/python -m image_cleaner --help
+```
+
+下文 Windows 命令均在项目根目录运行。Linux 将前缀改为 `.venv/bin/python` 并使用相应路径即可。每次筛选使用新的输出目录。
+
+## 2. 输入方式
+
+### 2.1 文件夹：适合直接批量导入
+
+```text
+D:\datasets\images\
+  animals\001.jpg
+  animals\001.txt
+  charts\002.png
+  charts\002.txt
+```
+
+递归发现 `.jpg/.jpeg/.png/.webp/.bmp/.tif/.tiff/.gif/.avif`。图片有同名 UTF-8 `.txt` 时加 `--sidecar-text`，否则只导入图片。默认不跟随目录符号链接；扩展名发现列表与实际可解码格式不同，具体解码能力取决于 Pillow。
+
+### 2.2 JSONL：适合图文配对与多机迁移
+
+每行至少一个字符串 `path`，可以附带 `text`、`id`、`metadata`：
+
+```json
+{"id":"original-001","path":"animals/001.jpg","text":"一只猫坐在窗边。","metadata":{"source":"dataset-a"}}
+{"id":"original-002","path":"charts/002.png","text":"一个展示月份销量的柱状图。"}
+```
+
+相对路径以 `--root` 为基准；省略时以输入 JSONL 所在目录为基准。原始 ID 保存为 `source_id`，其他额外字段归入 `metadata`。同一图片允许多条不同文本记录。跨节点推荐相对路径；绝对路径不受 `--root` 重映射。
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\pairs.jsonl" --root "D:\datasets\images" --output runs/pairs_statistics --config configs/statistics_only.json --workers 8
+```
+
+格式错误的输入 JSONL、非字符串文本或无法读取的 sidecar 会使导入报错；单张图片缺失或损坏在分析阶段记录为错误。工具不直接下载 URL 或读取压缩包内的图片。
+
+## 3. 推荐流程：先统计，再筛选，再导出
+
+### 3.1 全量分布统计
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\images" --output runs/statistics --config configs/statistics_only.json --workers 8 --sidecar-text
+```
+
+只处理图片且没有文本时移除 `--sidecar-text`。统计配置关闭尺寸/质量/文本可选阈值和去重，成功处理的静态图片全部保留；损坏、超过容量限制、动画/多页等仍作为错误记录。
+
+查看报告：
+
+```powershell
+Start-Process -FilePath "runs/statistics/curated/report.html"
+```
+
+`report.json` 适合程序读取，`report.html` 包含无外部依赖的分布图。先检查分辨率、宽高比、噪声与清晰度分布，再确定规则。
+
+### 3.2 保留 256p 及以上的图片
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_256p --resolution 256p
+```
+
+`256p` 的定义是 `min(width, height) >= 256`，表示短边大于或等于 256 像素，256 本身保留。它不表示缩放图片，与 `min_short_edge=256` 的尺寸边界相同。
+
+| 图片尺寸（宽×高） | `256p` | `256x256` | `384x256` |
+|---|---|---|---|
+| 256×256 | 保留 | 保留 | 拒绝 |
+| 384×256 | 保留 | 拒绝 | 保留 |
+| 256×384 | 保留 | 拒绝 | 拒绝 |
+| 255×384 | 拒绝 | 拒绝 | 拒绝 |
+| 257×384 | 保留 | 拒绝 | 拒绝 |
+| 512×512 | 保留 | 拒绝 | 拒绝 |
+
+其他选择：
+
+```powershell
+# 仅保留 256×256。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_square --resolution 256x256
+
+# 仅保留宽 384、高 256。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_landscape --resolution 384x256
+
+# 改为短边大于或等于 512。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_512p --resolution 512p
+
+# 关闭分辨率条件。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/all_resolutions --resolution any
+```
+
+尺寸以 EXIF 方向校正后的宽高为准：编码为 256×384、EXIF 要求旋转 90° 的图片会以 384×256 判断。��彩转换不改变尺寸；导出缩放发生在筛选之后。
+
+`filter` 等价于 `merge`，始终从分析分片里的全部记录重新判定，不能把它的 `--shards` 指向上一轮 `curated` 目录。即使第一轮某图片被阈值或去重排除，分析结果仍在分片中，可以再次参与筛选。原图不会被重新解码；物理导出仍需要原图存在。
+
+### 3.3 分辨率与其他筛选一起执行
+
+使用配置文件可同时加入宽高比、质量、文本条件或去重：
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/256p_deduplicated --config configs/audit.json --resolution 256p
+```
+
+上例额外开启去重；符合尺寸的重复记录仍会进入 `duplicate.jsonl`。如果只希望剔除短边小于 256 的图片，沿用统计配置或指定 `--config configs/above_256p.json`，其去重关闭。
+
+配置优先级：未传 `--config` 时继承分析时的完整配置；传了 `--config` 时从该 JSON 和代码默认值构造新配置，不是对原配置做部分补丁；`--resolution` 最后覆盖分辨率字段。所有启用规则取交集。若同时设置 `min_short_edge=512` 与 `resolution=256p`，最终仍要求短边至少 512；如需允许所有大于或等于 256 的尺寸，先关闭更严格的其他尺寸规则。
+
+阈值修改和精确分辨率筛选可以复用分析结果。`reject_animated/max_decode_pixels/metric_patch_size/alpha_background/convert_icc/text_unicode_form` 属于测量与预处理设置，改变这些设置需要重新分析。
+
+### 3.4 导出标准化图片与文本
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner export --curated runs/only_256p --output runs/export_256p --workers 8
+```
+
+只导出 `kept.jsonl` 中的记录，默认 PNG、RGB、保留已匹配尺寸，不做裁剪或放大。文件放在 `images` 子目录，`exported.jsonl` 的 `path` 为导出目录下的相对路径。导出会校验源文件 SHA-256；源文件在分析后发生变化会记录失败。
+
+`export_max_edge` 如被启用，可能改变筛选后图片尺寸；需要导出文件仍满足筛选条件时保持 `export_max_edge=null`。例如 1024×512 符合 256p 及以上，但若导出最长边限制为 384，则会缩成 384×192，输出不再满足短边至少 256 的条件。
+
+### 3.5 一键流程
+
+已经明确目标时可以直接执行：
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\images" --output runs/direct_256p --config configs/above_256p.json --workers 8 --export
+```
+
+也可以在 `run` 或 `analyze` 上直接传 `--resolution`；推荐第一次先完成全量统计。
+
+### 3.6 宽高比桶筛选
+
+比例始终为 EXIF 方向校正后的 **宽:高**。八个固定桶为 `1:1,2:3,3:2,3:4,4:3,9:16,16:9,21:9`。竖图与横图分别选择，例如选择 `2:3` 不会自动选择 `3:2`。
+
+```powershell
+# 在项目根目录执行。先运行 3.1 的统计任务，再用缓存分片筛选。
+# 严格多选：实际尺寸必须与任意一个选中桶完全同比分配。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_strict --aspect-buckets "1:1,2:3,3:2" --aspect-mode strict
+
+# 宽松全选：5% 偏差，也可以省略 tolerance 参数使用默认值。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_loose --aspect-buckets all --aspect-mode loose --aspect-tolerance 0.05
+
+# 更严格的 3% 容差，同时保留短边 >=256 的图片。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_3percent_256 --resolution 256p --aspect-buckets "3:4,4:3,9:16,16:9" --aspect-mode loose --aspect-tolerance 0.03
+
+# 覆盖已有配置、关闭桶条件。其他筛选条件继续生效。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_disabled --aspect-buckets none
+
+# 从文件夹直接运行，支持多进程。
+.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\images" --output runs/aspect_run --workers 8 --aspect-buckets all --aspect-mode loose
+
+# 使用示例配置。示例关闭去重以便单独观察桶筛选效果。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_config --config configs/aspect_loose.json
+```
+
+每次重筛选使用一个新的输出目录。`filter` 读取全部分析记录，包括此前被规则拒绝的图片；因此既能收紧也能放宽条件，不需要再次解码。解码失败的记录仍归入错误。
+
+| 参数 | 默认值 | 含义 |
+| --- | --- | --- |
+| `--aspect-buckets` | 不启用，或继承配置/分片 | 英文逗号分隔多选；`all` 是八桶并集；`none` 关闭；空值或非预设桶报错 |
+| `--aspect-mode` | `strict`，或继承配置/分片 | `strict` 精确匹配；`loose` 容差匹配 |
+| `--aspect-tolerance` | `0.05`，或继承配置/分片 | 有限非负小数，仅宽松模式生效；`0.05` 表示 5%，`0` 表示不允许偏差 |
+
+三个参数均支持 `analyze`、`filter`/`merge`、`run`。显式命令行参数优先于配置；未传参数保留配置值。没有传 `--config` 的 `filter` 继承分析分片配置；传入配置文件则按该文件及 Config 默认值构建整套筛选规则。
+
+设实际比例 `r=width/height`，目标桶比例 `b`。严格模式使用整数交叉相乘：例如 `2:3` 要求 `width×3 == height×2`。宽松模式要求 `δ=max(r/b,b/r)-1 <= aspect_tolerance`，包含边界。实现使用精确分数比较。例如选 `1:1`、偏差 5% 时，`1050×1000` 和 `1000×1050` 均通过，`1051×1000` 不通过。此对称定义下允许区间为 `[b/1.05, b×1.05]`，并非普通的 `[b×0.95,b×1.05]`。
+
+任意一个选中桶匹配即可通过。如果匹配多个桶，则只分配给偏差最小的桶；同偏差按上述固定八桶顺序选取，因此每张图片只计数一次。重复选择会合并。`all` 仍会过滤超出所有桶范围的图片。桶条件与分辨率、`min_aspect_ratio/max_aspect_ratio`、质量、文本条件取交集；不会裁剪或缩放图片。
+
+配置文件新增字段示例：
+
+```json
+{
+  "aspect_buckets": ["1:1", "2:3", "3:2"],
+  "aspect_mode": "loose",
+  "aspect_tolerance": 0.05
+}
+```
+
+`aspect_buckets` 也接受 `"all"`、`"none"` 或 `null`。多机仍使用第 6 节的同一 manifest 和 rank/world-size 流程；所有节点分析配置一致，收集全部分片后统一执行上面的 `filter` 命令，桶筛选无需各节点读取源图片。
+
+## 4. 各环节指标和判定规则
+
+### 4.1 导入、解码和容量检查
+
+| 字段/指标 | 意义 | 判定 |
+|---|---|---|
+| `input_count` | 清单记录数量，包含同图多文本记录 | 不是去重后的独立图片数 |
+| `original_width/original_height` | 文件编码中的原始尺寸 | 与 EXIF 校正后的尺寸分别保存 |
+| `original_format/original_mode` | 解码格式和像素模式 | 用于来源与格式审计 |
+| `frame_count` | 帧数或页数 | 默认 `reject_animated=true` 时，多帧/多页报处理错误 |
+| `max_decode_pixels` | 单图最大解码像素数 | 默认 100,000,000；超过限制报错 |
+| `error_count`、`error.jsonl` | 文件缺失、损坏、截断或处理异常 | 不进入有效分布统计与导出 |
+| `processing_success_rate` | 完成整套图片处理数 ÷ 输入记录数 | 是处理成功率，不是人工质量准确率 |
+
+### 4.2 标准化
+
+| 字段/设置 | 行为和验证方法 |
+|---|---|
+| `exif_transposed` | 是否按 EXIF 方向进行转置；查看标准化宽高并抽查方向 |
+| `icc_converted` | 有 ICC 且开启转换时转为 sRGB；失败记错误 |
+| `alpha_flattened` | 是否存在透明通道并按 `alpha_background` 合成；默认白色 |
+| `text_unicode_form` | NFC 默认；可选 NFKC 或 none；同时统一换行并去首尾/行尾空白 |
+| 导出的 `width/height`、像素模式 | 检查最终尺寸与 RGB 模式；导出可选等比例缩小 |
+
+标准化属于数据规范化，未实现模型训练的 dropout/weight decay，也不会执行默认去噪或锐化。16 位/浮点图片最终转为 8 位 RGB，本工具主要面向常规网页图像。
+
+### 4.3 分布统计、分辨率和宽高比
+
+| 字段 | 定义/单位 | 筛选配置 |
+|---|---|---|
+| `width` | EXIF 校正后的宽度，像素 | `resolution=WxH` 可精确限定 |
+| `height` | EXIF 校正后的高度，像素 | `resolution=WxH` 可精确限定 |
+| `short_edge` | min(width,height)，像素 | `resolution=Np` 要求大于或等于 N；`min_short_edge` 为包含边界的下限 |
+| `long_edge` | max(width,height)，像素 | `max_long_edge` 为上限 |
+| `pixels` | width×height | `min_pixels/max_pixels` |
+| `aspect_ratio` | width/height | `min_aspect_ratio/max_aspect_ratio` |
+| `orientations` | 横、竖、近方图数量 | 0.95≤W/H≤1.05 视为近方图；只是统计类别 |
+
+分辨率筛选不匹配时，原因是 `resolution_mismatch`。`min_short_edge=256` 与 `resolution=256p` 均包含 256，因此 255 不合格，256 和 257 合格。`resolution_filter.mode=short_edge_gte` 与 `comparison=">="` 在报告中记录这一判定；`WxH` 仍为精确宽高匹配。
+
+每个分布提供有效数量、缺失数量、最小值、最大值、均值、总体标准差、p1/p5/p25/p50/p75/p95/p99，以及固定桶直方图。桶为左闭右开，最后覆盖到无穷大；直方图是全量精确计数。分位数最多使用固定种子 20,000 条蓄水池样本；更大规模时 `quantiles_approximate=true`。
+
+`before` 覆盖成功处理的全部记录，`after` 覆盖最终保留记录；不代表按独立图片去重后的来源统计。分辨率匹配数另外直接按每条记录统计，避免粗直方图桶无法区分 255/256/257 的问题。
+
+### 4.4 图片技术质量
+
+默认在四角和中心最多五个原生像素区域测量，区域大小最多 `metric_patch_size=256`，相同区域去重，各指标取有效区域的中位数。不会先缩图再测量；可能漏掉未采样区域的局部缺陷。
+
+| 字段 | 计算方式、解释 | 筛选条件 |
+|---|---|---|
+| `blur_score` | 灰度区域上 Var(up+down+left+right−4×center)，拉普拉斯方差；通常越低越模糊 | 低于 `min_blur_score` 拒绝 |
+| `noise_sigma` | 在梯度最低约 30% 区域，用 3×3 高通残差计算 MAD/(0.67448975×6)，像素幅度范围 0–255 | 高于 `max_noise_sigma` 拒绝 |
+| `snr_proxy_db` | 每区域 20log10(灰度标准差/noise_sigma)，然后取区域中位数 | 低于 `min_snr_proxy_db` 拒绝 |
+| `blockiness` | 对水平/垂直 8 像素网格各相位求边界梯度与非边界梯度差；每轴取最大差，再平均并截断到非负 | 高于 `max_blockiness` 拒绝 |
+| `luminance` | 灰度均值，0–255 | 当前仅记录，无直接阈值 |
+| `contrast` | 灰度总体标准差 | 当前仅记录，无直接阈值 |
+| `metric_patch_count` | 实际采样区域数 | 当前仅记录，方便审计 |
+
+这些是代理指标：拉普拉斯方差可能因噪声升高，纹理会影响噪声估计，规则图案也会产生块效应分数。信噪比的“信号”采用局部亮度标准差，不是真实 SNR，也不是 PSNR。
+
+噪声或对比度接近零时，SNR 返回 `null` 并写入 `snr_proxy_undefined`；极小图片部分指标为 `null`。缺失值不会触发对应质量阈值。报告的 `missing` 表示未得到指标值，不表示质量合格。
+
+所有质量阈值默认 null（关闭）；先按照片/截图/图表/插画等类型抽查，再设置阈值。修改 `metric_patch_size` 会改变指标分布，必须重新分析并重新校准。
+
+### 4.5 文本筛选
+
+| 指标/设置 | 判定 |
+|---|---|
+| `text_chars` | 规范化后 Python 字符数量；缺失文本按 0 统计，不是 token 数或单词数 |
+| `min_text_chars` | 低于下限拒绝；设置为 1 可排除没有文字的样本 |
+| `max_text_chars` | 超过上限拒绝 |
+| `forbidden_text_patterns` | 任一 Python 正则表达式 `re.search` 命中即拒绝，默认区分大小写 |
+
+例如配置 `"forbidden_text_patterns": ["(?i)buy\\s+now", "点击购买"]` 可匹配部分广告文本。这是启发式文本规则，不能判断图片与文本是否语义对应。
+
+### 4.6 去重
+
+质量规则通过后再进行全局去重，以避免不合格图片挤掉合格代表。
+
+| 指标/类型 | 判定 | 配置 |
+|---|---|---|
+| `file_sha256`、`exact_file` | 原文件字节 SHA-256 一致 | `deduplicate=true` |
+| `pixel_sha256`、`exact_pixels` | 标准化 RGB 尺寸和像素一致 | `deduplicate=true` |
+| pHash 汉明距离 | 64 位低频 DCT 特征哈希差异 | 不超过 `phash_distance`，默认 4，可设 0–8 |
+| dHash 汉明距离 | 64 位相邻灰度梯度特征差异 | 不超过 `dhash_distance`，默认 4，可设 0–64 |
+| RGB 缩略图 RMSE | 16×16 RGB 图像 sqrt(mean((a−b)²)) | 不超过 `near_rgb_rmse`，默认 8.0 |
+| 宽高比差异 | abs(log(ratio_a/ratio_b)) | 不超过 `near_aspect_log_tolerance`，默认 0.03 |
+| `near_perceptual` | 上述近重复条件均满足 | `near_deduplicate=true` 且总去重开启 |
+
+pHash 使用相对 AC 系数容差抑制极小系数，与普通 pHash 数值不完全相同。所有近重复复核是启发式，不能代替语义 embedding 去重。
+
+默认 `duplicate_scope=image_text`：规范化文本也相同才归并，保留同图不同描述/问答；没有文本时按图片归并。`image` 会忽略文本差异。代表优先级为像素数降序、噪声升序、清晰度降序、清单序号升序，不是人工审美排序。
+
+`duplicate.jsonl` 给出 `duplicate_of/duplicate_kind/duplicate_metrics`。近重复记录目前保存 pHash 距离和 RGB RMSE，dHash 与比例条件用于判断但未单独写入距离字段。每个重复直接匹配一个保留代表，不通过无限传递链扩大分组。
+
+### 4.7 阶段评测指标
+
+令 N 为输入条数、D 为处理成功条数、M 为指定分辨率匹配条数、E 为全部规则通过条数、U 为重复条数、K 为最终保留条数：
+
+| `report.json` 字段 | 定义 |
+|---|---|
+| `input_count` | N |
+| `error_count` | N−D |
+| `stage_metrics.processing_success_count/rate` | D、D/N |
+| `stage_metrics.resolution_matched_count` | M，单独按尺寸条件计算，不含其他质量限制 |
+| `stage_metrics.resolution_mismatched_count` | D−M |
+| `stage_metrics.resolution_pass_rate` | M/D；分辨率条件关闭时为 1（D>0） |
+| `stage_metrics.rules_eligible_count/rules_pass_rate` | E=K+U、E/D |
+| `rejected_count` | D−E，至少一个规则不合格 |
+| `duplicate_count` | U |
+| `stage_metrics.duplicate_rate_among_eligible` | U/E |
+| `kept_count/stage_metrics.final_keep_rate` | K、K/N |
+| `before.reasons` | 最终各原因的出现次数；一条拒绝记录可有多个原因，不可直接加总当成样本数 |
+
+分母为零时��率为 null。比率是 0–1 的数值；乘 100 得百分比。每次完整输出满足 `N=K+rejected_count+U+error_count`。关闭去重时 U=0。
+
+这些指标衡量清洗流程和数据组成，不是模型性能或人工标注准确率。若要评估误删/漏删，按图片类型和规则分层抽取人工审核样本，统计“被拒绝但实际可用”的比例和“保留但实际不合格”的比例。后续训练收益需要固定训练预算、随机种子与验证集做对照实验。
+
+### 4.8 宽高比桶筛选评测指标
+
+打开输出目录的 `report.html` 查看新增宽高比桶部分；`report.json` 提供机器可读指标，`kept.jsonl`、`rejected.jsonl` 等提供逐条结果。
+
+| 指标/字段 | 定义与用途 |
+| --- | --- |
+| `stage_metrics.aspect_bucket_matched_count` | 成功解码记录中，单独满足桶条件的数量；不受其他阈值和去重影响 |
+| `aspect_bucket_mismatched_count` | 成功解码数量减去桶匹配数量 |
+| `aspect_bucket_pass_rate` | 桶匹配数 / 成功解码数；无成功解码记录为 null；关闭桶条件时成功解码记录全部通过 |
+| `aspect_bucket_filter.counts_before` | 所有成功解码图片的匹配桶归属计数，包含因其他条件拒绝或重复的图片 |
+| `aspect_bucket_filter.counts_after` | 最终 kept 图片的桶归属计数，已应用全部规则及去重 |
+| `aspect_bucket_filter` 其余字段 | 是否启用、选中桶、模式、容差、尺寸计算依据、偏差公式 |
+| 每条记录 `aspect_bucket` | 匹配且分配的桶；没有通过桶条件或关闭条件时为 null |
+| `aspect_bucket_nearest` | 最近的选中桶，即使不通过也可用来排查；关闭条件时为 null |
+| `aspect_bucket_deviation` | 到最近桶的对称相对偏差；例如 0.05 是 5%；关闭条件时为 null |
+| `aspect_bucket_match` | true/false 表示通过/未通过；关闭条件时为 null |
+| 拒绝原因 `aspect_bucket_mismatch` | 不满足任何选中桶；同一记录可同时包含多个拒绝原因 |
+
+上述逐条字段针对成功解码记录；错误记录可能没有尺寸与桶字段。`counts_before` 总和等于独立桶匹配数（条件启用时），`counts_after` 总和等于最终保留数。选中但没有图片的桶也输出 0；关闭条件时桶计数字典为空。质量评测可同时检查桶通过率、各桶覆盖量、最终保留率，并人工抽查 rejected 中临界偏差图片；各桶不执行均衡采样或配额。
+
+## 5. 配置文件和参数
+
+项目已有：
+
+| 配置 | 用途 |
+|---|---|
+| `configs/statistics_only.json` | 全量统计，关闭可选阈值与去重 |
+| `configs/above_256p.json` | 短边大于或等于 256，关闭去重 |
+| `configs/exact_256p.json` | 兼容旧文件名，内容与 above_256p 相同，采用大于或等于的新规则 |
+| `configs/audit.json` | 无可选技术质量阈值，开启默认去重 |
+| `configs/aspect_strict.json` | 严格选择 1:1、2:3、3:2，关闭去重 |
+| `configs/aspect_loose.json` | 宽松选择八桶，默认容差 5%，关闭去重 |
+| `configs/generation_example.json` | 示例：短边至少 512、比例 0.25–4、文本非空，并开启默认去重 |
+
+以下为可自定义的完整字段表，数值是默认值，不是推荐质量阈值：
+
+```json
+{
+  "resolution": null,
+  "min_short_edge": null,
+  "max_long_edge": null,
+  "min_pixels": null,
+  "max_pixels": null,
+  "min_aspect_ratio": null,
+  "aspect_buckets": null,
+  "aspect_mode": "strict",
+  "aspect_tolerance": 0.05,
+  "max_aspect_ratio": null,
+  "min_blur_score": null,
+  "max_noise_sigma": null,
+  "min_snr_proxy_db": null,
+  "max_blockiness": null,
+  "min_text_chars": null,
+  "max_text_chars": null,
+  "forbidden_text_patterns": [],
+  "reject_animated": true,
+  "max_decode_pixels": 100000000,
+  "metric_patch_size": 256,
+  "alpha_background": [255, 255, 255],
+  "convert_icc": true,
+  "text_unicode_form": "NFC",
+  "deduplicate": true,
+  "near_deduplicate": true,
+  "duplicate_scope": "image_text",
+  "phash_distance": 4,
+  "dhash_distance": 4,
+  "near_rgb_rmse": 8.0,
+  "near_aspect_log_tolerance": 0.03,
+  "export_max_edge": null,
+  "export_format": "png",
+  "export_jpeg_quality": 95
+}
+```
+
+`export_format` 可选 png/jpeg；JPEG `export_jpeg_quality` 为 1–100，采用无色度子采样，仍是有损输出。图片规范化不会自动统一为方形，固定裁剪和张量归一化由训练数据加载器执行。
+
+`resolution` 支持 `256p`（短边>=256）、`256x256`（精确宽高）等正整数格式；大小写与首尾空白会规范化，`256×256` 也接受。`any/none/null` 关闭分辨率条件。无后缀的 `256`、`0p`、负数、逗号多个值都非法；多目标请分别筛选到不同输出目录。
+
+各子命令参数：
+
+| 命令 | 主要必填参数 | 可选参数 |
+|---|---|---|
+| `prepare` | `--input --manifest` | `--root --sidecar-text` |
+| `analyze` | `--manifest --output` | `--root --config --resolution --aspect-buckets --aspect-mode --aspect-tolerance --workers --rank --world-size --resume` |
+| `filter/merge` | `--shards --output` | `--config --resolution --aspect-buckets --aspect-mode --aspect-tolerance` |
+| `export` | `--curated --output` | `--root --workers --resume` |
+| `run` | `--input --output` | `--root --config --resolution --aspect-buckets --aspect-mode --aspect-tolerance --workers --sidecar-text --export --resume` |
+
+`workers` 默认 min(8,CPU数量)。配置未知字段、非法类型、范围错误会报错；各子命令的 `--help` 可查看在线说明。
+
+## 6. 多机分片流程
+
+先创建全局固定清单：
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner prepare --input "D:\datasets\images" --manifest runs/distributed/input.jsonl --sidecar-text
+```
+
+将 `input.jsonl`、`input.jsonl.meta.json`、相同代码和配置分发到节点。每台机器都必须能访问对应原图，可以使用不同本地根目录。
+
+分别在两台机器执行：
+
+```powershell
+# 节点 0
+.\.venv\Scripts\python.exe -m image_cleaner analyze --manifest runs/distributed/input.jsonl --root "D:\node0\images" --output runs/distributed/shards --config configs/statistics_only.json --workers 8 --world-size 2 --rank 0
+
+# 节点 1
+.\.venv\Scripts\python.exe -m image_cleaner analyze --manifest runs/distributed/input.jsonl --root "E:\node1\images" --output runs/distributed/shards --config configs/statistics_only.json --workers 8 --world-size 2 --rank 1
+```
+
+每条清单按 `seq % world_size` 分配。每个节点本地写不同 rank 的 SQLite，任务退出后收集全部 `shard-*.sqlite` 到协调节点同一目录；不用让不同机器写同一个 SQLite。
+
+协调节点先汇总统计，然后按分辨率条件筛选：
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner merge --shards runs/distributed/shards --output runs/distributed/statistics
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/distributed/shards --output runs/distributed/only_256p --resolution 256p
+```
+
+若希望跨分片去重，在第二条命令增加 `--config configs/audit.json`。合并会验证全部 rank 完整、清单/配置/软件版本一致、序号不重复。筛选结果与使用同一清单的单机处理一致，去重代表顺序不依赖 worker 完成顺序。
+
+这是静态分片处理，没有自动节点调度或故障迁移。分析并行，最终筛选和全局去重由一个协调节点完成；数据和索引落磁盘，没有百万级运行性能保证。大图处理的解码内存与图片尺寸有关，可降低 workers 或最大解码像素限制。
+
+## 7. 输出、断点续跑和复核
+
+统计 `run` 输出清单、分片数据库，以及 `curated` 报告；`filter/merge` 的报告直接在其 `--output` 目录内，**不会再额外套一层 curated**。
+
+| 文件 | 用途 |
+|---|---|
+| `input.jsonl/.meta.json` | 固定输入与 SHA-256、条数、数据根目录 |
+| `shard-*.sqlite` | 完整分析记录与断点检查点，是重复筛选的数据源 |
+| `shard-*.jsonl` | 方便检查的分片记录 |
+| `kept.jsonl` | 最终保留的路径、文本、指标 |
+| `rejected.jsonl` | 各规则拒绝原因，包括 `resolution_mismatch` |
+| `duplicate.jsonl` | 重复类型、代表 ID 和近重复评分 |
+| `error.jsonl` | 单图处理失败及异常信息 |
+| `report.json/.html` | 配置、分辨率定义、阶段指标和前后分布 |
+| `exported.jsonl` | 标准化图片相对路径及文本 |
+| `export_errors.jsonl` | 导出失败清单 |
+| `export.meta.json` | 导出完成状态、计数及身份校验 |
+
+分析续跑：
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner analyze --manifest runs/distributed/input.jsonl --root "D:\node0\images" --output runs/distributed/shards --config configs/statistics_only.json --workers 8 --world-size 2 --rank 0 --resume
+```
+
+导出续跑：
+
+```powershell
+.\.venv\Scripts\python.exe -m image_cleaner export --curated runs/only_256p --output runs/export_256p --workers 8 --resume
+```
+
+`run --resume` 要求相同输入、配置、分辨率等身份设置；修改规则应使用 `filter` 输出到新目录。分析每 100 条提交一次；已提交项跳过。清单固定后保持原始文件不变。残留锁文件只能在确认任务退出后移除。
+
+合并/筛选暂不支持中途续跑，失败时用新输出目录重跑，不必重新分析。导出失败会记录清单并返回退出码 1；参数/文件操作等任务错误返回 2；分析阶段的个别图片错误不使整批命令失败，需检查 `error_count`。
+
+复核建议：检查总数守恒、目标尺寸匹配率、各原因抽样、清洗前后图片类别/宽高比分布变化，以及近重复误合并。为每轮保存独立目录及配置；后续训练/验证划分应让同图及其变体落在同一侧，本工具未自动划分数据集。
+
+## 8. 验证与功能边界
+
+在全新示例目录运行以下命令，可复现分辨率筛选，不依赖外部数据。示例是六张合成图片和一条损坏图片；256p 及以上预期保留五张（256×256、384×256、256×384、257×384、512×512）、尺寸拒绝一张、错误一张。重复执行请复用已生成输入并为任务更换新的输出目录。旧版筛选报告不会自动改写；重新 filter 到新目录，旧分析分片仍可复用。
+
+```powershell
+.\.venv\Scripts\python.exe examples/make_resolution_demo.py
+.\.venv\Scripts\python.exe -m image_cleaner run --input runs/resolution_demo_input --output runs/resolution_demo_statistics --config configs/statistics_only.json --workers 2 --sidecar-text
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/resolution_demo_statistics/shards --output runs/resolution_demo_256p --resolution 256p
+.\.venv\Scripts\python.exe -m image_cleaner export --curated runs/resolution_demo_256p --output runs/resolution_demo_export --workers 2
+```
+
+单元与集成测试：
+
+```powershell
+.\.venv\Scripts\python.exe -m unittest discover -s tests -v
+```
+
+测试包括包含边界的短边下限、精确宽高、255/256/257 边界、EXIF 后方向、配置覆盖、禁用尺寸条件、规则交集、无原图重复筛选，以及既有多进程/跨分片去重与导出测试。
+
+未包含 CLIP 图文语义对齐、VLM 事实核验、审美模型、OCR、水印分类器、语义 embedding 去重或训练模型性能评测。当前技术质量指标无法判断图片里的描述是否事实正确。

downloads/NMM-data-preprocess-0.3.0.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:161f65c55e0728b8e71c92f9ac70ac03e5cee942ac871afb6f8b5fc9e8e28c1e
+size 85450

examples/make_demo.py

@@ -0,0 +1,38 @@
+"""Create small synthetic fixtures, not real training data, under this project only."""
+from pathlib import Path
+import shutil
+
+import numpy as np
+from PIL import Image, ImageFilter
+
+
+def main():
+    root = Path(__file__).resolve().parents[1]/"runs"/"demo_input"
+    if root.exists():
+        raise SystemExit(f"Demo input already exists: {root}")
+    root.mkdir(parents=True)
+    rng = np.random.default_rng(42)
+    coarse = Image.fromarray(rng.integers(20, 235, (32, 32, 3), dtype=np.uint8))
+    image = coarse.resize((768, 512), Image.Resampling.BICUBIC)
+    image.save(root/"landscape.png")
+    shutil.copyfile(root/"landscape.png", root/"same_file.png")
+    image.save(root/"same_pixels.bmp")
+    image.save(root/"recompressed.jpg", quality=92)
+    image.transpose(Image.Transpose.ROTATE_90).save(root/"portrait.png")
+    image.filter(ImageFilter.GaussianBlur(6)).save(root/"blurred.png")
+    raw = np.asarray(image).astype(np.float64)
+    noisy = np.clip(raw + rng.normal(0, 15, raw.shape), 0, 255).astype(np.uint8)
+    Image.fromarray(noisy).save(root/"noisy.png")
+    image.resize((80, 60)).save(root/"small.png")
+    Image.new("RGB", (512, 512), "white").save(root/"flat.png")
+    Image.new("RGBA", (512, 512), (0, 255, 0, 0)).save(root/"transparent.png")
+    Image.new("RGB", (32, 1024), "blue").save(root/"extreme_aspect.png")
+    (root/"broken.jpg").write_bytes(b"invalid-image-fixture")
+    for path in root.iterdir():
+        if path.suffix.lower() in {".png", ".jpg", ".bmp"}:
+            path.with_suffix(".txt").write_text("合成测试图片，用于验证清洗工具。", encoding="utf-8")
+    print(root)
+
+
+if __name__ == "__main__":
+    main()

examples/make_resolution_demo.py

@@ -0,0 +1,26 @@
+"""Create six synthetic size cases and one corrupt fixture inside the project."""
+from pathlib import Path
+
+from PIL import Image, ImageDraw
+
+
+def main():
+    root = Path(__file__).resolve().parents[1]/"runs"/"resolution_demo_input"
+    if root.exists():
+        raise SystemExit(f"Demo input already exists: {root}")
+    root.mkdir(parents=True)
+    for i, (width, height) in enumerate([(256, 256), (384, 256), (256, 384),
+                                        (255, 384), (257, 384), (512, 512)]):
+        image = Image.new("RGB", (width, height), (35+i*25, 60, 100))
+        draw = ImageDraw.Draw(image)
+        draw.rectangle((15, 15, width-15, height-15), outline="white", width=3)
+        draw.text((25, 25), f"{width}x{height}", fill="white")
+        path = root/f"{i:02d}_{width}x{height}.png"
+        image.save(path)
+        path.with_suffix(".txt").write_text(f"合成尺寸测试图：{width}×{height}。", encoding="utf-8")
+    (root/"broken.jpg").write_bytes(b"corrupt-fixture")
+    print(root)
+
+
+if __name__ == "__main__":
+    main()

image_cleaner/__init__.py

@@ -0,0 +1,3 @@
+"""Image-text dataset curation without changing source files."""
+
+__version__ = "0.3.0"

image_cleaner/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+import sys
+
+if __name__ == "__main__":
+    sys.exit(main())

image_cleaner/aspect.py

@@ -0,0 +1,26 @@
+"""Deterministic width:height matching with exact inclusive tolerance boundaries."""
+from fractions import Fraction
+from functools import lru_cache
+
+
+@lru_cache(maxsize=128)
+def tolerance_fraction(tolerance):
+    return Fraction(str(tolerance))
+
+
+def assess_aspect(row, config):
+    result = {"aspect_bucket": None, "aspect_bucket_nearest": None,
+              "aspect_bucket_deviation": None, "aspect_bucket_match": None}
+    if not config.aspect_buckets:
+        return result
+    distances = []
+    for bucket in config.aspect_buckets:
+        numerator, denominator = map(int, bucket.split(":"))
+        a, b = row["width"] * denominator, row["height"] * numerator
+        distances.append((Fraction(abs(a-b), min(a, b)), bucket))
+    # min is stable: ties follow the fixed preset order normalized by Config.
+    deviation, nearest = min(distances, key=lambda item: item[0])
+    matched = deviation == 0 if config.aspect_mode == "strict" else deviation <= tolerance_fraction(config.aspect_tolerance)
+    result.update(aspect_bucket=nearest if matched else None, aspect_bucket_nearest=nearest,
+                  aspect_bucket_deviation=float(deviation), aspect_bucket_match=matched)
+    return result

image_cleaner/cli.py

@@ -0,0 +1,135 @@
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+import sqlite3
+from dataclasses import replace
+
+from .config import load_config
+from .io import prepare
+from .jobs import analyze, export_images, merge
+
+
+def add_aspect_arguments(p):
+    p.add_argument("--aspect-buckets", help="Width:height buckets, e.g. 1:1,2:3,3:2; all selects eight presets; none disables")
+    p.add_argument("--aspect-mode", choices=["strict", "loose"], help="Exact ratio or approximate ratio (default: strict)")
+    p.add_argument("--aspect-tolerance", type=float, help="Symmetric relative deviation, inclusive; default 0.05 (5%%), loose mode only")
+
+
+def parser():
+    p = argparse.ArgumentParser(description="Batch image-text curation: inspect, shard, globally deduplicate, export")
+    sub = p.add_subparsers(dest="command", required=True)
+    prep = sub.add_parser("prepare", help="Freeze a recursive folder or JSONL input into a manifest")
+    prep.add_argument("--input", required=True)
+    prep.add_argument("--manifest", required=True)
+    prep.add_argument("--root", help="Base directory for relative image paths")
+    prep.add_argument("--sidecar-text", action="store_true", help="Read sibling UTF-8 .txt captions")
+    inspection = sub.add_parser("analyze", help="Analyze one deterministic rank, resume using SQLite checkpoints")
+    inspection.add_argument("--manifest", required=True)
+    inspection.add_argument("--output", required=True)
+    inspection.add_argument("--config")
+    inspection.add_argument("--resolution", help="Keep short edge >=256 (256p), exact size (256x256), or any")
+    inspection.add_argument("--root", help="Override dataset root on this node")
+    inspection.add_argument("--workers", type=int, default=min(8, os.cpu_count() or 1))
+    inspection.add_argument("--rank", type=int, default=0)
+    inspection.add_argument("--world-size", type=int, default=1)
+    inspection.add_argument("--resume", action="store_true")
+    combined = sub.add_parser("merge", aliases=["filter"], help="Re-filter all analyzed shards, globally deduplicate and report")
+    combined.add_argument("--shards", required=True)
+    combined.add_argument("--output", required=True)
+    combined.add_argument("--config", help="Optional new filtering thresholds; preprocessing must remain identical")
+    combined.add_argument("--resolution", help="Keep short edge >=256 (256p), exact size (256x256), or any; overrides config")
+    add_aspect_arguments(inspection)
+    add_aspect_arguments(combined)
+    export = sub.add_parser("export", help="Write normalized retained images to a separate directory")
+    export.add_argument("--curated", required=True)
+    export.add_argument("--output", required=True)
+    export.add_argument("--root", help="Override root if images have moved to another node")
+    export.add_argument("--workers", type=int, default=min(8, os.cpu_count() or 1))
+    export.add_argument("--resume", action="store_true")
+    run = sub.add_parser("run", help="Single-machine prepare + multiprocess analyze + global merge")
+    run.add_argument("--input", required=True)
+    run.add_argument("--output", required=True)
+    run.add_argument("--root")
+    run.add_argument("--config")
+    run.add_argument("--resolution", help="Keep short edge >=256 (256p), exact size (256x256), or any; overrides config")
+    run.add_argument("--workers", type=int, default=min(8, os.cpu_count() or 1))
+    run.add_argument("--sidecar-text", action="store_true")
+    run.add_argument("--export", action="store_true")
+    run.add_argument("--resume", action="store_true")
+    add_aspect_arguments(run)
+    return p
+
+
+def cli_config(args):
+    config = load_config(args.config)
+    return replace(config, **cli_overrides(args))
+
+
+def cli_overrides(args):
+    return {name: getattr(args, name) for name in
+            ("resolution", "aspect_buckets", "aspect_mode", "aspect_tolerance")
+            if getattr(args, name) is not None}
+
+
+def dispatch(args):
+    if args.command == "prepare":
+        return prepare(args.input, args.manifest, args.root, args.sidecar_text)
+    if args.command == "analyze":
+        return analyze(args.manifest, args.output, cli_config(args), args.workers,
+                       args.rank, args.world_size, args.root, args.resume)
+    if args.command in {"merge", "filter"}:
+        return merge(args.shards, args.output, load_config(args.config) if args.config else None, **cli_overrides(args))
+    if args.command == "export":
+        return export_images(args.curated, args.output, args.workers, args.root, args.resume)
+    output = Path(args.output).resolve()
+    input_path = Path(args.input).resolve()
+    if input_path.is_dir() and output.is_relative_to(input_path):
+        raise ValueError("Output must be outside the source image directory")
+    config = cli_config(args)
+    manifest = output/"input.jsonl"
+    run_identity = {"input": str(input_path), "config": config.fingerprint(),
+                    "root": str(Path(args.root).resolve()) if args.root else None,
+                    "sidecar_text": args.sidecar_text}
+    from .io import write_json, exclusive_lock
+    with exclusive_lock(output/"run.lock"):
+        identity_path = output/"run.meta.json"
+        if identity_path.exists():
+            existing = json.loads(identity_path.read_text(encoding="utf-8"))
+            if not args.resume or existing != run_identity:
+                raise ValueError("Run exists or identity changed; use --resume with the same input/config")
+        else:
+            write_json(identity_path, run_identity)
+        if not manifest.exists():
+            prepare(args.input, manifest, args.root, args.sidecar_text)
+        analyze(manifest, output/"shards", config, args.workers, root=args.root, resume=args.resume)
+        if (output/"curated"/"curation.sqlite").exists():
+            if not args.resume:
+                raise ValueError("Run already merged; use --resume")
+            result = json.loads((output/"curated"/"report.json").read_text(encoding="utf-8"))
+            result = {k: result[k] for k in ["input_count", "kept_count", "rejected_count", "duplicate_count", "error_count"]}
+        else:
+            result = merge(output/"shards", output/"curated")
+        if args.export:
+            result["export"] = export_images(output/"curated", output/"normalized", args.workers, args.root, args.resume)
+        return result
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    try:
+        result = dispatch(args)
+    except (ValueError, OSError, sqlite3.Error) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    if args.command == "export" and result.get("error", 0):
+        return 1
+    if args.command == "run" and result.get("export", {}).get("error", 0):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

image_cleaner/config.py

@@ -0,0 +1,148 @@
+from dataclasses import asdict, dataclass, fields
+import hashlib
+import json
+import math
+from pathlib import Path
+import re
+
+ASPECT_BUCKETS = ("1:1", "2:3", "3:2", "3:4", "4:3", "9:16", "16:9", "21:9")
+
+
+def normalize_aspect_buckets(value):
+    if value is None:
+        return None
+    if isinstance(value, str):
+        value = value.strip().lower()
+        if value == "none":
+            return None
+        if value == "all":
+            return ASPECT_BUCKETS
+        value = [part.strip() for part in value.split(",")]
+    if not isinstance(value, (tuple, list)) or not value:
+        raise ValueError("aspect_buckets must be a nonempty list, comma-separated buckets, all, or none")
+    if any(not isinstance(bucket, str) or bucket not in ASPECT_BUCKETS for bucket in value):
+        raise ValueError(f"Unsupported aspect bucket; choose from {ASPECT_BUCKETS}")
+    return tuple(bucket for bucket in ASPECT_BUCKETS if bucket in value)
+
+
+def normalize_resolution(value):
+    """Np is an inclusive short-edge lower bound; WxH is exact oriented width and height."""
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError("resolution must be a string such as 256p or 256x256, or null")
+    value = value.strip().lower().replace("\u00d7", "x")
+    if value in {"any", "none"}:
+        return None
+    if re.fullmatch(r"[1-9][0-9]*p", value) or re.fullmatch(r"[1-9][0-9]*x[1-9][0-9]*", value):
+        return value
+    raise ValueError("Invalid resolution: use 256p (short edge >=256), 256x256 (exact width/height), or any")
+
+
+@dataclass(frozen=True)
+class Config:
+    # None means measure only. Thresholds must be calibrated on the target corpus.
+    resolution: str | None = None
+    aspect_buckets: tuple[str, ...] | None = None
+    aspect_mode: str = "strict"
+    aspect_tolerance: float = 0.05
+    min_short_edge: int | None = None
+    max_long_edge: int | None = None
+    min_pixels: int | None = None
+    max_pixels: int | None = None
+    min_aspect_ratio: float | None = None
+    max_aspect_ratio: float | None = None
+    min_blur_score: float | None = None
+    max_noise_sigma: float | None = None
+    min_snr_proxy_db: float | None = None
+    max_blockiness: float | None = None
+    min_text_chars: int | None = None
+    max_text_chars: int | None = None
+    forbidden_text_patterns: tuple[str, ...] = ()
+    reject_animated: bool = True
+    max_decode_pixels: int = 100_000_000
+    metric_patch_size: int = 256
+    alpha_background: tuple[int, int, int] = (255, 255, 255)
+    convert_icc: bool = True
+    text_unicode_form: str = "NFC"
+    phash_distance: int = 4
+    dhash_distance: int = 4
+    near_rgb_rmse: float = 8.0
+    near_aspect_log_tolerance: float = 0.03
+    deduplicate: bool = True
+    near_deduplicate: bool = True
+    duplicate_scope: str = "image_text"
+    export_max_edge: int | None = None
+    export_format: str = "png"
+    export_jpeg_quality: int = 95
+
+    def __post_init__(self):
+        object.__setattr__(self, "resolution", normalize_resolution(self.resolution))
+        object.__setattr__(self, "aspect_buckets", normalize_aspect_buckets(self.aspect_buckets))
+        if self.aspect_mode not in {"strict", "loose"}:
+            raise ValueError("aspect_mode must be strict or loose")
+        numeric = [f.name for f in fields(self) if f.name.startswith(("min_", "max_"))]
+        numeric += ["near_rgb_rmse", "near_aspect_log_tolerance", "aspect_tolerance"]
+        for name in numeric:
+            value = getattr(self, name)
+            if value is not None and (isinstance(value, bool) or not isinstance(value, (int, float))
+                                      or not math.isfinite(value)):
+                raise ValueError(f"{name} must be a finite number or null")
+            if value is not None and name != "min_snr_proxy_db" and value < 0:
+                raise ValueError(f"{name} must be non-negative")
+        if self.aspect_tolerance is None:
+            raise ValueError("aspect_tolerance must be a finite non-negative number")
+        for lo, hi in [("min_aspect_ratio", "max_aspect_ratio"), ("min_pixels", "max_pixels"),
+                       ("min_text_chars", "max_text_chars")]:
+            if getattr(self, lo) is not None and getattr(self, hi) is not None:
+                if getattr(self, lo) > getattr(self, hi):
+                    raise ValueError(f"{lo} must not exceed {hi}")
+        for name in ["min_short_edge", "max_long_edge", "min_pixels", "max_pixels",
+                     "min_text_chars", "max_text_chars", "export_max_edge", "max_decode_pixels",
+                     "metric_patch_size", "phash_distance", "dhash_distance", "export_jpeg_quality"]:
+            value = getattr(self, name)
+            if value is not None and (type(value) is not int or value < 0):
+                raise ValueError(f"{name} must be a non-negative integer")
+        if not 0 <= self.phash_distance <= 8 or not 0 <= self.dhash_distance <= 64:
+            raise ValueError("phash_distance must be 0..8; dhash_distance must be 0..64")
+        if self.metric_patch_size < 16 or self.max_decode_pixels < 1:
+            raise ValueError("metric_patch_size >= 16 and max_decode_pixels >= 1 required")
+        if self.export_max_edge is not None and self.export_max_edge < 1:
+            raise ValueError("export_max_edge must be positive")
+        if self.export_format not in {"png", "jpeg"} or not 1 <= self.export_jpeg_quality <= 100:
+            raise ValueError("export_format must be png/jpeg and JPEG quality 1..100")
+        if self.text_unicode_form not in {"NFC", "NFKC", "none"}:
+            raise ValueError("text_unicode_form must be NFC, NFKC or none")
+        if self.duplicate_scope not in {"image", "image_text"}:
+            raise ValueError("duplicate_scope must be image or image_text")
+        if len(self.alpha_background) != 3 or any(type(v) is not int or not 0 <= v <= 255
+                                                 for v in self.alpha_background):
+            raise ValueError("alpha_background must contain three integers in 0..255")
+        for name in ["reject_animated", "convert_icc", "deduplicate", "near_deduplicate"]:
+            if type(getattr(self, name)) is not bool:
+                raise ValueError(f"{name} must be boolean")
+        for pattern in self.forbidden_text_patterns:
+            if not isinstance(pattern, str):
+                raise ValueError("forbidden_text_patterns must contain strings")
+            re.compile(pattern)
+
+    def to_dict(self):
+        return asdict(self)
+
+    def fingerprint(self):
+        return hashlib.sha256(json.dumps(self.to_dict(), sort_keys=True).encode()).hexdigest()
+
+
+def load_config(path=None):
+    values = {} if path is None else json.loads(Path(path).read_text(encoding="utf-8-sig"))
+    if not isinstance(values, dict):
+        raise ValueError("Configuration must be a JSON object")
+    unknown = set(values) - {f.name for f in fields(Config)}
+    if unknown:
+        raise ValueError(f"Unknown configuration fields: {sorted(unknown)}")
+    for key in ["alpha_background", "forbidden_text_patterns"]:
+        if key in values:
+            if not isinstance(values[key], list):
+                raise ValueError(f"{key} must be a JSON array")
+            values[key] = tuple(values[key])
+    return Config(**values)

image_cleaner/images.py

@@ -0,0 +1,137 @@
+from io import BytesIO
+import hashlib
+import re
+import unicodedata
+import warnings
+
+from PIL import Image, ImageCms, ImageOps
+
+from .config import Config
+from .metrics import difference_hash, perceptual_hash, quality_metrics, thumbnail_signature
+
+
+def normalize_text(text, form):
+    if text is None:
+        return None
+    if not isinstance(text, str):
+        raise ValueError("text must be a string or null")
+    if form != "none":
+        text = unicodedata.normalize(form, text)
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    return "\n".join(line.rstrip() for line in text.split("\n")).strip()
+
+
+def canonical_image(path, config):
+    """Load one static image, transpose EXIF, color-manage, flatten alpha, return RGB."""
+    Image.MAX_IMAGE_PIXELS = config.max_decode_pixels
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", Image.DecompressionBombWarning)
+        with Image.open(path) as source:
+            w, h = source.size
+            if w * h > config.max_decode_pixels:
+                raise ValueError("decode_pixel_limit")
+            metadata = {"original_width": w, "original_height": h, "original_mode": source.mode,
+                        "original_format": source.format, "frame_count": getattr(source, "n_frames", 1)}
+            if metadata["frame_count"] > 1 and config.reject_animated:
+                raise ValueError("animated_or_multipage")
+            source.load()  # Detect truncated data even if metadata parsing succeeded.
+            oriented = ImageOps.exif_transpose(source)
+            metadata["exif_transposed"] = source.getexif().get(274, 1) not in (1, None)
+            alpha = None
+            if "A" in oriented.getbands() or "transparency" in oriented.info:
+                alpha = oriented.convert("RGBA").getchannel("A")
+            metadata["alpha_flattened"] = alpha is not None
+            icc = oriented.info.get("icc_profile")
+            metadata["icc_converted"] = False
+            if icc and config.convert_icc:
+                # RGB profiles cannot consume RGBA/P directly; CMYK profiles require CMYK input.
+                mode = oriented.mode if oriented.mode in {"RGB", "CMYK", "LAB", "L"} else "RGB"
+                oriented = ImageCms.profileToProfile(oriented.convert(mode),
+                    ImageCms.ImageCmsProfile(BytesIO(icc)), ImageCms.createProfile("sRGB"), outputMode="RGB")
+                metadata["icc_converted"] = True
+            rgb = oriented.convert("RGB")
+            if alpha is not None:
+                background = Image.new("RGB", rgb.size, config.alpha_background)
+                background.paste(rgb, mask=alpha)
+                rgb = background
+            return rgb.copy(), metadata
+
+
+def resolution_matches(row, resolution):
+    if resolution is None:
+        return True
+    if resolution.endswith("p"):
+        return row["short_edge"] >= int(resolution[:-1])
+    width, height = map(int, resolution.split("x"))
+    return row["width"] == width and row["height"] == height
+
+
+def filter_reasons(row, config):
+    from .aspect import assess_aspect
+    row.update(assess_aspect(row, config))
+    checks = [("short_edge", config.min_short_edge, "min_short_edge", "min"),
+              ("long_edge", config.max_long_edge, "max_long_edge", "max"),
+              ("pixels", config.min_pixels, "min_pixels", "min"),
+              ("pixels", config.max_pixels, "max_pixels", "max"),
+              ("aspect_ratio", config.min_aspect_ratio, "min_aspect_ratio", "min"),
+              ("aspect_ratio", config.max_aspect_ratio, "max_aspect_ratio", "max"),
+              ("blur_score", config.min_blur_score, "min_blur_score", "min"),
+              ("noise_sigma", config.max_noise_sigma, "max_noise_sigma", "max"),
+              ("snr_proxy_db", config.min_snr_proxy_db, "min_snr_proxy_db", "min"),
+              ("blockiness", config.max_blockiness, "max_blockiness", "max")]
+    reasons = []
+    if not resolution_matches(row, config.resolution):
+        reasons.append("resolution_mismatch")
+    if row["aspect_bucket_match"] is False:
+        reasons.append("aspect_bucket_mismatch")
+    for key, threshold, name, direction in checks:
+        value = row.get(key)
+        if threshold is not None and value is not None:
+            if (direction == "min" and value < threshold) or (direction == "max" and value > threshold):
+                reasons.append(name)
+    text = row.get("text")
+    if config.min_text_chars is not None and len(text or "") < config.min_text_chars:
+        reasons.append("min_text_chars")
+    if config.max_text_chars is not None and len(text or "") > config.max_text_chars:
+        reasons.append("max_text_chars")
+    if any(re.search(p, text or "") for p in config.forbidden_text_patterns):
+        reasons.append("forbidden_text_pattern")
+    return reasons
+
+
+def analyze_one(task):
+    item, path, config_dict = task
+    config = Config(**config_dict)
+    row = dict(item)
+    row.update({"source_path": str(path), "status": "error", "reasons": [], "warnings": []})
+    try:
+        row["text"] = normalize_text(item.get("text"), config.text_unicode_form)
+        digest = hashlib.sha256()
+        with open(path, "rb") as handle:
+            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                digest.update(chunk)
+        row["file_sha256"] = digest.hexdigest()
+        rgb, metadata = canonical_image(path, config)
+        row.update(metadata)
+        w, h = rgb.size
+        row.update(width=w, height=h, short_edge=min(w, h), long_edge=max(w, h),
+                   pixels=w*h, aspect_ratio=w/h)
+        pixel_hash = hashlib.sha256(f"RGB:{w}:{h}:".encode())
+        # Hash in strips to avoid making another full-size image bytes allocation.
+        for y in range(0, h, 128):
+            pixel_hash.update(rgb.crop((0, y, w, min(y+128, h))).tobytes())
+        row["pixel_sha256"] = pixel_hash.hexdigest()
+        row["phash"] = perceptual_hash(rgb)
+        row["dhash"] = difference_hash(rgb)
+        row["thumbnail"] = thumbnail_signature(rgb)
+        row.update(quality_metrics(rgb, config.metric_patch_size))
+        if row["snr_proxy_db"] is None:
+            row["warnings"].append("snr_proxy_undefined")
+        row["reasons"] = filter_reasons(row, config)
+        row["status"] = "rejected" if row["reasons"] else "candidate"
+        rgb.close()
+    except Exception as exc:
+        row["status"] = "error"
+        row["reasons"] = ["decode_or_processing_error"]
+        row["error"] = f"{type(exc).__name__}: {exc}"
+    return row

image_cleaner/io.py

@@ -0,0 +1,192 @@
+from concurrent.futures import FIRST_COMPLETED, ProcessPoolExecutor, wait
+from contextlib import contextmanager
+import hashlib
+import json
+import os
+from pathlib import Path
+import sqlite3
+import tempfile
+
+EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp", ".bmp", ".tif", ".tiff", ".gif", ".avif"}
+
+
+def json_line(value):
+    return json.dumps(value, ensure_ascii=False, allow_nan=False, separators=(",", ":")) + "\n"
+
+
+def sha256_file(path):
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+@contextmanager
+def atomic_text(path):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=path.name + ".", suffix=".tmp", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
+            yield handle
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def write_json(path, value):
+    with atomic_text(path) as handle:
+        json.dump(value, handle, ensure_ascii=False, allow_nan=False, indent=2)
+        handle.write("\n")
+
+
+def walk_images(root):
+    # Stable traversal independent of filesystem enumeration order; directory lists only.
+    for directory, dirs, files in os.walk(root, followlinks=False):
+        dirs[:] = sorted(d for d in dirs if not (Path(directory)/d).is_symlink())
+        for name in sorted(files):
+            path = Path(directory)/name
+            if path.suffix.lower() in EXTENSIONS:
+                yield path
+
+
+def prepare(input_path, manifest, root=None, sidecar_text=False):
+    input_path, manifest = Path(input_path).resolve(), Path(manifest).resolve()
+    if not input_path.exists():
+        raise ValueError(f"Input does not exist: {input_path}")
+    if input_path == manifest:
+        raise ValueError("Input and output manifest must differ")
+    if manifest.exists():
+        raise ValueError(f"Manifest already exists: {manifest}; choose a new path")
+    base = Path(root).resolve() if root else (input_path if input_path.is_dir() else input_path.parent)
+    # Output inside the input tree can be accidentally re-imported on subsequent runs.
+    if input_path.is_dir() and manifest.is_relative_to(input_path):
+        raise ValueError("Place the manifest outside the input image directory")
+    count = 0
+    if input_path.is_dir():
+        def entries():
+            for path in walk_images(input_path):
+                try:
+                    relative = path.relative_to(base).as_posix()
+                except ValueError as exc:
+                    raise ValueError("All discovered images must be beneath --root") from exc
+                item = {"path": relative}
+                txt = path.with_suffix(".txt")
+                if sidecar_text and txt.exists():
+                    item["text"] = txt.read_text(encoding="utf-8-sig")
+                yield item
+    else:
+        def entries():
+            with input_path.open(encoding="utf-8-sig") as handle:
+                for line_no, line in enumerate(handle, 1):
+                    if not line.strip():
+                        continue
+                    try:
+                        item = json.loads(line)
+                    except json.JSONDecodeError as exc:
+                        raise ValueError(f"Invalid JSON at input line {line_no}") from exc
+                    if not isinstance(item, dict) or not isinstance(item.get("path"), str):
+                        raise ValueError(f"Input line {line_no} requires a string path")
+                    if item.get("text") is not None and not isinstance(item["text"], str):
+                        raise ValueError(f"Input line {line_no}: text must be string/null")
+                    if "metadata" in item and not isinstance(item["metadata"], dict):
+                        raise ValueError(f"Input line {line_no}: metadata must be an object")
+                    # Preserve caption identity and arbitrary fields inside metadata to avoid
+                    # collisions with computed metrics (e.g. an input field named width).
+                    known = {"path", "text", "id", "metadata"}
+                    metadata = dict(item.get("metadata", {}))
+                    metadata.update({k: v for k, v in item.items() if k not in known})
+                    yield {"path": item["path"], "text": item.get("text"),
+                           "source_id": item.get("id"), "metadata": metadata}
+    with atomic_text(manifest) as handle:
+        for item in entries():
+            item["seq"] = count
+            item["id"] = f"sample-{count:012d}"
+            handle.write(json_line(item))
+            count += 1
+    if count == 0:
+        manifest.unlink()
+        raise ValueError("No images or manifest records found")
+    metadata = {"schema_version": 1, "count": count, "root": str(base),
+                "sha256": sha256_file(manifest)}
+    write_json(str(manifest) + ".meta.json", metadata)
+    return metadata
+
+
+def manifest_info(manifest, root=None):
+    manifest = Path(manifest).resolve()
+    metadata = json.loads(Path(str(manifest) + ".meta.json").read_text(encoding="utf-8"))
+    if metadata["sha256"] != sha256_file(manifest):
+        raise ValueError("Manifest has changed after prepare; prepare a new manifest")
+    base = Path(root or metadata["root"]).resolve()
+    return metadata, base
+
+
+def manifest_items(manifest):
+    with Path(manifest).open(encoding="utf-8") as handle:
+        for line in handle:
+            yield json.loads(line)
+
+
+def resolve_source(base, item):
+    path = Path(item["path"])
+    return path if path.is_absolute() else base/path
+
+
+@contextmanager
+def exclusive_lock(path):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        descriptor = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+    except FileExistsError as exc:
+        raise ValueError(f"Job is locked: {path}. If no job is running, remove its stale lock.") from exc
+    try:
+        os.write(descriptor, str(os.getpid()).encode())
+        os.close(descriptor)
+        yield
+    finally:
+        path.unlink(missing_ok=True)
+
+
+def connect(path):
+    db = sqlite3.connect(path)
+    db.execute("PRAGMA journal_mode=WAL")
+    db.execute("PRAGMA synchronous=NORMAL")
+    db.execute("PRAGMA cache_size=-32768")  # 32 MiB bounded page cache.
+    db.execute("PRAGMA temp_store=FILE")
+    return db
+
+
+def get_meta(db, key):
+    row = db.execute("SELECT value FROM metadata WHERE key=?", (key,)).fetchone()
+    return json.loads(row[0]) if row else None
+
+
+def set_meta(db, key, value):
+    db.execute("INSERT OR REPLACE INTO metadata VALUES (?,?)", (key, json.dumps(value)))
+
+
+def parallel_bounded(function, iterable, workers):
+    """At most 2*workers futures in memory, unlike eager Executor.map in Python <=3.13."""
+    if workers == 1:
+        yield from map(function, iterable)
+        return
+    iterator = iter(iterable)
+    with ProcessPoolExecutor(max_workers=workers) as pool:
+        pending = set()
+        exhausted = False
+        while pending or not exhausted:
+            while not exhausted and len(pending) < 2 * workers:
+                try:
+                    pending.add(pool.submit(function, next(iterator)))
+                except StopIteration:
+                    exhausted = True
+            if pending:
+                done, pending = wait(pending, return_when=FIRST_COMPLETED)
+                for future in done:
+                    yield future.result()

image_cleaner/jobs.py

@@ -0,0 +1,382 @@
+from collections import Counter
+from contextlib import closing
+from dataclasses import replace
+import hashlib
+import json
+import math
+from pathlib import Path
+import sqlite3
+import time
+from PIL import Image
+
+from . import __version__
+from .config import Config
+from .images import analyze_one, canonical_image, filter_reasons, resolution_matches
+from .io import (atomic_text, connect, exclusive_lock, get_meta, json_line, manifest_info,
+                 manifest_items, parallel_bounded, resolve_source, set_meta, sha256_file, write_json)
+from .metrics import thumbnail_rmse
+from .stats import DatasetStats, write_html
+
+
+def analyze(manifest, output, config, workers=1, rank=0, world_size=1, root=None, resume=False):
+    if workers < 1 or world_size < 1 or not 0 <= rank < world_size:
+        raise ValueError("workers/world-size must be positive and 0 <= rank < world-size")
+    info, base = manifest_info(manifest, root)
+    output = Path(output).resolve()
+    output.mkdir(parents=True, exist_ok=True)
+    path = output/f"shard-{rank:05d}-of-{world_size:05d}.sqlite"
+    expected_count = max(0, (info["count"] - 1 - rank) // world_size + 1)
+    identity = {"schema_version": 1, "software_version": __version__, "manifest_sha256": info["sha256"],
+                "input_count": info["count"], "rank": rank, "world_size": world_size,
+                "config_sha256": config.fingerprint(), "config": config.to_dict()}
+    # JSON normalizes tuple/list values for consistent equality after restart.
+    identity = json.loads(json.dumps(identity))
+    with exclusive_lock(str(path) + ".lock"):
+        exists = path.exists()
+        if exists and not resume:
+            raise ValueError(f"Shard already exists: {path}; use --resume")
+        db = connect(path)
+        try:
+            db.execute("CREATE TABLE IF NOT EXISTS metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+            db.execute("CREATE TABLE IF NOT EXISTS records (seq INTEGER PRIMARY KEY, payload TEXT NOT NULL)")
+            stored = get_meta(db, "identity")
+            if exists and stored != identity:
+                raise ValueError("Resume identity mismatch (manifest, config, ranks or software changed)")
+            set_meta(db, "identity", identity)
+            set_meta(db, "complete", False)
+            db.commit()
+            config_dict = config.to_dict()
+            def tasks():
+                for item in manifest_items(manifest):
+                    if item["seq"] % world_size != rank:
+                        continue
+                    if db.execute("SELECT 1 FROM records WHERE seq=?", (item["seq"],)).fetchone():
+                        continue
+                    yield item, str(resolve_source(base, item)), config_dict
+            count = 0
+            started = time.monotonic()
+            for row in parallel_bounded(analyze_one, tasks(), workers):
+                db.execute("INSERT INTO records VALUES (?,?)", (row["seq"], json_line(row)))
+                count += 1
+                if count % 100 == 0:
+                    db.commit()
+                    print(f"rank {rank}: analyzed {count} new images ({count/max(.01, time.monotonic()-started):.1f}/s)", flush=True)
+            db.commit()
+            total = db.execute("SELECT COUNT(*) FROM records").fetchone()[0]
+            if total != expected_count:
+                raise ValueError(f"Shard incomplete: expected {expected_count}, got {total}")
+            set_meta(db, "complete", True)
+            db.commit()
+            with atomic_text(path.with_suffix(".jsonl")) as handle:
+                for (payload,) in db.execute("SELECT payload FROM records ORDER BY seq"):
+                    handle.write(payload)
+            db.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+        finally:
+            db.close()
+    return {"shard": str(path), "records": total, "new_records": count}
+
+
+def hash_bands(value, radius):
+    """Pigeonhole guarantee: hashes at distance <=r share one of r+1 exact bands."""
+    integer = int(value, 16)
+    parts = radius+1
+    offset = 0
+    for part in range(parts):
+        width = 64//parts + (1 if part < 64 % parts else 0)
+        yield part, f"{(integer >> offset) & ((1 << width)-1):x}"
+        offset += width
+
+
+class DuplicateIndex:
+    """Disk-backed global index; only eligible retained representatives enter it."""
+    def __init__(self, db, config):
+        self.db, self.config = db, config
+        db.execute("CREATE TABLE hashes (kind TEXT, hash TEXT, owner INTEGER, PRIMARY KEY(kind,hash))")
+        db.execute("CREATE TABLE bands (part INTEGER, value TEXT, owner INTEGER)")
+        db.execute("CREATE INDEX band_lookup ON bands(part,value)")
+        db.execute("CREATE TABLE representatives (seq INTEGER PRIMARY KEY, payload TEXT NOT NULL)")
+
+    def find(self, row):
+        if not self.config.deduplicate:
+            return None
+        for kind, key in [("file", "file_sha256"), ("pixels", "pixel_sha256")]:
+            result = self.db.execute("SELECT owner FROM hashes WHERE kind=? AND hash=?", (kind, self.key(row, key))).fetchone()
+            if result:
+                return result[0], "exact_file" if kind == "file" else "exact_pixels", None
+        if not self.config.near_deduplicate:
+            return None
+        bands = list(hash_bands(row["phash"], self.config.phash_distance))
+        predicates = " OR ".join("(part=? AND value=?)" for _ in bands)
+        args = [v for band in bands for v in band]
+        query = ("SELECT r.seq,r.payload FROM representatives r JOIN "
+                 f"(SELECT DISTINCT owner FROM bands WHERE {predicates}) b ON r.seq=b.owner ORDER BY r.seq")
+        # Stream candidates from SQLite; repetitive corpora can produce large candidate sets.
+        for seq, payload in self.db.execute(query, args):
+            other = json.loads(payload)
+            if self.config.duplicate_scope == "image_text" and (row.get("text") or "") != (other.get("text") or ""):
+                continue
+            distance = (int(row["phash"], 16) ^ int(other["phash"], 16)).bit_count()
+            if distance > self.config.phash_distance:
+                continue
+            if (int(row["dhash"], 16) ^ int(other["dhash"], 16)).bit_count() > self.config.dhash_distance:
+                continue
+            if abs(math.log(row["aspect_ratio"]/other["aspect_ratio"])) > self.config.near_aspect_log_tolerance:
+                continue
+            rmse = thumbnail_rmse(row["thumbnail"], other["thumbnail"])
+            if rmse <= self.config.near_rgb_rmse:
+                return seq, "near_perceptual", {"phash_distance": distance, "thumbnail_rgb_rmse": rmse}
+        return None
+
+    def insert(self, row):
+        if not self.config.deduplicate:
+            return
+        for kind, key in [("file", "file_sha256"), ("pixels", "pixel_sha256")]:
+            self.db.execute("INSERT INTO hashes VALUES (?,?,?)", (kind, self.key(row, key), row["seq"]))
+        if self.config.near_deduplicate:
+            self.db.execute("INSERT INTO representatives VALUES (?,?)", (row["seq"], json_line(row)))
+            self.db.executemany("INSERT INTO bands VALUES (?,?,?)", [(p, value, row["seq"])
+                                for p, value in hash_bands(row["phash"], self.config.phash_distance)])
+
+    def key(self, row, key):
+        if self.config.duplicate_scope == "image":
+            return row[key]
+        text_hash = hashlib.sha256((row.get("text") or "").encode("utf-8")).hexdigest()
+        return row[key] + ":" + text_hash
+
+
+ANALYSIS_FIELDS = ["reject_animated", "max_decode_pixels", "metric_patch_size", "alpha_background",
+                   "convert_icc", "text_unicode_form"]
+
+
+def merge(shard_dir, output, config=None, resolution=None, aspect_buckets=None, aspect_mode=None, aspect_tolerance=None):
+    shard_dir, output = Path(shard_dir).resolve(), Path(output).resolve()
+    paths = sorted(shard_dir.glob("shard-*-of-*.sqlite"))
+    if not paths:
+        raise ValueError("No shard SQLite databases found")
+    output.mkdir(parents=True, exist_ok=True)
+    destination = output/"curation.sqlite"
+    with exclusive_lock(output/"merge.lock"):
+        if destination.exists():
+            raise ValueError("Merge output already exists; choose a new output directory to re-filter")
+        identities = []
+        for path in paths:
+            with closing(sqlite3.connect(path.as_uri() + "?mode=ro", uri=True)) as source:
+                identity = get_meta(source, "identity")
+                if not get_meta(source, "complete"):
+                    raise ValueError(f"Shard is incomplete: {path}")
+                identities.append(identity)
+        first = identities[0]
+        if any({k: v for k, v in identity.items() if k != "rank"} !=
+               {k: v for k, v in first.items() if k != "rank"} for identity in identities):
+            raise ValueError("Shard identities do not match")
+        if sorted(i["rank"] for i in identities) != list(range(first["world_size"])):
+            raise ValueError("Missing or duplicate shard ranks; all ranks are required for global deduplication")
+        source_config = Config(**first["config"])
+        config = config or source_config
+        overrides = {name: value for name, value in
+                     (("resolution", resolution), ("aspect_buckets", aspect_buckets),
+                      ("aspect_mode", aspect_mode), ("aspect_tolerance", aspect_tolerance)) if value is not None}
+        config = replace(config, **overrides)
+        for key in ANALYSIS_FIELDS:
+            if json.dumps(getattr(config, key)) != json.dumps(getattr(source_config, key)):
+                raise ValueError(f"Cannot re-filter with changed analysis setting {key}; analyze again")
+        temporary = output/"curation.building.sqlite"
+        if temporary.exists():
+            raise ValueError("Previous incomplete merge exists; choose a new output directory")
+        db = connect(temporary)
+        try:
+            db.execute("CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+            db.execute("CREATE TABLE records (seq INTEGER PRIMARY KEY, payload TEXT NOT NULL, status TEXT NOT NULL,"
+                       "pixels INTEGER NOT NULL, noise REAL NOT NULL, blur REAL NOT NULL)")
+            for path, identity in zip(paths, identities):
+                shard_count = 0
+                with closing(sqlite3.connect(path.as_uri() + "?mode=ro", uri=True)) as source:
+                    for seq, payload in source.execute("SELECT seq,payload FROM records ORDER BY seq"):
+                        row = json.loads(payload)
+                        if seq != row["seq"] or seq % first["world_size"] != identity["rank"] or not 0 <= seq < first["input_count"]:
+                            raise ValueError(f"Invalid shard sequence: {path}, {seq}")
+                        if row["status"] != "error":
+                            row["reasons"] = filter_reasons(row, config)
+                            row["status"] = "rejected" if row["reasons"] else "candidate"
+                        db.execute("INSERT INTO records VALUES (?,?,?,?,?,?)", (seq, json_line(row), row["status"],
+                                   row.get("pixels", 0), row.get("noise_sigma") or 0, row.get("blur_score") or 0))
+                        shard_count += 1
+                        if shard_count % 1000 == 0:
+                            db.commit()
+                expected = max(0, (first["input_count"]-1-identity["rank"])//first["world_size"]+1)
+                if shard_count != expected:
+                    raise ValueError(f"Wrong record count in {path}: {shard_count}, expected {expected}")
+            total = db.execute("SELECT COUNT(*) FROM records").fetchone()[0]
+            if total != first["input_count"]:
+                raise ValueError("Global record count does not match manifest")
+            db.execute("CREATE INDEX candidate_order ON records(status,pixels DESC,noise,blur DESC,seq)")
+            db.commit()
+            index = DuplicateIndex(db, config)
+            processed = 0
+            # Fetch bounded batches, then update status. The indexed candidate set shrinks.
+            while True:
+                batch = db.execute("SELECT seq,payload,pixels,noise,blur FROM records WHERE status='candidate' "
+                                   "ORDER BY pixels DESC,noise,blur DESC,seq LIMIT 500").fetchall()
+                if not batch:
+                    break
+                for seq, payload, pixels, noise, blur in batch:
+                    row = json.loads(payload)
+                    duplicate = index.find(row)
+                    if duplicate:
+                        owner, kind, metrics = duplicate
+                        row.update(status="duplicate", duplicate_of=f"sample-{owner:012d}",
+                                   duplicate_kind=kind, duplicate_metrics=metrics, reasons=[kind])
+                    else:
+                        row["status"] = "kept"
+                        index.insert(row)
+                    db.execute("UPDATE records SET payload=?,status=? WHERE seq=?", (json_line(row), row["status"], seq))
+                    processed += 1
+                db.commit()
+                print(f"global dedup: {processed} eligible images processed", flush=True)
+            before, after = DatasetStats(), DatasetStats()
+            resolution_matched = 0
+            aspect_matched = 0
+            bucket_before = dict.fromkeys(config.aspect_buckets or (), 0)
+            bucket_after = dict.fromkeys(config.aspect_buckets or (), 0)
+            destinations = {status: output/f"{status}.jsonl" for status in ["kept", "rejected", "duplicate", "error"]}
+            # SQLite is the authoritative output. JSONL and reports are streamed from it.
+            from contextlib import ExitStack
+            with ExitStack() as stack:
+                handles = {status: stack.enter_context(atomic_text(path)) for status, path in destinations.items()}
+                for (payload,) in db.execute("SELECT payload FROM records ORDER BY seq"):
+                    row = json.loads(payload)
+                    before.add(row)
+                    if row["status"] != "error":
+                        if row["aspect_bucket_match"] is not False:
+                            aspect_matched += 1
+                        if row["aspect_bucket"] is not None:
+                            bucket_before[row["aspect_bucket"]] += 1
+                            if row["status"] == "kept":
+                                bucket_after[row["aspect_bucket"]] += 1
+                    if row["status"] != "error" and resolution_matches(row, config.resolution):
+                        resolution_matched += 1
+                    if row["status"] == "kept":
+                        after.add(row)
+                    handles[row["status"]].write(payload)
+            counts = before.statuses
+            decoded = before.decoded
+            eligible = counts["kept"] + counts["duplicate"]
+            def rate(numerator, denominator):
+                return numerator / denominator if denominator else None
+            stage_metrics = {
+                "processing_success_count": decoded,
+                "processing_success_rate": rate(decoded, total),
+                "resolution_matched_count": resolution_matched,
+                "resolution_mismatched_count": decoded-resolution_matched,
+                "resolution_pass_rate": rate(resolution_matched, decoded),
+                "aspect_bucket_matched_count": aspect_matched,
+                "aspect_bucket_mismatched_count": decoded-aspect_matched,
+                "aspect_bucket_pass_rate": rate(aspect_matched, decoded),
+                "rules_eligible_count": eligible,
+                "rules_pass_rate": rate(eligible, decoded),
+                "duplicate_rate_among_eligible": rate(counts["duplicate"], eligible),
+                "final_keep_rate": rate(counts["kept"], total),
+            }
+            report = {"schema_version": 1, "software_version": __version__, "manifest_sha256": first["manifest_sha256"],
+                      "config": config.to_dict(), "input_count": total, "kept_count": counts["kept"],
+                      "rejected_count": counts["rejected"], "duplicate_count": counts["duplicate"], "error_count": counts["error"],
+                      "dedup_representative_order": "pixels DESC, noise_sigma ASC, blur_score DESC, seq ASC",
+                      "resolution_filter": {"requested": config.resolution, "basis": "dimensions_after_exif_transpose",
+                                            "mode": "short_edge_gte" if config.resolution and config.resolution.endswith("p")
+                                                    else "width_height" if config.resolution else "disabled",
+                                            "comparison": ">=" if config.resolution and config.resolution.endswith("p")
+                                                          else "==" if config.resolution else None},
+                      "stage_metrics": stage_metrics,
+                      "aspect_bucket_filter": {"enabled": config.aspect_buckets is not None,
+                                               "selected_buckets": config.aspect_buckets or (),
+                                               "mode": config.aspect_mode, "tolerance": config.aspect_tolerance,
+                                               "basis": "dimensions_after_exif_transpose",
+                                               "deviation": "max(r/b,b/r)-1",
+                                               "counts_before": bucket_before, "counts_after": bucket_after},
+                      "before": before.result(), "after": after.result()}
+            set_meta(db, "report", report)
+            set_meta(db, "complete", True)
+            db.commit()
+            db.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+            # Leave no WAL dependency when publishing the database.
+            db.execute("PRAGMA journal_mode=DELETE")
+        finally:
+            db.close()
+        temporary.replace(destination)
+        write_json(output/"report.json", report)
+        write_html(output/"report.html", report)
+    return {k: report[k] for k in ["input_count", "kept_count", "rejected_count", "duplicate_count", "error_count"]}
+
+
+def export_images(curated_dir, output, workers=1, root=None, resume=False):
+    curated_dir, output = Path(curated_dir).resolve(), Path(output).resolve()
+    if workers < 1:
+        raise ValueError("workers must be positive")
+    output.mkdir(parents=True, exist_ok=True)
+    report = json.loads((curated_dir/"report.json").read_text(encoding="utf-8"))
+    config = Config(**report["config"])
+    fingerprint = hashlib.sha256(json.dumps({"manifest": report["manifest_sha256"], "config": config.to_dict()},
+                                           sort_keys=True).encode()).hexdigest()
+    with exclusive_lock(output/"export.lock"):
+        meta_path = output/"export.meta.json"
+        if meta_path.exists():
+            meta = json.loads(meta_path.read_text(encoding="utf-8"))
+            if not resume or meta["fingerprint"] != fingerprint:
+                raise ValueError("Export already exists or configuration differs; choose a new output directory")
+        elif any(output.iterdir()):
+            # Only the lock is present for a new destination.
+            if any(p.name != "export.lock" for p in output.iterdir()):
+                raise ValueError("Export destination must be empty")
+        write_json(meta_path, {"fingerprint": fingerprint, "complete": False})
+        def tasks():
+            for item in manifest_items(curated_dir/"kept.jsonl"):
+                path = resolve_source(Path(root).resolve(), item) if root else Path(item["source_path"])
+                target = output/"images"/f'{item["seq"]//10000:06d}'/(item["id"] + "." + ("jpg" if config.export_format == "jpeg" else "png"))
+                yield item, str(path), str(target), config.to_dict(), resume
+        counts = Counter()
+        with atomic_text(output/"exported.jsonl") as retained, atomic_text(output/"export_errors.jsonl") as errors:
+            for result in parallel_bounded(export_one, tasks(), workers):
+                status = result.pop("export_status")
+                counts[status] += 1
+                if status == "ok":
+                    result["source_path"] = result.pop("path")
+                    result["path"] = Path(result.pop("output_path")).relative_to(output).as_posix()
+                    retained.write(json_line(result))
+                else:
+                    errors.write(json_line(result))
+        write_json(meta_path, {"fingerprint": fingerprint, "complete": counts["error"] == 0,
+                              "exported": counts["ok"], "errors": counts["error"]})
+    return dict(counts)
+
+
+def export_one(task):
+    item, source, target, config_dict, resume = task
+    result = {"id": item["id"], "path": source, "text": item.get("text"),
+              "metadata": item.get("metadata", {}), "source_id": item.get("source_id")}
+    config = Config(**config_dict)
+    target = Path(target)
+    receipt = target.with_suffix(target.suffix + ".receipt.json")
+    try:
+        # Resume assumes the frozen manifest but verifies the actual source bytes.
+        if sha256_file(source) != item["file_sha256"]:
+            raise ValueError("Source changed after analysis")
+        if resume and target.exists() and receipt.exists():
+            saved = json.loads(receipt.read_text(encoding="utf-8"))
+            if saved["source_sha256"] == item["file_sha256"] and saved["output_sha256"] == sha256_file(target):
+                result.update(export_status="ok", output_path=str(target), width=saved["width"], height=saved["height"])
+                return result
+        rgb, _ = canonical_image(source, config)
+        if config.export_max_edge:
+            rgb.thumbnail((config.export_max_edge, config.export_max_edge), resample=Image.Resampling.LANCZOS)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        temporary = target.with_suffix(target.suffix + ".tmp")
+        save_options = {"quality": config.export_jpeg_quality, "subsampling": 0} if config.export_format == "jpeg" else {}
+        rgb.save(temporary, format=config.export_format.upper(), **save_options)
+        temporary.replace(target)
+        write_json(receipt, {"source_sha256": item["file_sha256"], "output_sha256": sha256_file(target),
+                             "width": rgb.width, "height": rgb.height})
+        result.update(export_status="ok", output_path=str(target), width=rgb.width, height=rgb.height)
+        rgb.close()
+    except Exception as exc:
+        result.update(export_status="error", error=f"{type(exc).__name__}: {exc}")
+    return result

image_cleaner/metrics.py

@@ -0,0 +1,91 @@
+"""Native-pixel patch metrics; noise and SNR are proxies, not reference-based PSNR."""
+import base64
+from functools import lru_cache
+import math
+
+import numpy as np
+from PIL import Image
+
+
+@lru_cache(maxsize=1)
+def dct_basis():
+    x = np.arange(32)
+    k = np.arange(8)[:, None]
+    return np.cos(np.pi * (2 * x + 1) * k / 64)
+
+
+def perceptual_hash(image):
+    gray = np.asarray(image.convert("L").resize((32, 32), Image.Resampling.LANCZOS), dtype=np.float64)
+    dct = dct_basis() @ gray @ dct_basis().T
+    values = dct.flatten()
+    # Sparse/flat images contain coefficients near numerical zero. Their signs are
+    # unstable after JPEG recompression, so ignore values negligible relative to AC.
+    tolerance = max(1e-6, float(np.max(np.abs(values[1:]))) * 1e-3)
+    values[np.abs(values) <= tolerance] = 0
+    bits = values > np.median(values[1:]) + tolerance
+    bits[0] = False  # DC is brightness, not spatial content.
+    return f"{int.from_bytes(np.packbits(bits).tobytes(), 'big'):016x}"
+
+
+def difference_hash(image):
+    gray = np.asarray(image.convert("L").resize((9, 8), Image.Resampling.LANCZOS))
+    return f"{int.from_bytes(np.packbits(gray[:, 1:] > gray[:, :-1]).tobytes(), 'big'):016x}"
+
+
+def thumbnail_signature(image):
+    data = np.asarray(image.resize((16, 16), Image.Resampling.LANCZOS), dtype=np.uint8)
+    return base64.b64encode(data.tobytes()).decode("ascii")
+
+
+def thumbnail_rmse(a, b):
+    x = np.frombuffer(base64.b64decode(a), dtype=np.uint8).astype(np.float64)
+    y = np.frombuffer(base64.b64decode(b), dtype=np.uint8).astype(np.float64)
+    return float(np.sqrt(np.mean((x - y) ** 2)))
+
+
+def patch_metrics(gray):
+    if min(gray.shape) < 3:
+        return {"blur_score": None, "noise_sigma": None, "snr_proxy_db": None,
+                "blockiness": None, "luminance": float(gray.mean()), "contrast": float(gray.std())}
+    center = gray[1:-1, 1:-1]
+    up, down = gray[:-2, 1:-1], gray[2:, 1:-1]
+    left, right = gray[1:-1, :-2], gray[1:-1, 2:]
+    lap = up + down + left + right - 4 * center
+    # High-pass kernel has L2 norm 6. Restrict estimation to low-gradient regions.
+    high = (gray[:-2, :-2] + gray[:-2, 2:] + gray[2:, :-2] + gray[2:, 2:]
+            - 2 * (up + down + left + right) + 4 * center)
+    gradient = np.abs(right - left) + np.abs(down - up)
+    flat = high[gradient <= np.quantile(gradient, 0.3)]
+    sigma = float(np.median(np.abs(flat - np.median(flat))) / (0.6744897501960817 * 6))
+    contrast = float(gray.std())
+    snr = 20 * math.log10(contrast / sigma) if sigma > 1e-8 and contrast > 1e-8 else None
+    # JPEG boundaries are tested at every phase because source crops may shift the 8px grid.
+    block_scores = []
+    for axis in [0, 1]:
+        diff = np.abs(np.diff(gray, axis=axis))
+        n = diff.shape[axis]
+        if n >= 16:
+            phase_scores = []
+            indices = np.arange(n)
+            for phase in range(8):
+                border = indices % 8 == phase
+                phase_scores.append(float(np.take(diff, indices[border], axis=axis).mean()
+                                          - np.take(diff, indices[~border], axis=axis).mean()))
+            block_scores.append(max(phase_scores))
+    return {"blur_score": float(lap.var()), "noise_sigma": sigma, "snr_proxy_db": snr,
+            "blockiness": float(max(0, np.mean(block_scores))) if block_scores else None,
+            "luminance": float(gray.mean()), "contrast": contrast}
+
+
+def quality_metrics(image, patch_size=256):
+    w, h = image.size
+    pw, ph = min(w, patch_size), min(h, patch_size)
+    positions = sorted({(0, 0), (w-pw, 0), (0, h-ph), (w-pw, h-ph), ((w-pw)//2, (h-ph)//2)})
+    patches = [patch_metrics(np.asarray(image.crop((x, y, x+pw, y+ph)).convert("L"),
+                                        dtype=np.float64)) for x, y in positions]
+    result = {}
+    for key in patches[0]:
+        values = [p[key] for p in patches if p[key] is not None]
+        result[key] = float(np.median(values)) if values else None
+    result["metric_patch_count"] = len(patches)
+    return result

image_cleaner/stats.py

@@ -0,0 +1,141 @@
+from collections import Counter
+import html
+import json
+import math
+import random
+
+import numpy as np
+
+from .io import atomic_text
+
+
+BINS = {
+    "width": [0, 224, 512, 768, 1024, 2048, 4096, 8192, math.inf],
+    "height": [0, 224, 512, 768, 1024, 2048, 4096, 8192, math.inf],
+    "short_edge": [0, 224, 512, 768, 1024, 2048, 4096, 8192, math.inf],
+    "long_edge": [0, 224, 512, 768, 1024, 2048, 4096, 8192, math.inf],
+    "pixels": [0, 224**2, 512**2, 1024**2, 2048**2, 4096**2, 8192**2, math.inf],
+    "aspect_ratio": [0, .25, .5, .75, .95, 1.05, 1.33, 2, 4, math.inf],
+    "blur_score": [0, 5, 20, 50, 100, 200, 500, 1000, 5000, math.inf],
+    "noise_sigma": [0, .5, 1, 2, 4, 8, 16, 32, math.inf],
+    "snr_proxy_db": [-math.inf, 0, 10, 20, 30, 40, 50, 60, math.inf],
+    "blockiness": [0, .5, 1, 2, 4, 8, 16, 32, math.inf],
+    "text_chars": [0, 1, 10, 30, 100, 300, 1000, 3000, math.inf],
+}
+
+
+class Distribution:
+    def __init__(self, bins, seed=17, capacity=20_000):
+        self.bins = bins
+        self.hist = [0] * (len(bins)-1)
+        self.n = 0
+        self.mean = self.m2 = 0.0
+        self.low = math.inf
+        self.high = -math.inf
+        self.sample = []
+        self.random = random.Random(seed)
+        self.capacity = capacity
+        self.missing = 0
+
+    def add(self, value):
+        if value is None or not math.isfinite(value):
+            self.missing += 1
+            return
+        self.n += 1
+        delta = value - self.mean
+        self.mean += delta / self.n
+        self.m2 += delta * (value - self.mean)
+        self.low, self.high = min(self.low, value), max(self.high, value)
+        slot = int(np.searchsorted(self.bins, value, side="right")) - 1
+        self.hist[max(0, min(slot, len(self.hist)-1))] += 1
+        if len(self.sample) < self.capacity:
+            self.sample.append(value)
+        else:
+            slot = self.random.randrange(self.n)
+            if slot < self.capacity:
+                self.sample[slot] = value
+
+    def result(self):
+        def boundary(value):
+            return "-inf" if value == -math.inf else "inf" if value == math.inf else value
+        percentiles = [1, 5, 25, 50, 75, 95, 99]
+        quantiles = np.percentile(self.sample, percentiles).tolist() if self.sample else [None]*7
+        return {"count": self.n, "missing": self.missing, "min": self.low if self.n else None,
+                "max": self.high if self.n else None, "mean": self.mean if self.n else None,
+                "std": math.sqrt(self.m2/self.n) if self.n else None,
+                "quantiles": dict(zip([f"p{p}" for p in percentiles], quantiles)),
+                "quantiles_approximate": self.n > self.capacity, "quantile_sample_size": len(self.sample),
+                "histogram": [{"left": boundary(a), "right": boundary(b), "count": c}
+                              for a, b, c in zip(self.bins[:-1], self.bins[1:], self.hist)]}
+
+
+class DatasetStats:
+    def __init__(self):
+        self.distributions = {name: Distribution(bins) for name, bins in BINS.items()}
+        self.total = self.decoded = 0
+        self.statuses, self.reasons, self.formats, self.orientations = [Counter() for _ in range(4)]
+
+    def add(self, row):
+        self.total += 1
+        self.statuses[row["status"]] += 1
+        self.reasons.update(row.get("reasons", []))
+        if "width" not in row or row["status"] == "error":
+            return
+        self.decoded += 1
+        self.formats[row["original_format"]] += 1
+        ratio = row["aspect_ratio"]
+        self.orientations["square" if .95 <= ratio <= 1.05 else "landscape" if ratio > 1 else "portrait"] += 1
+        for name, distribution in self.distributions.items():
+            value = len(row.get("text") or "") if name == "text_chars" else row.get(name)
+            distribution.add(value)
+
+    def result(self):
+        return {"total": self.total, "decoded": self.decoded, "statuses": dict(self.statuses),
+                "reasons": dict(self.reasons), "formats": dict(self.formats),
+                "orientations": dict(self.orientations),
+                "distributions": {name: d.result() for name, d in self.distributions.items()}}
+
+
+def write_html(path, report):
+    labels = {"width": "宽度", "height": "高度", "short_edge": "短边", "long_edge": "长边",
+              "pixels": "总像素数", "aspect_ratio": "宽高比 W/H", "blur_score": "清晰度代理（拉普拉斯方差）",
+              "noise_sigma": "噪声估计 σ", "snr_proxy_db": "信噪比代理 dB", "blockiness": "块效应代理",
+              "text_chars": "文本字符数"}
+    with atomic_text(path) as handle:
+        handle.write('<!doctype html><html lang="zh-CN"><meta charset="utf-8"><title>图片清洗报告</title>'
+                     '<style>body{font:16px system-ui;max-width:1200px;margin:32px auto;padding:0 20px;'
+                     'color:#1e293b;background:#f8fafc}section{background:white;padding:20px;margin:20px 0;'
+                     'border-radius:12px}svg{width:100%;max-height:260px}pre{white-space:pre-wrap}'
+                     '.legend{color:#2563eb}text{font:11px system-ui}</style><h1>图片清洗报告</h1>')
+        handle.write('<p>原始分布为成功解码后的标准化方向；蓝色为原始数据，绿色为筛选保留数据。'
+                     '直方图为精确计数，分位数最多使用 20,000 条蓄水池样本。噪声、信噪比和块效应为代理指标。</p>')
+        summary = {k: report[k] for k in ["input_count", "kept_count", "rejected_count", "duplicate_count", "error_count"]}
+        handle.write('<section><pre>' + html.escape(json.dumps(summary, ensure_ascii=False, indent=2)) + '</pre></section>')
+        if "stage_metrics" in report:
+            handle.write('<section><h2>分辨率筛选与阶段指标</h2><pre>' + html.escape(json.dumps(
+                {"resolution_filter": report["resolution_filter"], "stage_metrics": report["stage_metrics"]},
+                ensure_ascii=False, indent=2)) + '</pre></section>')
+        if "aspect_bucket_filter" in report:
+            handle.write('<section><h2>宽高比桶筛选</h2><pre>' + html.escape(json.dumps(
+                report["aspect_bucket_filter"], ensure_ascii=False, indent=2)) + '</pre></section>')
+        for name, label in labels.items():
+            original = report["before"]["distributions"][name]
+            retained = report["after"]["distributions"][name]
+            bins, kept = original["histogram"], retained["histogram"]
+            peak = max(1, max(b["count"] for b in bins))
+            width = 900 / len(bins)
+            handle.write('<section><h2>' + label + '</h2><svg viewBox="0 0 960 260" role="img" aria-label="' + label + '分布">')
+            for i, (b, k) in enumerate(zip(bins, kept)):
+                x = 30 + width*i
+                for offset, count, color in [(0, b["count"], "#2563eb"), (.4, k["count"], "#16a34a")]:
+                    height = 180*count/peak
+                    handle.write(f'<rect x="{x+width*offset:.1f}" y="{205-height:.1f}" width="{width*.35:.1f}" '
+                                 f'height="{height:.1f}" fill="{color}"><title>{count}</title></rect>')
+                text = html.escape(f'{b["left"]}–{b["right"]}')
+                handle.write(f'<text x="{x:.1f}" y="228" transform="rotate(12 {x:.1f} 228)">{text}</text>')
+            handle.write('</svg><p class="legend">蓝：原始　绿：保留</p><pre>')
+            handle.write(html.escape(json.dumps({"before": original["quantiles"], "after": retained["quantiles"]},
+                                               ensure_ascii=False, indent=2)))
+            handle.write('</pre></section>')
+        handle.write('<section><h2>筛选原因</h2><pre>' + html.escape(json.dumps(report["before"]["reasons"],
+                     ensure_ascii=False, indent=2)) + '</pre></section></html>')

index.html

@@ -1,19 +1,15 @@
-<!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
-</html>
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="description" content="图片文本数据初筛代码、分布统计、尺寸与宽高比筛选、质量指标、去重和多机部署教程。"><title>NMM-data-preprocess · 图片文本数据初筛</title><link rel="stylesheet" href="assets/style.css"><script defer src="assets/app.js"></script></head>
+<body>
+<header class="topbar"><a class="brand" href="index.html">NMM<span> / </span>data-preprocess</a><nav aria-label="主要导航"><a href="manual/QUICKSTART.html">开始使用</a><a href="manual/PARAMETERS.html">参数参考</a><a href="manual/DEPLOYMENT.html">部署</a><a href="https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess/tree/main" target="_blank" rel="noopener">源代码 ↗</a></nav></header>
+<main class="landing">
+<section class="hero"><p class="eyebrow">原生图片—文本模型 / 训练前数据初筛</p><h1>先看清数据，<br>再决定保留什么。</h1><p class="lead">从图片文件夹或图文清单开始，统计尺寸与质量分布，按分辨率和宽高比筛选，再完成全局去重与标准化导出。</p><div class="actions"><a class="button primary" href="manual/QUICKSTART.html">阅读逐步教程 →</a><a class="button" href="downloads/NMM-data-preprocess-0.3.0.zip" download>下载源码 v0.3.0 ↓</a></div><p class="note">Python 3.10+ · CPU 多进程 · 多机静态分片 · Windows / Linux / Docker</p></section>
+<section class="pipeline" aria-label="清洗流程"><div><b>01</b><strong>导入</strong><span>文件夹 / JSONL</span></div><div><b>02</b><strong>统计</strong><span>尺寸 / 技术质量</span></div><div><b>03</b><strong>筛选</strong><span>规则 / 全局去重</span></div><div><b>04</b><strong>导出</strong><span>RGB 图片 / 图文清单</span></div></section>
+<section class="intro"><h2>完整教程与代码说明</h2><p>这个 Space 提供文档、命令设置和代码下载。清洗任务通过 CLI 在你的本地机器或服务器运行。</p><div class="guide-grid"><a class="guide" href="manual/QUICKSTART.html"><small>从零开始</small><h3>逐步使用教程</h3><p>下载、安装、合成样例、第一轮统计、筛选与导出。</p><span>阅读教程 →</span></a><a class="guide" href="manual/USAGE.html"><small>评测与规则</small><h3>完整操作手册</h3><p>逐阶段指标、公式、报告字段、质量校准和误删评估。</p><span>查看手册 →</span></a><a class="guide" href="manual/PARAMETERS.html"><small>全部设置</small><h3>参数参考</h3><p>每个 CLI 与 JSON 字段的默认值、约束、优先级和示例。</p><span>查询参数 →</span></a><a class="guide" href="manual/DEPLOYMENT.html"><small>本地与多机</small><h3>部署指南</h3><p>Windows、Linux、Docker、rank 分片、续跑和 Space 发布。</p><span>部署运行 →</span></a><a class="guide" href="manual/ARCHITECTURE.html"><small>实现细节</small><h3>代码与功能说明</h3><p>模块职责、数据流、文件格式、去重机制与当前边界。</p><span>了解实现 →</span></a></div></section>
+<section class="generator" id="commands"><div class="section-heading"><div><p class="eyebrow">配置尺寸与比例</p><h2>生成一条筛选命令</h2></div><span class="tag">复用统计缓存，无需重新解码</span></div><p>先按教程完成统计，将分片放在 <code>runs/statistics/shards</code>。以下设置只生成命令，可直接复制到终端。</p><div class="form-grid"><label>终端环境<select id="platform"><option value="windows">Windows PowerShell</option><option value="linux">Linux Bash</option></select></label><label>分辨率下限<input id="resolution" type="text" value="256p" placeholder="256p / 384x256 / any"></label><label>匹配策略<select id="mode"><option value="loose">宽松过滤</option><option value="strict">严格过滤</option></select></label><label>宽松偏差（%）<input id="tolerance" type="number" min="0" step="0.1" value="5"></label></div><fieldset class="buckets"><legend>宽:高桶（多选）</legend><label><input type="checkbox" name="bucket" value="1:1" checked>1:1</label><label><input type="checkbox" name="bucket" value="2:3" checked>2:3</label><label><input type="checkbox" name="bucket" value="3:2" checked>3:2</label><label><input type="checkbox" name="bucket" value="3:4" checked>3:4</label><label><input type="checkbox" name="bucket" value="4:3" checked>4:3</label><label><input type="checkbox" name="bucket" value="9:16" checked>9:16</label><label><input type="checkbox" name="bucket" value="16:9" checked>16:9</label><label><input type="checkbox" name="bucket" value="21:9" checked>21:9</label><button type="button" id="select-all">全选</button><button type="button" id="select-none">关闭桶条件</button></fieldset><p id="command-error" class="error" role="alert"></p><pre><code id="command"></code></pre><p class="note">输出到 <code>runs/filtered</code>；已有结果时请改用新目录。命令继承分析配置中的质量与去重设置。256p 表示短边 ≥256，包含 256。</p>
+<details><summary>用实际尺寸检查比例规则</summary><div class="form-grid"><label>图片宽（像素）<input id="width" type="number" min="1" step="1" value="1050"></label><label>图片高（像素）<input id="height" type="number" min="1" step="1" value="1000"></label></div><p id="ratio-result" aria-live="polite"></p><p class="note">偏差 δ=max(r/b,b/r)−1，包含阈值边界。实际 CLI 用精确分数比较；这里只展示所选桶和分辨率条件，不判断图片质量、文字和重复。</p></details></section>
+<section class="features"><h2>当前初筛覆盖</h2><div class="feature-grid"><article><h3>分布统计</h3><p>分辨率、短边、长边、像素数、比例和质量分布；全量直方图与抽样分位数。</p></article><article><h3>分辨率与八桶筛选</h3><p>短边下限、精确宽高、严格比例和默认 5% 可调宽松偏差。</p></article><article><h3>规范化与文本规则</h3><p>EXIF、ICC、RGB、透明背景、Unicode、文本长度与正则检查。</p></article><article><h3>技术质量代理</h3><p>模糊、噪声、信噪比与块效应指标；阈值需针对你的数据校准。</p></article><article><h3>全局去重</h3><p>文件和像素精确去重，pHash / dHash / RMSE 联合近重复复核。</p></article><article><h3>多进程与多机</h3><p>SQLite 检查点与静态 rank；汇总分片后统一筛选、去重和报告。</p></article></div></section>
+<section class="callout"><h2>看报告时，先核对这些数字</h2><p>输入总数 = 保留 + 拒绝 + 重复 + 错误。比较分辨率独立通过率、桶独立通过率、最终保留率，以及各桶筛选前后数量。初筛结果仍需人工抽查图文对应关系与质量。</p><a href="manual/USAGE.html">阅读所有指标的定义 →</a></section>
+</main><footer>HanWangTJU / NMM-data-preprocess · v0.3.0<span>静态教程与代码入口 · 图片在本地处理</span></footer>
+</body></html>

manual/ARCHITECTURE.html

@@ -0,0 +1,222 @@
+<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>代码说明 · NMM-data-preprocess</title><link rel="stylesheet" href="../assets/style.css"><script defer src="../assets/app.js"></script></head><body><header class="topbar"><a class="brand" href="../index.html">NMM<span> / </span>data-preprocess</a><nav><a href="https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess/tree/main">源代码 ↗</a><a href="../downloads/NMM-data-preprocess-0.3.0.zip" download>下载源码 ↓</a></nav></header><div class="manual-layout"><aside class="sidebar"><a href="../index.html">← 返回首页</a><a class="" href="QUICKSTART.html">逐步教程</a><a class="" href="USAGE.html">完整手册</a><a class="" href="PARAMETERS.html">参数参考</a><a class="" href="DEPLOYMENT.html">部署指南</a><a class="active" href="ARCHITECTURE.html">代码说明</a><h2>本页目录</h2><div class="toc">
+<ul>
+<li><a href="#1-当前版本与数据流">1. 当前版本与数据流</a></li>
+<li><a href="#2-功能矩阵">2. 功能矩阵</a></li>
+<li><a href="#3-源码文件说明">3. 源码文件说明</a></li>
+<li><a href="#4-记录格式与状态">4. 记录格式与状态</a></li>
+<li><a href="#5-为什么统计后能反复筛选">5. 为什么统计后能反复筛选</a></li>
+<li><a href="#6-并行去重和内存">6. 并行、去重和内存</a></li>
+<li><a href="#7-当前没有覆盖的训练前审核">7. 当前没有覆盖的训练前审核</a></li>
+<li><a href="#8-验证与版本">8. 验证与版本</a></li>
+</ul>
+</div>
+</aside><main class="manual"><h1 id="代码结构功能与实现边界">代码结构、功能与实现边界</h1>
+<h2 id="1-当前版本与数据流">1. 当前版本与数据流</h2>
+<p>当前清洗库版本 0.3.0，面向图片—文本对。主要流程：</p>
+<pre><code class="language-text">图片文件夹 / 图文 JSONL
+        │ prepare：稳定编号、固定清单与 SHA-256
+        ▼
+input.jsonl + input.jsonl.meta.json
+        │ analyze：rank 分片、本机进程池、规范化、测量
+        ▼
+各 rank 的 SQLite + JSONL
+        │ merge/filter：重算规则、全局去重、流式统计
+        ▼
+kept / rejected / duplicate / error + HTML/JSON 报告
+        │ export：源哈希校验、输出规范化 RGB
+        ▼
+标准化图片 + exported.jsonl → 训练数据加载器
+</code></pre>
+<p><code>run</code> 将单机 prepare、analyze、merge 顺序串联，可选 export。静态 Space 仅展示文档与命令，算法在用户机器运行。</p>
+<h2 id="2-功能矩阵">2. 功能矩阵</h2>
+<table>
+<thead>
+<tr>
+<th>环节</th>
+<th>已实现</th>
+<th>输出/限制</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>批量导入</td>
+<td>递归图片目录、同名 txt、图文 JSONL</td>
+<td>固定清单，路径和原始 ID 可追溯</td>
+</tr>
+<tr>
+<td>解码检查</td>
+<td>坏文件、截断、像素容量、动画/多页</td>
+<td>单图失败进入 error，不删除源图</td>
+</tr>
+<tr>
+<td>标准化</td>
+<td>EXIF、ICC→sRGB、RGB、透明合成、Unicode/空白</td>
+<td>无模型推理，无默认裁剪</td>
+</tr>
+<tr>
+<td>尺寸统计</td>
+<td>宽高、短/长边、像素、比例、方向分类</td>
+<td>全量直方图，最多 20000 样本估计分位数</td>
+</tr>
+<tr>
+<td>尺寸筛选</td>
+<td>短边 &gt;=Np、精确 WxH、其他尺寸阈值</td>
+<td>条件取交集，包含边界</td>
+</tr>
+<tr>
+<td>宽高比桶</td>
+<td>八桶、多选/全选、严格/宽松、可调容差</td>
+<td>固定桶，不做桶均衡采样</td>
+</tr>
+<tr>
+<td>技术质量</td>
+<td>模糊、噪声、SNR、块效应代理</td>
+<td>最多五个原生像素区域，不是人工质量结论</td>
+</tr>
+<tr>
+<td>文本检查</td>
+<td>长度、Unicode、广告等正则</td>
+<td>不评估图文语义一致性</td>
+</tr>
+<tr>
+<td>精确去重</td>
+<td>原字节、规范化像素</td>
+<td>跨全部分片全局处理</td>
+</tr>
+<tr>
+<td>近重复</td>
+<td>pHash、dHash、比例、RGB RMSE 联合</td>
+<td>启发式，不是 embedding 语义去重</td>
+</tr>
+<tr>
+<td>并行/续跑</td>
+<td>本机进程池、多机静态 rank、SQLite 检查点</td>
+<td>合并由单协调节点，无自动调度</td>
+</tr>
+<tr>
+<td>导出</td>
+<td>独立 RGB PNG/JPEG、缩小长边、清单、续跑校验</td>
+<td>原图不改动，固定裁剪由训练端完成</td>
+</tr>
+</tbody>
+</table>
+<p>用户提到的“正则化”在此实现中是数据规范化和规则校验；不包含训练损失正则化、数据增强或张量标准化。</p>
+<h2 id="3-源码文件说明">3. 源码文件说明</h2>
+<table>
+<thead>
+<tr>
+<th>文件</th>
+<th>主要职责</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>image_cleaner/cli.py</code></td>
+<td>argparse 子命令、CLI 覆盖、run 串联与返回码</td>
+</tr>
+<tr>
+<td><code>image_cleaner/config.py</code></td>
+<td>不可变 Config、JSON 加载、字段与数值校验、配置指纹</td>
+</tr>
+<tr>
+<td><code>image_cleaner/io.py</code></td>
+<td>目录导入、JSONL、清单身份、原子写入、锁、SQLite、限流进程池</td>
+</tr>
+<tr>
+<td><code>image_cleaner/images.py</code></td>
+<td>EXIF/色彩/透明度/文本规范化、单图分析与筛选原因</td>
+</tr>
+<tr>
+<td><code>image_cleaner/aspect.py</code></td>
+<td>精确分数比较、对称偏差、确定性桶分配</td>
+</tr>
+<tr>
+<td><code>image_cleaner/metrics.py</code></td>
+<td>原生区域质量测量、pHash/dHash、缩略图与 RMSE</td>
+</tr>
+<tr>
+<td><code>image_cleaner/jobs.py</code></td>
+<td>分片分析、全局过滤、落盘去重索引、导出与续跑</td>
+</tr>
+<tr>
+<td><code>image_cleaner/stats.py</code></td>
+<td>增量统计、蓄水池分位数、内嵌 SVG HTML 报告</td>
+</tr>
+<tr>
+<td><code>tests/test_pipeline.py</code></td>
+<td>导入/清洗/去重/导出/分片/续跑/容量等测试</td>
+</tr>
+<tr>
+<td><code>tests/test_aspect.py</code></td>
+<td>容差边界、横竖桶、重叠分配、CLI、缓存重筛选</td>
+</tr>
+<tr>
+<td><code>configs/</code></td>
+<td>统计、尺寸、桶、去重、生成数据示例配置</td>
+</tr>
+<tr>
+<td><code>examples/</code></td>
+<td>生成合成演示样本</td>
+</tr>
+<tr>
+<td><code>docker/Dockerfile</code></td>
+<td>CLI 容器部署，不启动 Web 服务</td>
+</tr>
+<tr>
+<td><code>tools/build_space.py</code></td>
+<td>文档转换、静态页面、源码 ZIP、发布文件校验清单</td>
+</tr>
+<tr>
+<td><code>tools/publish_space.py</code></td>
+<td>从环境变量读取 Token，检查账号并发布白名单文件</td>
+</tr>
+<tr>
+<td><code>web/</code></td>
+<td>Space 首页模板、样式与交互脚本</td>
+</tr>
+</tbody>
+</table>
+<p><code>index.html</code>、<code>manual/*.html</code> 与 <code>downloads/*.zip</code> 是发布构建产物。运行结果在 runs，虚拟环境在 .venv，两者不发布。</p>
+<h2 id="4-记录格式与状态">4. 记录格式与状态</h2>
+<p>外部 JSONL 每条必须有字符串 path；text 为字符串或 null，metadata 为对象。输入 id 会保存为 source_id，程序生成稳定 <code>sample-000000000000</code> 等 ID 与 seq。其他外部字段放入 metadata，避免覆盖计算指标。</p>
+<p>分析记录包含源路径、规范化文本、原始/校正宽高、文件/像素哈希、质量指标、预处理元数据、警告和筛选原因。最终状态：</p>
+<table>
+<thead>
+<tr>
+<th>状态</th>
+<th>含义</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>kept</td>
+<td>所有规则通过，且没有归并到其他代表</td>
+</tr>
+<tr>
+<td>rejected</td>
+<td>至少一个尺寸/桶/质量/文本规则不通过</td>
+</tr>
+<tr>
+<td>duplicate</td>
+<td>规则通过，但精确或近重复判定归并到代表</td>
+</tr>
+<tr>
+<td>error</td>
+<td>无法成功解码、规范化或测量</td>
+</tr>
+</tbody>
+</table>
+<p>最终满足 <code>input_count=kept+rejected+duplicate+error</code>。同一拒绝记录可以有多个原因，原因计数不可当成样本数相加。</p>
+<h2 id="5-为什么统计后能反复筛选">5. 为什么统计后能反复筛选</h2>
+<p>analyze 保存成功处理的完整指标，即使当时被阈值拒绝也写入 SQLite。filter 从全部记录重新计算规则，而不是仅读取上一次 kept。因此放宽阈值能恢复以前被拒绝的记录，收紧阈值也无需读源图片。</p>
+<p>六项测量设置（reject_animated、max_decode_pixels、metric_patch_size、alpha_background、convert_icc、text_unicode_form）不允许在重筛选中改变。变化会使缓存指标不再对应新处理逻辑，需要重新分析。</p>
+<h2 id="6-并行去重和内存">6. 并行、去重和内存</h2>
+<p>进程池并发队列约为 workers 的两倍，结果逐条写入 SQLite。rank 使用 <code>seq % world_size</code>，每个 rank 写单独数据库。全局 merge 校验完整分片并按稳定优先级处理候选。</p>
+<p>精确去重索引基于哈希，近重复使用 pHash 的 r+1 分段索引召回候选，再复核联合条件。索引和排序主要落磁盘，不将全量图片或全量指标载入内存；没有全数据两两比较。</p>
+<p>合并批量处理 500 条候选，SQLite 缓存约 32 MiB，分位数抽样上限 20000。图片解码内存仍随原图像素与 workers 增长。大量相似图片、纯色图或高半径设置会增加复核成本，不能据此承诺百万/亿级吞吐量。</p>
+<h2 id="7-当前没有覆盖的训练前审核">7. 当前没有覆盖的训练前审核</h2>
+<p>当前不包含 OCR、水印/人脸/隐私识别、NSFW/版权判定、CLIP 语义一致性、美学模型、语义 embedding 去重、训练/验证集防泄漏、WebDataset/Parquet 输入、视频/音频、训练采样配额、动态集群调度。</p>
+<p>初筛保留仅代表通过已配置规则；训练前仍应按来源、内容类别和任务需求抽查，确认图文对齐及样本可用性。若后续扩展，应保留现有 source_id、稳定清单和每条决策原因便于追溯。</p>
+<h2 id="8-验证与版本">8. 验证与版本</h2>
+<p>现有 21 项清洗测试覆盖正好 5% 边界、零容差、桶重叠、源文件删除后的缓存筛选、多进程/双分片一致性、去重、多文本、断点续跑、导出校验、分辨率包含边界等。发布时另核验文档参数与代码、ZIP 白名单和页面链接。</p>
+<p>恢复分析要求软件版本与配置指纹一致。合并旧分片需要同一批分片身份一致且当前代码能够读取其字段；不要混用不同软件版本、不同清单或不同 world-size 的分片。版本号不代表数据清洗标准或模型效果保证。</p></main></div><footer>NMM-data-preprocess · v0.3.0<span>图片文本数据初筛教程</span></footer></body></html>

manual/DEPLOYMENT.html

@@ -0,0 +1,206 @@
+<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>部署指南 · NMM-data-preprocess</title><link rel="stylesheet" href="../assets/style.css"><script defer src="../assets/app.js"></script></head><body><header class="topbar"><a class="brand" href="../index.html">NMM<span> / </span>data-preprocess</a><nav><a href="https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess/tree/main">源代码 ↗</a><a href="../downloads/NMM-data-preprocess-0.3.0.zip" download>下载源码 ↓</a></nav></header><div class="manual-layout"><aside class="sidebar"><a href="../index.html">← 返回首页</a><a class="" href="QUICKSTART.html">逐步教程</a><a class="" href="USAGE.html">完整手册</a><a class="" href="PARAMETERS.html">参数参考</a><a class="active" href="DEPLOYMENT.html">部署指南</a><a class="" href="ARCHITECTURE.html">代码说明</a><h2>本页目录</h2><div class="toc">
+<ul>
+<li><a href="#1-部署形式如何选择">1. 部署形式如何选择</a></li>
+<li><a href="#2-windows-部署">2. Windows 部署</a></li>
+<li><a href="#3-linux-部署">3. Linux 部署</a></li>
+<li><a href="#4-docker-cli-部署">4. Docker CLI 部署</a></li>
+<li><a href="#5-两台服务器的完整流程">5. 两台服务器的完整流程</a><ul>
+<li><a href="#51-制作一份全局清单">5.1 制作一份全局清单</a></li>
+<li><a href="#52-各节点分析">5.2 各节点分析</a></li>
+<li><a href="#53-收集分片">5.3 收集分片</a></li>
+<li><a href="#54-统一导出">5.4 统一导出</a></li>
+</ul>
+</li>
+<li><a href="#6-续跑重筛选与故障处理">6. 续跑、重筛选与故障处理</a></li>
+<li><a href="#7-hugging-face-space-的发布方式">7. Hugging Face Space 的发布方式</a></li>
+<li><a href="#8-部署后的验收">8. 部署后的验收</a></li>
+</ul>
+</div>
+</aside><main class="manual"><h1 id="部署分布式运行与发布指南">部署、分布式运行与发布指南</h1>
+<h2 id="1-部署形式如何选择">1. 部署形式如何选择</h2>
+<table>
+<thead>
+<tr>
+<th>场景</th>
+<th>方式</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>初次使用、少量验证</td>
+<td>Windows / Linux 虚拟环境 + CLI</td>
+</tr>
+<tr>
+<td>单台服务器大批量</td>
+<td>Linux CLI，多进程 analyze，磁盘上的 SQLite</td>
+</tr>
+<tr>
+<td>环境一致性与隔离</td>
+<td>Docker CLI 容器，挂载原图与任务目录</td>
+</tr>
+<tr>
+<td>多机数据分析</td>
+<td>同一 manifest，静态 rank/world-size，汇总完整分片</td>
+</tr>
+<tr>
+<td>在线共享代码和教程</td>
+<td>Hugging Face 静态 Space；不执行清洗后台</td>
+</tr>
+</tbody>
+</table>
+<p>清洗不依赖 GPU，也不加载大模型。核心依赖 Python&gt;=3.10、NumPy&gt;=1.26,&lt;3、Pillow&gt;=10.4,&lt;13。实际解码格式取决于 Pillow 构建与可用编解码器，文件扩展名支持不保证所有格式均能解码。</p>
+<h2 id="2-windows-部署">2. Windows 部署</h2>
+<pre><code class="language-powershell">git clone https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess multimodal_training
+cd multimodal_training
+py -3.12 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --upgrade pip
+.\.venv\Scripts\python.exe -m pip install -e .
+.\.venv\Scripts\python.exe -m image_cleaner --help
+.\.venv\Scripts\python.exe -m unittest discover -s tests -v
+</code></pre>
+<p>不需要激活虚拟环境或修改 PowerShell 执行策略。路径有空格时加双引号。不要把 output 放到图片输入树中，以免后续重新导入导出文件。</p>
+<p>默认 workers 为 min(8,CPU 数量)，大图先设 2 或 4，观察内存与吞吐量再上调。配置 max_decode_pixels 控制解码容量；降低上限会把超限图片记入 error，不能替代缩图。</p>
+<h2 id="3-linux-部署">3. Linux 部署</h2>
+<pre><code class="language-bash">git clone https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess multimodal_training
+cd multimodal_training
+python3 -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install -e .
+.venv/bin/python -m image_cleaner --help
+.venv/bin/python -m unittest discover -s tests -v
+</code></pre>
+<pre><code class="language-bash">.venv/bin/python -m image_cleaner run --input /data/images --output /jobs/statistics --config configs/statistics_only.json --workers 8 --sidecar-text
+.venv/bin/python -m image_cleaner filter --shards /jobs/statistics/shards --output /jobs/filtered --config configs/audit.json --resolution 256p --aspect-buckets all --aspect-mode loose --aspect-tolerance 0.05
+.venv/bin/python -m image_cleaner export --curated /jobs/filtered --output /jobs/normalized --workers 8
+</code></pre>
+<p>离线运行前应在对应平台准备 Python、包安装文件和代码。可以执行 <code>pip download . --dest wheels</code> 收集核心依赖；打包方式和平台不同，应在目标环境验证。原图、任务文件建议放在可靠���地盘或受控共享存储，优先使用快盘承载 SQLite。</p>
+<h2 id="4-docker-cli-部署">4. Docker CLI 部署</h2>
+<p>从项目根目录构建：</p>
+<pre><code class="language-bash">docker build -f docker/Dockerfile -t nmm-data-preprocess:0.3.0 .
+docker run --rm nmm-data-preprocess:0.3.0 --help
+</code></pre>
+<p>以下为 Linux 主机路径示例。先创建输出目录，并确保容器 UID 1000 对其有写权限；数据目录只读挂载：</p>
+<pre><code class="language-bash">mkdir -p /jobs/nmm
+docker run --rm \
+  -v /data/images:/data/images:ro \
+  -v /jobs/nmm:/jobs \
+  -v &quot;$PWD/configs:/configs:ro&quot; \
+  nmm-data-preprocess:0.3.0 \
+  run --input /data/images --output /jobs/statistics --config /configs/statistics_only.json --workers 4 --sidecar-text
+
+docker run --rm \
+  -v /jobs/nmm:/jobs \
+  -v &quot;$PWD/configs:/configs:ro&quot; \
+  nmm-data-preprocess:0.3.0 \
+  filter --shards /jobs/statistics/shards --output /jobs/filtered --config /configs/audit.json --resolution 256p --aspect-buckets all --aspect-mode loose
+
+docker run --rm \
+  -v /data/images:/data/images:ro \
+  -v /jobs/nmm:/jobs \
+  nmm-data-preprocess:0.3.0 \
+  export --curated /jobs/filtered --output /jobs/normalized --workers 4
+</code></pre>
+<p>第二条仅使用缓存分片，无须挂载源图；第三条 export 必须能访问原图，路径保持与分析时相同，或通过 <code>--root</code> 改写。容器不是 HF Docker Space 应用，没有监听 Web 端口。</p>
+<p>Windows Docker Desktop 中将 Linux 主机路径替换为实际 Windows 路径；PowerShell 多行续行用反引号，或把命令写成一行，不使用 Bash 的反斜线续行。Dockerfile 是提供的部署方案，Docker 是否可用需在用户环境实际构建验证。</p>
+<h2 id="5-两台服务器的完整流程">5. 两台服务器的完整流程</h2>
+<h3 id="51-制作一份全局清单">5.1 制作一份全局清单</h3>
+<p>在协调机器运行：</p>
+<pre><code class="language-bash">.venv/bin/python -m image_cleaner prepare --input /data/images --manifest /jobs/input.jsonl --sidecar-text
+</code></pre>
+<p>把 <code>input.jsonl</code>、<code>input.jsonl.meta.json</code>、同一代码版本和统计配置分发到所有分析节点。每台节点都要能访问属于其 rank 的图片，图片根目录可以不同；相对路径结构必须保持一致。</p>
+<h3 id="52-各节点分析">5.2 各节点分析</h3>
+<p>节点 0：</p>
+<pre><code class="language-bash">.venv/bin/python -m image_cleaner analyze --manifest /jobs/input.jsonl --root /mnt/images --output /jobs/node0 --config configs/statistics_only.json --rank 0 --world-size 2 --workers 8
+</code></pre>
+<p>节点 1：</p>
+<pre><code class="language-bash">.venv/bin/python -m image_cleaner analyze --manifest /jobs/input.jsonl --root /dataset/images --output /jobs/node1 --config configs/statistics_only.json --rank 1 --world-size 2 --workers 8
+</code></pre>
+<p>每条记录按 <code>seq % 2</code> 分配。不要让两个节点使用同一 rank，也不要向同一个 SQLite 并发写入。节点失败后在原节点增加 <code>--resume</code>，其余参数不变。</p>
+<h3 id="53-收集分片">5.3 收集分片</h3>
+<p>分析进程正常退出后，将各节点的 <code>shard-00000-of-00002.sqlite</code> 与 <code>shard-00001-of-00002.sqlite</code> 放到协调节点 <code>/jobs/all_shards</code>；JSONL 可同时保留用于检查，但 merge 读取 SQLite。必须等分析完成再复制，避免只复制仍依赖 WAL 的数据库。</p>
+<p>先形成统计报告，然后全局筛选去重：</p>
+<pre><code class="language-bash">.venv/bin/python -m image_cleaner merge --shards /jobs/all_shards --output /jobs/global_statistics
+.venv/bin/python -m image_cleaner filter --shards /jobs/all_shards --output /jobs/global_filtered --config configs/audit.json --resolution 256p --aspect-buckets all --aspect-mode loose --aspect-tolerance 0.05
+</code></pre>
+<p>两轮都不需要原图。协调节点会验证所有 rank 完整、配置/清单/身份一致、总记录数匹配；缺失 rank 时拒绝合并，不能把局部去重当全局去重。</p>
+<h3 id="54-统一导出">5.4 统一导出</h3>
+<p>协调节点必须能访问全部保留原图，以统一根目录覆盖各节点不同的绝对 source_path：</p>
+<pre><code class="language-bash">.venv/bin/python -m image_cleaner export --curated /jobs/global_filtered --root /coordinator/images --output /jobs/global_export --workers 8
+</code></pre>
+<p>相对图片路径依据原清单保持不变。当前 CLI 不把导出任务再分配到多个 rank，多机能力主要在 analyze 阶段。</p>
+<h2 id="6-续跑重筛选与故障处理">6. 续跑、重筛选与故障处理</h2>
+<table>
+<thead>
+<tr>
+<th>情况</th>
+<th>操作</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>analyze 正常中断</td>
+<td>相同命令加 --resume；同 manifest/config/version/rank</td>
+</tr>
+<tr>
+<td>run 需要继续</td>
+<td>相同命令加 --resume，不��输入、配置、root、sidecar 设置</td>
+</tr>
+<tr>
+<td>export 中断</td>
+<td>相同命令加 --resume；会检查源和已有输出哈希</td>
+</tr>
+<tr>
+<td>想调整尺寸、桶或质量阈值</td>
+<td>从原 shards filter 到新的输出目录</td>
+</tr>
+<tr>
+<td>想调整颜色、测量区域等</td>
+<td>新输出目录重新 analyze，再 merge</td>
+</tr>
+<tr>
+<td>merge 中途失败</td>
+<td>无中途续跑支持；选新输出目录重新 merge，复用 shards</td>
+</tr>
+<tr>
+<td>出现 .lock</td>
+<td>先确认对应进程已退出，才删除该特定锁；运行中不能删</td>
+</tr>
+<tr>
+<td>源文件在分析后变更</td>
+<td>export 拒绝哈希不一致的样本；重新制作/分析数据</td>
+</tr>
+<tr>
+<td>缺少 rank</td>
+<td>补齐原任务的分片，不修改 world-size 去掩盖缺失</td>
+</tr>
+</tbody>
+</table>
+<p>analyze 每 100 条提交一次检查点，异常退出最多重算尚未提交的记录。改变软件版本会影响 resume 身份，生产作业应固定版本与配置，保存元数据。</p>
+<p>代码读取整个 manifest 再挑选本 rank，不是自动调度器；超大清单、偏斜大图、共享盘拥塞可能限制速度。建议先测 1–10 万代表性图片，记录图片/秒、CPU、峰值内存、磁盘占用、错误率和各规则保留率，再确定节点与进程数。已有测试不等于百万级吞吐量基准。</p>
+<h2 id="7-hugging-face-space-的发布方式">7. Hugging Face Space 的发布方式</h2>
+<p>本项目使用静态 Space：根 README YAML 指定 <code>sdk: static</code> 与 <code>app_file: index.html</code>。页面包含教程、参数、代码下载、命令生成器和比例匹配演示；不连接用户文件系统、不提交训练图片、不运行服务器清洗。</p>
+<p>选择静态托管使文档入口无需清洗计算资源。官方规则参见 <a href="https://huggingface.co/docs/hub/spaces-sdks-static">Static HTML Spaces</a> 和 <a href="https://huggingface.co/docs/hub/spaces-config-reference">配置参考</a>。</p>
+<p>构建发布文件：</p>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m pip install -e &quot;.[publish]&quot;
+.\.venv\Scripts\python.exe tools/build_space.py
+</code></pre>
+<p>本地预览：</p>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m http.server 8000 --bind 127.0.0.1
+</code></pre>
+<p>打开 <code>http://127.0.0.1:8000/index.html</code>。这是预览服务器，不是清洗 API。终端 Ctrl+C 停止。</p>
+<p>发布脚本仅从当前进程的 <code>HF_TOKEN</code> 读取认证，不使用账号密码，不调用持久化 login，不把 Token 写到任何文件。可在安全终端设置环境变量，或从秘密管理器注入；不要在脚本和配置中硬编码真实 Token。</p>
+<pre><code class="language-bash"># HF_TOKEN 已通过环境或秘密管理器注入。
+.venv/bin/python tools/publish_space.py --repo-id HanWangTJU/NMM-data-preprocess
+</code></pre>
+<p>脚本检查登录身份与仓库命名空间；创建不存在的 public static Space，或更新已有 static Space。它不删除远端文件、不变更现有私有性，也不申请付费硬件。先构建再发布，使用 release/publish-manifest.json 指定白名单与 SHA-256；发布前校验哈希、路径和凭据模式。</p>
+<p>发布内容包括库、测试、配置、示例、教程、页面、Dockerfile 和源码 ZIP；排除 .venv、runs、个人原图、运行日志、认证信息与系统路径。README 和 ZIP 保持同一版本，发布收据保存 repo ID、提交 ID、文件数量和页面地址。</p>
+<p>如果网络直连失败，可按实际网络环境设置 HTTPS_PROXY 连接官方 huggingface.co；不要为上传将认证 Token 发给未经确认的镜像站。权限不足时需要具有目标 Space 写入/创建权限的 Token。</p>
+<h2 id="8-部署后的验收">8. 部署后的验收</h2>
+<ol>
+<li><code>--help</code> 可用，测试通过，合成样例能统计/筛选/导出。</li>
+<li>报告四类数量守恒，错误清单包含合成坏文件。</li>
+<li>256p 和宽高比 5% 临界行为符合说明。</li>
+<li>双 rank 与单机结果一致，源图删除后的缓存 filter 正常。</li>
+<li>在线文档和源码 ZIP 可打开，远端文件没有凭据或个人数据。</li>
+<li>实际数据上再做人工抽查与性能试运行，确认阈值和资源设置合适。</li>
+</ol></main></div><footer>NMM-data-preprocess · v0.3.0<span>图片文本数据初筛教程</span></footer></body></html>

manual/PARAMETERS.html

@@ -0,0 +1,549 @@
+<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>参数参考 · NMM-data-preprocess</title><link rel="stylesheet" href="../assets/style.css"><script defer src="../assets/app.js"></script></head><body><header class="topbar"><a class="brand" href="../index.html">NMM<span> / </span>data-preprocess</a><nav><a href="https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess/tree/main">源代码 ↗</a><a href="../downloads/NMM-data-preprocess-0.3.0.zip" download>下载源码 ↓</a></nav></header><div class="manual-layout"><aside class="sidebar"><a href="../index.html">← 返回首页</a><a class="" href="QUICKSTART.html">逐步教程</a><a class="" href="USAGE.html">完整手册</a><a class="active" href="PARAMETERS.html">参数参考</a><a class="" href="DEPLOYMENT.html">部署指南</a><a class="" href="ARCHITECTURE.html">代码说明</a><h2>本页目录</h2><div class="toc">
+<ul>
+<li><a href="#1-如何设置参数">1. 如何设置参数</a></li>
+<li><a href="#2-所有-cli-参数">2. 所有 CLI 参数</a><ul>
+<li><a href="#prepare固定输入清单">prepare：固定输入清单</a></li>
+<li><a href="#analyze分析一个分片">analyze：分析一个分片</a></li>
+<li><a href="#filter-merge重筛选与全局去重">filter / merge：重筛选与全局去重</a></li>
+<li><a href="#共用尺寸与宽高比参数">共用尺寸与宽高比参数</a></li>
+<li><a href="#export标准化输出">export：标准化输出</a></li>
+<li><a href="#run单机完整流程">run：单机完整流程</a></li>
+</ul>
+</li>
+<li><a href="#3-全部-json-配置字段">3. 全部 JSON 配置字段</a><ul>
+<li><a href="#尺寸与比例">尺寸与比例</a></li>
+<li><a href="#质量与文字">质量与文字</a></li>
+<li><a href="#预处理与测量">预处理与测量</a></li>
+<li><a href="#去重">去重</a></li>
+<li><a href="#导出">导出</a></li>
+</ul>
+</li>
+<li><a href="#4-典型配置组合">4. 典型配置组合</a><ul>
+<li><a href="#只做第一轮统计">只做第一轮统计</a></li>
+<li><a href="#尺寸比例文字与去重">尺寸、比例、文字与去重</a></li>
+<li><a href="#原图规范化并限制导出长边">原图规范化并限制导出长边</a></li>
+</ul>
+</li>
+<li><a href="#5-无效设置与返回码">5. 无效设置与返回码</a></li>
+</ul>
+</div>
+</aside><main class="manual"><h1 id="参数参考与设置方法">参数参考与设置方法</h1>
+<h2 id="1-如何设置参数">1. 如何设置参数</h2>
+<p>运行形式是 <code>python -m image_cleaner &lt;子命令&gt; ...</code>；安装后也可用 <code>image-cleaner &lt;子命令&gt; ...</code>。Windows 下建议直接使用虚拟环境的 <code>.\.venv\Scripts\python.exe</code>，Linux 使用 <code>.venv/bin/python</code>。</p>
+<p>CLI 提供流程与常用尺寸条件；质量、文本、去重、导出等设置集中在 JSON 配置文件中，由 <code>--config</code> 加载。配置采用 UTF-8，不能写注释；布尔值用 <code>true/false</code>，关闭可选阈值用 <code>null</code>。所有未知字段会报错，避免拼写错误被静默忽略。</p>
+<p>优先级：</p>
+<ol>
+<li><code>analyze/run</code>：Config 默认值 → JSON 配置 → 显式 CLI 尺寸/宽高比参数。</li>
+<li><code>filter/merge</code> 未传配置：继承分析分片完整配置 → 显式 CLI 参数。</li>
+<li><code>filter/merge</code> 传配置：Config 默认值 → 新 JSON 配置 → 显式 CLI 参数；不与分片字段逐项合并。</li>
+<li><code>export</code>：使用 curated/report.json 中的配置；不接受另一个 <code>--config</code>。</li>
+</ol>
+<p>例如统计分片使用 <code>statistics_only.json</code> 时去重关闭，仅加 <code>--resolution 256p</code> 不会开启去重；添加 <code>--config configs/audit.json</code> 才切换到该配置中的去重设置。</p>
+<h2 id="2-所有-cli-参数">2. 所有 CLI 参数</h2>
+<h3 id="prepare固定输入清单">prepare：固定输入清单</h3>
+<table>
+<thead>
+<tr>
+<th>参数</th>
+<th>必填/默认</th>
+<th>说明</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>--input</code></td>
+<td>必填</td>
+<td>图片目录或 UTF-8 JSONL</td>
+</tr>
+<tr>
+<td><code>--manifest</code></td>
+<td>必填</td>
+<td>写入固定清单，同时生成 <code>.meta.json</code>；不能覆盖已有清单</td>
+</tr>
+<tr>
+<td><code>--root</code></td>
+<td>自动推断</td>
+<td>相对图片路径的根目录；目录输入默认自身，JSONL 默认其父目录</td>
+</tr>
+<tr>
+<td><code>--sidecar-text</code></td>
+<td>false</td>
+<td>文件夹输入时读取同名 UTF-8 <code>.txt</code>；JSONL 文本直接来自 text</td>
+</tr>
+</tbody>
+</table>
+<h3 id="analyze分析一个分片">analyze：分析一个分片</h3>
+<table>
+<thead>
+<tr>
+<th>参数</th>
+<th>必填/默认</th>
+<th>说明</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>--manifest</code></td>
+<td>必填</td>
+<td>prepare 生成的清单，必须有配套 <code>.meta.json</code></td>
+</tr>
+<tr>
+<td><code>--output</code></td>
+<td>必填</td>
+<td>分片输出目录</td>
+</tr>
+<tr>
+<td><code>--config</code></td>
+<td>Config 默认值</td>
+<td>JSON 配置文件</td>
+</tr>
+<tr>
+<td><code>--root</code></td>
+<td>清单元数据 root</td>
+<td>当前节点的图片根目录，可与制作清单的机器不同</td>
+</tr>
+<tr>
+<td><code>--workers</code></td>
+<td>min(8, CPU 数量)</td>
+<td>本机分析进程数，正整数</td>
+</tr>
+<tr>
+<td><code>--rank</code></td>
+<td>0</td>
+<td>当前分片编号，0 开始</td>
+</tr>
+<tr>
+<td><code>--world-size</code></td>
+<td>1</td>
+<td>总分片数，正整数，rank 必须小于该值</td>
+</tr>
+<tr>
+<td><code>--resume</code></td>
+<td>false</td>
+<td>使用相同清单、配置、版本和分片参数恢复已有 SQLite</td>
+</tr>
+<tr>
+<td>尺寸/桶参数</td>
+<td>见下表</td>
+<td>支持 resolution 与三个 aspect 参数</td>
+</tr>
+</tbody>
+</table>
+<h3 id="filter-merge重筛选与全局去重">filter / merge：重筛选与全局去重</h3>
+<p>两个名称调用同一实现。</p>
+<table>
+<thead>
+<tr>
+<th>参数</th>
+<th>必填/默认</th>
+<th>说明</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>--shards</code></td>
+<td>必填</td>
+<td>同一 manifest、版本和分析配置的全部 rank SQLite 所在目录</td>
+</tr>
+<tr>
+<td><code>--output</code></td>
+<td>必填</td>
+<td>一个新的输出目录，不接受覆盖已有合并结果</td>
+</tr>
+<tr>
+<td><code>--config</code></td>
+<td>继承分析配置</td>
+<td>新筛选配置；不能改变预处理/测量设置</td>
+</tr>
+<tr>
+<td>尺寸/桶参数</td>
+<td>见下表</td>
+<td>覆盖有效配置对应字段</td>
+</tr>
+</tbody>
+</table>
+<h3 id="共用尺寸与宽高比参数">共用尺寸与宽高比参数</h3>
+<p>适用于 <code>analyze</code>、<code>run</code>、<code>filter/merge</code>。</p>
+<table>
+<thead>
+<tr>
+<th>参数</th>
+<th>Config 默认值</th>
+<th>取值与规则</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>--resolution</code></td>
+<td>null</td>
+<td><code>256p</code> 短边 &gt;=256；<code>384x256</code> 精确宽高；<code>any/none</code> 关闭；必须为正整数尺寸</td>
+</tr>
+<tr>
+<td><code>--aspect-buckets</code></td>
+<td>null</td>
+<td>多选例如 <code>"1:1,2:3"</code>；<code>all</code> 八桶并集；<code>none</code> 关闭；空选择报错</td>
+</tr>
+<tr>
+<td><code>--aspect-mode</code></td>
+<td>strict</td>
+<td>strict 精确整数比例；loose 容差模式</td>
+</tr>
+<tr>
+<td><code>--aspect-tolerance</code></td>
+<td>0.05</td>
+<td>有限非负数，只作用于 loose；0.05=5%，0=不允许偏差</td>
+</tr>
+</tbody>
+</table>
+<p>八桶固定为 <code>1:1,2:3,3:2,3:4,4:3,9:16,16:9,21:9</code>，不支持自定义。所有尺寸条件基于 EXIF 校正后的宽和高；不自动互换横竖桶。严格模式忽略容差参数；未选择桶时模式和容差不会启用过滤。</p>
+<h3 id="export标准化输出">export：标准化输出</h3>
+<table>
+<thead>
+<tr>
+<th>参数</th>
+<th>必填/默认</th>
+<th>说明</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>--curated</code></td>
+<td>必填</td>
+<td>filter/merge 输出目录，或 run 的 curated 子目录</td>
+</tr>
+<tr>
+<td><code>--output</code></td>
+<td>必填</td>
+<td>独立导出目录</td>
+</tr>
+<tr>
+<td><code>--root</code></td>
+<td>记录 source_path</td>
+<td>图片移动后覆盖源图片根目录</td>
+</tr>
+<tr>
+<td><code>--workers</code></td>
+<td>min(8, CPU 数量)</td>
+<td>本机导出进程数，正整数</td>
+</tr>
+<tr>
+<td><code>--resume</code></td>
+<td>false</td>
+<td>使用相同配置和输出目录续跑，校验源文件和已导出文件哈希</td>
+</tr>
+</tbody>
+</table>
+<h3 id="run单机完整流程">run：单机完整流程</h3>
+<table>
+<thead>
+<tr>
+<th>参数</th>
+<th>必填/默认</th>
+<th>说明</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>--input</code></td>
+<td>必填</td>
+<td>图片文件夹或 JSONL</td>
+</tr>
+<tr>
+<td><code>--output</code></td>
+<td>必填</td>
+<td>工作目录，下设 input、shards、curated 等</td>
+</tr>
+<tr>
+<td><code>--root</code></td>
+<td>自动推断</td>
+<td>图片根目录</td>
+</tr>
+<tr>
+<td><code>--config</code></td>
+<td>Config 默认值</td>
+<td>分析与筛选配置</td>
+</tr>
+<tr>
+<td><code>--workers</code></td>
+<td>min(8, CPU 数量)</td>
+<td>本机多进程数量</td>
+</tr>
+<tr>
+<td><code>--sidecar-text</code></td>
+<td>false</td>
+<td>文件夹输入读取同名文本</td>
+</tr>
+<tr>
+<td><code>--export</code></td>
+<td>false</td>
+<td>合并后导出到 normalized 子目录</td>
+</tr>
+<tr>
+<td><code>--resume</code></td>
+<td>false</td>
+<td>恢复同输入、配置、根目录和 sidecar 设置的已有任务</td>
+</tr>
+<tr>
+<td>尺寸/桶参数</td>
+<td>见上表</td>
+<td>CLI 覆盖相应 JSON 字段</td>
+</tr>
+</tbody>
+</table>
+<p>每个子命令均支持 <code>--help</code>。没有 CLI 参数直接设置质量阈值，也没有 <code>--workers</code> 控制 merge：最终合并由单进程协调。</p>
+<h2 id="3-全部-json-配置字段">3. 全部 JSON 配置字段</h2>
+<h3 id="尺寸与比例">尺寸与比例</h3>
+<table>
+<thead>
+<tr>
+<th>字段</th>
+<th>默认值</th>
+<th>单位/范围与行为</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>resolution</td>
+<td>null</td>
+<td>Np / WxH / any / none；语义同 CLI</td>
+</tr>
+<tr>
+<td>aspect_buckets</td>
+<td>null</td>
+<td>数组、逗号字符串、all、none 或 null；规范化成固定顺序，重复值合并</td>
+</tr>
+<tr>
+<td>aspect_mode</td>
+<td>strict</td>
+<td>strict / loose</td>
+</tr>
+<tr>
+<td>aspect_tolerance</td>
+<td>0.05</td>
+<td>非负有限数，包含边界；不得为 null；设置很大将显著放宽筛选</td>
+</tr>
+<tr>
+<td>min_short_edge</td>
+<td>null</td>
+<td>非负整数像素，下限</td>
+</tr>
+<tr>
+<td>max_long_edge</td>
+<td>null</td>
+<td>非负整数像素，上限</td>
+</tr>
+<tr>
+<td>min_pixels</td>
+<td>null</td>
+<td>非负整数像素总数，下限</td>
+</tr>
+<tr>
+<td>max_pixels</td>
+<td>null</td>
+<td>非负整数像素总数，上限，不小于 min_pixels</td>
+</tr>
+<tr>
+<td>min_aspect_ratio</td>
+<td>null</td>
+<td>非负有限数 W/H，下限</td>
+</tr>
+<tr>
+<td>max_aspect_ratio</td>
+<td>null</td>
+<td>非负有限数 W/H，上限，不小于 min_aspect_ratio</td>
+</tr>
+</tbody>
+</table>
+<p>所有下限用 <code>&gt;=</code>、上限用 <code>&lt;=</code>，条件取交集。选择多个桶只在桶之间取并集，不会放宽其他规则。</p>
+<h3 id="质量与文字">质量与文字</h3>
+<table>
+<thead>
+<tr>
+<th>字段</th>
+<th>默认值</th>
+<th>单位/范围与行为</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>min_blur_score</td>
+<td>null</td>
+<td>非负有限数；拉普拉斯方差下限</td>
+</tr>
+<tr>
+<td>max_noise_sigma</td>
+<td>null</td>
+<td>非负有限数；灰度 0–255 尺度噪声估计上限</td>
+</tr>
+<tr>
+<td>min_snr_proxy_db</td>
+<td>null</td>
+<td>有限数，允许负数；SNR 代理 dB 下限</td>
+</tr>
+<tr>
+<td>max_blockiness</td>
+<td>null</td>
+<td>非负有限数；块效应代理上限</td>
+</tr>
+<tr>
+<td>min_text_chars</td>
+<td>null</td>
+<td>非负整数，规范化文本字符数量下限</td>
+</tr>
+<tr>
+<td>max_text_chars</td>
+<td>null</td>
+<td>非负整数，字符上限，不小于 min_text_chars</td>
+</tr>
+<tr>
+<td>forbidden_text_patterns</td>
+<td>[]</td>
+<td>字符串数组；任意 Python 正则命中则拒绝；忽略大小写可用 (?i)</td>
+</tr>
+</tbody>
+</table>
+<p>质量指标缺失时不会触发对应阈值，应另行审计报告 missing 与 warnings。所有质量阈值都需要在目标数据域校准，不能将默认 null 理解为“自动判断质量”。SNR 是代理指标，不是真实 SNR/PSNR。</p>
+<h3 id="预处理与测量">预处理与测量</h3>
+<table>
+<thead>
+<tr>
+<th>字段</th>
+<th>默认值</th>
+<th>单位/范围与行为</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>reject_animated</td>
+<td>true</td>
+<td>布尔值；拒绝动画/多页；false 时只处理所读首帧/第一页</td>
+</tr>
+<tr>
+<td>max_decode_pixels</td>
+<td>100000000</td>
+<td>正整数；单图解码像素上限，超限记录为错误</td>
+</tr>
+<tr>
+<td>metric_patch_size</td>
+<td>256</td>
+<td>整数 &gt;=16；角落和中心的原生像素测量区域边长上限</td>
+</tr>
+<tr>
+<td>alpha_background</td>
+<td>[255,255,255]</td>
+<td>三个 0–255 整数；透明区域合成背景</td>
+</tr>
+<tr>
+<td>convert_icc</td>
+<td>true</td>
+<td>有 ICC 时转 sRGB；无 ICC 时按 Pillow 的 RGB 转换处理</td>
+</tr>
+<tr>
+<td>text_unicode_form</td>
+<td>NFC</td>
+<td>NFC / NFKC / none；仍执行换行与首尾空白规范化</td>
+</tr>
+</tbody>
+</table>
+<p>这六项会改变解码、标准化或指标，重筛选时必须与源分片一致；改变它们需重新 analyze。EXIF 校正与 RGB 转换始终执行。设置 max_decode_pixels 是容量限制，不会缩小超限原图。</p>
+<h3 id="去重">去重</h3>
+<table>
+<thead>
+<tr>
+<th>字段</th>
+<th>默认值</th>
+<th>范围与行为</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>deduplicate</td>
+<td>true</td>
+<td>去重总开关，关闭后所有去重均关闭</td>
+</tr>
+<tr>
+<td>near_deduplicate</td>
+<td>true</td>
+<td>开启近重复，须同时开启 deduplicate；false 仍做精确去重</td>
+</tr>
+<tr>
+<td>duplicate_scope</td>
+<td>image_text</td>
+<td>image_text：图片与规范化文字都满足；image：忽略文字差异</td>
+</tr>
+<tr>
+<td>phash_distance</td>
+<td>4</td>
+<td>整数 0–8，64 位 pHash 汉明距离上限</td>
+</tr>
+<tr>
+<td>dhash_distance</td>
+<td>4</td>
+<td>整数 0–64，64 位 dHash 汉明距离上限</td>
+</tr>
+<tr>
+<td>near_rgb_rmse</td>
+<td>8.0</td>
+<td>非负有限数；16×16 RGB 缩略图 RMSE 上限</td>
+</tr>
+<tr>
+<td>near_aspect_log_tolerance</td>
+<td>0.03</td>
+<td>非负有限数；abs(log(r1/r2)) 上限，与桶容差是不同参数</td>
+</tr>
+</tbody>
+</table>
+<p>近重复条件全部满足才归并。代表优先级为像素多、噪声低、清晰度高、清单 seq 小；不依赖 worker 完成顺序。精确去重检查原文件哈希和标准化像素哈希，作用域包含文本规则。</p>
+<h3 id="导出">导出</h3>
+<table>
+<thead>
+<tr>
+<th>字段</th>
+<th>默认值</th>
+<th>范围与行为</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>export_max_edge</td>
+<td>null</td>
+<td>正整数像素；导出时限制长边，只缩小，不放大</td>
+</tr>
+<tr>
+<td>export_format</td>
+<td>png</td>
+<td>png / jpeg</td>
+</tr>
+<tr>
+<td>export_jpeg_quality</td>
+<td>95</td>
+<td>整数 1–100；JPEG 无色度子采样，仍为有损输出</td>
+</tr>
+</tbody>
+</table>
+<p>导出参数不修改统计阶段尺寸。缩图可能因整数取整产生微小比例变化，报告桶归属针对导出前的规范化原尺寸。修改导出设置先重新 filter 到新 curated 目录再 export。</p>
+<h2 id="4-典型配置组合">4. 典型配置组合</h2>
+<h3 id="只做第一轮统计">只做第一轮统计</h3>
+<pre><code class="language-json">{&quot;deduplicate&quot;:false,&quot;near_deduplicate&quot;:false}
+</code></pre>
+<h3 id="尺寸比例文字与去重">尺寸、比例、文字与去重</h3>
+<pre><code class="language-json">{
+  &quot;resolution&quot;: &quot;256p&quot;,
+  &quot;aspect_buckets&quot;: [&quot;1:1&quot;,&quot;2:3&quot;,&quot;3:2&quot;,&quot;9:16&quot;,&quot;16:9&quot;],
+  &quot;aspect_mode&quot;: &quot;loose&quot;,
+  &quot;aspect_tolerance&quot;: 0.05,
+  &quot;min_text_chars&quot;: 1,
+  &quot;deduplicate&quot;: true,
+  &quot;near_deduplicate&quot;: true,
+  &quot;duplicate_scope&quot;: &quot;image_text&quot;,
+  &quot;export_format&quot;: &quot;png&quot;
+}
+</code></pre>
+<h3 id="原图规范化并限制导出长边">原图规范化并限制导出长边</h3>
+<pre><code class="language-json">{&quot;resolution&quot;:&quot;256p&quot;,&quot;export_max_edge&quot;:1024,&quot;export_format&quot;:&quot;jpeg&quot;,&quot;export_jpeg_quality&quot;:95}
+</code></pre>
+<p><code>generation_example.json</code> 的 512 下限和比例范围是演示配置，不是通用训练推荐。<code>exact_256p.json</code> 是兼容旧文件名，内容实际为短边 &gt;=256，请优先使用含义清晰的 <code>above_256p.json</code>。</p>
+<h2 id="5-无效设置与返回码">5. 无效设置与返回码</h2>
+<p>常见非法值：<code>resolution=256</code>、<code>aspect_buckets=[]</code>、<code>aspect_tolerance=5%</code>、数值 NaN/Infinity、负容差、拼错字段、质量阈值写成字符串、正则语法错误。容差 CLI 只能写数值，5% 写 0.05。</p>
+<p>正常完成返回 0；CLI 捕获的配置/文件/SQLite 错误返回 2；export 存在导出失败，或 run 的导出环节存在失败，返回 1。单图分析失败会记入 error，通常整个分析仍返回 0，应核对报告。非法正则等未统一捕获的异常可能显示 Python traceback 并返回非零。</p>
+<p>完整算法公式与各字段的评测解释见 <a href="USAGE.html">使用手册</a>，故障恢复见 <a href="DEPLOYMENT.html">部署指南</a>。</p></main></div><footer>NMM-data-preprocess · v0.3.0<span>图片文本数据初筛教程</span></footer></body></html>

manual/QUICKSTART.html

@@ -0,0 +1,100 @@
+<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>逐步教程 · NMM-data-preprocess</title><link rel="stylesheet" href="../assets/style.css"><script defer src="../assets/app.js"></script></head><body><header class="topbar"><a class="brand" href="../index.html">NMM<span> / </span>data-preprocess</a><nav><a href="https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess/tree/main">源代码 ↗</a><a href="../downloads/NMM-data-preprocess-0.3.0.zip" download>下载源码 ↓</a></nav></header><div class="manual-layout"><aside class="sidebar"><a href="../index.html">← 返回首页</a><a class="active" href="QUICKSTART.html">逐步教程</a><a class="" href="USAGE.html">完整手册</a><a class="" href="PARAMETERS.html">参数参考</a><a class="" href="DEPLOYMENT.html">部署指南</a><a class="" href="ARCHITECTURE.html">代码说明</a><h2>本页目录</h2><div class="toc">
+<ul>
+<li><a href="#1-下载代码">1. 下载代码</a></li>
+<li><a href="#2-windows-安装">2. Windows 安装</a></li>
+<li><a href="#3-linux-安装">3. Linux 安装</a></li>
+<li><a href="#4-先用合成样例跑通">4. 先用合成样例跑通</a></li>
+<li><a href="#5-实际数据怎样输入">5. 实际数据怎样输入</a></li>
+<li><a href="#6-在统计后筛选尺寸与宽高比">6. 在统计后筛选尺寸与宽高比</a></li>
+<li><a href="#7-再加入文本与去重规则">7. 再加入文本与去重规则</a></li>
+<li><a href="#8-查看报告导出训练清单">8. 查看报告、导出训练清单</a></li>
+<li><a href="#9-测试和后续阅读">9. 测试和后续阅读</a></li>
+</ul>
+</div>
+</aside><main class="manual"><h1 id="从下载到第一轮图片文本初筛">从下载到第一轮图片—文本初筛</h1>
+<h2 id="1-下载代码">1. 下载代码</h2>
+<p>安装 Python 3.10 或更新版本，建议 Python 3.12。使用 Git 下载，或者在 Space 首页下载源码 ZIP，解压到 <code>multimodal_training</code>。</p>
+<pre><code class="language-bash">git clone https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess multimodal_training
+cd multimodal_training
+</code></pre>
+<p>后续命令都在此目录运行。安装过程需要联网下载 NumPy 和 Pillow；实际清洗不需要联网或 GPU。</p>
+<h2 id="2-windows-安装">2. Windows 安装</h2>
+<p>在 PowerShell 执行，无需激活环境或修改执行策略：</p>
+<pre><code class="language-powershell">py -3.12 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --upgrade pip
+.\.venv\Scripts\python.exe -m pip install -e .
+.\.venv\Scripts\python.exe -m image_cleaner --help
+</code></pre>
+<p>如果没有 Python 3.12，将第一条改为 <code>python -m venv .venv</code>，并先确认 <code>python --version</code> 至少为 3.10。</p>
+<h2 id="3-linux-安装">3. Linux 安装</h2>
+<pre><code class="language-bash">python3 -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install -e .
+.venv/bin/python -m image_cleaner --help
+</code></pre>
+<p>后文 Windows 命令中的 <code>.\.venv\Scripts\python.exe</code> 在 Linux 替换为 <code>.venv/bin/python</code>，路径也换成实际 Linux 路径。</p>
+<h2 id="4-先用合成样例跑通">4. 先用合成样例跑通</h2>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe examples/make_demo.py
+.\.venv\Scripts\python.exe -m image_cleaner run --input runs/demo_input --output runs/tutorial_statistics --config configs/statistics_only.json --workers 2 --sidecar-text
+</code></pre>
+<p>合成示例包括重压缩、同像素不同格式、模糊、噪声、低分辨率、透明图、极端宽高比和坏文件。示例不是真实训练数据。生成脚本发现目标目录已存在时会停止，避免覆盖。</p>
+<p>预期输入 12 条，成功处理 11 条、错误 1 条；统计配置关闭可选阈值和去重，所以 11 条成功记录全部保留。打开 <code>runs/tutorial_statistics/curated/report.html</code>，查看原始分布与质量代理指标。坏文件应出现在 <code>error.jsonl</code>，不会使全批分析终止。</p>
+<h2 id="5-实际数据怎样输入">5. 实际数据怎样输入</h2>
+<p>最直接的方式是递归扫描图片文件夹：</p>
+<pre><code class="language-text">D:/datasets/images/
+  animal/cat.jpg
+  animal/cat.txt
+  scene/road.png
+  scene/road.txt
+</code></pre>
+<p>添加 <code>--sidecar-text</code> 会读取同名 <code>.txt</code> 文本（UTF-8）。没有文本的图片仍可导入；后续可用 <code>min_text_chars</code> 条件筛掉。</p>
+<p>已有图文配对时更推荐 JSONL，一行一条，路径相对 <code>--root</code>：</p>
+<pre><code class="language-json">{&quot;id&quot;:&quot;cat-001&quot;,&quot;path&quot;:&quot;animal/cat.jpg&quot;,&quot;text&quot;:&quot;一只猫坐在窗边。&quot;,&quot;metadata&quot;:{&quot;source&quot;:&quot;my_corpus&quot;}}
+{&quot;id&quot;:&quot;road-002&quot;,&quot;path&quot;:&quot;scene/road.png&quot;,&quot;text&quot;:&quot;雨后的城市道路。&quot;}
+</code></pre>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner run --input &quot;D:\datasets\pairs.jsonl&quot; --root &quot;D:\datasets\images&quot; --output runs/my_statistics --config configs/statistics_only.json --workers 8
+</code></pre>
+<p>输出目录应位于原始图片文件夹之外。工具不修改或删除原始图片。文件夹导入未显式启用 <code>--sidecar-text</code> 时，不会自动配对文本。</p>
+<h2 id="6-在统计后筛选尺寸与宽高比">6. 在统计后筛选尺寸与宽高比</h2>
+<pre><code class="language-powershell"># 短边 &gt;=256；宽高比在八桶内，允许 5% 对称偏差。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/tutorial_statistics/shards --output runs/tutorial_filtered --resolution 256p --aspect-buckets all --aspect-mode loose --aspect-tolerance 0.05
+
+# 严格只留方图或 3:2 横图，输出到另一个目录。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/tutorial_statistics/shards --output runs/tutorial_strict --resolution 256p --aspect-buckets &quot;1:1,3:2&quot; --aspect-mode strict
+</code></pre>
+<p><code>256p</code> 的定义是 <code>min(width,height)&gt;=256</code>，包括正好 256；不要求短边必须等于 256。<code>256x256</code> 才是精确尺寸。宽高比始终按方向校正后的宽:高计算。</p>
+<p>宽松偏差为 <code>max(r/b,b/r)-1</code>，<code>0.05</code> 表示 5%。参数说明和完整边界例子见 <a href="USAGE.html">完整手册</a>。重筛选读取原分析分片，不重复解码；规则取交集。</p>
+<h2 id="7-再加入文本与去重规则">7. 再加入文本与去重规则</h2>
+<p>在项目根目录新建 <code>my_rules.json</code>：</p>
+<pre><code class="language-json">{
+  &quot;resolution&quot;: &quot;256p&quot;,
+  &quot;aspect_buckets&quot;: &quot;all&quot;,
+  &quot;aspect_mode&quot;: &quot;loose&quot;,
+  &quot;aspect_tolerance&quot;: 0.05,
+  &quot;min_text_chars&quot;: 1,
+  &quot;deduplicate&quot;: true,
+  &quot;near_deduplicate&quot;: true,
+  &quot;duplicate_scope&quot;: &quot;image_text&quot;
+}
+</code></pre>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/tutorial_statistics/shards --output runs/tutorial_dedup --config my_rules.json
+</code></pre>
+<p>显式提供 JSON 配置文件时，未写字段使用 Config 默认值，而不是与分析分片逐项合并。默认开启精确与近重复去重；纯统计配置特意关闭了它们。同图不同规范化文本默认保留；改为 <code>duplicate_scope=image</code> 会忽略文本差异。</p>
+<p>质量阈值如 <code>min_blur_score</code>、<code>max_noise_sigma</code>、<code>min_snr_proxy_db</code>、<code>max_blockiness</code> 应先在代表性样本上校准，再写入配置；没有跨数据域通用的推荐数值。</p>
+<h2 id="8-查看报告导出训练清单">8. 查看报告、导出训练清单</h2>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner export --curated runs/tutorial_dedup --output runs/tutorial_export --workers 2
+</code></pre>
+<p>清洗目录有 <code>kept/rejected/duplicate/error.jsonl</code>、<code>report.json</code>、<code>report.html</code>、<code>curation.sqlite</code>。导出目录有 RGB 图片、相对路径与文本组成的 <code>exported.jsonl</code>、失败清单和续跑元数据。</p>
+<p>优先核对以下项目：</p>
+<ol>
+<li>输入数等于保留、拒绝、重复、错误四类数量之和。</li>
+<li>错误数及错误原因；质量缺失指标并不等于通过人工质量检验。</li>
+<li>分辨率与桶的独立通过率，以及全部规则通过率。</li>
+<li>各桶前后样本数量；抽查被拒绝的临界图片和近重复判定。</li>
+<li>最终图文是否对应。当前工具没有图文语义一致性模型。</li>
+</ol>
+<p>导出的文本已做 Unicode 与空白规范化；图片做 EXIF、色彩、透明度与 RGB 标准化。训练时的张量归一化、裁剪和多模态对齐仍由训练数据加载器负责。</p>
+<h2 id="9-测试和后续阅读">9. 测试和后续阅读</h2>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m unittest discover -s tests -v
+</code></pre>
+<p>基础版本包含 21 项清洗测试。详细参数见 <a href="PARAMETERS.html">参数参考</a>，多机与续跑见 <a href="DEPLOYMENT.html">部署指南</a>，逐阶段指标见 <a href="USAGE.html">完整手册</a>，实现细节见 <a href="ARCHITECTURE.html">代码说明</a>。</p></main></div><footer>NMM-data-preprocess · v0.3.0<span>图片文本数据初筛教程</span></footer></body></html>

manual/USAGE.html

@@ -0,0 +1,816 @@
+<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>完整手册 · NMM-data-preprocess</title><link rel="stylesheet" href="../assets/style.css"><script defer src="../assets/app.js"></script></head><body><header class="topbar"><a class="brand" href="../index.html">NMM<span> / </span>data-preprocess</a><nav><a href="https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess/tree/main">源代码 ↗</a><a href="../downloads/NMM-data-preprocess-0.3.0.zip" download>下载源码 ↓</a></nav></header><div class="manual-layout"><aside class="sidebar"><a href="../index.html">← 返回首页</a><a class="" href="QUICKSTART.html">逐步教程</a><a class="active" href="USAGE.html">完整手册</a><a class="" href="PARAMETERS.html">参数参考</a><a class="" href="DEPLOYMENT.html">部署指南</a><a class="" href="ARCHITECTURE.html">代码说明</a><h2>本页目录</h2><div class="toc">
+<ul>
+<li><a href="#1-工具范围和运行环境">1. 工具范围和运行环境</a></li>
+<li><a href="#2-输入方式">2. 输入方式</a><ul>
+<li><a href="#21-文件夹适合直接批量导入">2.1 文件夹：适合直接批量导入</a></li>
+<li><a href="#22-jsonl适合图文配对与多机迁移">2.2 JSONL：适合图文配对与多机迁移</a></li>
+</ul>
+</li>
+<li><a href="#3-推荐流程先统计再筛选再导出">3. 推荐流程：先统计，再筛选，再导出</a><ul>
+<li><a href="#31-全量分布统计">3.1 全量分布统计</a></li>
+<li><a href="#32-保留-256p-及以上的图片">3.2 保留 256p 及以上的图片</a></li>
+<li><a href="#33-分辨率与其他筛选一起执行">3.3 分辨率与其他筛选一起执行</a></li>
+<li><a href="#34-导出标准化图片与文本">3.4 导出标准化图片与文本</a></li>
+<li><a href="#35-一键流程">3.5 一键流程</a></li>
+<li><a href="#36-宽高比桶筛选">3.6 宽高比桶筛选</a></li>
+</ul>
+</li>
+<li><a href="#4-各环节指标和判定规则">4. 各环节指标和判定规则</a><ul>
+<li><a href="#41-导入解码和容量检查">4.1 导入、解码和容量检查</a></li>
+<li><a href="#42-标准化">4.2 标准化</a></li>
+<li><a href="#43-分布统计分辨率和宽高比">4.3 分布统计、分辨率和宽高比</a></li>
+<li><a href="#44-图片技术质量">4.4 图片技术质量</a></li>
+<li><a href="#45-文本筛选">4.5 文本筛选</a></li>
+<li><a href="#46-去重">4.6 去重</a></li>
+<li><a href="#47-阶段评测指标">4.7 阶段评测指标</a></li>
+<li><a href="#48-宽高比桶筛选评测指标">4.8 宽高比桶筛选评测指标</a></li>
+</ul>
+</li>
+<li><a href="#5-配置文件和参数">5. 配置文件和参数</a></li>
+<li><a href="#6-多机分片流程">6. 多机分片流程</a></li>
+<li><a href="#7-输出断点续跑和复核">7. 输出、断点续跑和复核</a></li>
+<li><a href="#8-验证与功能边界">8. 验证与功能边界</a></li>
+</ul>
+</div>
+</aside><main class="manual"><h1 id="图片文本数据清洗完整操作与指标手册">图片—文本数据清洗：完整操作与指标手册</h1>
+<h2 id="1-工具范围和运行环境">1. 工具范围和运行环境</h2>
+<p>本工具处理本地图片与可选文本，完成导入、规范化测量、分布统计、分辨率/质量筛选、去重和独立导出。源文件不修改、不删除。保留/拒绝/重复/错误的判断通过输出清单表达。</p>
+<p>Python 3.10+；Windows 与 Linux；基础处理不需要 GPU。先下载仓库，以下以安装目录为例：</p>
+<pre><code class="language-text">D:\projects\multimodal_training
+</code></pre>
+<p>Windows 首次安装需要建立 <code>.venv</code>，完成后进入项目目录使用：</p>
+<pre><code class="language-powershell">cd D:\projects\multimodal_training
+.\.venv\Scripts\python.exe -m image_cleaner --help
+</code></pre>
+<p>新机器首次安装：</p>
+<pre><code class="language-powershell">python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e .
+</code></pre>
+<p>Linux 对应安装与命令前缀：</p>
+<pre><code class="language-bash">python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+.venv/bin/python -m image_cleaner --help
+</code></pre>
+<p>下文 Windows 命令均在项目根目录运行。Linux 将前缀改为 <code>.venv/bin/python</code> 并使用相应路径即可。每次筛选使用新的输出目录。</p>
+<h2 id="2-输入方式">2. 输入方式</h2>
+<h3 id="21-文件夹适合直接批量导入">2.1 文件夹：适合直接批量导入</h3>
+<pre><code class="language-text">D:\datasets\images\
+  animals\001.jpg
+  animals\001.txt
+  charts\002.png
+  charts\002.txt
+</code></pre>
+<p>递归发现 <code>.jpg/.jpeg/.png/.webp/.bmp/.tif/.tiff/.gif/.avif</code>。图片有同名 UTF-8 <code>.txt</code> 时加 <code>--sidecar-text</code>，否则只导入图片。默认不跟随目录符号链接；扩展名发现列表与实际可解码格式不同，具体解码能力取决于 Pillow。</p>
+<h3 id="22-jsonl适合图文配对与多机迁移">2.2 JSONL：适合图文配对与多机迁移</h3>
+<p>每行至少一个字符串 <code>path</code>，可以附带 <code>text</code>、<code>id</code>、<code>metadata</code>：</p>
+<pre><code class="language-json">{&quot;id&quot;:&quot;original-001&quot;,&quot;path&quot;:&quot;animals/001.jpg&quot;,&quot;text&quot;:&quot;一只猫坐在窗边。&quot;,&quot;metadata&quot;:{&quot;source&quot;:&quot;dataset-a&quot;}}
+{&quot;id&quot;:&quot;original-002&quot;,&quot;path&quot;:&quot;charts/002.png&quot;,&quot;text&quot;:&quot;一个展示月份销量的柱状图。&quot;}
+</code></pre>
+<p>相对路径以 <code>--root</code> 为基准；省略时以输入 JSONL 所在目录为基准。原始 ID 保存为 <code>source_id</code>，其他额外字段归入 <code>metadata</code>。同一图片允许多条不同文本记录。跨节点推荐相对路径；绝对路径不受 <code>--root</code> 重映射。</p>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner run --input &quot;D:\datasets\pairs.jsonl&quot; --root &quot;D:\datasets\images&quot; --output runs/pairs_statistics --config configs/statistics_only.json --workers 8
+</code></pre>
+<p>格式错误的输入 JSONL、非字符串文本或无法读取的 sidecar 会使导入报错；单张图片缺失或损坏在分析阶段记录为错误。工具不直接下载 URL 或读取压缩包内的图片。</p>
+<h2 id="3-推荐流程先统计再筛选再导出">3. 推荐流程：先统计，再筛选，再导出</h2>
+<h3 id="31-全量分布统计">3.1 全量分布统计</h3>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner run --input &quot;D:\datasets\images&quot; --output runs/statistics --config configs/statistics_only.json --workers 8 --sidecar-text
+</code></pre>
+<p>只处理图片且没有文本时移除 <code>--sidecar-text</code>。统计配置关闭尺寸/质量/文本可选阈值和去重，成功处理的静态图片全部保留；损坏、超过容量限制、动画/多页等仍作为错误记录。</p>
+<p>查看报告：</p>
+<pre><code class="language-powershell">Start-Process -FilePath &quot;runs/statistics/curated/report.html&quot;
+</code></pre>
+<p><code>report.json</code> 适合程序读取，<code>report.html</code> 包含无外部依赖的分布图。先检查分辨率、宽高比、噪声与清晰度分布，再确定规则。</p>
+<h3 id="32-保留-256p-及以上的图片">3.2 保留 256p 及以上的图片</h3>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_256p --resolution 256p
+</code></pre>
+<p><code>256p</code> 的定义是 <code>min(width, height) &gt;= 256</code>，表示短边大于或等于 256 像素，256 本身保留。它不表示缩放图片，与 <code>min_short_edge=256</code> 的尺寸边界相同。</p>
+<table>
+<thead>
+<tr>
+<th>图片尺寸（宽×高）</th>
+<th><code>256p</code></th>
+<th><code>256x256</code></th>
+<th><code>384x256</code></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>256×256</td>
+<td>保留</td>
+<td>保留</td>
+<td>拒绝</td>
+</tr>
+<tr>
+<td>384×256</td>
+<td>保留</td>
+<td>拒绝</td>
+<td>保留</td>
+</tr>
+<tr>
+<td>256×384</td>
+<td>保留</td>
+<td>拒绝</td>
+<td>拒绝</td>
+</tr>
+<tr>
+<td>255×384</td>
+<td>拒绝</td>
+<td>拒绝</td>
+<td>拒绝</td>
+</tr>
+<tr>
+<td>257×384</td>
+<td>保留</td>
+<td>拒绝</td>
+<td>拒绝</td>
+</tr>
+<tr>
+<td>512×512</td>
+<td>保留</td>
+<td>拒绝</td>
+<td>拒绝</td>
+</tr>
+</tbody>
+</table>
+<p>其他选择：</p>
+<pre><code class="language-powershell"># 仅保留 256×256。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_square --resolution 256x256
+
+# 仅保留宽 384、高 256。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_landscape --resolution 384x256
+
+# 改为短边大于或等于 512。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_512p --resolution 512p
+
+# 关闭分辨率条件。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/all_resolutions --resolution any
+</code></pre>
+<p>尺寸以 EXIF 方向校正后的宽高为准：编码为 256×384、EXIF 要求旋转 90° 的图片会以 384×256 判断。色彩转换不改变尺寸；导出缩放发生在筛选之后。</p>
+<p><code>filter</code> 等价于 <code>merge</code>，始终从分析分片里的全部记录重新判定，不能把它的 <code>--shards</code> 指向上一轮 <code>curated</code> 目录。即使第一轮某图片被阈值或去重排除，分析结果仍在分片中，可以再次参与筛选。原图不会被重新解码；物理导出仍需要原图存在。</p>
+<h3 id="33-分辨率与其他筛选一起执行">3.3 分辨率与其他筛选一��执行</h3>
+<p>使用配置文件可同时加入宽高比、质量、文本条件或去重：</p>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/256p_deduplicated --config configs/audit.json --resolution 256p
+</code></pre>
+<p>上例额外开启去重；符合尺寸的重复记录仍会进入 <code>duplicate.jsonl</code>。如果只希望剔除短边小于 256 的图片，沿用统计配置或指定 <code>--config configs/above_256p.json</code>，其去重关闭。</p>
+<p>配置优先级：未传 <code>--config</code> 时继承分析时的完整配置；传了 <code>--config</code> 时从该 JSON 和代码默认值构造新配置，不是对原配置做部分补丁；<code>--resolution</code> 最后覆盖分辨率字段。所有启用规则取交集。若同时设置 <code>min_short_edge=512</code> 与 <code>resolution=256p</code>，最终仍要求短边至少 512；如需允许所有大于或等于 256 的尺寸，先关闭更严格的其他尺寸规则。</p>
+<p>阈值修改和精确分辨率筛选可以复用分析结果。<code>reject_animated/max_decode_pixels/metric_patch_size/alpha_background/convert_icc/text_unicode_form</code> 属于测量与预处理设置，改变这些设置需要重新分析。</p>
+<h3 id="34-导出标准化图片与文本">3.4 导出标准化图片与文本</h3>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner export --curated runs/only_256p --output runs/export_256p --workers 8
+</code></pre>
+<p>只导出 <code>kept.jsonl</code> 中的记录，默认 PNG、RGB、保留已匹配尺寸，不做裁剪或放大。文件放在 <code>images</code> 子目录，<code>exported.jsonl</code> 的 <code>path</code> 为导出目录下的相对路径。导出会校验源文件 SHA-256；源文件在分析后发生变化会记录失败。</p>
+<p><code>export_max_edge</code> 如被启用，可能改变筛选后图片尺寸；需要导出文件仍满足筛选条件时保持 <code>export_max_edge=null</code>。例如 1024×512 符合 256p 及以上，但若导出最长边限制为 384，则会缩成 384×192，输出不再满足短边至少 256 的条件。</p>
+<h3 id="35-一键流程">3.5 一键流程</h3>
+<p>已经明确目标时可以直接执行：</p>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner run --input &quot;D:\datasets\images&quot; --output runs/direct_256p --config configs/above_256p.json --workers 8 --export
+</code></pre>
+<p>也可以在 <code>run</code> 或 <code>analyze</code> 上直接传 <code>--resolution</code>；推荐第一次先完成全量统计。</p>
+<h3 id="36-宽高比桶筛选">3.6 宽高比桶筛选</h3>
+<p>比例始终为 EXIF 方向校正后的 <strong>宽:高</strong>。八个固定桶为 <code>1:1,2:3,3:2,3:4,4:3,9:16,16:9,21:9</code>。竖图与横图分别选择，例如选择 <code>2:3</code> 不会自动选择 <code>3:2</code>。</p>
+<pre><code class="language-powershell"># 在项目根目录执行。先运行 3.1 的统计任务，再用缓存分片筛选。
+# 严格多选：实际尺寸必须与任意一个选中桶完全同比分配。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_strict --aspect-buckets &quot;1:1,2:3,3:2&quot; --aspect-mode strict
+
+# 宽松全选：5% 偏差，也可以省略 tolerance 参数使用默认值。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_loose --aspect-buckets all --aspect-mode loose --aspect-tolerance 0.05
+
+# 更严格的 3% 容差，同时保留短边 &gt;=256 的图片。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_3percent_256 --resolution 256p --aspect-buckets &quot;3:4,4:3,9:16,16:9&quot; --aspect-mode loose --aspect-tolerance 0.03
+
+# 覆盖已有配置、关闭桶条件。其他筛选条件继续生效。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_disabled --aspect-buckets none
+
+# 从文件夹直接运行，支持多进程。
+.\.venv\Scripts\python.exe -m image_cleaner run --input &quot;D:\datasets\images&quot; --output runs/aspect_run --workers 8 --aspect-buckets all --aspect-mode loose
+
+# 使用示例配置。示例关闭去重以便单独观察桶筛选效果。
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_config --config configs/aspect_loose.json
+</code></pre>
+<p>每次重筛选使用一个新的输出目录。<code>filter</code> 读取全部分析记录，包括此前被规则拒绝的图片；因此既能收紧也能放宽条件，不需要再次解码。解码失败的记录仍归入错误。</p>
+<table>
+<thead>
+<tr>
+<th>参数</th>
+<th>默认值</th>
+<th>含义</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>--aspect-buckets</code></td>
+<td>不启用，或继承配置/分片</td>
+<td>英文逗号分隔多选；<code>all</code> 是八桶并集；<code>none</code> 关闭；空值或非预设桶报错</td>
+</tr>
+<tr>
+<td><code>--aspect-mode</code></td>
+<td><code>strict</code>，或继承配置/分片</td>
+<td><code>strict</code> 精确匹配；<code>loose</code> 容差匹配</td>
+</tr>
+<tr>
+<td><code>--aspect-tolerance</code></td>
+<td><code>0.05</code>，或继承配置/分片</td>
+<td>有限非负小数，仅宽松模式生效；<code>0.05</code> 表示 5%，<code>0</code> 表示不允许偏差</td>
+</tr>
+</tbody>
+</table>
+<p>三个参数均支持 <code>analyze</code>、<code>filter</code>/<code>merge</code>、<code>run</code>。显式命令行参数优先于配置；未传参数保留配置值。没有传 <code>--config</code> 的 <code>filter</code> 继承分析分片配置；传入配置文件则按该文件及 Config 默认值构建整套筛选规则。</p>
+<p>设实际比例 <code>r=width/height</code>，目标桶比例 <code>b</code>。严格模式使用整数交叉相乘：例如 <code>2:3</code> 要求 <code>width×3 == height×2</code>。宽松模式要求 <code>δ=max(r/b,b/r)-1 &lt;= aspect_tolerance</code>，包含边界。实现使用精确分数比较。例如选 <code>1:1</code>、偏差 5% 时，<code>1050×1000</code> 和 <code>1000×1050</code> 均通过，<code>1051×1000</code> 不通过。此对称定义下允许区间为 <code>[b/1.05, b×1.05]</code>，并非普通的 <code>[b×0.95,b×1.05]</code>。</p>
+<p>任意一个选中桶匹配即可通过。如果匹配多个桶，则只分配给偏差最小的桶；同偏差按上述固定八桶顺序选取，因此每张图片只计数一次。重复选择会合并。<code>all</code> 仍会过滤超出所有桶范围的图片。桶条件与分辨率、<code>min_aspect_ratio/max_aspect_ratio</code>、质量、文本条件取交集；不会裁剪或缩放图片。</p>
+<p>配置文件新增字段示例：</p>
+<pre><code class="language-json">{
+  &quot;aspect_buckets&quot;: [&quot;1:1&quot;, &quot;2:3&quot;, &quot;3:2&quot;],
+  &quot;aspect_mode&quot;: &quot;loose&quot;,
+  &quot;aspect_tolerance&quot;: 0.05
+}
+</code></pre>
+<p><code>aspect_buckets</code> 也接受 <code>"all"</code>、<code>"none"</code> 或 <code>null</code>。多机仍使用第 6 节的同一 manifest 和 rank/world-size 流程；所有节点分析配置一致，收集全部分片后统一执行上面的 <code>filter</code> 命令，桶筛选无需各节点读取源图片。</p>
+<h2 id="4-各环节指标和判定规则">4. 各环节指标和判定规则</h2>
+<h3 id="41-导入解码和容量检查">4.1 导入、解码和容量检查</h3>
+<table>
+<thead>
+<tr>
+<th>字段/指标</th>
+<th>意义</th>
+<th>判定</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>input_count</code></td>
+<td>清单记录数量，包含同图多文本记录</td>
+<td>不是去重后的独立图片数</td>
+</tr>
+<tr>
+<td><code>original_width/original_height</code></td>
+<td>文件编码中的原始尺寸</td>
+<td>与 EXIF 校正后的尺寸分别保存</td>
+</tr>
+<tr>
+<td><code>original_format/original_mode</code></td>
+<td>解码格式和像素模式</td>
+<td>用于来源与格式审计</td>
+</tr>
+<tr>
+<td><code>frame_count</code></td>
+<td>帧数或页数</td>
+<td>默认 <code>reject_animated=true</code> 时，多帧/多页报处理错误</td>
+</tr>
+<tr>
+<td><code>max_decode_pixels</code></td>
+<td>单图最大解码像素数</td>
+<td>默认 100,000,000；超过限制报错</td>
+</tr>
+<tr>
+<td><code>error_count</code>、<code>error.jsonl</code></td>
+<td>文件缺失、损坏、截断或处理异常</td>
+<td>不进入有效分布统计与导出</td>
+</tr>
+<tr>
+<td><code>processing_success_rate</code></td>
+<td>完成整套图片处理数 ÷ 输入记录数</td>
+<td>是处理成功率，不是人工质量准确率</td>
+</tr>
+</tbody>
+</table>
+<h3 id="42-标准化">4.2 标准化</h3>
+<table>
+<thead>
+<tr>
+<th>字段/设置</th>
+<th>行为和验证方法</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>exif_transposed</code></td>
+<td>是否按 EXIF 方向进行转置；查看标准化宽高并抽查方向</td>
+</tr>
+<tr>
+<td><code>icc_converted</code></td>
+<td>有 ICC 且开启转换时转为 sRGB；失败记错误</td>
+</tr>
+<tr>
+<td><code>alpha_flattened</code></td>
+<td>是否存在透明通道并按 <code>alpha_background</code> 合成；默认白色</td>
+</tr>
+<tr>
+<td><code>text_unicode_form</code></td>
+<td>NFC 默认；可选 NFKC 或 none；同时统一换行并去首尾/行尾空白</td>
+</tr>
+<tr>
+<td>导出的 <code>width/height</code>、像素模式</td>
+<td>检查最终尺寸与 RGB 模式；导出可选等比例缩小</td>
+</tr>
+</tbody>
+</table>
+<p>标准化属于数据规范化，未实现模型训练的 dropout/weight decay，也不会执行默认去噪或锐化。16 位/浮点图片最终转为 8 位 RGB，本工具主要面向常规网页图像。</p>
+<h3 id="43-分布统计分辨率和宽高比">4.3 分布统计、分辨率和宽高比</h3>
+<table>
+<thead>
+<tr>
+<th>字段</th>
+<th>定义/单位</th>
+<th>筛选配置</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>width</code></td>
+<td>EXIF 校正后的宽度，像素</td>
+<td><code>resolution=WxH</code> 可精确限定</td>
+</tr>
+<tr>
+<td><code>height</code></td>
+<td>EXIF 校正后的高度，像素</td>
+<td><code>resolution=WxH</code> 可精确限定</td>
+</tr>
+<tr>
+<td><code>short_edge</code></td>
+<td>min(width,height)，像素</td>
+<td><code>resolution=Np</code> 要求大于或等于 N；<code>min_short_edge</code> 为包含边界的下限</td>
+</tr>
+<tr>
+<td><code>long_edge</code></td>
+<td>max(width,height)，像素</td>
+<td><code>max_long_edge</code> 为上限</td>
+</tr>
+<tr>
+<td><code>pixels</code></td>
+<td>width×height</td>
+<td><code>min_pixels/max_pixels</code></td>
+</tr>
+<tr>
+<td><code>aspect_ratio</code></td>
+<td>width/height</td>
+<td><code>min_aspect_ratio/max_aspect_ratio</code></td>
+</tr>
+<tr>
+<td><code>orientations</code></td>
+<td>横、竖、近方图数量</td>
+<td>0.95≤W/H≤1.05 视为近方图；只是统计类别</td>
+</tr>
+</tbody>
+</table>
+<p>分辨率筛选不匹配时，原因是 <code>resolution_mismatch</code>。<code>min_short_edge=256</code> 与 <code>resolution=256p</code> 均包含 256，因此 255 不合格，256 和 257 合格。<code>resolution_filter.mode=short_edge_gte</code> 与 <code>comparison="&gt;="</code> 在报告中记录这一判定；<code>WxH</code> 仍为精确宽高匹配。</p>
+<p>每个分布提供有效数量、缺失数量、最小值、最大值、均值、总体标准差、p1/p5/p25/p50/p75/p95/p99，以及固定桶直方图。桶为左闭右开，最后覆盖到无穷大；直方图是全量精确计数。分位数最多使用固定种子 20,000 条蓄水池样本；更大规模时 <code>quantiles_approximate=true</code>。</p>
+<p><code>before</code> 覆盖成功处理的全部记录，<code>after</code> 覆盖最终保留记录；不代表按独立图片去重后的来源统计。分辨率匹配数另外直接按每条记录统计，避免粗直方图桶无法区分 255/256/257 的问题。</p>
+<h3 id="44-图片技术质量">4.4 图片技术质量</h3>
+<p>默认在四角和中心最多五个原生像素区域测量，区域大小最多 <code>metric_patch_size=256</code>，相同区域去重，各指标取有效区域的中位数。不会先缩图再测量；可能漏掉未采样区域的局部缺陷。</p>
+<table>
+<thead>
+<tr>
+<th>字段</th>
+<th>计算方式、解释</th>
+<th>筛选条件</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>blur_score</code></td>
+<td>灰度区域上 Var(up+down+left+right−4×center)，拉普拉斯方差；通常越低越模糊</td>
+<td>低于 <code>min_blur_score</code> 拒绝</td>
+</tr>
+<tr>
+<td><code>noise_sigma</code></td>
+<td>在梯度最低约 30% 区域，用 3×3 高通残差计算 MAD/(0.67448975×6)，像素幅度范围 0–255</td>
+<td>高于 <code>max_noise_sigma</code> 拒绝</td>
+</tr>
+<tr>
+<td><code>snr_proxy_db</code></td>
+<td>每区域 20log10(灰度标准差/noise_sigma)，然后取区域中位数</td>
+<td>低于 <code>min_snr_proxy_db</code> 拒绝</td>
+</tr>
+<tr>
+<td><code>blockiness</code></td>
+<td>对水平/垂直 8 像素网格各相位求边界梯度与非边界梯度差；每轴取最大差，再平均并截断到非负</td>
+<td>高于 <code>max_blockiness</code> 拒绝</td>
+</tr>
+<tr>
+<td><code>luminance</code></td>
+<td>灰度均值，0–255</td>
+<td>当前仅记录，无直接阈值</td>
+</tr>
+<tr>
+<td><code>contrast</code></td>
+<td>灰度总体标准差</td>
+<td>当前仅记录，无直接阈值</td>
+</tr>
+<tr>
+<td><code>metric_patch_count</code></td>
+<td>实际采样区域数</td>
+<td>当前仅记录，方便审计</td>
+</tr>
+</tbody>
+</table>
+<p>这些是代理指标：拉普拉斯方差可能因噪声升高，纹理会影响噪声估计，规则图案也会产生块效应分数。信噪比的“信号”采用局部亮度标准差，不是真实 SNR，也不是 PSNR。</p>
+<p>噪声或对比度接近零时，SNR 返回 <code>null</code> 并写入 <code>snr_proxy_undefined</code>；极小图片部分指标为 <code>null</code>。缺失值不会触发对应质量阈值。报告的 <code>missing</code> 表示未得到指标值，不表示质量合格。</p>
+<p>所有质量阈值默认 null（关闭）；先按照片/截图/图表/插画等类型抽查，再设置阈值。修改 <code>metric_patch_size</code> 会改变指标分布，必须重新分析并重新校准。</p>
+<h3 id="45-文本筛选">4.5 文本筛选</h3>
+<table>
+<thead>
+<tr>
+<th>指标/设置</th>
+<th>判定</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>text_chars</code></td>
+<td>规范化后 Python 字符数量；缺失文本按 0 统计，不是 token 数或单词数</td>
+</tr>
+<tr>
+<td><code>min_text_chars</code></td>
+<td>低于下限拒绝；设置为 1 可排除没���文字的样本</td>
+</tr>
+<tr>
+<td><code>max_text_chars</code></td>
+<td>超过上限拒绝</td>
+</tr>
+<tr>
+<td><code>forbidden_text_patterns</code></td>
+<td>任一 Python 正则表达式 <code>re.search</code> 命中即拒绝，默认区分大小写</td>
+</tr>
+</tbody>
+</table>
+<p>例如配置 <code>"forbidden_text_patterns": ["(?i)buy\\s+now", "点击购买"]</code> 可匹配部分广告文本。这是启发式文本规则，不能判断图片与文本是否语义对应。</p>
+<h3 id="46-去重">4.6 去重</h3>
+<p>质量规则通过后再进行全局去重，以避免不合格图片挤掉合格代表。</p>
+<table>
+<thead>
+<tr>
+<th>指标/类型</th>
+<th>判定</th>
+<th>配置</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>file_sha256</code>、<code>exact_file</code></td>
+<td>原文件字节 SHA-256 一致</td>
+<td><code>deduplicate=true</code></td>
+</tr>
+<tr>
+<td><code>pixel_sha256</code>、<code>exact_pixels</code></td>
+<td>标准化 RGB 尺寸和像素一致</td>
+<td><code>deduplicate=true</code></td>
+</tr>
+<tr>
+<td>pHash 汉明距离</td>
+<td>64 位低频 DCT 特征哈希差异</td>
+<td>不超过 <code>phash_distance</code>，默认 4，可设 0–8</td>
+</tr>
+<tr>
+<td>dHash 汉明距离</td>
+<td>64 位相邻灰度梯度特征差异</td>
+<td>不超过 <code>dhash_distance</code>，默认 4，可设 0–64</td>
+</tr>
+<tr>
+<td>RGB 缩略图 RMSE</td>
+<td>16×16 RGB 图像 sqrt(mean((a−b)²))</td>
+<td>不超过 <code>near_rgb_rmse</code>，默认 8.0</td>
+</tr>
+<tr>
+<td>宽高比差异</td>
+<td>abs(log(ratio_a/ratio_b))</td>
+<td>不超过 <code>near_aspect_log_tolerance</code>，默认 0.03</td>
+</tr>
+<tr>
+<td><code>near_perceptual</code></td>
+<td>上述近重复条件均满足</td>
+<td><code>near_deduplicate=true</code> 且总去重开启</td>
+</tr>
+</tbody>
+</table>
+<p>pHash 使用相对 AC 系数容差抑制极小系数，与普通 pHash 数值不完全相同。所有近重复复核是启发式，不能代替语义 embedding 去重。</p>
+<p>默认 <code>duplicate_scope=image_text</code>：规范化文本也相同才归并，保留同图不同描述/问答；没有文本时按图片归并。<code>image</code> 会忽略文本差异。代表优先级为像素数降序、噪声升序、清晰度降序、清单序号升序，不是人工审美排序。</p>
+<p><code>duplicate.jsonl</code> 给出 <code>duplicate_of/duplicate_kind/duplicate_metrics</code>。近重复记录目前保存 pHash 距离和 RGB RMSE，dHash 与比例条件用于判断但未单独写入距离字段。每个重复直接匹配一个保留代表，不通过无限传递链扩大分组。</p>
+<h3 id="47-阶段评测指标">4.7 阶段评测指标</h3>
+<p>令 N 为输入条数、D 为处理成功条数、M 为指定分辨率匹配条数、E 为全部规则通过条数、U 为重复条数、K 为最终保留条数：</p>
+<table>
+<thead>
+<tr>
+<th><code>report.json</code> 字段</th>
+<th>定义</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>input_count</code></td>
+<td>N</td>
+</tr>
+<tr>
+<td><code>error_count</code></td>
+<td>N−D</td>
+</tr>
+<tr>
+<td><code>stage_metrics.processing_success_count/rate</code></td>
+<td>D、D/N</td>
+</tr>
+<tr>
+<td><code>stage_metrics.resolution_matched_count</code></td>
+<td>M，单独按尺寸条件计算，不含其他质量限制</td>
+</tr>
+<tr>
+<td><code>stage_metrics.resolution_mismatched_count</code></td>
+<td>D−M</td>
+</tr>
+<tr>
+<td><code>stage_metrics.resolution_pass_rate</code></td>
+<td>M/D；分辨率条件关闭时为 1（D&gt;0）</td>
+</tr>
+<tr>
+<td><code>stage_metrics.rules_eligible_count/rules_pass_rate</code></td>
+<td>E=K+U、E/D</td>
+</tr>
+<tr>
+<td><code>rejected_count</code></td>
+<td>D−E，至少一个规则不合格</td>
+</tr>
+<tr>
+<td><code>duplicate_count</code></td>
+<td>U</td>
+</tr>
+<tr>
+<td><code>stage_metrics.duplicate_rate_among_eligible</code></td>
+<td>U/E</td>
+</tr>
+<tr>
+<td><code>kept_count/stage_metrics.final_keep_rate</code></td>
+<td>K、K/N</td>
+</tr>
+<tr>
+<td><code>before.reasons</code></td>
+<td>最终各原因的出现次数；一条拒绝记录可有多个原因，不可直接加总当成样本数</td>
+</tr>
+</tbody>
+</table>
+<p>分母为零时比率为 null。比率是 0–1 的数值；乘 100 得百分比。每次完整输出满足 <code>N=K+rejected_count+U+error_count</code>。关闭去重时 U=0。</p>
+<p>这些指标衡量清洗流程和数据组成，不是模型性能或人工标注准确率。若要评估误删/漏删，按图片类型和规则分层抽取人工审核样本，统计“被拒绝但实际可用”的比例和“保留但实际不合格”的比例。后续训练收益需要固定训练预算、随机种子与验证集做对照实验。</p>
+<h3 id="48-宽高比桶筛选评测指标">4.8 宽高比桶筛选评测指标</h3>
+<p>打开输出目录的 <code>report.html</code> 查看新增宽高比桶部分；<code>report.json</code> ���供机器可读指标，<code>kept.jsonl</code>、<code>rejected.jsonl</code> 等提供逐条结果。</p>
+<table>
+<thead>
+<tr>
+<th>指标/字段</th>
+<th>定义与用途</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>stage_metrics.aspect_bucket_matched_count</code></td>
+<td>成功解码记录中，单独满足桶条件的数量；不受其他阈值和去重影响</td>
+</tr>
+<tr>
+<td><code>aspect_bucket_mismatched_count</code></td>
+<td>成功解码数量减去桶匹配数量</td>
+</tr>
+<tr>
+<td><code>aspect_bucket_pass_rate</code></td>
+<td>桶匹配数 / 成功解码数；无成功解码记录为 null；关闭桶条件时成功解码记录全部通过</td>
+</tr>
+<tr>
+<td><code>aspect_bucket_filter.counts_before</code></td>
+<td>所有成功解码图片的匹配桶归属计数，包含因其他条件拒绝或重复的图片</td>
+</tr>
+<tr>
+<td><code>aspect_bucket_filter.counts_after</code></td>
+<td>最终 kept 图片的桶归属计数，已应用全部规则及去重</td>
+</tr>
+<tr>
+<td><code>aspect_bucket_filter</code> 其余字段</td>
+<td>是否启用、选中桶、模式、容差、尺寸计算依据、偏差公式</td>
+</tr>
+<tr>
+<td>每条记录 <code>aspect_bucket</code></td>
+<td>匹配且分配的桶；没有通过桶条件或关闭条件时为 null</td>
+</tr>
+<tr>
+<td><code>aspect_bucket_nearest</code></td>
+<td>最近的选中桶，即使不通过也可用来排查；关闭条件时为 null</td>
+</tr>
+<tr>
+<td><code>aspect_bucket_deviation</code></td>
+<td>到最近桶的对称相对偏差；例如 0.05 是 5%；关闭条件时为 null</td>
+</tr>
+<tr>
+<td><code>aspect_bucket_match</code></td>
+<td>true/false 表示通过/未通过；关闭条件时为 null</td>
+</tr>
+<tr>
+<td>拒绝原因 <code>aspect_bucket_mismatch</code></td>
+<td>不满足任何选中桶；同一记录可同时包含多个拒绝原因</td>
+</tr>
+</tbody>
+</table>
+<p>上述逐条字段针对成功解码记录；错误记录可能没有尺寸与桶字段。<code>counts_before</code> 总和等于独立桶匹配数（条件启用时），<code>counts_after</code> 总和等于最终保留数。选中但没有图片的桶也输出 0；关闭条件时桶计数字典为空。质量评测可同时检查桶通过率、各桶覆盖量、最终保留率，并人工抽查 rejected 中临界偏差图片；各桶不执行均衡采样或配额。</p>
+<h2 id="5-配置文件和参数">5. 配置文件和参数</h2>
+<p>项目已有：</p>
+<table>
+<thead>
+<tr>
+<th>配置</th>
+<th>用途</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>configs/statistics_only.json</code></td>
+<td>全量统计，关闭可选阈值与去重</td>
+</tr>
+<tr>
+<td><code>configs/above_256p.json</code></td>
+<td>短边大于或等于 256，关闭去重</td>
+</tr>
+<tr>
+<td><code>configs/exact_256p.json</code></td>
+<td>兼容旧文件名，内容与 above_256p 相同，采用大于或等于的新规则</td>
+</tr>
+<tr>
+<td><code>configs/audit.json</code></td>
+<td>无可选技术质量阈值，开启默认去重</td>
+</tr>
+<tr>
+<td><code>configs/aspect_strict.json</code></td>
+<td>严格选择 1:1、2:3、3:2，关闭去重</td>
+</tr>
+<tr>
+<td><code>configs/aspect_loose.json</code></td>
+<td>宽松选择八桶，默认容差 5%，关闭去重</td>
+</tr>
+<tr>
+<td><code>configs/generation_example.json</code></td>
+<td>示例：短边至少 512、比例 0.25–4、文本非空，并开启默认去重</td>
+</tr>
+</tbody>
+</table>
+<p>以下为可自定义的完整字段表，数值是默认值，不是推荐质量阈值：</p>
+<pre><code class="language-json">{
+  &quot;resolution&quot;: null,
+  &quot;min_short_edge&quot;: null,
+  &quot;max_long_edge&quot;: null,
+  &quot;min_pixels&quot;: null,
+  &quot;max_pixels&quot;: null,
+  &quot;min_aspect_ratio&quot;: null,
+  &quot;aspect_buckets&quot;: null,
+  &quot;aspect_mode&quot;: &quot;strict&quot;,
+  &quot;aspect_tolerance&quot;: 0.05,
+  &quot;max_aspect_ratio&quot;: null,
+  &quot;min_blur_score&quot;: null,
+  &quot;max_noise_sigma&quot;: null,
+  &quot;min_snr_proxy_db&quot;: null,
+  &quot;max_blockiness&quot;: null,
+  &quot;min_text_chars&quot;: null,
+  &quot;max_text_chars&quot;: null,
+  &quot;forbidden_text_patterns&quot;: [],
+  &quot;reject_animated&quot;: true,
+  &quot;max_decode_pixels&quot;: 100000000,
+  &quot;metric_patch_size&quot;: 256,
+  &quot;alpha_background&quot;: [255, 255, 255],
+  &quot;convert_icc&quot;: true,
+  &quot;text_unicode_form&quot;: &quot;NFC&quot;,
+  &quot;deduplicate&quot;: true,
+  &quot;near_deduplicate&quot;: true,
+  &quot;duplicate_scope&quot;: &quot;image_text&quot;,
+  &quot;phash_distance&quot;: 4,
+  &quot;dhash_distance&quot;: 4,
+  &quot;near_rgb_rmse&quot;: 8.0,
+  &quot;near_aspect_log_tolerance&quot;: 0.03,
+  &quot;export_max_edge&quot;: null,
+  &quot;export_format&quot;: &quot;png&quot;,
+  &quot;export_jpeg_quality&quot;: 95
+}
+</code></pre>
+<p><code>export_format</code> 可选 png/jpeg；JPEG <code>export_jpeg_quality</code> 为 1–100，采用无色度子采样，仍是有损输出。图片规范化不会自动统一为方形，固定裁剪和张量归一化由训练数据加载器执行。</p>
+<p><code>resolution</code> 支持 <code>256p</code>（短边&gt;=256）、<code>256x256</code>（精确宽高）等正整数格式；大小写与首尾空白会规范化，<code>256×256</code> 也接受。<code>any/none/null</code> 关闭分辨率条件。无后缀的 <code>256</code>、<code>0p</code>、负数、逗号多个值都非法；多目标请分别筛选到不同输出目录。</p>
+<p>各子命令参数：</p>
+<table>
+<thead>
+<tr>
+<th>命令</th>
+<th>主要必填参数</th>
+<th>可选参数</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>prepare</code></td>
+<td><code>--input --manifest</code></td>
+<td><code>--root --sidecar-text</code></td>
+</tr>
+<tr>
+<td><code>analyze</code></td>
+<td><code>--manifest --output</code></td>
+<td><code>--root --config --resolution --aspect-buckets --aspect-mode --aspect-tolerance --workers --rank --world-size --resume</code></td>
+</tr>
+<tr>
+<td><code>filter/merge</code></td>
+<td><code>--shards --output</code></td>
+<td><code>--config --resolution --aspect-buckets --aspect-mode --aspect-tolerance</code></td>
+</tr>
+<tr>
+<td><code>export</code></td>
+<td><code>--curated --output</code></td>
+<td><code>--root --workers --resume</code></td>
+</tr>
+<tr>
+<td><code>run</code></td>
+<td><code>--input --output</code></td>
+<td><code>--root --config --resolution --aspect-buckets --aspect-mode --aspect-tolerance --workers --sidecar-text --export --resume</code></td>
+</tr>
+</tbody>
+</table>
+<p><code>workers</code> 默认 min(8,CPU数量)。配置未知字段、非法类型、范围错误会报错；各子命令的 <code>--help</code> 可查看在线说明。</p>
+<h2 id="6-多机分片流程">6. 多机分片流程</h2>
+<p>先创建全局固定清单：</p>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner prepare --input &quot;D:\datasets\images&quot; --manifest runs/distributed/input.jsonl --sidecar-text
+</code></pre>
+<p>将 <code>input.jsonl</code>、<code>input.jsonl.meta.json</code>、相同代码和配置分发到节点。每台机器都必须能访问对应原图，可以使用不同本地根目录。</p>
+<p>分别在两台机器执行：</p>
+<pre><code class="language-powershell"># 节点 0
+.\.venv\Scripts\python.exe -m image_cleaner analyze --manifest runs/distributed/input.jsonl --root &quot;D:\node0\images&quot; --output runs/distributed/shards --config configs/statistics_only.json --workers 8 --world-size 2 --rank 0
+
+# 节点 1
+.\.venv\Scripts\python.exe -m image_cleaner analyze --manifest runs/distributed/input.jsonl --root &quot;E:\node1\images&quot; --output runs/distributed/shards --config configs/statistics_only.json --workers 8 --world-size 2 --rank 1
+</code></pre>
+<p>每条清单按 <code>seq % world_size</code> 分配。每个节点本地写不同 rank 的 SQLite，任务退出后收集全部 <code>shard-*.sqlite</code> 到协调节点同一目录；不用让不同机器写同一个 SQLite。</p>
+<p>协调节点先汇总统计，然后按分辨率条件筛选：</p>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner merge --shards runs/distributed/shards --output runs/distributed/statistics
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/distributed/shards --output runs/distributed/only_256p --resolution 256p
+</code></pre>
+<p>若希望跨分片去重，在第二条命令增加 <code>--config configs/audit.json</code>。合并会验证全部 rank 完整、清单/配置/软件版本一致、序号不重复。筛选结果与使用同一清单的单机处理一致，去重代表顺序不依赖 worker 完成顺序。</p>
+<p>这是静态分片处理，没有自动节点调度或故障迁移。分析并行，最终筛选和全局去重由一个协调节点完成；数据和索引落磁盘，没有百万级运行性能保证。大图处理的解码内存与图片尺寸有关，可降低 workers 或最大解码像素限制。</p>
+<h2 id="7-输出断点续跑和复核">7. 输出、断点续跑和复核</h2>
+<p>统计 <code>run</code> 输出清单、分片数据库，以及 <code>curated</code> 报告；<code>filter/merge</code> 的报告直接在其 <code>--output</code> 目录内，<strong>不会再额外套一层 curated</strong>。</p>
+<table>
+<thead>
+<tr>
+<th>文件</th>
+<th>用途</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>input.jsonl/.meta.json</code></td>
+<td>固定输入与 SHA-256、条数、数据根目录</td>
+</tr>
+<tr>
+<td><code>shard-*.sqlite</code></td>
+<td>完整分析记录与断点检查点，是重复筛选的数据源</td>
+</tr>
+<tr>
+<td><code>shard-*.jsonl</code></td>
+<td>方便检查的分片记录</td>
+</tr>
+<tr>
+<td><code>kept.jsonl</code></td>
+<td>最终保留的路径、文本、指标</td>
+</tr>
+<tr>
+<td><code>rejected.jsonl</code></td>
+<td>各规则拒绝原因，包括 <code>resolution_mismatch</code></td>
+</tr>
+<tr>
+<td><code>duplicate.jsonl</code></td>
+<td>重复类型、代表 ID 和近重复评分</td>
+</tr>
+<tr>
+<td><code>error.jsonl</code></td>
+<td>单图处理失败及异常信息</td>
+</tr>
+<tr>
+<td><code>report.json/.html</code></td>
+<td>配置、分辨率定义、阶段指标和前后分布</td>
+</tr>
+<tr>
+<td><code>exported.jsonl</code></td>
+<td>标准化图片相对路径及文本</td>
+</tr>
+<tr>
+<td><code>export_errors.jsonl</code></td>
+<td>导出失败清单</td>
+</tr>
+<tr>
+<td><code>export.meta.json</code></td>
+<td>导出完成状态、计数及身份校验</td>
+</tr>
+</tbody>
+</table>
+<p>分析续跑：</p>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner analyze --manifest runs/distributed/input.jsonl --root &quot;D:\node0\images&quot; --output runs/distributed/shards --config configs/statistics_only.json --workers 8 --world-size 2 --rank 0 --resume
+</code></pre>
+<p>导出续跑：</p>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m image_cleaner export --curated runs/only_256p --output runs/export_256p --workers 8 --resume
+</code></pre>
+<p><code>run --resume</code> 要求相同输入、配置、分辨率等身份设置；修改规则应使用 <code>filter</code> 输出到新目录。分析每 100 条提交一次；已提交项跳过。清单固定后保持原始文件不变。残留锁文件只能在确认任务退出后移除。</p>
+<p>合并/筛选暂不支持中途续跑，失败时用新输出目录重跑，不必重新分析。导出失败会记录清单并返回退出码 1；参数/文件操作等任务错误返回 2；分析阶段的个别图片错误不使整批命令失败，需检查 <code>error_count</code>。</p>
+<p>复核建议：检查总数守恒、目标尺寸匹配率、各原因抽样、清洗前后图片类别/宽高比分布变化，以及近重复误合并。为每轮保存独立目录及配置；后续训练/验证划分应让同图及其变体落在同一侧，本工具未自动划分数据集。</p>
+<h2 id="8-验证与功能边界">8. 验证与功能边界</h2>
+<p>在全新示例目录运行以下命令，可复现分辨率筛选，不依赖外部数据。示例是六张合成图片和一条损坏图片；256p 及以上预期保留五张（256×256、384×256、256×384、257×384、512×512）、尺寸拒绝一张、错误一张。重复执行请复用已生成输入并为任务更换新的输出目录。旧版筛选报告不会自动改写；重新 filter 到新目录，旧分析分片仍可复用。</p>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe examples/make_resolution_demo.py
+.\.venv\Scripts\python.exe -m image_cleaner run --input runs/resolution_demo_input --output runs/resolution_demo_statistics --config configs/statistics_only.json --workers 2 --sidecar-text
+.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/resolution_demo_statistics/shards --output runs/resolution_demo_256p --resolution 256p
+.\.venv\Scripts\python.exe -m image_cleaner export --curated runs/resolution_demo_256p --output runs/resolution_demo_export --workers 2
+</code></pre>
+<p>单元与集成测试：</p>
+<pre><code class="language-powershell">.\.venv\Scripts\python.exe -m unittest discover -s tests -v
+</code></pre>
+<p>测试包括包含边界的短边下限、精确宽高、255/256/257 边界、EXIF 后方向、配置覆盖、禁用尺寸条件、规则交集、无原图重复筛选，以及既有多进程/跨分片去重与导出测试。</p>
+<p>未包含 CLIP 图文语义对齐、VLM 事实核验、审美模型、OCR、水印分类器、语义 embedding 去重或训练模型性能评测。当前技术质量指标无法判断图片里的描述是否事实正确。</p></main></div><footer>NMM-data-preprocess · v0.3.0<span>图片文本数据初筛教程</span></footer></body></html>

pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "multimodal-image-cleaner"
+version = "0.3.0"
+description = "Streaming, sharded image-text dataset inspection and curation"
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.26,<3", "Pillow>=10.4,<13"]
+
+[project.optional-dependencies]
+publish = ["huggingface_hub>=0.34,<2", "Markdown>=3.7,<4"]
+
+[project.scripts]
+image-cleaner = "image_cleaner.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["image_cleaner*"]

tests/test_aspect.py

@@ -0,0 +1,103 @@
+import json
+from pathlib import Path
+import tempfile
+import unittest
+
+from PIL import Image
+from image_cleaner.aspect import assess_aspect
+from image_cleaner.config import ASPECT_BUCKETS, Config
+from image_cleaner.cli import main
+from image_cleaner.images import filter_reasons
+from image_cleaner.io import prepare, manifest_items
+from image_cleaner.jobs import analyze, merge
+
+
+class AspectTests(unittest.TestCase):
+    def match(self, width, height, **kwargs):
+        return assess_aspect({"width": width, "height": height}, Config(**kwargs))
+
+    def test_strict_presets_orientation_and_all(self):
+        for bucket in ASPECT_BUCKETS:
+            w, h = map(int, bucket.split(":"))
+            self.assertEqual(self.match(w*20, h*20, aspect_buckets="all")["aspect_bucket"], bucket)
+        self.assertFalse(self.match(60, 40, aspect_buckets="2:3")["aspect_bucket_match"])
+        self.assertFalse(self.match(9, 21, aspect_buckets="all")["aspect_bucket_match"])
+        self.assertFalse(self.match(1001, 1000, aspect_buckets="1:1")["aspect_bucket_match"])
+
+    def test_inclusive_symmetric_boundary_and_custom_tolerance(self):
+        for w, h in [(1050, 1000), (1000, 1050)]:
+            row = self.match(w, h, aspect_buckets="1:1", aspect_mode="loose")
+            self.assertTrue(row["aspect_bucket_match"])
+            self.assertEqual(row["aspect_bucket_deviation"], .05)
+        for w, h in [(1051, 1000), (1000, 1051)]:
+            self.assertFalse(self.match(w, h, aspect_buckets="1:1", aspect_mode="loose")["aspect_bucket_match"])
+        self.assertTrue(self.match(1100, 1000, aspect_buckets="1:1", aspect_mode="loose", aspect_tolerance=.1)["aspect_bucket_match"])
+        self.assertFalse(self.match(1001, 1000, aspect_buckets="1:1", aspect_mode="loose", aspect_tolerance=0)["aspect_bucket_match"])
+
+    def test_overlap_assignment_and_tie(self):
+        self.assertEqual(self.match(1400, 1000, aspect_buckets="3:2,4:3", aspect_mode="loose", aspect_tolerance=.2)["aspect_bucket"], "4:3")
+        self.assertEqual(self.match(100, 100, aspect_buckets="3:2,2:3", aspect_mode="loose", aspect_tolerance=.5)["aspect_bucket"], "2:3")
+
+    def test_validation_and_normalization(self):
+        for value in ["", "1:1,", [], "4:5", ["all"], 5]:
+            with self.assertRaises(ValueError):
+                Config(aspect_buckets=value)
+        for value in [None, True, -1, float("nan"), float("inf")]:
+            with self.assertRaises(ValueError):
+                Config(aspect_tolerance=value)
+        self.assertEqual(Config(aspect_buckets="3:2,1:1,1:1").aspect_buckets, ("1:1", "3:2"))
+        self.assertIsNone(Config(aspect_buckets="none").aspect_buckets)
+        with self.assertRaises(ValueError):
+            Config(aspect_mode="invalid")
+
+    def test_disabled_clears_stale_assignment(self):
+        row = {"width": 100, "height": 100, "short_edge": 100, "aspect_bucket": "1:1"}
+        self.assertEqual(filter_reasons(row, Config()), [])
+        self.assertIsNone(row["aspect_bucket"])
+        self.assertIsNone(row["aspect_bucket_match"])
+
+    def test_sharded_cached_filter_cli_and_reports(self):
+        temp_root = Path(__file__).resolve().parents[1]/"runs"/"test_tmp"
+        temp_root.mkdir(parents=True, exist_ok=True)
+        with tempfile.TemporaryDirectory(dir=temp_root) as temp:
+            root = Path(temp)
+            images = root/"images"
+            images.mkdir()
+            for i, size in enumerate([(256, 256), (315, 300), (316, 300), (300, 450), (128, 128)]):
+                Image.new("RGB", size, "blue").save(images/f"{i}.png")
+            (images/"broken.jpg").write_bytes(b"broken")
+            manifest = root/"input.jsonl"
+            prepare(images, manifest)
+            config = Config(deduplicate=False, near_deduplicate=False)
+            analyze(manifest, root/"single", config, workers=2)
+            for rank in range(2):
+                analyze(manifest, root/"shards", config, workers=2, rank=rank, world_size=2)
+            # Remove source bytes: repeated filtering must use cached measurements only.
+            for path in images.iterdir():
+                path.unlink()
+            args = ["filter", "--shards", str(root/"shards"), "--output", str(root/"loose"),
+                    "--aspect-buckets", "1:1,2:3", "--aspect-mode", "loose", "--resolution", "256p"]
+            self.assertEqual(main(args), 0)
+            report = json.loads((root/"loose"/"report.json").read_text(encoding="utf-8"))
+            self.assertEqual(report["kept_count"], 3)
+            self.assertEqual(report["stage_metrics"]["aspect_bucket_matched_count"], 4)
+            self.assertEqual(report["stage_metrics"]["aspect_bucket_pass_rate"], .8)
+            self.assertEqual(report["aspect_bucket_filter"]["counts_before"], {"1:1": 3, "2:3": 1})
+            self.assertEqual(report["aspect_bucket_filter"]["counts_after"], {"1:1": 2, "2:3": 1})
+            merge(root/"single", root/"equivalent", resolution="256p", aspect_buckets="1:1,2:3", aspect_mode="loose")
+            for status in ["kept", "rejected", "error", "duplicate"]:
+                self.assertEqual((root/"loose"/f"{status}.jsonl").read_bytes(), (root/"equivalent"/f"{status}.jsonl").read_bytes())
+            merge(root/"shards", root/"strict", aspect_buckets="1:1,2:3")
+            strict = list(manifest_items(root/"strict"/"rejected.jsonl"))
+            self.assertEqual(len(strict), 2)
+            self.assertIn("aspect_bucket_mismatch", strict[0]["reasons"])
+            self.assertIsNone(strict[0]["aspect_bucket"])
+            self.assertIsNotNone(strict[0]["aspect_bucket_nearest"])
+            args[args.index(str(root/"loose"))] = str(root/"tighter")
+            self.assertEqual(main(args + ["--aspect-tolerance", "0.03"]), 0)
+            tighter = json.loads((root/"tighter"/"report.json").read_text(encoding="utf-8"))
+            self.assertEqual(tighter["kept_count"], 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_pipeline.py

@@ -0,0 +1,275 @@
+import json
+from pathlib import Path
+import random
+import sqlite3
+import tempfile
+import unittest
+
+import numpy as np
+from PIL import Image, ImageFilter
+
+from image_cleaner.config import Config, load_config
+from image_cleaner.images import analyze_one, canonical_image, normalize_text
+from image_cleaner.io import manifest_items, prepare
+from image_cleaner.jobs import analyze, export_images, hash_bands, merge
+from image_cleaner.metrics import quality_metrics
+
+
+class PipelineTests(unittest.TestCase):
+    def setUp(self):
+        temp_root = Path(__file__).resolve().parents[1]/"runs"/"test_tmp"
+        temp_root.mkdir(parents=True, exist_ok=True)
+        self.temp = tempfile.TemporaryDirectory(dir=temp_root)
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+        self.images = self.root/"input"
+        self.images.mkdir()
+        rng = np.random.default_rng(123)
+        self.rgb = Image.fromarray(rng.integers(0, 256, (96, 128, 3), dtype=np.uint8))
+
+    def save(self, name, image=None):
+        path = self.images/name
+        (image or self.rgb).save(path)
+        return path
+
+    def row(self, path, config=Config()):
+        return analyze_one(({"seq": 0, "id": "sample-000000000000", "path": path.name}, str(path), config.to_dict()))
+
+    def rows(self, directory, kind):
+        return list(manifest_items(directory/f"{kind}.jsonl"))
+
+    def test_pixel_duplicates_and_corrupt_files(self):
+        self.save("one.png")
+        self.save("two.bmp")
+        (self.images/"broken.jpg").write_bytes(b"not a jpeg")
+        manifest = self.root/"input.jsonl"
+        prepare(self.images, manifest)
+        analyze(manifest, self.root/"shards", Config())
+        output = self.root/"curated"
+        result = merge(self.root/"shards", output)
+        self.assertEqual(result, {"input_count": 3, "kept_count": 1, "rejected_count": 0,
+                                  "duplicate_count": 1, "error_count": 1})
+        self.assertEqual(self.rows(output, "duplicate")[0]["duplicate_kind"], "exact_pixels")
+        report = json.loads((output/"report.json").read_text(encoding="utf-8"))
+        self.assertEqual(report["before"]["distributions"]["width"]["count"], 2)
+        self.assertEqual(report["after"]["distributions"]["width"]["count"], 1)
+        self.assertTrue((output/"report.html").exists())
+
+    def test_single_and_two_shards_are_identical_and_resume(self):
+        self.save("a.png")
+        self.save("b.bmp")
+        self.save("c.png", Image.new("RGB", (60, 100), "blue"))
+        self.save("d.png", Image.new("RGB", (60, 100), "red"))
+        manifest = self.root/"input.jsonl"
+        prepare(self.images, manifest)
+        config = Config()
+        analyze(manifest, self.root/"single", config, workers=2)
+        analyze(manifest, self.root/"distributed", config, workers=2, rank=0, world_size=2)
+        with self.assertRaisesRegex(ValueError, "Missing"):
+            merge(self.root/"distributed", self.root/"incomplete")
+        analyze(manifest, self.root/"distributed", config, workers=2, rank=1, world_size=2)
+        result = analyze(manifest, self.root/"distributed", config, rank=1, world_size=2, resume=True)
+        self.assertEqual(result["new_records"], 0)
+        merge(self.root/"single", self.root/"single_out")
+        merge(self.root/"distributed", self.root/"dist_out")
+        for kind in ["kept", "duplicate", "rejected", "error"]:
+            self.assertEqual(self.rows(self.root/"single_out", kind), self.rows(self.root/"dist_out", kind))
+        self.assertEqual(len(self.rows(self.root/"dist_out", "kept")), 3)  # Different flat colors survive.
+
+    def test_exif_and_alpha_normalization(self):
+        path = self.images/"rotated.jpg"
+        exif = Image.Exif()
+        exif[274] = 6
+        Image.new("RGB", (40, 20), "red").save(path, exif=exif)
+        rgb, metadata = canonical_image(path, Config())
+        self.assertEqual(rgb.size, (20, 40))
+        self.assertTrue(metadata["exif_transposed"])
+        alpha = self.save("alpha.png", Image.new("RGBA", (20, 20), (255, 0, 0, 0)))
+        rgb, metadata = canonical_image(alpha, Config())
+        self.assertEqual(rgb.getpixel((0, 0)), (255, 255, 255))
+        self.assertTrue(metadata["alpha_flattened"])
+
+    def test_noise_estimate_and_blur_are_separate(self):
+        rng = np.random.default_rng(13)
+        clean = np.full((256, 256), 128.0)
+        noisy = np.clip(clean + rng.normal(0, 8, clean.shape), 0, 255).astype(np.uint8)
+        metrics = quality_metrics(Image.fromarray(noisy).convert("RGB"))
+        self.assertGreater(metrics["noise_sigma"], 4)
+        self.assertLess(metrics["noise_sigma"], 12)
+        checker = ((np.indices((256, 256)).sum(axis=0)//8) % 2 * 255).astype(np.uint8)
+        sharp = Image.fromarray(checker).convert("RGB")
+        blurred = sharp.filter(ImageFilter.GaussianBlur(3))
+        self.assertGreater(quality_metrics(sharp)["blur_score"], quality_metrics(blurred)["blur_score"])
+        flat = quality_metrics(Image.new("RGB", (128, 128), "white"))
+        self.assertIsNone(flat["snr_proxy_db"])
+
+    def test_filters_and_refilter_without_redecode(self):
+        self.save("large.png")
+        self.save("small.png", Image.new("RGB", (20, 30), "green"))
+        manifest = self.root/"manifest.jsonl"
+        prepare(self.images, manifest)
+        analyze(manifest, self.root/"shards", Config())
+        result = merge(self.root/"shards", self.root/"out", Config(min_short_edge=50))
+        self.assertEqual(result["rejected_count"], 1)
+        self.assertIn("min_short_edge", self.rows(self.root/"out", "rejected")[0]["reasons"])
+        with self.assertRaisesRegex(ValueError, "analysis setting"):
+            merge(self.root/"shards", self.root/"invalid", Config(metric_patch_size=128))
+
+    def test_captions_preserved_and_image_scope_optional(self):
+        path = self.save("a.png")
+        input_manifest = self.root/"raw.jsonl"
+        records = [{"path": str(path), "id": "original1", "text": "first", "license": "example"},
+                   {"path": str(path), "id": "original2", "text": "second"},
+                   {"path": str(path), "id": "original3", "text": "first"}]
+        input_manifest.write_text("".join(json.dumps(r)+"\n" for r in records), encoding="utf-8")
+        manifest = self.root/"manifest.jsonl"
+        prepare(input_manifest, manifest)
+        analyze(manifest, self.root/"shards", Config())
+        result = merge(self.root/"shards", self.root/"out")
+        self.assertEqual(result["kept_count"], 2)
+        self.assertEqual(result["duplicate_count"], 1)
+        self.assertEqual(self.rows(self.root/"out", "kept")[0]["metadata"]["license"], "example")
+        result = merge(self.root/"shards", self.root/"image_scope", Config(duplicate_scope="image"))
+        self.assertEqual(result["kept_count"], 1)
+
+    def test_export_resume_and_changed_source(self):
+        path = self.save("a.png")
+        manifest = self.root/"manifest.jsonl"
+        prepare(self.images, manifest)
+        config = Config(export_max_edge=64)
+        analyze(manifest, self.root/"shards", config)
+        merge(self.root/"shards", self.root/"out")
+        result = export_images(self.root/"out", self.root/"export", workers=2)
+        self.assertEqual(result, {"ok": 1})
+        exported = self.rows(self.root/"export", "exported")[0]
+        with Image.open(self.root/"export"/exported["path"]) as image:
+            self.assertEqual(image.size, (64, 48))
+            self.assertEqual(image.mode, "RGB")
+        self.assertEqual(export_images(self.root/"out", self.root/"export", resume=True), {"ok": 1})
+        path.write_bytes(b"changed")
+        self.assertEqual(export_images(self.root/"out", self.root/"export", resume=True), {"error": 1})
+
+    def test_hash_band_candidate_recall(self):
+        rng = random.Random(34)
+        for radius in range(9):
+            for _ in range(20):
+                value = rng.getrandbits(64)
+                neighbor = value
+                for bit in rng.sample(range(64), radius):
+                    neighbor ^= 1 << bit
+                original_bands = set(hash_bands(f"{value:016x}", radius))
+                near_bands = set(hash_bands(f"{neighbor:016x}", radius))
+                self.assertTrue(original_bands & near_bands)
+
+    def test_invalid_config_and_frozen_manifest(self):
+        with self.assertRaises(ValueError):
+            Config(min_aspect_ratio=2, max_aspect_ratio=1)
+        with self.assertRaises(ValueError):
+            Config(phash_distance=12)
+        self.save("one.png")
+        manifest = self.root/"manifest.jsonl"
+        prepare(self.images, manifest)
+        with self.assertRaisesRegex(ValueError, "identity"):
+            analyze(manifest, self.root/"shards", Config())
+            analyze(manifest, self.root/"shards", Config(min_short_edge=100), resume=True)
+        manifest.write_text(manifest.read_text(encoding="utf-8")+"\n", encoding="utf-8")
+        with self.assertRaisesRegex(ValueError, "changed"):
+            analyze(manifest, self.root/"new_shards", Config())
+
+    def test_more_than_one_dedup_batch(self):
+        path = self.save("one.png")
+        raw = self.root/"raw.jsonl"
+        raw.write_text("".join(json.dumps({"path": str(path), "text": str(i)})+"\n" for i in range(503)), encoding="utf-8")
+        manifest = self.root/"manifest.jsonl"
+        prepare(raw, manifest)
+        analyze(manifest, self.root/"shards", Config(near_deduplicate=False))
+        result = merge(self.root/"shards", self.root/"out")
+        self.assertEqual(result["kept_count"], 503)
+
+    def test_small_images_and_text_normalization(self):
+        path = self.save("tiny.png", Image.new("RGB", (1, 1), "red"))
+        row = self.row(path)
+        self.assertEqual(row["status"], "candidate")
+        self.assertIsNone(row["blur_score"])
+        self.assertEqual(normalize_text(" e\u0301 \r\nsecond  ", "NFC"), "é\nsecond")
+
+    def test_near_duplicate_recompression(self):
+        # Smooth spatial content survives recompression with perceptual/color guards.
+        y, x = np.indices((256, 256))
+        data = np.stack([(x % 256), (y % 256), ((x+y)//2 % 256)], axis=-1).astype(np.uint8)
+        image = Image.fromarray(data)
+        self.save("one.png", image)
+        image.save(self.images/"two.jpg", quality=92)
+        manifest = self.root/"manifest.jsonl"
+        prepare(self.images, manifest)
+        analyze(manifest, self.root/"shards", Config())
+        result = merge(self.root/"shards", self.root/"out")
+        self.assertEqual(result["duplicate_count"], 1)
+        self.assertEqual(self.rows(self.root/"out", "duplicate")[0]["duplicate_kind"], "near_perceptual")
+
+    def test_resolution_lower_bound_after_statistics_and_cli_override(self):
+        from image_cleaner.cli import dispatch, parser
+        config = Config(deduplicate=False, near_deduplicate=False)
+        for i, size in enumerate([(256, 256), (384, 256), (256, 384), (255, 384), (257, 384), (512, 512)]):
+            self.save(f"{i}.png", Image.new("RGB", size, (10+i*20, 20, 30)))
+        manifest = self.root/"manifest.jsonl"
+        prepare(self.images, manifest)
+        analyze(manifest, self.root/"shards", config, workers=2)
+        merge(self.root/"shards", self.root/"statistics")
+        args = parser().parse_args(["filter", "--shards", str(self.root/"shards"),
+                                   "--output", str(self.root/"only_256p"), "--resolution", "256p"])
+        result = dispatch(args)
+        self.assertEqual(result["kept_count"], 5)
+        self.assertEqual(result["rejected_count"], 1)
+        self.assertTrue(all(r["short_edge"] >= 256 for r in self.rows(self.root/"only_256p", "kept")))
+        self.assertTrue(all("resolution_mismatch" in r["reasons"]
+                            for r in self.rows(self.root/"only_256p", "rejected")))
+        report = json.loads((self.root/"only_256p"/"report.json").read_text(encoding="utf-8"))
+        self.assertEqual(report["stage_metrics"]["resolution_matched_count"], 5)
+        self.assertEqual(report["stage_metrics"]["resolution_pass_rate"], 5/6)
+        self.assertEqual(report["resolution_filter"]["mode"], "short_edge_gte")
+        self.assertEqual(report["resolution_filter"]["comparison"], ">=")
+        config_path = self.root/"resolution.json"
+        config_path.write_text(json.dumps({**config.to_dict(), "resolution": "512p"}), encoding="utf-8")
+        args = parser().parse_args(["merge", "--shards", str(self.root/"shards"),
+                                   "--output", str(self.root/"only_square"), "--config", str(config_path),
+                                   "--resolution", "256x256"])
+        self.assertEqual(dispatch(args)["kept_count"], 1)
+        self.assertEqual(self.rows(self.root/"only_square", "kept")[0]["width"], 256)
+        self.assertEqual(merge(self.root/"shards", self.root/"reset", Config(**{
+            **config.to_dict(), "resolution": "256p"}), resolution="any")["kept_count"], 6)
+
+    def test_resolution_validation_and_rule_intersection(self):
+        from image_cleaner.images import filter_reasons
+        for bad in ["256", "0p", "0x256", "256x0", "256.0p", "256p,512p", 256, "-256p"]:
+            with self.subTest(bad=bad), self.assertRaises(ValueError):
+                Config(resolution=bad)
+        self.assertEqual(Config(resolution=" 256P ").resolution, "256p")
+        self.assertEqual(Config(resolution="256\u00d7384").resolution, "256x384")
+        path = self.save("match.png", Image.new("RGB", (257, 384), "blue"))
+        row = self.row(path, Config(resolution="256p", min_short_edge=300))
+        self.assertEqual(row["status"], "rejected")
+        self.assertEqual(row["reasons"], ["min_short_edge"])
+        self.assertEqual(filter_reasons(row, Config(resolution="384x256")), ["resolution_mismatch"])
+
+    def test_resolution_refilter_requires_no_source_reads(self):
+        path = self.save("match.png", Image.new("RGB", (384, 256), "blue"))
+        exif = Image.Exif()
+        exif[274] = 6
+        Image.new("RGB", (256, 384), "red").save(self.images/"rotated.jpg", exif=exif)
+        manifest = self.root/"manifest.jsonl"
+        prepare(self.images, manifest)
+        config = Config(deduplicate=False)
+        analyze(manifest, self.root/"shards", config, rank=0, world_size=2)
+        analyze(manifest, self.root/"shards", config, rank=1, world_size=2)
+        # Filtering should use dimensions already stored in the analysis database.
+        for image in self.images.iterdir():
+            image.unlink()
+        result = merge(self.root/"shards", self.root/"out", resolution="384x256")
+        self.assertEqual(result["kept_count"], 2)
+        self.assertEqual(result["rejected_count"], 0)
+        self.assertTrue(all((r["width"], r["height"]) == (384, 256) for r in self.rows(self.root/"out", "kept")))
+
+
+if __name__ == "__main__":
+    unittest.main()

tools/build_space.py

@@ -0,0 +1,125 @@
+"""Build an offline static tutorial and a source-only release archive."""
+import hashlib
+import html
+import json
+from pathlib import Path
+import re
+import sys
+import zipfile
+
+import markdown
+from markdown.extensions.toc import slugify_unicode
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from image_cleaner import __version__
+
+REPO = "HanWangTJU/NMM-data-preprocess"
+DOCS = {"QUICKSTART": "逐步教程", "USAGE": "完整手册", "PARAMETERS": "参数参考",
+        "DEPLOYMENT": "部署指南", "ARCHITECTURE": "代码说明"}
+SOURCE_DIRS = ("image_cleaner", "configs", "docs", "examples", "tests", "tools", "web", "docker")
+ROOT_FILES = ("README.md", "pyproject.toml", ".gitignore", ".dockerignore")
+ALLOWED_SUFFIXES = {".py", ".json", ".md", ".html", ".css", ".js"}
+
+
+def source_files():
+    paths = [ROOT/name for name in ROOT_FILES]
+    for directory in SOURCE_DIRS:
+        for path in (ROOT/directory).rglob("*"):
+            if path.is_file() and (path.suffix in ALLOWED_SUFFIXES or path.name == "Dockerfile"):
+                if "__pycache__" not in path.parts:
+                    paths.append(path)
+    for path in paths:
+        if path.is_symlink() or not path.resolve().is_relative_to(ROOT):
+            raise ValueError("Publish source must remain inside the project")
+    return sorted(set(paths))
+
+
+def check_content(content):
+    if re.search(rb"hf_[A-Za-z0-9]{20,}", content):
+        raise ValueError("A credential-like Hugging Face token was detected; publication stopped")
+    if re.search(rb"(?i)(?:password|passwd)\s*[:=]\s*['\"][^'\"]{4,}['\"]", content):
+        raise ValueError("A password assignment was detected; publication stopped")
+
+
+def check_path(path):
+    if path.is_symlink() or not path.resolve().is_relative_to(ROOT):
+        raise ValueError("Publish path must remain inside the project")
+    if path.suffix == ".zip":
+        with zipfile.ZipFile(path) as archive:
+            expected = {p.relative_to(ROOT).as_posix() for p in source_files()}
+            if set(archive.namelist()) != expected:
+                raise ValueError("Archive contents differ from source whitelist")
+            for name in archive.namelist():
+                check_content(archive.read(name))
+    else:
+        check_content(path.read_bytes())
+
+
+def publish_files():
+    return source_files() + [ROOT/"index.html", ROOT/"assets/style.css", ROOT/"assets/app.js"] + [
+        ROOT/"manual"/(name + ".html") for name in DOCS
+    ] + [ROOT/"downloads"/f"NMM-data-preprocess-{__version__}.zip"]
+
+
+def rewrite_links(body):
+    def rewrite(match):
+        target = html.unescape(match.group(1))
+        base, _, fragment = target.partition("#")
+        if base.endswith(".md"):
+            stem = Path(base).stem
+            if stem in DOCS:
+                return 'href="' + stem + ".html" + ("#"+fragment if fragment else "") + '"'
+            return 'href="https://huggingface.co/spaces/' + REPO + '/blob/main/' + html.escape(base) + '"'
+        return match.group(0)
+    return re.sub(r'href="([^"]+)"', rewrite, body)
+
+
+def build():
+    for directory in ["manual", "assets", "downloads", "release"]:
+        (ROOT/directory).mkdir(exist_ok=True)
+    (ROOT/"index.html").write_text((ROOT/"web/index.template.html").read_text(encoding="utf-8").replace(
+        "@@VERSION@@", __version__), encoding="utf-8")
+    for filename in ["style.css", "app.js"]:
+        (ROOT/"assets"/filename).write_bytes((ROOT/"web"/filename).read_bytes())
+    for name, title in DOCS.items():
+        renderer = markdown.Markdown(extensions=["toc", "tables", "fenced_code", "sane_lists"],
+                                     extension_configs={"toc": {"toc_depth": "2-3", "slugify": slugify_unicode}})
+        body = rewrite_links(renderer.convert((ROOT/"docs"/(name+".md")).read_text(encoding="utf-8")))
+        nav = "".join(f'<a class="{"active" if key == name else ""}" href="{key}.html">{label}</a>'
+                      for key, label in DOCS.items())
+        page = ('<!doctype html><html lang="zh-CN"><head><meta charset="utf-8">'
+                '<meta name="viewport" content="width=device-width,initial-scale=1">'
+                f'<title>{title} · NMM-data-preprocess</title><link rel="stylesheet" href="../assets/style.css">'
+                '<script defer src="../assets/app.js"></script></head><body><header class="topbar">'
+                '<a class="brand" href="../index.html">NMM<span> / </span>data-preprocess</a>'
+                f'<nav><a href="https://huggingface.co/spaces/{REPO}/tree/main">源代码 ↗</a>'
+                f'<a href="../downloads/NMM-data-preprocess-{__version__}.zip" download>下载源码 ↓</a></nav></header>'
+                f'<div class="manual-layout"><aside class="sidebar"><a href="../index.html">← 返回首页</a>{nav}'
+                f'<h2>本页目录</h2>{renderer.toc}</aside><main class="manual">{body}</main></div>'
+                f'<footer>NMM-data-preprocess · v{__version__}<span>图片文本数据初���教程</span></footer></body></html>')
+        (ROOT/"manual"/(name+".html")).write_text(page, encoding="utf-8")
+    archive_path = ROOT/"downloads"/f"NMM-data-preprocess-{__version__}.zip"
+    with zipfile.ZipFile(archive_path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        for path in source_files():
+            check_path(path)
+            # Fixed metadata makes the archive reproducible across local runs.
+            entry = zipfile.ZipInfo(path.relative_to(ROOT).as_posix(), date_time=(2026, 1, 1, 0, 0, 0))
+            entry.compress_type = zipfile.ZIP_DEFLATED
+            entry.external_attr = 0o644 << 16
+            archive.writestr(entry, path.read_bytes())
+    files = []
+    for path in publish_files():
+        check_path(path)
+        data = path.read_bytes()
+        files.append({"path": path.relative_to(ROOT).as_posix(), "bytes": len(data),
+                      "sha256": hashlib.sha256(data).hexdigest()})
+    manifest = {"repo_id": REPO, "version": __version__, "files": files,
+                "archive": archive_path.relative_to(ROOT).as_posix()}
+    (ROOT/"release/publish-manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2)+"\n", encoding="utf-8")
+    print(json.dumps({"version": __version__, "publish_files": len(files),
+                      "publish_bytes": sum(item["bytes"] for item in files), "archive": manifest["archive"]}))
+
+
+if __name__ == "__main__":
+    build()

tools/check_release.py

@@ -0,0 +1,64 @@
+"""Validate built local links, documented Config coverage, and source ZIP contents."""
+from dataclasses import fields
+from html.parser import HTMLParser
+import json
+from pathlib import Path
+import re
+import sys
+from urllib.parse import unquote, urlsplit
+import zipfile
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from image_cleaner.config import Config
+
+
+class Page(HTMLParser):
+    def __init__(self, path):
+        super().__init__()
+        self.ids, self.links = set(), []
+        self.feed(path.read_text(encoding="utf-8"))
+
+    def handle_starttag(self, tag, attrs):
+        values = dict(attrs)
+        if "id" in values:
+            self.ids.add(values["id"])
+        if tag in {"a", "link", "script"}:
+            value = values.get("href", values.get("src"))
+            if value:
+                self.links.append(value)
+
+
+def main():
+    pages = [ROOT/"index.html"] + sorted((ROOT/"manual").glob("*.html"))
+    parsed = {path.resolve(): Page(path) for path in pages}
+    checked = 0
+    for path, page in parsed.items():
+        for link in page.links:
+            target = urlsplit(link)
+            if target.scheme or target.netloc:
+                continue
+            resolved = (path.parent/unquote(target.path)).resolve() if target.path else path
+            if not resolved.is_relative_to(ROOT) or not resolved.is_file():
+                raise ValueError(f"Broken local link: {path.name} -> {link}")
+            if target.fragment and resolved.suffix == ".html":
+                if unquote(target.fragment) not in parsed[resolved].ids:
+                    raise ValueError(f"Broken anchor: {path.name} -> {link}")
+            checked += 1
+    documented = set(re.findall(r"^\| ([a-z_]+) \|", (ROOT/"docs/PARAMETERS.md").read_text(encoding="utf-8"), re.M))
+    missing = {field.name for field in fields(Config)} - documented
+    if missing:
+        raise ValueError(f"Undocumented Config fields: {sorted(missing)}")
+    manifest = json.loads((ROOT/"release/publish-manifest.json").read_text(encoding="utf-8"))
+    with zipfile.ZipFile(ROOT/manifest["archive"]) as archive:
+        if archive.testzip() is not None:
+            raise ValueError("Corrupt source archive")
+        if any(part in {".venv", "runs", "release", "__pycache__"} for name in archive.namelist() for part in Path(name).parts):
+            raise ValueError("Excluded local artifacts were found in archive")
+        source_count = len(archive.namelist())
+    print(json.dumps({"html_pages": len(pages), "local_links_verified": checked,
+                      "config_fields_documented": len(fields(Config)), "source_archive_files": source_count}))
+
+
+if __name__ == "__main__":
+    main()

tools/check_web.js

@@ -0,0 +1,22 @@
+"use strict";
+const assert = require("node:assert/strict");
+const {bucketAssessment, buildFilterCommand} = require("../web/app.js");
+for (const [width, height] of [[1050,1000],[1000,1050]]) {
+  assert.equal(bucketAssessment(width,height,["1:1"],"loose",5).matched,true);
+}
+for (const [width, height] of [[1051,1000],[1000,1051]]) {
+  assert.equal(bucketAssessment(width,height,["1:1"],"loose",5).matched,false);
+}
+assert.equal(bucketAssessment(1000,1000,["2:3","3:2"],"loose",50).bucket,"2:3");
+assert.equal(bucketAssessment(1400,1000,["3:2","4:3"],"loose",20).bucket,"4:3");
+assert.equal(bucketAssessment(1001,1000,["1:1"],"strict",5).matched,false);
+assert.equal(bucketAssessment(1000,1000,["1:1"],"loose",0).matched,true);
+assert.equal(bucketAssessment(1001,1000,["1:1"],"loose",0).matched,false);
+assert.equal(bucketAssessment(1001,1000,["1:1"],"loose",1e-8).matched,false);
+assert.ok(buildFilterCommand("windows","256p",["1:1"],"loose",5).includes("--aspect-tolerance 0.05"));
+assert.ok(buildFilterCommand("linux","384x256",["2:3","3:2"],"strict",5).includes('--aspect-buckets "2:3,3:2" --aspect-mode strict'));
+assert.ok(buildFilterCommand("linux","any",[],"strict",5).endsWith("--aspect-buckets none"));
+assert.throws(() => buildFilterCommand("linux","256p;echo injected",[],"loose",5));
+assert.throws(() => buildFilterCommand("linux","256p",["1:1"],"loose",-1));
+assert.throws(() => buildFilterCommand("linux","256p",["1:1"],"loose",Infinity));
+console.log("Browser command generator and exact ratio boundary checks passed.");

tools/publish_space.py

@@ -0,0 +1,73 @@
+"""Publish an audited source/documentation whitelist using a process-only HF_TOKEN."""
+import argparse
+import hashlib
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+from huggingface_hub import HfApi, CommitOperationAdd
+from huggingface_hub.errors import RepositoryNotFoundError
+from build_space import ROOT, check_path, publish_files
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repo-id", default="HanWangTJU/NMM-data-preprocess")
+    args = parser.parse_args()
+    token = os.environ.get("HF_TOKEN")
+    if not token:
+        raise ValueError("Set HF_TOKEN in the current process environment before publishing")
+    manifest = json.loads((ROOT/"release/publish-manifest.json").read_text(encoding="utf-8"))
+    expected = {path.relative_to(ROOT).as_posix() for path in publish_files()}
+    actual = [entry["path"] for entry in manifest["files"]]
+    if set(actual) != expected or len(actual) != len(expected):
+        raise ValueError("Manifest differs from the publication whitelist; rebuild first")
+    operations = []
+    for entry in manifest["files"]:
+        path = ROOT/entry["path"]
+        check_path(path)
+        if hashlib.sha256(path.read_bytes()).hexdigest() != entry["sha256"]:
+            raise ValueError("A release file changed after build; rebuild before publishing")
+        operations.append(CommitOperationAdd(path_in_repo=entry["path"], path_or_fileobj=str(path)))
+    api = HfApi(token=token)
+    user = api.whoami()["name"]
+    if args.repo_id.split("/")[0] != user:
+        raise ValueError("Authenticated account does not match the requested Space namespace")
+    try:
+        info = api.repo_info(args.repo_id, repo_type="space")
+        if info.sdk != "static":
+            raise ValueError("Existing Space is not static; refusing to replace its SDK")
+        parent_commit = info.sha
+    except RepositoryNotFoundError as exc:
+        if getattr(exc.response, "status_code", None) != 404:
+            raise
+        api.create_repo(args.repo_id, repo_type="space", space_sdk="static", private=False)
+        parent_commit = api.repo_info(args.repo_id, repo_type="space").sha
+    commit = api.create_commit(repo_id=args.repo_id, repo_type="space", operations=operations,
+                               parent_commit=parent_commit,
+                               commit_message=f"Publish NMM data preprocessing v{manifest['version']} with Chinese tutorials")
+    info = api.repo_info(args.repo_id, repo_type="space", revision=commit.oid, files_metadata=True)
+    remote = {item.rfilename: item for item in info.siblings}
+    if not expected.issubset(remote):
+        raise ValueError("Commit completed but a published path is missing; inspect repository")
+    if any(remote[item["path"]].size != item["bytes"] for item in manifest["files"]):
+        raise ValueError("Committed file sizes do not match release manifest")
+    receipt = {"repo_id": args.repo_id, "version": manifest["version"], "commit": commit.oid,
+               "space_url": f"https://huggingface.co/spaces/{args.repo_id}",
+               "published_file_count": len(operations), "verified_remote_sizes": True,
+               "published_at_utc": datetime.now(timezone.utc).isoformat()}
+    (ROOT/"release/publish-receipt.json").write_text(json.dumps(receipt, indent=2)+"\n", encoding="utf-8")
+    print(json.dumps(receipt, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:
+        # Do not print HTTP request objects or environment values on authentication failures.
+        status = getattr(getattr(exc, "response", None), "status_code", None)
+        print(json.dumps({"ok": False, "error_type": type(exc).__name__, "http_status": status,
+                          "reason": str(exc) if isinstance(exc, ValueError) else "Hugging Face request failed"}), file=sys.stderr)
+        sys.exit(2)

web/app.js

@@ -0,0 +1,94 @@
+"use strict";
+// Use integer rational comparisons in the browser calculator, like the CLI.
+function decimalFraction(value) {
+  const parts = String(value).toLowerCase().split("e");
+  const mantissa = parts[0].split(".");
+  let numerator = BigInt(mantissa.join(""));
+  const exponent = Number(parts[1] || 0) - (mantissa[1] || "").length;
+  let denominator = 1n;
+  if (exponent >= 0) numerator *= 10n ** BigInt(exponent);
+  else denominator = 10n ** BigInt(-exponent);
+  return [numerator, denominator];
+}
+function bucketAssessment(width, height, buckets, mode, percent) {
+  let best = null;
+  const [tn, td] = decimalFraction(percent);
+  for (const bucket of buckets) {
+    const [n, d] = bucket.split(":").map(BigInt);
+    const a = BigInt(width) * d, b = BigInt(height) * n;
+    const difference = a >= b ? a - b : b - a, base = a <= b ? a : b;
+    const matched = mode === "strict" ? difference === 0n : difference * td * 100n <= base * tn;
+    if (best === null || difference * best.base < best.difference * base) {
+      best = {bucket, difference, base, matched};
+    }
+  }
+  return best;
+}
+function buildFilterCommand(platform, resolution, buckets, mode, percent) {
+  if (!/^(?:[1-9][0-9]*p|[1-9][0-9]*x[1-9][0-9]*|any|none)$/.test(resolution)) {
+    throw new Error("分辨率请填写 256p、384x256 或 any；数字需为正整数。");
+  }
+  if (mode === "loose" && (!Number.isFinite(Number(percent)) || Number(percent) < 0 || String(percent).trim() === "")) {
+    throw new Error("宽松偏差需为有限非负数，例如 5 表示 5%。");
+  }
+  const python = platform === "windows" ? ".\\.venv\\Scripts\\python.exe" : ".venv/bin/python";
+  const selected = buckets.length === 8 ? "all" : buckets.length ? '"' + buckets.join(",") + '"' : "none";
+  let command = `${python} -m image_cleaner filter --shards runs/statistics/shards --output runs/filtered --resolution ${resolution} --aspect-buckets ${selected}`;
+  if (buckets.length) {
+    command += ` --aspect-mode ${mode}`;
+    if (mode === "loose") command += ` --aspect-tolerance ${Number(percent) / 100}`;
+  }
+  return command;
+}
+if (typeof module !== "undefined") module.exports = {bucketAssessment, buildFilterCommand};
+if (typeof document !== "undefined") {
+  document.querySelectorAll("table").forEach(table => {
+    const wrapper = document.createElement("div"); wrapper.className = "table-scroll";
+    table.parentNode.insertBefore(wrapper, table); wrapper.appendChild(table);
+  });
+  document.querySelectorAll("pre").forEach(pre => {
+    const button = document.createElement("button"); button.className = "copy-code";
+    button.type = "button"; button.textContent = "复制";
+    button.addEventListener("click", async () => {
+      const value = pre.querySelector("code") ? pre.querySelector("code").textContent : pre.textContent.replace(/复制$/, "");
+      try {
+        await navigator.clipboard.writeText(value); button.textContent = "已复制";
+      } catch (_) { button.textContent = "请选中后复制"; }
+      setTimeout(() => {button.textContent = "复制";}, 2000);
+    });
+    pre.appendChild(button);
+  });
+  if (document.getElementById("command")) {
+    const ids = ["platform", "resolution", "mode", "tolerance", "width", "height"];
+    const controls = Object.fromEntries(ids.map(id => [id, document.getElementById(id)]));
+    const buckets = [...document.querySelectorAll('input[name="bucket"]')];
+    const update = () => {
+      const selected = buckets.filter(x => x.checked).map(x => x.value);
+      const mode = controls.mode.value, percent = controls.tolerance.value;
+      controls.tolerance.disabled = mode === "strict";
+      const error = document.getElementById("command-error"), output = document.getElementById("command");
+      try {
+        output.textContent = buildFilterCommand(controls.platform.value, controls.resolution.value.trim().toLowerCase(), selected, mode, percent);
+        error.textContent = "";
+      } catch (e) { output.textContent = "请先修正参数。"; error.textContent = e.message; }
+      const result = document.getElementById("ratio-result"), w = Number(controls.width.value), h = Number(controls.height.value);
+      if (!Number.isSafeInteger(w) || !Number.isSafeInteger(h) || w < 1 || h < 1) {
+        result.textContent = "请输入大于零的整数宽高。"; return;
+      }
+      if (error.textContent) { result.textContent = "请先修正筛选参数。"; return; }
+      const best = bucketAssessment(w, h, selected, mode, mode === "strict" ? "0" : percent);
+      const resolution = controls.resolution.value.trim().toLowerCase();
+      let sizeMatched = true;
+      if (resolution.endsWith("p")) sizeMatched = Math.min(w, h) >= Number(resolution.slice(0, -1));
+      else if (resolution.includes("x")) {
+        const [rw, rh] = resolution.split("x").map(Number); sizeMatched = w === rw && h === rh;
+      }
+      const bucketMessage = best ? `${best.matched ? "桶条件通过" : "桶条件未通过"}；最近桶 ${best.bucket}，偏差 ${(Number(best.difference) / Number(best.base) * 100).toFixed(3)}%` : "桶条件已关闭";
+      result.textContent = `${w}×${h}：${bucketMessage}；分辨率条件${sizeMatched ? "通过" : "未通过"}。`;
+    };
+    [...Object.values(controls), ...buckets].forEach(x => x.addEventListener("input", update));
+    document.getElementById("select-all").addEventListener("click", () => {buckets.forEach(x => x.checked = true); update();});
+    document.getElementById("select-none").addEventListener("click", () => {buckets.forEach(x => x.checked = false); update();});
+    update();
+  }
+}

web/index.template.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="description" content="图片文本数据初筛代码、分布统计、尺寸与宽高比筛选、质量指标、去重和多机部署教程。"><title>NMM-data-preprocess · 图片文本数据初筛</title><link rel="stylesheet" href="assets/style.css"><script defer src="assets/app.js"></script></head>
+<body>
+<header class="topbar"><a class="brand" href="index.html">NMM<span> / </span>data-preprocess</a><nav aria-label="主要导航"><a href="manual/QUICKSTART.html">开始使用</a><a href="manual/PARAMETERS.html">参数参考</a><a href="manual/DEPLOYMENT.html">部署</a><a href="https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess/tree/main" target="_blank" rel="noopener">源代码 ↗</a></nav></header>
+<main class="landing">
+<section class="hero"><p class="eyebrow">原生图片—文本模型 / 训练前数据初筛</p><h1>先看清数据，<br>再决定保留什么。</h1><p class="lead">从图片文件夹或图文清单开始，统计尺寸与质量分布，按分辨率和宽高比筛选，再完成全局去重与标准化导出。</p><div class="actions"><a class="button primary" href="manual/QUICKSTART.html">阅读逐步教程 →</a><a class="button" href="downloads/NMM-data-preprocess-@@VERSION@@.zip" download>下载源码 v@@VERSION@@ ↓</a></div><p class="note">Python 3.10+ · CPU 多进程 · 多机静态分片 · Windows / Linux / Docker</p></section>
+<section class="pipeline" aria-label="清洗流程"><div><b>01</b><strong>导入</strong><span>文件夹 / JSONL</span></div><div><b>02</b><strong>统计</strong><span>尺寸 / 技术质量</span></div><div><b>03</b><strong>筛选</strong><span>规则 / 全局去重</span></div><div><b>04</b><strong>导出</strong><span>RGB 图片 / 图文清单</span></div></section>
+<section class="intro"><h2>完整教程与代码说明</h2><p>这个 Space 提供文档、命令设置和代码下载。清洗任务通过 CLI 在你的本地机器或服务器运行。</p><div class="guide-grid"><a class="guide" href="manual/QUICKSTART.html"><small>从零开始</small><h3>逐步使用教程</h3><p>下载、安装、合成样例、第一轮统计、筛选与导出。</p><span>阅读教程 →</span></a><a class="guide" href="manual/USAGE.html"><small>评测与规则</small><h3>完整操作手册</h3><p>逐阶段指标、公式、报告字段、质量校准和误删评估。</p><span>查看手册 →</span></a><a class="guide" href="manual/PARAMETERS.html"><small>全部设置</small><h3>参数参考</h3><p>每个 CLI 与 JSON 字段的默认值、约束、优先级和示例。</p><span>查询参数 →</span></a><a class="guide" href="manual/DEPLOYMENT.html"><small>本地与多机</small><h3>部署指南</h3><p>Windows、Linux、Docker、rank 分片、续跑和 Space 发布。</p><span>部署运行 →</span></a><a class="guide" href="manual/ARCHITECTURE.html"><small>实现细节</small><h3>代码与功能说明</h3><p>模块职责、数据流、文件格式、去重机制与当前边界。</p><span>了解实现 →</span></a></div></section>
+<section class="generator" id="commands"><div class="section-heading"><div><p class="eyebrow">配置尺寸与比例</p><h2>生成一条筛选命令</h2></div><span class="tag">复用统计缓存，无需重新解码</span></div><p>先按教程完成统计，将分片放在 <code>runs/statistics/shards</code>。以下设置只生成命令，可直接复制到终端。</p><div class="form-grid"><label>终端环境<select id="platform"><option value="windows">Windows PowerShell</option><option value="linux">Linux Bash</option></select></label><label>分辨率下限<input id="resolution" type="text" value="256p" placeholder="256p / 384x256 / any"></label><label>匹配策略<select id="mode"><option value="loose">宽松过滤</option><option value="strict">严格过滤</option></select></label><label>宽松偏差（%）<input id="tolerance" type="number" min="0" step="0.1" value="5"></label></div><fieldset class="buckets"><legend>宽:高桶（多选）</legend><label><input type="checkbox" name="bucket" value="1:1" checked>1:1</label><label><input type="checkbox" name="bucket" value="2:3" checked>2:3</label><label><input type="checkbox" name="bucket" value="3:2" checked>3:2</label><label><input type="checkbox" name="bucket" value="3:4" checked>3:4</label><label><input type="checkbox" name="bucket" value="4:3" checked>4:3</label><label><input type="checkbox" name="bucket" value="9:16" checked>9:16</label><label><input type="checkbox" name="bucket" value="16:9" checked>16:9</label><label><input type="checkbox" name="bucket" value="21:9" checked>21:9</label><button type="button" id="select-all">全选</button><button type="button" id="select-none">关闭桶条件</button></fieldset><p id="command-error" class="error" role="alert"></p><pre><code id="command"></code></pre><p class="note">输出到 <code>runs/filtered</code>；已有结果时请改用新目录。命令继承分析���置中的质量与去重设置。256p 表示短边 ≥256，包含 256。</p>
+<details><summary>用实际尺寸检查比例规则</summary><div class="form-grid"><label>图片宽（像素）<input id="width" type="number" min="1" step="1" value="1050"></label><label>图片高（像素）<input id="height" type="number" min="1" step="1" value="1000"></label></div><p id="ratio-result" aria-live="polite"></p><p class="note">偏差 δ=max(r/b,b/r)−1，包含阈值边界。实际 CLI 用精确分数比较；这里只展示所选桶和分辨率条件，不判断图片质量、文字和重复。</p></details></section>
+<section class="features"><h2>当前初筛覆盖</h2><div class="feature-grid"><article><h3>分布统计</h3><p>分辨率、短边、长边、像素数、比例和质量分布；全量直方图与抽样分位数。</p></article><article><h3>分辨率与八桶筛选</h3><p>短边下限、精确宽高、严格比例和默认 5% 可调宽松偏差。</p></article><article><h3>规范化与文本规则</h3><p>EXIF、ICC、RGB、透明背景、Unicode、文本长度与正则检查。</p></article><article><h3>技术质量代理</h3><p>模糊、噪声、信噪比与块效应指标；阈值需针对你的数据校准。</p></article><article><h3>全局去重</h3><p>文件和像素精确去重，pHash / dHash / RMSE 联合近重复复核。</p></article><article><h3>多进程与多机</h3><p>SQLite 检查点与静态 rank；汇总分片后统一筛选、去重和报告。</p></article></div></section>
+<section class="callout"><h2>看报告时，先核对这些数字</h2><p>输入总数 = 保留 + 拒绝 + 重复 + 错误。比较分辨率独立通过率、桶独立通过率、最终保留率，以及各桶筛选前后数量。初筛结果仍需人工抽查图文对应关系与质量。</p><a href="manual/USAGE.html">阅读所有指标的定义 →</a></section>
+</main><footer>HanWangTJU / NMM-data-preprocess · v@@VERSION@@<span>静态教程与代码入口 · 图片在本地处理</span></footer>
+</body></html>

web/style.css

@@ -0,0 +1 @@
+:root{--ink:#12273b;--muted:#596c7a;--teal:#087d70;--line:#d9e3e8;--surface:#f3f7f9;--paper:#fff}*{box-sizing:border-box}html{scroll-behavior:smooth;scroll-padding-top:88px}body{margin:0;background:var(--paper);color:var(--ink);font-family:Inter,"Microsoft YaHei",system-ui,sans-serif;line-height:1.8}a{color:var(--teal);text-decoration:none}a:hover{text-decoration:underline}.topbar{position:sticky;top:0;z-index:20;min-height:72px;display:flex;justify-content:space-between;gap:20px;align-items:center;padding:15px max(24px,calc((100vw - 1180px)/2));border-bottom:1px solid var(--line);background:rgba(255,255,255,.97)}.brand{font-weight:750;letter-spacing:-.5px;color:var(--ink);white-space:nowrap}.brand span{color:var(--teal)}nav{display:flex;gap:24px;font-size:14px}nav a{color:var(--muted)}.landing{max-width:1180px;margin:auto;padding:0 28px}.hero{padding:75px 0 58px;max-width:900px}.eyebrow{font-size:12px;letter-spacing:1.5px;font-weight:700;color:var(--teal)}h1{font-size:clamp(36px,5.2vw,64px);line-height:1.24;letter-spacing:-1.8px;margin:22px 0}h2{font-size:26px;line-height:1.45;letter-spacing:-.5px}h3{font-size:19px;line-height:1.5}.lead{font-size:19px;max-width:740px;color:var(--muted)}.actions{display:flex;gap:12px;flex-wrap:wrap;margin:30px 0 17px}.button{display:inline-block;padding:11px 22px;border:1px solid var(--line);border-radius:7px;font-weight:600;color:var(--ink);font-size:14px}.primary{background:var(--teal);border-color:var(--teal);color:#fff}.button:hover{text-decoration:none;filter:brightness(.95)}.note{font-size:13px;color:var(--muted)}.pipeline{display:grid;grid-template-columns:repeat(4,1fr);border-top:1px solid var(--line);border-bottom:1px solid var(--line);padding:23px 0;gap:20px}.pipeline div{display:grid;grid-template-columns:36px 1fr;column-gap:12px}.pipeline b{grid-row:span 2;color:var(--teal);font-size:14px}.pipeline strong{font-size:17px}.pipeline span{font-size:12px;color:var(--muted)}.intro,.features{padding:48px 0 20px}.intro>p,.generator>p{color:var(--muted)}.guide-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:16px;margin-top:24px}.guide{border:1px solid var(--line);border-radius:9px;padding:23px;color:var(--ink);transition:background .15s}.guide:hover{background:var(--surface);text-decoration:none}.guide small{color:var(--teal);font-size:12px}.guide h3{margin:8px 0}.guide p{font-size:14px;color:var(--muted);margin:8px 0 20px}.guide span{font-size:13px;font-weight:600;color:var(--teal)}.generator{margin-top:38px;padding:30px;background:var(--surface);border:1px solid var(--line);border-radius:10px}.section-heading{display:flex;justify-content:space-between;gap:16px;align-items:center}.section-heading h2{margin:5px 0}.section-heading .eyebrow{margin:0}.tag{font-size:11px;border:1px solid #bbd9d2;border-radius:40px;padding:4px 11px;color:var(--teal)}.form-grid{display:grid;grid-template-columns:repeat(4,1fr);gap:16px;margin:24px 0}.form-grid label{display:flex;flex-direction:column;font-size:13px;gap:7px;font-weight:600}input,select,button{font:inherit}input[type=text],input[type=number],select{width:100%;border:1px solid #bdcdd6;background:white;padding:10px;border-radius:5px;color:var(--ink);font-size:14px}input:focus,select:focus,button:focus-visible,a:focus-visible{outline:2px solid var(--teal);outline-offset:3px}.buckets{padding:14px 0;border:0;display:flex;flex-wrap:wrap;gap:12px}.buckets legend{font-size:13px;font-weight:600}.buckets label{padding:6px 10px;border:1px solid var(--line);border-radius:5px;background:white;font-size:13px;cursor:pointer}.buckets input{accent-color:var(--teal);margin-right:6px}.buckets button{border:0;color:var(--teal);background:transparent;cursor:pointer;font-size:12px;padding:5px}pre{background:#142a3b;color:#e5edf2;border-radius:7px;padding:22px 24px;white-space:pre-wrap;overflow-wrap:anywhere;overflow-x:auto;position:relative;font-size:13px;line-height:1.75}pre code{background:transparent;color:inherit;padding:0}code{font-family:"Cascadia Code",Consolas,monospace;font-size:.88em;background:#eaf0f3;padding:2px 5px;border-radius:4px}.copy-code{position:absolute;right:7px;top:6px;cursor:pointer;color:#d6eee8;background:#294759;border:1px solid #537180;border-radius:4px;font-size:11px;padding:3px 8px}.error{color:#aa302b;font-size:13px}.error:empty{display:none}details{margin-top:20px;border-top:1px solid var(--line);padding-top:16px}summary{cursor:pointer;font-size:14px;font-weight:600}details .form-grid{grid-template-columns:repeat(2,minmax(120px,200px))}#ratio-result{font-size:14px;font-weight:600;color:var(--teal)}.feature-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:20px}.feature-grid article{border-top:2px solid var(--line);padding:12px 0}.feature-grid p{color:var(--muted);font-size:14px}.callout{border-left:3px solid var(--teal);padding:5px 26px;margin:30px 0 64px;background:var(--surface)}.callout h2{font-size:22px;padding-top:18px}.callout p{font-size:15px;max-width:900px}.callout a{display:inline-block;font-size:14px;margin-bottom:20px}footer{max-width:1180px;margin:auto;padding:24px 28px;border-top:1px solid var(--line);color:var(--muted);font-size:12px;display:flex;justify-content:space-between;gap:20px}.manual-layout{display:grid;grid-template-columns:240px minmax(0,1fr);gap:48px;max-width:1230px;margin:0 auto;padding:38px 28px 65px}.sidebar{position:sticky;top:108px;align-self:start;font-size:13px;max-height:calc(100vh - 135px);overflow:auto}.sidebar>a{display:block;margin-bottom:10px;padding:7px 11px;border-left:2px solid transparent;color:var(--muted)}.sidebar>a.active{color:var(--teal);border-color:var(--teal);background:var(--surface)}.sidebar h2{font-size:13px;color:var(--muted);margin:25px 0 10px}.toc ul{list-style:none;padding-left:0}.toc ul ul{padding-left:13px}.toc a{color:var(--muted);font-size:12px;display:block;line-height:1.6;margin-bottom:9px}.manual{min-width:0;font-size:15px}.manual h1{font-size:34px;margin:8px 0 27px;letter-spacing:-1px}.manual h2{margin:45px 0 18px;padding-top:12px;border-top:1px solid var(--line);font-size:24px}.manual h3{font-size:18px;margin-top:28px}.manual li{margin-bottom:5px}.manual pre{font-size:12px}.table-scroll{overflow:auto;margin:22px 0}.manual table{border-collapse:collapse;width:100%;font-size:13px}.manual td,.manual th{padding:12px;text-align:left;vertical-align:top;border:1px solid var(--line)}.manual th{background:var(--surface);font-weight:600}.manual blockquote{padding:5px 20px;border-left:3px solid var(--teal);margin:20px 0;color:var(--muted)}@media(max-width:900px){.guide-grid,.feature-grid{grid-template-columns:repeat(2,1fr)}.form-grid{grid-template-columns:repeat(2,1fr)}.tag{display:none}.topbar{padding:15px 20px}nav{gap:14px}.manual-layout{grid-template-columns:185px minmax(0,1fr);gap:24px}}@media(max-width:620px){.topbar{position:relative;flex-direction:column;align-items:flex-start;gap:6px}.brand{font-size:16px}nav{font-size:12px;flex-wrap:wrap}.landing{padding:0 20px}.hero{padding:40px 0 35px}h1{font-size:40px}.lead{font-size:16px}.pipeline{grid-template-columns:repeat(2,1fr);gap:20px}.guide-grid,.feature-grid{grid-template-columns:1fr}.generator{padding:22px 16px}.form-grid{gap:12px}.form-grid label{font-size:12px}.manual-layout{display:block;padding:22px 16px}.sidebar{position:relative;top:0;max-height:none;border-bottom:1px solid var(--line);margin-bottom:28px}.sidebar .toc,.sidebar h2{display:none}.sidebar>a{display:inline-block;font-size:12px;margin:3px;padding:4px 8px}.manual h1{font-size:29px}.manual h2{font-size:22px}footer{flex-direction:column;gap:4px}.section-heading h2{font-size:23px}}