superbook-pdf

Fork of dnobori/DN_SuperBook_PDF_Converter

フォーク元の素晴らしき芸術的なREADME.md : 正直、これを読めばすべてがわかる

Rust で完全リライトしたスキャン書籍 PDF 高品質化ツール

オリジナル著者: 登 大遊 (Daiyuu Nobori) 様 Rust リライト: clearclown ライセンス: AGPL v3.0

---

Before / After

	Before (左)	After (右)
解像度	1242×2048 px	2363×3508 px
ファイルサイズ	981 KB	1.6 MB
品質	ぼやけ、低コントラスト	鮮明、高コントラスト

RealESRGAN による AI 超解像で、文字のエッジが鮮明になり、読みやすさが大幅に向上します。

---

特徴

• Rust 実装 - C# 版を完全リライト。メモリ効率が大幅に改善されています
• AI 超解像 - RealESRGAN で画像を高解像度化
• 日本語 OCR - YomiToku による文字認識
• 傾き補正 - 大津二値化 + Hough 変換で自動補正
• Web UI - ブラウザから直感的に操作できます

---

Web UI

ブラウザベースのインターフェースで、コマンドラインに慣れていない方でも簡単に使えます。ファイルをドラッグ&ドロップするだけで変換が始まります。

---

インストール

必要なもの

項目	要件
OS	Linux / macOS / Windows
Rust	1.78 以上 (ソースビルド時)
Poppler	pdftoppm コマンド

AI機能を使う場合は、Python 3.10以上と NVIDIA GPU (CUDA 11.8+) が必要です。

Note: 開発とテストは主に Linux で行っていますが、Rust で書かれているため macOS や Windows でも動作します。

1. システム依存パッケージ

# Ubuntu/Debian
sudo apt update
sudo apt install -y poppler-utils python3 python3-venv

# Fedora
sudo dnf install -y poppler-utils python3

# macOS (Homebrew)
brew install poppler python

# Windows (Chocolatey)
choco install poppler python

2. superbook-pdf のインストール

一番簡単な方法は crates.io からインストールすることです:

cargo install superbook-pdf --features web

これで superbook-pdf コマンドが使えるようになります。

ソースからビルドしたい場合:

git clone https://github.com/clearclown/DN_SuperBook_PDF_Converter_Linux.git
cd DN_SuperBook_PDF_Converter_Linux/superbook-pdf
cargo build --release --features web

3. AI機能のセットアップ (ネイティブ実行時)

Note: Docker/Podman を使う場合はこの手順は不要です。コンテナにはAI機能がプリインストールされています。

AI超解像 (RealESRGAN) と OCR (YomiToku) を使いたい場合は、Python環境をセットアップします:

cd ai_bridge

# Python 仮想環境を作成
python3 -m venv .venv
source .venv/bin/activate

# GPU版 PyTorch をインストール
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# AI依存パッケージをインストール
pip install -r requirements.txt

重要: 実行時に SUPERBOOK_VENV 環境変数を設定してください:

# 一時的に設定
export SUPERBOOK_VENV=/path/to/ai_bridge/.venv

# または .bashrc に追加
echo 'export SUPERBOOK_VENV=/path/to/ai_bridge/.venv' >> ~/.bashrc

この環境変数が設定されていないと、AI機能 (超解像・OCR) は動作しません。

4. Docker/Podman で実行 (推奨)

環境構築が面倒な場合は、コンテナを使うのが一番簡単です。GPU・AI機能がすべてセットアップ済みです。

ワンライナーでPDF変換:

# まずイメージをビルド
docker build -t superbook-pdf superbook-pdf/

# Docker (GPU使用)
docker run --rm --gpus all \
  -v $(pwd)/input:/data/input:ro \
  -v $(pwd)/output:/data/output:rw \
  superbook-pdf:latest \
  convert /data/input/book.pdf -o /data/output/ --advanced --ocr

# Podman (GPU使用)
podman build -t superbook-pdf superbook-pdf/
podman run --rm --device nvidia.com/gpu=all \
  -v $(pwd)/input:/data/input:ro \
  -v $(pwd)/output:/data/output:rw \
  superbook-pdf:latest \
  convert /data/input/book.pdf -o /data/output/ --advanced --ocr

Web UI を起動:

プロジェクトルートから1コマンドで起動できます。

# NVIDIA GPU環境 (デフォルト)
docker compose up -d

