vivlio-starter-pdf

License: AGPL-3.0 Ruby

vivlio-starter の AGPL 拡張プラグイン。HexaPDF を活用した高度な PDF 解析・後処理機能を提供します。

概要

vivlio-starter 本体（MIT）が提供する Standard Mode を拡張し、以下の出版向け機能を追加します。

機能 説明
PDF → Markdown 変換 HexaPDF でテキスト・画像を高精度に抽出し、Markdown に変換
画像抽出（WebP 化） PDF 内の XObject を解析し、WebP 形式で書き出し
OCR 連携 スキャン PDF を自動検出し、Tesseract で日本語 OCR を実行
OCR テキスト補正 日本語空白圧縮、括弧正規化、prh 辞書による誤読修正
隠しノンブル 入稿用 PDF の塗り足し領域にページ番号をオーバーレイ
PDF アウトライン HTML 見出しを解析し、PDF のブックマークツリーを構築

インストール

gem としてインストール

gem install vivlio-starter-pdf

インストール完了時に、OCR 機能を利用するために必要な外部ツールも案内されます。

外部ツール（OCR 利用時）

brew install tesseract tesseract-lang poppler vips

vs pdf:read を Standard Mode で実行した際にも、Enhanced Mode へ切り替えるためのインストール手順が自動案内されます。

使い方

vivlio-starter との連携（プラグイン専用）

vivlio-starter-pdf は vivlio-starter の Enhanced Mode プラグインとしてのみ動作します。gem をインストールすると、vs pdf:read 実行時に HexaPDF / OCR ベースの拡張パイプラインへ自動切り替えされます。

vs pdf:read document.pdf

標準（MIT）実装に戻して動作を比べたいときは、環境変数で無効化できます。

VIVLIO_PDF_PLUGIN=disable vs build

Ruby API

require "vivlio_starter/pdf"

# PDF → Markdown 変換
result = VivlioStarter::Pdf::Reader.new("input.pdf",
  ocr: { mode: "auto", languages: ["jpn"], dpi: 300 }
).execute

# アウトライン付与
provider = VivlioStarter::Pdf::EnhancedProvider.new
provider.add_outline!(pdf_path, items, max_level: 3)

# 隠しノンブル
provider.stamp_nombre!(pdf_path, bleed_pt: 8.5)

stamp_nombre! / add_outline! は成功で true、失敗で false を返し、page_count は失敗で nil を返します。例外は外へ出しません（本体のビルドパイプラインの途中から呼ばれるため）。失敗しても入力 PDF は書き換えません。

add_outline! の items は { level:, text:, page: } の配列です。壊れた項目（不正な UTF-8 のタイトル・範囲外ページ・空タイトル）は 1 件ずつ飛ばして残りを書き込み、飛ばした理由をログに出します。

設定

config/book.yml の pdf_read セクションで挙動を制御できます。

pdf_read:
  text_area:
    top_margin: 18
    bottom_margin: 20
    inner_margin: 15
    outer_margin: 12
  page_separator: false
  ocr:
    mode: auto
    languages:
      - japanese
    dpi: 300
    psm: 3
    inline_image_text: include

依存ライブラリ

ライブラリ バージョン 用途
HexaPDF ~> 1.0 PDF 解析・編集
ruby-vips ~> 2.2 高速画像処理

外部ツール（任意）

ツール 用途
Tesseract OCR エンジン
poppler（pdftoppm） PDF → 画像変換
libvips 画像処理バックエンド

開発

git clone https://github.com/Atelier-Mirai/vivlio-starter-pdf.git
cd vivlio-starter-pdf
bundle install
bundle exec rake test

ライセンス

GNU Affero General Public License v3.0 (AGPL-3.0)

vivlio-starter 本体（MIT）とは異なるライセンスです。HexaPDF の AGPL ライセンスに準拠しています。

作者

Atelier Mirai