Metadata-Version: 2.4
Name: classics-index
Version: 0.1.2
Summary: Chapter indexes (卷 / 篇 / 回) for scanned Chinese books, built from OCR of the running header
Author: socratic-tutor contributors
License: MIT
Project-URL: Homepage, https://github.com/Icefox12138/socratic-tutor/tree/main/packages/classics-index
Project-URL: Repository, https://github.com/Icefox12138/socratic-tutor
Project-URL: Issues, https://github.com/Icefox12138/socratic-tutor/issues
Keywords: chinese-classics,scanned-books,ocr,table-of-contents
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: ocr
Requires-Dist: paddleocr>=3; extra == "ocr"
Requires-Dist: pillow; extra == "ocr"
Dynamic: license-file

# classics-index

从**扫描本**的版心（页边书眉）OCR 里建章回索引：卷 → 篇 → 回。不依赖任何在线服务，纯 Python，无第三方运行时依赖（OCR 引擎是可选的）。

```
pip install -e .
classics-index volumes --headers heads.jsonl --out toc.json
classics-index pian    --toc toc.json --band titles.jsonl --out toc-pian.json
classics-index hui     --ocr hui.jsonl --names "1=西游记,2=水浒传" --out hui.json
classics-index find    --toc toc.json --q 卷3
```

## 它解决什么问题

点校本、影印本没有文本层，目录页也常常 OCR 不可用。但**每一页的页眉都印着卷次**（"史記卷二"）或回目（"灵根育孕源流出心性修持大道生"）。于是：

| 输入 | 输出 |
|---|---|
| 每页页眉带的 OCR（`{"page": n, "vol": 2}`） | 卷的起止页，连续覆盖全书 |
| 每页右侧标题带的 OCR（`{"page": n, "lines": [...]}`） | 篇名页与篇页码范围 |
| 章回小说每页页眉 OCR（`{"page": n, "texts": [...]}`） | 回目分段、附录标记、多部书切分 |

## 设计上的三个关键判据

1. **卷靠"连续 ≥5 页"**：目录页也会写出"史記卷十三"，那种孤页会被丢掉。
2. **篇靠"行的形态"而不是字号**：实测卷眉（48 px 宽）比篇名（46 px）还宽，宽度阈值不可靠；可靠的是"短行 + 序号结尾干净"（目录行末尾是"："或省略号）。
3. **回靠"页眉标题变化"**：章回小说每页页眉都印着当前回目，标题一变就是新回；附录（"附/录"）重复上一回页眉，不能占回号。

## 数据从哪来

配套的 OCR 脚本在本仓库的 `eval/p3/`（`vertical_header_ocr.py`、`vertical_title_ocr.py`、`novel_hui_ocr.py`），它们只是 PaddleOCR 的一层薄封装：

- 版心带：页面右侧 18%、高度 8%–55%，1.2 s/页；
- 标题带：右侧 42%、高度 3%–65%，3.5 s/页；
- 章回页眉：全宽、高度 3%–15%，0.55 s/页。

把任意 OCR 引擎的结果整理成本包要的 JSONL 也行。

## 已在什么数据上验证

| 书 | 规模 | 结果 |
|---|---|---|
| 《史记》点校本 一 | 358 页 | 7 卷 + 7 篇，覆盖 358/358 |
| 《三国志》二 | 140 页 | 卷10–14 五篇篇名正确 |
| 四大名著合订本 | 2745/5291 页 | 215 回目段 / 3 部（过切 +1%） |

## 限制

- 版心位置是按中华书局版式调的，换版式要调裁切参数；
- 章回小说的"换书边界"会晚一回（下一部第一回的页眉常没有"第一回"）；
- 只处理竖排/横排的中文印刷体，不做手写、不做多栏学术期刊。

## 许可

尚未选定（建议 MIT）；选好之前不要发布到任何包索引。