# AMD GPU環境 (ROCm)
docker compose -f docker-compose.yml -f docker-compose.rocm.yml up -d

# CPUのみ
docker compose -f docker-compose.yml -f docker-compose.cpu.yml up -d

# Podman (NVIDIA GPU)
podman compose up -d

# Podman (AMD GPU)
podman compose -f docker-compose.yml -f docker-compose.rocm.yml up -d

# Podman (CPUのみ)
podman compose -f docker-compose.yml -f docker-compose.cpu.yml up -d

# ログ確認
docker compose logs -f

# 停止
docker compose down

ブラウザで http://localhost:8080 を開けば使えます。

ローカルでイメージをビルド:

# Docker (NVIDIA)
docker compose build

# Docker (AMD ROCm)
docker compose -f docker-compose.yml -f docker-compose.rocm.yml build

# Podman
podman compose build

# 単体ビルド (CLI用)
cd superbook-pdf
docker build -t superbook-pdf .

Note: NVIDIA GPU、AMD GPU (ROCm)、CPUのみの3環境に対応しています。

---

コマンドの使い方

基本的な使い方

# シンプルな変換
superbook-pdf convert input.pdf -o output/

# 高品質変換 (AI超解像 + カラー補正 + オフセット調整)
superbook-pdf convert input.pdf -o output/ --advanced

# OCR付き高品質変換
superbook-pdf convert input.pdf -o output/ --advanced --ocr

# GPUを使わない場合
superbook-pdf convert input.pdf -o output/ --no-gpu

Web UI を起動する

superbook-pdf serve --port 8080

ブラウザで http://localhost:8080 を開いてください。

コマンド一覧

superbook-pdf <COMMAND>

Commands:
  convert     PDFを変換する
  serve       Web UIを起動する
  reprocess   失敗したページを再処理する
  info        システム情報を表示する
  cache-info  キャッシュ情報を表示する

convert コマンドのオプション

よく使うオプションをまとめました:

オプション	説明
-o, --output <DIR>	出力先ディレクトリ (デフォルト: ./output)
--advanced	高品質処理を有効化 (おすすめ)
--ocr	日本語OCRを有効化
--no-gpu	GPUを使わない
--no-upscale	AI超解像をスキップ
--no-deskew	傾き補正をスキップ
--dpi <N>	出力DPI (デフォルト: 300)
--max-pages <N>	処理するページ数を制限 (テスト用)
-v, -vv, -vvv	ログの詳細度を上げる
--dry-run	実際には処理せず、実行計画を表示

全オプションは superbook-pdf convert --help で確認できます。

serve コマンドのオプション

オプション	説明
-p, --port <PORT>	ポート番号 (デフォルト: 8080)
-b, --bind <ADDR>	バインドアドレス (デフォルト: 127.0.0.1)
--upload-limit <MB>	アップロード上限 (デフォルト: 500MB)

---

処理パイプライン

1. PDF画像抽出 - pdftoppm で 300 DPI 抽出
2. マージントリム - 0.5% の余白を除去
3. AI超解像 - RealESRGAN で 2x アップスケール
4. 傾き補正 - 大津二値化 + Hough変換
5. カラー補正 - 紙色の白化 (--advanced)
6. PDF生成 - メタデータ同期
7. OCR - YomiToku (--ocr)

---

トラブルシューティング

問題	解決策
pdftoppm: command not found	sudo apt install poppler-utils
RealESRGAN が動かない	SUPERBOOK_VENV 環境変数を設定してください
GPU が使用されない	PyTorchのCUDA版をインストール: pip install torch --index-url https://download.pytorch.org/whl/cu121
メモリ不足	--max-pages 10 で分割処理するか、--chunk-size 5 でチャンク処理

---

ライセンス

AGPL v3.0 - LICENSE

---

謝辞

• 登 大遊 (Daiyuu Nobori) 様 - オリジナル実装
• RealESRGAN - AI超解像
• YomiToku - 日本語OCR

---

開発について

このプロジェクトの開発には、AIエージェントツールを活用しています:

• claude-code-aida - Claude Code用AIDAプラグイン
• AIDA - マルチエージェント開発フレームワーク (現在メンテナンス中)

これらのツールにより、TDD (テスト駆動開発) に基づいた品質の高いコード生成と、効率的な開発サイクルを実現しています。