kindle-pdf-cropper

自动剪裁 PDF 四周白边与页眉/页脚、为 Kindle 生成阅读优化 PDF/EPUB 的命令行工具。

• 剪掉每页四周白边 + 页眉/页脚 + 页码，只保留正文内容；
• 可选 --split：把每页上下切成两页，输出横版页面，Kindle 横屏阅读字号接近翻倍；
  • 默认（自适应切分）：不指定重叠参数时，程序自动把切线放在两行文字之间的空白处—— 文字型 PDF 用文本行 bbox 找行间空隙，扫描型 PDF 用图像识别算法找两行之间的空白带—— 因此不会切断任何一行，也不需要重叠区域；
  • 也可以显式指定 --split-overlap-* 恢复"中线切分 + 两页重叠"的旧模式；
• 自适应文字型与扫描图片型 PDF；输出结果保持原样——文字仍是文字、 扫描图仍是扫描图，文字/公式/表格的排版完全不变，只做整页剪裁与切分；
• 输出 PDF（文字/矢量/图片保真）或 EPUB（固定版式，排版不重排）。

技术选型调研见 docs/research.md，算法设计见 docs/design.md。

安装

要求 Python ≥ 3.10。

cd kindle-pdf-cropper
python -m venv .venv
.venv\Scripts\activate            # Windows
# source .venv/bin/activate       # Linux / macOS
pip install -e .

快速开始

# 只裁白边和页眉页脚，输出 PDF（默认）
kindle-crop 书.pdf

# 裁切 + 上下切分成横版两页（自适应：切线自动落在两行文字之间的空白处，不切行）
kindle-crop 书.pdf --split -o out/书_横版

# 旧模式：中线切分 + 两页重叠（需要指定重叠参数）
kindle-crop 书.pdf --split --split-overlap-pt 20 -o out/书_横版

# 同时输出 PDF 和 EPUB（自动：文字页=SVG，扫描页=位图）
kindle-crop 书.pdf --format both -o out/书

# 扫描件：调大安全边距、提高 EPUB 位图质量
kindle-crop 扫描.pdf --padding 10 --epub-dpi 220 --format epub

# 调试：把每页的分析叠加图（裁剪框/页眉页脚带/切分框）导出成 PNG
kindle-crop 书.pdf --debug-dir debug

常用参数

自适应切分说明（--split）

不指定 --split-overlap-* 时，切分线按如下方式自动确定：

1. 文字型 PDF：取裁剪区内所有文本行 bbox，找出相邻两行之间宽度足够的空白间隙 （≥ 0.4 × 中位行高），把切线放在该间隙正中——上一行完整保留在上半页， 下一行完整保留在下半页，中间无重叠也不丢内容；
2. 扫描型 PDF：用图像识别算法对裁剪区做逐像素行投影，找到连续 "无墨水行"的空白带（行间空白即使只有几像素宽也能分辨），要求 切线行及其上下 1px 均为纯空白，把切线放在空白带正中；被两侧实心 墨块夹住的空隙（图/大公式内部）优先级最低——只要别处有文字间隙， 就不会把一张图切成两半；
3. 若整页几乎找不到可用空白带（如旋转 90° 的扫描页），退化为中线切分， 保证上下两页尺寸均衡。

指定 --split-overlap-* 后恢复旧模式：在中线切分，两页保留 max(比例×裁剪高, 最小点数) 的重叠，保证中线附近的一行不会显示不全。

水印 / 重复图案去除（扫描页自动）

许多扫描版书籍带有浅色水印（如对角重复的站点文字、页脚图案、扫描边缘带）， 它们出现在每一页的相同位置，会干扰页眉/页脚判定（例如把页脚区域和正文合并成 一个大色带，导致页眉页脚都裁不掉）。

程序默认自动检测并去除这类重复图案：

1. 在全书中均匀抽样（最多 40 页），对每个像素计算跨页中位灰度；
2. 某像素在多数页面上恒定比纸张更暗（中位数低于背景阈值），而正文像素在 多数页面是背景色 → 该像素属于水印/页眉/页框/扫描边缘等重复图案；
3. 把这些像素从分析用的墨水掩码中剔除（正文像素基本不受影响）， 再执行页眉/页脚检测与裁剪——页脚区域不再被水印"糊住"；
4. 保护措施：若某页剔除后内容不足原墨迹的 35%，则保留原样（防止把 "每页相同的表格/插图"误当水印删掉）；文字型（born-digital）PDF 不启用。

如需关闭：kindle-crop 书.pdf --no-watermark-removal。

输出说明

• PDF 输出：每个输出页的页面尺寸就是裁剪后的尺寸（物理裁剪，而非仅改 CropBox， 任何阅读器都稳定显示）；文字保持可选中的文字，表格线/公式等矢量、嵌入字体原样保留； 目录与元数据保留。
• EPUB 输出：EPUB 是流式重排容器，若要保持排版不变只能用固定版式： 每页钉死一个 viewport。
  • 文字页 → 内联 SVG（文字仍为文字，矢量图形保留）；
  • 扫描页 → 整页 JPEG/PNG 位图；
  • 若你的阅读器对 SVG/固定版式支持不佳（如部分 Kindle 固件），请用 --epub-mode image 或直接使用 PDF 输出。

示例文件

examples/ 下有生成的样例（文字型、扫描型、旋转扫描型）： 运行 python tests/make_samples.py text examples/sample_text.pdf 等重新生成。

开发与测试

pip install -e .[dev]
python -m pytest

测试覆盖：边距/页眉页脚分析、扫描与旋转页、PDF 输出文字保真、切分重叠、 自适应切分（文字行间 / 扫描空白带 / 旋转页退避）、EPUB 结构与内容校验、CLI 端到端。

许可

MIT，见 LICENSE。