isbnx 0.0.1__tar.gz

isbnx-0.0.1/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.3
+Name: isbnx
+Version: 0.0.1
+Summary: 从 PDF、图片、压缩包和 EPUB 文件中提取 ISBN 号，支持 ONNX 检测和 OCR 识别
+Author: zscmmm
+Author-email: zscmmm <111739721+zscmmm@users.noreply.github.com>
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: mneia-isbn>=0.0.3
+Requires-Dist: opencv-python>=4.13.0.92
+Requires-Dist: pillow>=12.2.0
+Requires-Dist: pydantic-settings>=2.14.2
+Requires-Dist: pymupdf>=1.27.2.3
+Requires-Dist: pyzbar>=0.1.9
+Requires-Dist: rapidocr>=3.9.0
+Requires-Dist: rarfile>=4.2
+Requires-Dist: onnxruntime>=1.27.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/zscmmm/isbnx
+Project-URL: Documentation, https://isbnx.readthedocs.org
+Project-URL: Repository, https://github.com/zscmmm/isbnx.git
+Project-URL: Issues, https://github.com/zscmmm/isbnx/issues
+Project-URL: Changelog, https://github.com/zscmmm/isbnx/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+
+# isbnx
+
+> 从 PDF、图片、EPUB、MOBI 和压缩包中智能提取 ISBN 号
+
+[![Python](https://img.shields.io/badge/python-≥3.11-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://isbnx.readthedocs.org)
+
+
+
+---
+
+## 安装
+
+```bash
+pip install isbnx
+# 或
+uv add isbnx
+```
+
+### 系统依赖
+
+- pyzbar, [参考安装](https://pypi.org/project/pyzbar/), 自己简单测试准确率好像比[zbarlight](https://pypi.org/project/zbarlight/)好一些,单安装依赖有点麻烦
+
+    - **win**: 需要一些c++动态库, 
+    - **macOS**: 需要设置 `DYLD_LIBRARY_PATH` 以支持条形码解码
+
+    ```bash
+    echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc
+    ```
+
+
+- pdf-inspector, 可选, [参考安装](https://github.com/firecrawl/pdf-inspector), 需要配置rust,不然可能安装不成功
+
+
+
+
+---
+
+## 快速开始
+
+### 统一入口
+
+```python
+from isbnx import extract
+
+# 自动根据文件后缀选择提取方式
+result = extract("cover.png")
+if result.success:
+    print(result.bookinfo.isbn13)  # 9787123456789
+```
+
+### 使用 ISBNX 类
+
+```python
+from isbnx import ISBNX
+
+# 从图片提取
+result = ISBNX().from_image("cover.png")
+
+# 从 PDF 提取（支持文本型和扫描件）
+result = ISBNX().from_pdf("book.pdf")
+
+# 从 EPUB 提取
+result = ISBNX().from_epub("book.epub")
+
+# 从 MOBI 提取
+result = ISBNX().from_mobi("book.mobi")
+
+# 从压缩包提取（支持 ZIP/RAR/UVZ）
+result = ISBNX().from_archive("book.zip")
+
+# 或使用统一的自动分发入口
+result = ISBNX().extract("book.pdf")
+```
+
+---
+
+## 支持的文件格式
+
+| 类型 | 后缀 | 提取策略 |
+|------|------|----------|
+| **图片** | `.png` `.jpg` `.jpeg` | ONNX 检测 → OCR / 条码解码 |
+| **PDF** | `.pdf` | 书签定位 + 文本搜索（文本型）→ 渲染图片检测（扫描件） |
+| **EPUB** | `.epub` | OPF 元数据优先 → XHTML 内容扫描 |
+| **MOBI** | `.mobi` | EXTH 元数据优先 → 文本记录扫描 |
+| **压缩包** | `.zip` `.rar` `.uvz` | `meta.xml` → `bookinfo.dat` → `leg001.pdg` → 兜底 PDG 图片 |
+
+---
+
+## 核心流程
+
+```
+输入文件
+    │
+    ▼
+文件类型判断 ───→ 图片 ───→ ONNX YOLO 检测 ───→ OCR / 条码解码 ───→ ISBN 提取
+    │              PDF ───→ 类型判断（文本/扫描）─→ 文本搜索 / 渲染检测
+    │              EPUB ──→ OPF 元数据 / XHTML 扫描
+    │              MOBI ──→ EXTH 元数据 / 文本记录扫描
+    │              压缩包 ─→ meta.xml → bookinfo.dat → PDG 图片解码 → 检测
+    │
+    ▼
+ ExtractResult
+  ├── success: bool          # 是否提取成功
+  ├── bookinfo.isbn13        # ISBN-13
+  ├── bookinfo.isbn10        # ISBN-10
+  ├── bookinfo.ssid          # SS 号（压缩包特有）
+  ├── locate                 # 定位信息（页码、方法）
+  ├── ocr                    # OCR 原始识别文本
+  ├── meta                   # 文件元信息
+  └── elapsed                # 耗时（秒）
+```
+
+---
+
+## 配置
+
+### 严格等级
+
+通过 `strict` 参数控制提取结果的校验严格程度：
+
+| 等级 | 含义 | 适用场景 |
+|:----:|------|----------|
+| 1 | ISBN **和** SSID 都必须存在且有效 | 最高严格 |
+| 2 | ISBN 必须存在且校验通过 | 图片/PDF 检测 |
+| 3 | ISBN 有效 **或** SSID 存在（默认） | 压缩包提取 |
+
+### 自定义配置
+
+```python
+from isbnx import ISBNX
+from isbnx.config import Settings
+
+# 嵌套配置通过 dict 传参
+config = Settings(
+    strict=2,                           # 严格等级
+    ocr={"ocr_model": "medium"},        # OCR 精度（small / medium）
+    detector={"conf_threshold": 0.5},   # ONNX 检测阈值
+    pdf={"front_start": 1, "back_end": 3},
+)
+
+result = ISBNX(config=config).from_image("cover.png")
+```
+
+### 运行时调整
+
+```python
+from isbnx.config import configure
+
+configure(
+    strict=2,
+    ocr={"ocr_model": "medium"},
+    detector={"conf_threshold": 0.5},
+)
+```
+
+---
+
+## 输出模型
+
+所有提取结果使用 Pydantic 模型，可通过一致的接口访问：
+
+```python
+result = ISBNX().from_image("cover.png")
+
+# 基本状态
+result.success     # True / False
+result.error       # 失败原因（如有）
+
+# 书籍信息
+result.bookinfo.isbn       # 原始 ISBN
+result.bookinfo.isbn13     # ISBN-13 格式
+result.bookinfo.isbn10     # ISBN-10 格式
+result.bookinfo.isbn_valid # 校验是否合法
+result.bookinfo.ssid       # SS 号（压缩包）
+
+# 定位信息
+result.locate.page         # 命中页码
+result.locate.method       # 定位方式（onnx / text / bookmark / ...）
+result.locate.score        # 检测置信度
+
+# OCR 结果
+result.ocr.lines           # OCR 文本行
+result.ocr.text            # 全部文本（换行拼接）
+
+# 元信息
+result.meta.source         # 源文件路径
+result.meta.source_type    # 源文件类型
+
+# 耗时
+result.elapsed             # 处理耗时（秒）
+```
+
+---
+
+## 项目结构
+
+```
+isbnx/
+├── src/
+│   └── isbnx/
+│       ├── __init__.py        # 公开 API 入口
+│       ├── isbnx.py           # ISBNX 主类，统一提取接口
+│       ├── config.py          # Pydantic-Settings 配置管理
+│       ├── models.py          # Pydantic 数据模型
+│       ├── detector.py        # ONNX YOLO 检测器 + 检测/OCR 流水线
+│       ├── pdf.py             # PDF ISBN 提取
+│       ├── epub.py            # EPUB ISBN 提取
+│       ├── mobi.py            # MOBI ISBN 提取
+│       ├── archive.py         # 压缩包（PDG）ISBN 提取
+│       ├── pdf_type.py        # PDF 类型检测（文本/扫描）
+│       ├── model/             # ONNX 模型文件
+│       │   └── isbndetect_yolo.onnx
+│       ├── ocr/               # OCR 引擎
+│       │   ├── isbnx_pyzbar.py    # 条形码解码
+│       │   └── isbnx_rapiocr.py   # RapidOCR 文字识别
+│       ├── pdgview/           # PDG 图片解码器
+│       └── utils/             # 工具函数
+│           ├── cip_rules.py   # CIP 数据提取规则
+│           ├── io.py          # 文件 I/O 工具
+│           └── isbn_utils.py  # ISBN 提取与校验
+├── tests/                     # 测试用例
+├── docs/                      # MkDocs 文档
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## 开发
+
+### 环境要求
+
+- Python ≥ 3.10, 只在 python 3.13上进行测试开发的
+- [uv](https://docs.astral.sh/uv/) 包管理器
+
+### 本地开发
+
+```bash
+# 克隆项目
+git clone https://github.com/zscmmm/isbnx.git
+cd isbnx
+
+# 创建虚拟环境并安装依赖
+uv sync --group dev
+
+# 运行测试
+uv run pytest
+
+# 构建文档
+uv run mkdocs serve
+```
+
+---
+
+## 基准测试
+
+`isbnx` 与同类工具 `cipx` 的对比测试报告详见 [isbnx vs cipx 报告](https://isbnx.readthedocs.org/isbnx_vs_cipx_report/)。
+
+---
+
+## 路线图
+
+- [x] 图片 ISBN 提取
+- [x] PDF 提取（文本型 + 扫描件）
+- [x] EPUB 提取
+- [x] MOBI 提取
+- [x] 压缩包（PDG）提取
+- [x] ONNX YOLO 深度学习检测
+- [x] 条形码解码
+- [x] 文档网站（MkDocs）
+- [ ] LLM 解析 CIP 字段
+
+---
+
+## 许可证
+
+本项目基于 MIT 许可证开源 — 详见 [LICENSE](LICENSE) 文件。
+
+---
+
+## 相关项目
+
+- [mneia-isbn](https://pypi.org/project/mneia-isbn/) — ISBN 解析与校验库
+- [pyzbar](https://pypi.org/project/pyzbar/) -条形码解析库
+- [cipx](https://github.com/zscmmm/cipx) — CIP 信息提取工具

isbnx-0.0.1/README.md

@@ -0,0 +1,288 @@
+
+# isbnx
+
+> 从 PDF、图片、EPUB、MOBI 和压缩包中智能提取 ISBN 号
+
+[![Python](https://img.shields.io/badge/python-≥3.11-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://isbnx.readthedocs.org)
+
+
+
+---
+
+## 安装
+
+```bash
+pip install isbnx
+# 或
+uv add isbnx
+```
+
+### 系统依赖
+
+- pyzbar, [参考安装](https://pypi.org/project/pyzbar/), 自己简单测试准确率好像比[zbarlight](https://pypi.org/project/zbarlight/)好一些,单安装依赖有点麻烦
+
+    - **win**: 需要一些c++动态库, 
+    - **macOS**: 需要设置 `DYLD_LIBRARY_PATH` 以支持条形码解码
+
+    ```bash
+    echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc
+    ```
+
+
+- pdf-inspector, 可选, [参考安装](https://github.com/firecrawl/pdf-inspector), 需要配置rust,不然可能安装不成功
+
+
+
+
+---
+
+## 快速开始
+
+### 统一入口
+
+```python
+from isbnx import extract
+
+# 自动根据文件后缀选择提取方式
+result = extract("cover.png")
+if result.success:
+    print(result.bookinfo.isbn13)  # 9787123456789
+```
+
+### 使用 ISBNX 类
+
+```python
+from isbnx import ISBNX
+
+# 从图片提取
+result = ISBNX().from_image("cover.png")
+
+# 从 PDF 提取（支持文本型和扫描件）
+result = ISBNX().from_pdf("book.pdf")
+
+# 从 EPUB 提取
+result = ISBNX().from_epub("book.epub")
+
+# 从 MOBI 提取
+result = ISBNX().from_mobi("book.mobi")
+
+# 从压缩包提取（支持 ZIP/RAR/UVZ）
+result = ISBNX().from_archive("book.zip")
+
+# 或使用统一的自动分发入口
+result = ISBNX().extract("book.pdf")
+```
+
+---
+
+## 支持的文件格式
+
+| 类型 | 后缀 | 提取策略 |
+|------|------|----------|
+| **图片** | `.png` `.jpg` `.jpeg` | ONNX 检测 → OCR / 条码解码 |
+| **PDF** | `.pdf` | 书签定位 + 文本搜索（文本型）→ 渲染图片检测（扫描件） |
+| **EPUB** | `.epub` | OPF 元数据优先 → XHTML 内容扫描 |
+| **MOBI** | `.mobi` | EXTH 元数据优先 → 文本记录扫描 |
+| **压缩包** | `.zip` `.rar` `.uvz` | `meta.xml` → `bookinfo.dat` → `leg001.pdg` → 兜底 PDG 图片 |
+
+---
+
+## 核心流程
+
+```
+输入文件
+    │
+    ▼
+文件类型判断 ───→ 图片 ───→ ONNX YOLO 检测 ───→ OCR / 条码解码 ───→ ISBN 提取
+    │              PDF ───→ 类型判断（文本/扫描）─→ 文本搜索 / 渲染检测
+    │              EPUB ──→ OPF 元数据 / XHTML 扫描
+    │              MOBI ──→ EXTH 元数据 / 文本记录扫描
+    │              压缩包 ─→ meta.xml → bookinfo.dat → PDG 图片解码 → 检测
+    │
+    ▼
+ ExtractResult
+  ├── success: bool          # 是否提取成功
+  ├── bookinfo.isbn13        # ISBN-13
+  ├── bookinfo.isbn10        # ISBN-10
+  ├── bookinfo.ssid          # SS 号（压缩包特有）
+  ├── locate                 # 定位信息（页码、方法）
+  ├── ocr                    # OCR 原始识别文本
+  ├── meta                   # 文件元信息
+  └── elapsed                # 耗时（秒）
+```
+
+---
+
+## 配置
+
+### 严格等级
+
+通过 `strict` 参数控制提取结果的校验严格程度：
+
+| 等级 | 含义 | 适用场景 |
+|:----:|------|----------|
+| 1 | ISBN **和** SSID 都必须存在且有效 | 最高严格 |
+| 2 | ISBN 必须存在且校验通过 | 图片/PDF 检测 |
+| 3 | ISBN 有效 **或** SSID 存在（默认） | 压缩包提取 |
+
+### 自定义配置
+
+```python
+from isbnx import ISBNX
+from isbnx.config import Settings
+
+# 嵌套配置通过 dict 传参
+config = Settings(
+    strict=2,                           # 严格等级
+    ocr={"ocr_model": "medium"},        # OCR 精度（small / medium）
+    detector={"conf_threshold": 0.5},   # ONNX 检测阈值
+    pdf={"front_start": 1, "back_end": 3},
+)
+
+result = ISBNX(config=config).from_image("cover.png")
+```
+
+### 运行时调整
+
+```python
+from isbnx.config import configure
+
+configure(
+    strict=2,
+    ocr={"ocr_model": "medium"},
+    detector={"conf_threshold": 0.5},
+)
+```
+
+---
+
+## 输出模型
+
+所有提取结果使用 Pydantic 模型，可通过一致的接口访问：
+
+```python
+result = ISBNX().from_image("cover.png")
+
+# 基本状态
+result.success     # True / False
+result.error       # 失败原因（如有）
+
+# 书籍信息
+result.bookinfo.isbn       # 原始 ISBN
+result.bookinfo.isbn13     # ISBN-13 格式
+result.bookinfo.isbn10     # ISBN-10 格式
+result.bookinfo.isbn_valid # 校验是否合法
+result.bookinfo.ssid       # SS 号（压缩包）
+
+# 定位信息
+result.locate.page         # 命中页码
+result.locate.method       # 定位方式（onnx / text / bookmark / ...）
+result.locate.score        # 检测置信度
+
+# OCR 结果
+result.ocr.lines           # OCR 文本行
+result.ocr.text            # 全部文本（换行拼接）
+
+# 元信息
+result.meta.source         # 源文件路径
+result.meta.source_type    # 源文件类型
+
+# 耗时
+result.elapsed             # 处理耗时（秒）
+```
+
+---
+
+## 项目结构
+
+```
+isbnx/
+├── src/
+│   └── isbnx/
+│       ├── __init__.py        # 公开 API 入口
+│       ├── isbnx.py           # ISBNX 主类，统一提取接口
+│       ├── config.py          # Pydantic-Settings 配置管理
+│       ├── models.py          # Pydantic 数据模型
+│       ├── detector.py        # ONNX YOLO 检测器 + 检测/OCR 流水线
+│       ├── pdf.py             # PDF ISBN 提取
+│       ├── epub.py            # EPUB ISBN 提取
+│       ├── mobi.py            # MOBI ISBN 提取
+│       ├── archive.py         # 压缩包（PDG）ISBN 提取
+│       ├── pdf_type.py        # PDF 类型检测（文本/扫描）
+│       ├── model/             # ONNX 模型文件
+│       │   └── isbndetect_yolo.onnx
+│       ├── ocr/               # OCR 引擎
+│       │   ├── isbnx_pyzbar.py    # 条形码解码
+│       │   └── isbnx_rapiocr.py   # RapidOCR 文字识别
+│       ├── pdgview/           # PDG 图片解码器
+│       └── utils/             # 工具函数
+│           ├── cip_rules.py   # CIP 数据提取规则
+│           ├── io.py          # 文件 I/O 工具
+│           └── isbn_utils.py  # ISBN 提取与校验
+├── tests/                     # 测试用例
+├── docs/                      # MkDocs 文档
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## 开发
+
+### 环境要求
+
+- Python ≥ 3.10, 只在 python 3.13上进行测试开发的
+- [uv](https://docs.astral.sh/uv/) 包管理器
+
+### 本地开发
+
+```bash
+# 克隆项目
+git clone https://github.com/zscmmm/isbnx.git
+cd isbnx
+
+# 创建虚拟环境并安装依赖
+uv sync --group dev
+
+# 运行测试
+uv run pytest
+
+# 构建文档
+uv run mkdocs serve
+```
+
+---
+
+## 基准测试
+
+`isbnx` 与同类工具 `cipx` 的对比测试报告详见 [isbnx vs cipx 报告](https://isbnx.readthedocs.org/isbnx_vs_cipx_report/)。
+
+---
+
+## 路线图
+
+- [x] 图片 ISBN 提取
+- [x] PDF 提取（文本型 + 扫描件）
+- [x] EPUB 提取
+- [x] MOBI 提取
+- [x] 压缩包（PDG）提取
+- [x] ONNX YOLO 深度学习检测
+- [x] 条形码解码
+- [x] 文档网站（MkDocs）
+- [ ] LLM 解析 CIP 字段
+
+---
+
+## 许可证
+
+本项目基于 MIT 许可证开源 — 详见 [LICENSE](LICENSE) 文件。
+
+---
+
+## 相关项目
+
+- [mneia-isbn](https://pypi.org/project/mneia-isbn/) — ISBN 解析与校验库
+- [pyzbar](https://pypi.org/project/pyzbar/) -条形码解析库
+- [cipx](https://github.com/zscmmm/cipx) — CIP 信息提取工具

isbnx-0.0.1/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "isbnx"
+version = "0.0.1"
+description = "从 PDF、图片、压缩包和 EPUB 文件中提取 ISBN 号，支持 ONNX 检测和 OCR 识别"
+readme = "README.md"
+authors = [
+    { name = "zscmmm", email = "111739721+zscmmm@users.noreply.github.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "loguru>=0.7.3",
+    "mneia-isbn>=0.0.3",
+    "opencv-python>=4.13.0.92",
+    "pillow>=12.2.0",
+    "pydantic-settings>=2.14.2",
+    "pymupdf>=1.27.2.3",
+    "pyzbar>=0.1.9",
+    "rapidocr>=3.9.0",
+    "rarfile>=4.2",
+    "onnxruntime>=1.27.0",
+]
+
+[dependency-groups]
+dev = [
+    "pdf_inspector>=0.2.0",
+    "mkdocs>=1.6.1,<2.0",
+    "mkdocs-autorefs>=1.4.1,<2.0",
+    "mkdocs-material>=9.6.12,<10.0",
+    "mkdocstrings[python]>=0.29.1,<1.0",
+    "pytest>=8.3.5",
+]
+
+
+# [project.scripts]
+# isbnx = "isbnx:main"
+
+[build-system]
+requires = ["uv_build>=0.11.24,<0.12.0"]
+build-backend = "uv_build"
+
+[[tool.uv.index]]
+url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
+default = true
+
+
+
+[project.urls]
+Homepage = "https://github.com/zscmmm/isbnx"
+Documentation = "https://isbnx.readthedocs.org"
+Repository = "https://github.com/zscmmm/isbnx.git"
+Issues = "https://github.com/zscmmm/isbnx/issues"
+Changelog = "https://github.com/zscmmm/isbnx/blob/main/CHANGELOG.md"

isbnx-0.0.1/src/isbnx/__init__.py

@@ -0,0 +1,20 @@
+from isbnx.config import Settings, configure, settings
+from isbnx.isbnx import ISBNX, extract
+from isbnx.models import Detect, ExtractResult, Locate, Meta, OCRResult
+
+__all__ = [
+    "Settings",
+    "configure",
+    "settings",
+    "ISBNX",
+    "extract",
+    "Detect",
+    "Locate",
+    "Meta",
+    "OCRResult",
+    "ExtractResult",
+]
+
+
+def main() -> None:
+    print("Hello from isbnx!")