visual-preview

Visual Preview — 扫描预处理效果可视化

Task

prep-scan 做了一堆看不见的事：擦红蓝馆藏章、去对角线水印、刮掉淡灰重复水印、裁掉页眉页脚。但用户看不到——用户只得到一份 cleaned.pdf 和一句"清理完成"。这个 skill 把每页处理前后的对比直接弹到浏览器里，让用户回答三个问题：

1. 擦对了吗：水印 / 馆藏章是不是真的没了
2. 擦过头了吗：有没有误伤正文（淡墨古籍最危险）
3. 裁合适吗：页眉页脚裁得是不是正好，没切到正文首行

不给用户看等于把清理结果当黑盒交付——下游校对发现误伤已经晚了。

---

Process

Step 1 — 定位 workspace + prep 目录

路径约定：prep-scan 把图像中间态放在 <workspace>.ocr/prep/{pages,cleaned_pages}，本 skill 消费同一份目录。HTML 输出固定落在 <workspace>.ocr/previews/visual-prep.html。权威规范见插件的 references/workspace-layout.md。

INPUT="$1"

# 用户可能传：
#   (a) PDF 路径  ~/Downloads/论文.pdf      → 推断 论文.ocr/
#   (b) 工作区    ~/Downloads/论文.ocr/     → 直接用
#   (c) prep 目录 ~/Downloads/论文.ocr/prep → 取父目录作为工作区
if [ -d "$INPUT" ]; then
    case "$INPUT" in
        */prep)        OCR="$(dirname "$INPUT")" ;;
        *.ocr|*.ocr/)  OCR="${INPUT%/}" ;;
        *)             OCR="$INPUT" ;;
    esac
elif [ -f "$INPUT" ] && echo "$INPUT" | grep -qE '\.pdf$'; then
    DIR=$(dirname "$INPUT")
    BASE=$(basename "$INPUT" .pdf)
    OCR="$DIR/$BASE.ocr"
else
    echo "找不到工作区或 PDF：$INPUT"; exit 1
fi

PREP="$OCR/prep"
test -d "$PREP/pages"         || { echo "缺 $PREP/pages";         exit 2; }
test -d "$PREP/cleaned_pages" || { echo "缺 $PREP/cleaned_pages"; exit 2; }
mkdir -p "$OCR/previews"

Step 2 — 跑脚本

python3 "${CLAUDE_PLUGIN_ROOT}/skills/visual-preview/scripts/visualize_prep.py" \
    --prep-dir "$PREP" \
    --out "$OCR/previews/visual-prep.html" \
    $( [ -n "$SAMPLE" ] && echo "--sample $SAMPLE" ) \
    $( [ "$NO_DIFF" = "1" ] && echo "--no-diff" )

Step 3 — 脚本行为规范（visualize_prep.py 必须实现）

3.1 输入收集

• <prep-dir>/pages/page_*.png → 原始页
• <prep-dir>/cleaned_pages/page_*.png → 清理后
• 两者按文件名配对；任一侧缺失视作该页无效

3.2 差异热图生成

对每一对 (orig, clean)：

1. 若两图尺寸不同（证明裁边了），把 clean 上下或左右 pad 到 orig 尺寸（白边填充），再做 diff
2. cv2.absdiff(orig, clean) → 灰度 → 阈值 > 25 的像素视为"被清理"
3. 生成叠加热图：原图 + 半透明红色（[0,0,255] BGR，alpha=0.4）覆盖差异像素
4. 保存到 <prep-dir>/diff_pages/page_N.png
5. 计算清理比例：(差异像素数 / 总像素数) * 100%