vivlio-starter-pdf 1.0.1

data/README.md

@@ -0,0 +1,120 @@
+# vivlio-starter-pdf
+
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%204.0-red.svg)](https://www.ruby-lang.org/)
+
+**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 としてインストール
+
+```zsh
+gem install vivlio-starter-pdf
+```
+
+インストール完了時に、OCR 機能を利用するために必要な外部ツールも案内されます。
+
+### 外部ツール（OCR 利用時）
+
+```zsh
+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 ベースの拡張パイプラインへ自動切り替えされます。
+
+```zsh
+vs pdf:read document.pdf
+```
+
+### Ruby API
+
+```ruby
+require "vivlio/starter/pdf"
+
+# PDF → Markdown 変換
+result = Vivlio::Starter::PDF::Reader.new("input.pdf",
+  ocr: { mode: "auto", languages: ["jpn"], dpi: 300 }
+).execute
+
+# アウトライン付与
+provider = Vivlio::Starter::Pdf::EnhancedProvider.new
+provider.add_outline!(pdf_path, items, max_level: 3)
+
+# 隠しノンブル
+provider.stamp_nombre!(pdf_path, bleed_pt: 8.5)
+```
+
+## 設定
+
+`config/book.yml` の `pdf_read` セクションで挙動を制御できます。
+
+```yaml
+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](https://hexapdf.gettalong.org/) | ~> 1.0 | PDF 解析・編集 |
+| [ruby-vips](https://github.com/libvips/ruby-vips) | ~> 2.2 | 高速画像処理 |
+
+### 外部ツール（任意）
+
+| ツール | 用途 |
+| --- | --- |
+| Tesseract | OCR エンジン |
+| poppler（pdftoppm） | PDF → 画像変換 |
+| libvips | 画像処理バックエンド |
+
+## 開発
+
+```zsh
+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)](LICENSE)
+
+vivlio-starter 本体（MIT）とは異なるライセンスです。HexaPDF の AGPL ライセンスに準拠しています。
+
+## 作者
+
+[Atelier Mirai](https://github.com/Atelier-Mirai)

data/RELEASE_NOTE.md

@@ -0,0 +1,133 @@
+# vivlio-starter-pdf 1.0.0 Release Note
+
+## 🎉 最初のメジャーリリース
+
+vivlio-starter-pdf 1.0.0 をリリースできることを大変嬉しく思います。これは **vivlio-starter** の AGPL 拡張プラグインで、HexaPDF を活用した高度な PDF 解析・後処理機能を提供します。
+
+## 🚀 主要機能
+
+### PDF → Markdown 変換
+- HexaPDF でテキスト・画像を高精度に抽出
+- 精密な座標解析による行・段落の再構成
+- Markdown 形式での構造化出力
+
+### OCR 連携と日本語対応 🆕
+- スキャン PDF を自動検出
+- Tesseract による日本語 OCR 実行
+- OCR テキストの空白圧縮と括弧正規化
+- prh 辞書による誤読修正
+
+### 画像抽出と位置合わせ
+- PDF 内の XObject を解析し、WebP 形式で書き出し
+- テキスト行と画像の精密な座標マッピング
+- イラスト領域の自動検出と除外
+
+### 出版向け機能
+- **隠しノンブル**: 入稿用 PDF の塗り足し領域にページ番号をオーバーレイ
+- **PDF アウトライン**: HTML 見出しを解析し、PDF のブックマークツリーを構築
+
+## 📦 インストール
+
+```ruby
+# Gemfile
+gem 'vivlio-starter-pdf', '~> 1.0.0'
+```
+
+```bash
+bundle install
+```
+
+### 外部ツール（OCR 利用時）
+
+```bash
+brew install tesseract tesseract-lang poppler vips
+```
+
+## 💡 使用例
+
+### vivlio-starter との連携（プラグイン専用）
+
+```bash
+# Enhanced Mode で自動的に HexaPDF/OCR パイプラインを使用
+vs pdf:read document.pdf
+```
+
+### Ruby API
+
+```ruby
+require "vivlio/starter/pdf"
+
+# PDF → Markdown 変換
+result = Vivlio::Starter::PDF::Reader.new("input.pdf",
+  ocr: { mode: "auto", languages: ["jpn"], dpi: 300 }
+).execute
+
+# アウトライン付与
+provider = Vivlio::Starter::Pdf::EnhancedProvider.new
+provider.add_outline!(pdf_path, items, max_level: 3)
+
+# 隠しノンブル
+provider.stamp_nombre!(pdf_path, bleed_pt: 8.5)
+```
+
+## 🔧 設定
+
+`config/book.yml` の `pdf_read` セクションで挙動を制御：
+
+```yaml
+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
+```
+
+## ✅ テスト品質
+
+- **網羅的なテストスイート**
+- **実環境での動作検証**
+- **外部ツール連携のテスト**
+
+## 🔄 0.1.0 からの変更点
+
+### 新機能
+- 完全な OCR 連携と日本語対応
+- 画像位置合わせの精密化
+- PDF アウトライン生成機能
+- 隠しノンブル機能
+
+### 改善
+- gemspec の RubyGems 公開設定
+- ドキュメントの整備
+- 外部ツールの自動案内
+
+## 🎯 実績
+
+- **vivlio-starter** Enhanced Mode で実稼働
+- **日本語出版** 向けの最適化完了
+- **HexaPDF** との高度な連携実現
+- **AGPL-3.0** ライセンス準拠
+
+## 📋 互換性
+
+- **Ruby**: 4.0+
+- **依存**: hexapdf (~> 1.0), ruby-vips (~> 2.2)
+- **外部ツール**: Tesseract, poppler, libvips（OCR 使用時）
+- **セマンティックバージョニング**: 1.x.x 系は後方互換性を保証
+
+## 🙏 感謝
+
+vivlio-starter-pdf の開発にあたり、HexaPDF の強力な PDF 処理能力と、日本語出版の現場でのニーズが大きな助けとなりました。特に OCR 連携と日本語テキスト処理についての知見は、本プラグインをより実用的なものにする上で不可欠でした。
+
+---
+
+**vivlio-starter-pdf 1.0.0**: 高度な PDF 処理のための強力な拡張プラグイン

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/exe/vivlio-starter-pdf

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'vivlio/starter/pdf'
+
+# vivlio-starter-pdf CLI
+# Provides basic version information for debugging and user confirmation
+
+module Vivlio
+  module Starter
+    module PDF
+      class CLI
+        def self.run(args = [])
+          case args[0]
+          when '--version', '-v'
+            puts "vivlio-starter-pdf #{VERSION}"
+          when '--help', '-h', nil
+            puts <<~HELP
+              vivlio-starter-pdf #{VERSION} - Advanced PDF processor for vivlio-starter
+              
+              Usage:
+                vivlio-starter-pdf [options]
+              
+              Options:
+                --version, -v  Print version and exit
+                --help, -h     Print this help and exit
+              
+              Description:
+                vivlio-starter-pdf is an AGPL-licensed plugin for vivlio-starter
+                that provides advanced PDF processing capabilities including:
+                - PDF to Markdown conversion using HexaPDF
+                - Japanese OCR support with Tesseract
+                - Image extraction and precise positioning
+                - PDF outline generation and hidden pagination
+              
+              This is a plugin and should be used through vivlio-starter:
+                vs pdf:read document.pdf
+              
+              For more information, visit: https://github.com/Atelier-Mirai/vivlio-starter-pdf
+            HELP
+          else
+            puts "Error: Unknown option '#{args[0]}'"
+            puts "Use 'vivlio-starter-pdf --help' for usage information."
+            exit 1
+          end
+        end
+      end
+    end
+  end
+end
+
+Vivlio::Starter::PDF::CLI.run(ARGV)

data/lib/vivlio/starter/cli/pdf/enhanced_provider.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "hexapdf"
+require_relative "utilities"
+require_relative "log_helper"
+require_relative "outline_writer"
+
+module Vivlio
+  module Starter
+    module Pdf
+      # vivlio-starter 本体から呼び出される HexaPDF ベースのプロバイダ
+      #
+      # 隠しノンブル書き込み・PDF アウトライン付与など、
+      # Enhanced Mode 固有の PDF 操作を提供する。
+      class EnhancedProvider
+        # 隠しノンブルに使用するフォント名
+        FONT_NAME = "Helvetica"
+        # 隠しノンブルのフォントサイズ（pt）
+        FONT_SIZE_PT = 6
+
+        # PDF のページ数を取得する
+        def page_count(pdf_path)
+          Utilities.page_count(pdf_path)
+        end
+
+        # 空白ページ PDF が存在しなければ生成する
+        def ensure_blank_page_pdf(path, width_pt, height_pt)
+          Utilities.ensure_blank_page_pdf(path, width_pt, height_pt)
+        end
+
+        # PDF の各ページに隠しノンブル（ページ番号）を書き込む
+        # 奇数ページは左端、偶数ページは右端に 90° 回転して配置する
+        # @param pdf_path [String] 対象 PDF のパス
+        # @param bleed_pt [Float] 塗り足し幅（pt）
+        # @return [Boolean] 成功なら true
+        def stamp_nombre!(pdf_path, bleed_pt:)
+          return false unless File.exist?(pdf_path)
+
+          document = HexaPDF::Document.open(pdf_path)
+          total = document.pages.count
+          return false if total.zero?
+
+          LogHelper.log_action("[NombreStamper] 隠しノンブルを書き込みます（#{total} ページ）[Enhanced Mode]…")
+
+          document.pages.each_with_index do |page, idx|
+            stamp_page(page, idx + 1, bleed_pt: bleed_pt.to_f)
+          end
+
+          document.write(pdf_path, optimize: true)
+          LogHelper.log_success("[NombreStamper] 隠しノンブル書き込み完了（#{total} ページ）")
+          true
+        rescue StandardError => e
+          LogHelper.log_error("[NombreStamper] 隠しノンブル書き込みに失敗: #{e.message}")
+          false
+        end
+
+        # PDF にアウトライン（しおり）を付与する
+        # OutlineWriter を使い、階層構造を HexaPDF のアウトラインツリーに変換する
+        # @param pdf_path [String] 対象 PDF のパス
+        # @param items [Array<Hash>] アウトライン項目（:level, :text, :page）
+        # @param max_level [Integer] アウトラインの最大階層深度
+        # @return [Boolean] 成功なら true
+        def add_outline!(pdf_path, items, max_level:)
+          return false unless File.exist?(pdf_path)
+
+          document = HexaPDF::Document.open(pdf_path)
+          writer = OutlineWriter.new(document, max_level:, on_skip: method(:log_outline_skip))
+          inserted = writer.write(items)
+          if inserted.zero?
+            LogHelper.log_warn("[OutlineWriter] 有効なアウトライン項目が存在しないためスキップしました")
+            return false
+          end
+
+          document.write(pdf_path, optimize: true)
+          LogHelper.log_success("[OutlineWriter] PDF にアウトラインを #{inserted} 件追加しました")
+          true
+        rescue StandardError => e
+          LogHelper.log_error("[OutlineWriter] PDF アウトライン付与に失敗: #{e.message}")
+          false
+        end
+
+        private
+
+        # 1 ページに隠しノンブルを描画する
+        # 奇数ページは左端 90°、偶数ページは右端 -90° に回転配置する
+        def stamp_page(page, page_number, bleed_pt:)
+          canvas = page.canvas(type: :overlay)
+          box = page.box(:media)
+
+          canvas.font(FONT_NAME, size: FONT_SIZE_PT)
+          canvas.fill_color(0)
+
+          x_offset = bleed_pt / 2.0
+          y_center = box.height / 2.0
+
+          if page_number.odd?
+            draw_rotated_text(canvas, page_number.to_s, x: x_offset, y: y_center, angle: 90)
+          else
+            draw_rotated_text(canvas, page_number.to_s, x: box.width - x_offset, y: y_center, angle: -90)
+          end
+        end
+
+        # キャンバス上の指定座標にテキストを回転描画する
+        def draw_rotated_text(canvas, text, x:, y:, angle:)
+          canvas
+            .save_graphics_state
+            .translate(x, y)
+            .rotate(angle)
+            .text(text, at: [0, 0])
+            .restore_graphics_state
+        end
+
+        # OutlineWriter のスキップ通知をログに出力するコールバック
+        def log_outline_skip(message)
+          LogHelper.log_warn("[OutlineWriter] #{message}")
+        end
+      end
+    end
+  end
+end

data/lib/vivlio/starter/cli/pdf/log_helper.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Vivlio
+  module Starter
+    module Pdf
+      # Logging helper that integrates with vivlio-starter CLI when available
+      module LogHelper
+        module_function
+
+        def log_action(message)
+          dispatch(:log_action, message) { puts(message) }
+        end
+
+        def log_info(message)
+          dispatch(:log_info, message) { puts(message) }
+        end
+
+        def log_success(message)
+          dispatch(:log_success, message) { puts(message) }
+        end
+
+        def log_warn(message)
+          dispatch(:log_warn, message) { warn(message) }
+        end
+
+        def log_error(message)
+          dispatch(:log_error, message) { warn(message) }
+        end
+
+        def dispatch(method, message)
+          if defined?(Vivlio::Starter::CLI::Common)
+            Vivlio::Starter::CLI::Common.public_send(method, message)
+          else
+            yield if block_given?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vivlio/starter/cli/pdf/outline_writer.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "hexapdf"
+
+module Vivlio
+  module Starter
+    module Pdf
+      # Internal helper responsible for translating outline entries into HexaPDF structures.
+      class OutlineWriter
+        # @param doc [HexaPDF::Document] target document
+        # @param max_level [Integer] maximum depth allowed in the outline tree
+        # @param on_skip [Proc,nil] callback triggered when an entry is ignored
+        def initialize(doc, max_level:, on_skip: nil)
+          @doc = doc
+          @max_level = max_level.to_i.clamp(1, 6)
+          @page_count = @doc.pages.count
+          @on_skip = on_skip
+        end
+
+        # Writes the given +items+ into the document outline.
+        # @param items [Array<Hash>] entries with :level, :text, :page
+        # @return [Integer] number of inserted outline nodes
+        def write(items)
+          return 0 if @page_count.zero?
+
+          normalized = Array(items).filter_map { normalize_entry(it) }
+          return 0 if normalized.empty?
+
+          outline_root = rebuild_outline_root
+          stack = [{ level: 0, node: outline_root }]
+          inserted = 0
+
+          normalized.each do |entry|
+            parent = parent_for(entry[:level], stack)
+            destination = resolve_destination(entry[:page])
+            unless destination
+              warn_skip("page #{entry[:page]} is outside 1-#{@page_count}")
+              next
+            end
+
+            item = parent.add_item(entry[:text], destination:, open: entry[:level] < @max_level)
+            stack << { level: entry[:level], node: item }
+            inserted += 1
+          end
+
+          if inserted.zero?
+            @doc.catalog.delete(:Outlines)
+            return 0
+          end
+
+          inserted
+        end
+
+        private
+
+        # Normalizes a raw hash into a consistent entry structure.
+        def normalize_entry(raw)
+          text = fetch(raw, :text, fetch(raw, :title, nil)).to_s.strip
+          warn_skip("missing title for outline entry: #{raw.inspect}") if text.empty?
+          return nil if text.empty?
+
+          page = fetch(raw, :page, nil).to_i
+          if page <= 0
+            warn_skip("invalid page for outline entry: #{raw.inspect}")
+            return nil
+          end
+
+          level = fetch(raw, :level, 1).to_i
+          level = 1 if level < 1
+          level = @max_level if level > @max_level
+
+          { text:, page:, level: }
+        end
+
+        # Fetches a value from the entry by symbol or string key.
+        def fetch(raw, key, fallback)
+          if raw.respond_to?(:[]) && (raw[key] || raw[key.to_s])
+            raw[key] || raw[key.to_s]
+          else
+            fallback
+          end
+        end
+
+        # Returns the proper parent node for the requested level.
+        def parent_for(level, stack)
+          while stack.last[:level] >= level
+            break if stack.size == 1
+            stack.pop
+          end
+          stack.last[:node]
+        end
+
+        # Resolves the destination page for an entry.
+        def resolve_destination(page_number)
+          index = page_number.to_i - 1
+          return nil unless index.between?(0, @page_count - 1)
+
+          @doc.pages[index]
+        rescue StandardError
+          nil
+        end
+
+        # Recreates an empty outline root before inserting new nodes.
+        def rebuild_outline_root
+          @doc.catalog.delete(:Outlines)
+          outline_root = @doc.add({ Type: :Outlines }, type: :Outlines)
+          @doc.catalog[:Outlines] = outline_root
+          outline_root
+        end
+
+        # Emits skip notifications through the provided callback.
+        def warn_skip(message)
+          @on_skip&.call(message)
+        end
+      end
+    end
+  end
+end

data/lib/vivlio/starter/cli/pdf/utilities.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "hexapdf"
+
+module Vivlio
+  module Starter
+    module Pdf
+      # HexaPDF を使った PDF 共通ユーティリティ
+      module Utilities
+        module_function
+
+        # PDF のページ数を取得する
+        # @param file [String]
+        # @return [Integer, nil]
+        def page_count(file)
+          return nil unless File.exist?(file)
+
+          if system("which pdfinfo >/dev/null 2>&1")
+            info = `pdfinfo "#{file}" 2>/dev/null`
+            pages = info[/^Pages:\s+(\d+)/i, 1]
+            return pages.to_i if pages
+          end
+
+          doc = HexaPDF::Document.open(file)
+          doc.pages.count
+        rescue StandardError
+          nil
+        end
+
+        # 空白ページ PDF を生成する
+        # @param path [String]
+        # @param width_pt [Float]
+        # @param height_pt [Float]
+        def ensure_blank_page_pdf(path, width_pt, height_pt)
+          return path if File.exist?(path)
+
+          doc = HexaPDF::Document.new
+          doc.pages.add([0, 0, width_pt, height_pt])
+          doc.write(path, optimize: true)
+          path
+        end
+      end
+    end
+  end
+end