img2ppt 1.3.4__tar.gz

img2ppt-1.3.4/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: img2ppt
+Version: 1.3.4
+Summary: スライド画像/PDF から PowerPoint を自動生成するパイプライン (Windows 専用)
+License-Expression: MIT
+Keywords: powerpoint,ocr,pptx,slide,image
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics :: Presentation
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow>=10.4.0
+Requires-Dist: opencv-python>=4.11.0
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: winrt-Windows.Media.Ocr>=3.2.1
+Requires-Dist: python-pptx>=1.0.0
+Requires-Dist: pypdfium2>=0.28.0
+Requires-Dist: janome>=0.5.0
+
+# img2ppt
+
+スライド画像（JPG/PNG）または PDF を PowerPoint（.pptx）に自動変換するツールです。  
+テキスト・図形・背景を自動認識し、16:9 スライドとして再構成します。
+
+> **動作環境**: Windows 11 専用 / Python 3.12 以上
+
+---
+
+## インストール
+
+```cmd
+pip install .
+```
+
+これだけで全依存ライブラリ（OpenCV / Pillow / python-pptx / pypdfium2 / janome 等）が一括インストールされます。
+
+### インストール確認
+
+```cmd
+img2ppt --help
+```
+
+---
+
+## 使い方
+
+### 基本
+
+```cmd
+:: 画像ファイルを変換
+img2ppt スライド.jpg -d 出力フォルダ
+
+:: クリップボードの画像を変換（引数なし）
+img2ppt -d 出力フォルダ
+
+:: PDF を変換（全ページ → 1 ファイルの PPTX）
+img2ppt 資料.pdf -d 出力フォルダ
+```
+
+### 入力モード
+
+| モード | 方法 | 説明 |
+| --- | --- | --- |
+| ファイル指定 | `img2ppt <ファイルパス>` | JPG / PNG / PDF を直接指定 |
+| クリップボード | `img2ppt`（引数なし） | 画像をコピーしてからそのまま実行 |
+| PDF | 拡張子 `.pdf` のファイルを指定 | 全ページを 1 つの PPTX にまとめる |
+
+---
+
+## 出力ファイル
+
+`-d` で指定したディレクトリに以下が出力されます。
+
+| ファイル | 説明 |
+| --- | --- |
+| `{stem}.pptx` | **最終 PowerPoint** |
+| `{stem}.json` | 認識結果の構造化 JSON |
+| `{stem}_04_inpainted.png` | テキスト除去後の画像 |
+| `{stem}_05_1_segment_filled.png` | セグメント検出結果（シルエット） |
+| `{stem}_05_2_mask_segment.png` | セグメントマスク画像 |
+| `{stem}_06_1_content_inpainted.png` | コンテンツ除去後の画像 |
+| `{stem}_06_2_mask_colorize.png` | カラー分割マスク |
+| `{stem}_06_3_colorized.png` | カラー分割結果 |
+
+デバッグ用の可視化画像（`vis_` プレフィックス）は `--debug` を付けると追加出力されます。
+
+---
+
+## オプション一覧
+
+### 基本オプション
+
+| オプション | デフォルト | 説明 |
+| --- | --- | --- |
+| `-d`, `--output-dir` | `test/` | 出力ディレクトリ |
+| `-o`, `--output-json` | 自動 | 最終 JSON の出力パス（単一ページ時のみ有効） |
+| `-v`, `--verbose` | オフ | 詳細ログを表示（省略時はプログレスバーのみ） |
+| `--debug` | オフ | デバッグ用可視化画像（`vis_xxx`）を出力 |
+| `--keep-tmp` | オフ | 処理後も一時ディレクトリを削除しない |
+| `--tmp-dir` | システム一時領域 | 一時ディレクトリの作成場所を指定 |
+| `--pdf-dpi` | `150` | PDF ページ変換の解像度（DPI） |
+
+### 出力パス個別指定
+
+| オプション | 説明 |
+| --- | --- |
+| `--output-inpaint` | Step4 テキスト除去画像の出力パス |
+| `--output-seg-filled` | Step5 シルエット画像の出力パス |
+| `--output-mask-seg` | Step5 マスク画像の出力パス |
+
+### 画像鮮明化（Step1）
+
+低解像度・圧縮ノイズが多い画像の OCR 精度を上げるための前処理です。  
+PNG または長辺 1280px 以上の JPG は自動スキップされます。
+
+| オプション | デフォルト | 説明 |
+| --- | --- | --- |
+| `--denoise-h` | `10` | ノイズ除去強度（大きいほど強く除去、ぼけやすい） |
+| `--bilateral-d` | `9` | エッジ保持フィルタの近傍径 |
+| `--sigma-color` | `60.0` | エッジ保持フィルタの色シグマ |
+| `--sigma-space` | `60.0` | エッジ保持フィルタの空間シグマ |
+| `--unsharp-radius` | `2` | 輪郭強調の半径（px） |
+| `--unsharp-percent` | `200` | 輪郭強調の強度（%） |
+| `--unsharp-threshold` | `2` | 輪郭強調の閾値 |
+
+### テキスト除去（Step4）
+
+| オプション | デフォルト | 説明 |
+| --- | --- | --- |
+| `--sample-offset` | `3` | 背景色サンプリング位置（bbox 端から何 px 外側か） |
+| `--fill-expand` | `2` | テキスト除去の塗り範囲拡張量（px） |
+
+### セグメント検出（Step5）
+
+| オプション | デフォルト | 説明 |
+| --- | --- | --- |
+| `--sat-max` | `40` | 背景とみなす最大彩度（HSV-S、0〜255） |
+| `--val-min` | `200` | 背景とみなす最小輝度（HSV-V、0〜255） |
+
+### OCR 品質フィルタ（Step2.5）
+
+| オプション | デフォルト | 説明 |
+| --- | --- | --- |
+| `--ocr-min-height` | `8` | bbox 最小高さ（px）。これ未満は除外 |
+| `--ocr-threshold` | `0.45` | 総合スコア閾値。これ未満のテキストを除外 |
+
+### PowerPoint 生成（Step7）
+
+| オプション | デフォルト | 説明 |
+| --- | --- | --- |
+| `--bg-tolerance` | `20` | 図形の背景透過許容幅（RGB 各チャンネル ±n） |
+
+---
+
+## 実行例
+
+```cmd
+:: 高解像度 PDF を変換
+img2ppt 資料.pdf -d C:\output --pdf-dpi 200
+
+:: デバッグ: 全中間ファイルを残して詳細ログを表示
+img2ppt スライド.jpg -d C:\output --debug --keep-tmp --verbose
+
+:: クリップボード画像を変換してデスクトップに保存
+img2ppt -d %USERPROFILE%\Desktop
+
+:: OCR フィルタを緩めて誤除外を減らす
+img2ppt スライド.jpg -d C:\output --ocr-threshold 0.35
+```
+
+---
+
+## うまくいかないときは
+
+| 症状 | 試すこと |
+| --- | --- |
+| テキストが認識されない | `--ocr-threshold` を下げる（例: `0.35`） |
+| 誤認識テキストが残る | `--ocr-threshold` を上げる（例: `0.55`） |
+| 背景色で塗りつぶしがうまくいかない | `--sample-offset` や `--fill-expand` を調整する |
+| 図形の背景が透過しすぎる / されない | `--bg-tolerance` を調整する（大きくすると透過が広がる） |
+| 低彩度アイコンが検出されない | `--sat-max` を上げる（例: `50`） |
+| 処理の途中経過を確認したい | `--debug --keep-tmp --verbose` を付けて実行する |
+
+---
+
+## パイプライン概要
+
+| ステップ | モジュール | 処理内容 |
+| --- | --- | --- |
+| Step1 | `clarify.py` | 画像鮮明化（ノイズ除去・輪郭強調） |
+| Step2 | `ocr.py` | Windows.Media.Ocr でテキスト検出・認識 |
+| Step2.5 | `ocr_filter.py` | geometric / unicode / bigram / morph スコアで文字化けを除外 |
+| Step3 | `split.py` | OCR bbox 後処理・複数テキスト混入 bbox を分割 |
+| Step4 | `inpaint.py` | テキスト領域を背景色で除去・修復 |
+| Step5 | `segment.py` | HSV 2値化 + 連結成分ラベリングでオブジェクト検出 |
+| Step6 | `colorize.py` | container を投影プロファイル法で矩形分割・内包正規化 |
+| Step7 | `pptx_gen.py` | JSON + 中間画像から PowerPoint スライドを生成 |
+
+---
+
+## 依存ライブラリ
+
+| ライブラリ | ライセンス | 用途 |
+| --- | --- | --- |
+| `winrt-Windows.Media.Ocr` | MIT | テキスト検出・認識（Windows 標準 OCR） |
+| `opencv-python` | Apache 2.0 | 画像処理 |
+| `Pillow` | HPND（MIT互換） | 画像入出力 |
+| `numpy` | BSD | 配列処理 |
+| `python-pptx` | MIT | PowerPoint ファイル生成 |
+| `pypdfium2` | Apache 2.0 | PDF → 画像変換 |
+| `janome` | MIT | 形態素解析（OCR 品質フィルタ） |
+
+---
+
+## ライセンス
+
+MIT License

img2ppt-1.3.4/README.md

@@ -0,0 +1,198 @@
+# img2ppt
+
+スライド画像（JPG/PNG）または PDF を PowerPoint（.pptx）に自動変換するツールです。  
+テキスト・図形・背景を自動認識し、16:9 スライドとして再構成します。
+
+> **動作環境**: Windows 11 専用 / Python 3.12 以上
+
+---
+
+## インストール
+
+```cmd
+pip install .
+```
+
+これだけで全依存ライブラリ（OpenCV / Pillow / python-pptx / pypdfium2 / janome 等）が一括インストールされます。
+
+### インストール確認
+
+```cmd
+img2ppt --help
+```
+
+---
+
+## 使い方
+
+### 基本
+
+```cmd
+:: 画像ファイルを変換
+img2ppt スライド.jpg -d 出力フォルダ
+
+:: クリップボードの画像を変換（引数なし）
+img2ppt -d 出力フォルダ
+
+:: PDF を変換（全ページ → 1 ファイルの PPTX）
+img2ppt 資料.pdf -d 出力フォルダ
+```
+
+### 入力モード
+
+| モード | 方法 | 説明 |
+| --- | --- | --- |
+| ファイル指定 | `img2ppt <ファイルパス>` | JPG / PNG / PDF を直接指定 |
+| クリップボード | `img2ppt`（引数なし） | 画像をコピーしてからそのまま実行 |
+| PDF | 拡張子 `.pdf` のファイルを指定 | 全ページを 1 つの PPTX にまとめる |
+
+---
+
+## 出力ファイル
+
+`-d` で指定したディレクトリに以下が出力されます。
+
+| ファイル | 説明 |
+| --- | --- |
+| `{stem}.pptx` | **最終 PowerPoint** |
+| `{stem}.json` | 認識結果の構造化 JSON |
+| `{stem}_04_inpainted.png` | テキスト除去後の画像 |
+| `{stem}_05_1_segment_filled.png` | セグメント検出結果（シルエット） |
+| `{stem}_05_2_mask_segment.png` | セグメントマスク画像 |
+| `{stem}_06_1_content_inpainted.png` | コンテンツ除去後の画像 |
+| `{stem}_06_2_mask_colorize.png` | カラー分割マスク |
+| `{stem}_06_3_colorized.png` | カラー分割結果 |
+
+デバッグ用の可視化画像（`vis_` プレフィックス）は `--debug` を付けると追加出力されます。
+
+---
+
+## オプション一覧
+
+### 基本オプション
+
+| オプション | デフォルト | 説明 |
+| --- | --- | --- |
+| `-d`, `--output-dir` | `test/` | 出力ディレクトリ |
+| `-o`, `--output-json` | 自動 | 最終 JSON の出力パス（単一ページ時のみ有効） |
+| `-v`, `--verbose` | オフ | 詳細ログを表示（省略時はプログレスバーのみ） |
+| `--debug` | オフ | デバッグ用可視化画像（`vis_xxx`）を出力 |
+| `--keep-tmp` | オフ | 処理後も一時ディレクトリを削除しない |
+| `--tmp-dir` | システム一時領域 | 一時ディレクトリの作成場所を指定 |
+| `--pdf-dpi` | `150` | PDF ページ変換の解像度（DPI） |
+
+### 出力パス個別指定
+
+| オプション | 説明 |
+| --- | --- |
+| `--output-inpaint` | Step4 テキスト除去画像の出力パス |
+| `--output-seg-filled` | Step5 シルエット画像の出力パス |
+| `--output-mask-seg` | Step5 マスク画像の出力パス |
+
+### 画像鮮明化（Step1）
+
+低解像度・圧縮ノイズが多い画像の OCR 精度を上げるための前処理です。  
+PNG または長辺 1280px 以上の JPG は自動スキップされます。
+
+| オプション | デフォルト | 説明 |
+| --- | --- | --- |
+| `--denoise-h` | `10` | ノイズ除去強度（大きいほど強く除去、ぼけやすい） |
+| `--bilateral-d` | `9` | エッジ保持フィルタの近傍径 |
+| `--sigma-color` | `60.0` | エッジ保持フィルタの色シグマ |
+| `--sigma-space` | `60.0` | エッジ保持フィルタの空間シグマ |
+| `--unsharp-radius` | `2` | 輪郭強調の半径（px） |
+| `--unsharp-percent` | `200` | 輪郭強調の強度（%） |
+| `--unsharp-threshold` | `2` | 輪郭強調の閾値 |
+
+### テキスト除去（Step4）
+
+| オプション | デフォルト | 説明 |
+| --- | --- | --- |
+| `--sample-offset` | `3` | 背景色サンプリング位置（bbox 端から何 px 外側か） |
+| `--fill-expand` | `2` | テキスト除去の塗り範囲拡張量（px） |
+
+### セグメント検出（Step5）
+
+| オプション | デフォルト | 説明 |
+| --- | --- | --- |
+| `--sat-max` | `40` | 背景とみなす最大彩度（HSV-S、0〜255） |
+| `--val-min` | `200` | 背景とみなす最小輝度（HSV-V、0〜255） |
+
+### OCR 品質フィルタ（Step2.5）
+
+| オプション | デフォルト | 説明 |
+| --- | --- | --- |
+| `--ocr-min-height` | `8` | bbox 最小高さ（px）。これ未満は除外 |
+| `--ocr-threshold` | `0.45` | 総合スコア閾値。これ未満のテキストを除外 |
+
+### PowerPoint 生成（Step7）
+
+| オプション | デフォルト | 説明 |
+| --- | --- | --- |
+| `--bg-tolerance` | `20` | 図形の背景透過許容幅（RGB 各チャンネル ±n） |
+
+---
+
+## 実行例
+
+```cmd
+:: 高解像度 PDF を変換
+img2ppt 資料.pdf -d C:\output --pdf-dpi 200
+
+:: デバッグ: 全中間ファイルを残して詳細ログを表示
+img2ppt スライド.jpg -d C:\output --debug --keep-tmp --verbose
+
+:: クリップボード画像を変換してデスクトップに保存
+img2ppt -d %USERPROFILE%\Desktop
+
+:: OCR フィルタを緩めて誤除外を減らす
+img2ppt スライド.jpg -d C:\output --ocr-threshold 0.35
+```
+
+---
+
+## うまくいかないときは
+
+| 症状 | 試すこと |
+| --- | --- |
+| テキストが認識されない | `--ocr-threshold` を下げる（例: `0.35`） |
+| 誤認識テキストが残る | `--ocr-threshold` を上げる（例: `0.55`） |
+| 背景色で塗りつぶしがうまくいかない | `--sample-offset` や `--fill-expand` を調整する |
+| 図形の背景が透過しすぎる / されない | `--bg-tolerance` を調整する（大きくすると透過が広がる） |
+| 低彩度アイコンが検出されない | `--sat-max` を上げる（例: `50`） |
+| 処理の途中経過を確認したい | `--debug --keep-tmp --verbose` を付けて実行する |
+
+---
+
+## パイプライン概要
+
+| ステップ | モジュール | 処理内容 |
+| --- | --- | --- |
+| Step1 | `clarify.py` | 画像鮮明化（ノイズ除去・輪郭強調） |
+| Step2 | `ocr.py` | Windows.Media.Ocr でテキスト検出・認識 |
+| Step2.5 | `ocr_filter.py` | geometric / unicode / bigram / morph スコアで文字化けを除外 |
+| Step3 | `split.py` | OCR bbox 後処理・複数テキスト混入 bbox を分割 |
+| Step4 | `inpaint.py` | テキスト領域を背景色で除去・修復 |
+| Step5 | `segment.py` | HSV 2値化 + 連結成分ラベリングでオブジェクト検出 |
+| Step6 | `colorize.py` | container を投影プロファイル法で矩形分割・内包正規化 |
+| Step7 | `pptx_gen.py` | JSON + 中間画像から PowerPoint スライドを生成 |
+
+---
+
+## 依存ライブラリ
+
+| ライブラリ | ライセンス | 用途 |
+| --- | --- | --- |
+| `winrt-Windows.Media.Ocr` | MIT | テキスト検出・認識（Windows 標準 OCR） |
+| `opencv-python` | Apache 2.0 | 画像処理 |
+| `Pillow` | HPND（MIT互換） | 画像入出力 |
+| `numpy` | BSD | 配列処理 |
+| `python-pptx` | MIT | PowerPoint ファイル生成 |
+| `pypdfium2` | Apache 2.0 | PDF → 画像変換 |
+| `janome` | MIT | 形態素解析（OCR 品質フィルタ） |
+
+---
+
+## ライセンス
+
+MIT License

img2ppt-1.3.4/img2ppt/__init__.py

@@ -0,0 +1,3 @@
+"""img2ppt — スライド画像/PDF → PowerPoint 自動変換パイプライン"""
+
+__version__ = "1.3.4"

img2ppt-1.3.4/img2ppt/__main__.py

@@ -0,0 +1,3 @@
+from img2ppt.cli import main
+
+main()

img2ppt-1.3.4/img2ppt/clarify.py

@@ -0,0 +1,259 @@
+"""
+画像鮮明化モジュール
+
+イラスト・図版・JPG画像向けに以下の処理を順に適用する:
+  1. fastNlMeansDenoisingColored : JPEGブロックノイズ・輝度ムラを除去
+  2. bilateralFilter             : 輪郭を保持しつつ色むら・揺らぎを平滑化
+  3. UnsharpMask                 : エッジ・輪郭線を鮮明化
+
+--roi を指定した場合は対象領域のみ処理して元画像に合成する。
+省略した場合は画像全体を処理する。アルファチャンネルは保持される。
+"""
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+import cv2
+import numpy as np
+from PIL import Image, ImageFilter
+
+
+def _process_region(
+    bgr: np.ndarray,
+    denoise_h: int,
+    denoise_template: int,
+    denoise_search: int,
+    bilateral_d: int,
+    bilateral_sigma_color: float,
+    bilateral_sigma_space: float,
+    unsharp_radius: int,
+    unsharp_percent: int,
+    unsharp_threshold: int,
+) -> np.ndarray:
+    """BGR配列に鮮明化処理を適用してBGR配列で返す。"""
+
+    # ── Step1: ノイズ除去 ────────────────────────────────────────────────
+    # denoise_h      : ノイズ除去強度。大きいほど強くノイズを除去するが、細部がぼける。
+    #                  JPEGアーティファクトが目立つ画像では 10〜15、きれいな画像は 5 程度。
+    # denoise_template: テンプレートウィンドウサイズ(px、奇数)。大きいほど精度が上がるが遅い。通常 7。
+    # denoise_search  : 探索ウィンドウサイズ(px、奇数)。大きいほど広範囲を比較して精度UP。通常 21。
+    denoised = cv2.fastNlMeansDenoisingColored(
+        bgr,
+        h=denoise_h,
+        hColor=denoise_h,
+        templateWindowSize=denoise_template,
+        searchWindowSize=denoise_search,
+    )
+
+    # ── Step2: バイラテラルフィルタ ──────────────────────────────────────
+    # 輪郭（エッジ）を保持しながら色むら・ノイズを平滑化する。
+    # bilateral_d          : フィルタの近傍径(px)。大きいほど広範囲を平滑化するが遅い。通常 9。
+    # bilateral_sigma_color: 色空間のシグマ値。大きいほど色の違いを無視して平滑化する。
+    #                        小さいと色の差が少し違うだけで別エッジとみなし、強いシャープ感が残る。
+    #                        通常 60〜80。大きくすると塗り絵的な質感になる。
+    # bilateral_sigma_space: 座標空間のシグマ値。大きいほど遠くのピクセルも参照する。
+    #                        通常 60〜80。大きくすると広域にぼかしが広がる。
+    bilateral = cv2.bilateralFilter(
+        denoised,
+        d=bilateral_d,
+        sigmaColor=bilateral_sigma_color,
+        sigmaSpace=bilateral_sigma_space,
+    )
+
+    # ── Step3: アンシャープマスク（輪郭強調） ────────────────────────────
+    # ぼかした画像との差分を元画像に加算してエッジを際立たせる。
+    # unsharp_radius   : ぼかし半径(px)。大きいほど広いエッジを強調する。通常 1〜3。
+    #                    大きくすると輪郭が太くなり、小さくすると細かいテクスチャが強調される。
+    # unsharp_percent  : 強調強度(%)。100が等倍加算、200で2倍加算。
+    #                    上げるほどシャープになるが、ノイズや縞も強調されてしまう。
+    #                    通常 150〜200。OCR前処理として使う場合は高め（160〜200）が有効。
+    # unsharp_threshold: この輝度差(0〜255)以下のエッジは強調しない。
+    #                    0にするとノイズも強調される。2〜5 程度が無難。
+    pil = Image.fromarray(cv2.cvtColor(bilateral, cv2.COLOR_BGR2RGB))
+    sharpened = pil.filter(
+        ImageFilter.UnsharpMask(
+            radius=unsharp_radius,
+            percent=unsharp_percent,
+            threshold=unsharp_threshold,
+        )
+    )
+    return cv2.cvtColor(np.array(sharpened), cv2.COLOR_RGB2BGR)
+
+
+def clarify(
+    src: Path,
+    dst: Path,
+    roi: tuple[int, int, int, int] | None = None,
+    skip_if_clean: bool = True,
+    # ノイズ除去強度: 上げると強くノイズを消すが細部がぼける（JPEGアーティファクトが強い画像は 10〜15）
+    denoise_h: int = 10,
+    # テンプレートウィンドウ: 通常 7 固定で問題なし
+    denoise_template: int = 7,
+    # 探索ウィンドウ: 通常 21 固定で問題なし（大きくすると精度UP・速度DOWN）
+    denoise_search: int = 21,
+    # バイラテラル近傍径: 大きくすると広範囲平滑化（遅くなる）。通常 9
+    bilateral_d: int = 9,
+    # 色シグマ: 大きくすると色差を無視して平滑化。通常 60〜80
+    bilateral_sigma_color: float = 60.0,
+    # 座標シグマ: 大きくすると広域にぼかし。通常 60〜80
+    bilateral_sigma_space: float = 60.0,
+    # アンシャープ半径: 大きくすると太いエッジを強調。通常 2
+    unsharp_radius: int = 2,
+    # アンシャープ強度(%): 上げるほどシャープ。OCR前処理は 160〜200 が有効
+    unsharp_percent: int = 200,
+    # アンシャープ閾値: この輝度差以下のエッジは無視（ノイズ抑制）。通常 2
+    unsharp_threshold: int = 2,
+) -> Path:
+    """
+    画像を鮮明化して dst に保存し、dst を返す。
+
+    roi: (x1, y1, x2, y2) を指定した場合はその領域のみ処理。
+         None の場合は画像全体を処理。
+    skip_if_clean: True の場合、高品質画像はスキップ（元画像をコピー）。
+                   - PNG ファイル（ロスレス）
+                   - JPG/JPEG で1280px以上の解像度
+    """
+    raw = np.frombuffer(src.read_bytes(), dtype=np.uint8)
+    img_bgr = cv2.imdecode(raw, cv2.IMREAD_UNCHANGED)
+    if img_bgr is None:
+        raise FileNotFoundError(f"画像を読み込めません: {src}")
+
+    has_alpha = img_bgr.ndim == 3 and img_bgr.shape[2] == 4
+    if has_alpha:
+        bgr, alpha = img_bgr[:, :, :3], img_bgr[:, :, 3]
+    else:
+        bgr, alpha = img_bgr, None
+
+    h, w = bgr.shape[:2]
+
+    # ── スキップ判定：高品質画像の場合は元画像をコピーして返す ────────────
+    if skip_if_clean and roi is None:
+        suffix = src.suffix.lower()
+        is_png = suffix == ".png"
+        is_high_res_jpg = suffix in [".jpg", ".jpeg"] and max(h, w) >= 1280
+        if is_png or is_high_res_jpg:
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, dst)
+            print(f"鮮明化スキップ: {src.name} ({w}×{h} px) ← 高品質ファイル")
+            return dst
+    kwargs = dict(
+        denoise_h=denoise_h,
+        denoise_template=denoise_template,
+        denoise_search=denoise_search,
+        bilateral_d=bilateral_d,
+        bilateral_sigma_color=bilateral_sigma_color,
+        bilateral_sigma_space=bilateral_sigma_space,
+        unsharp_radius=unsharp_radius,
+        unsharp_percent=unsharp_percent,
+        unsharp_threshold=unsharp_threshold,
+    )
+
+    if roi is None:
+        result_bgr = _process_region(bgr, **kwargs)
+        print(f"処理範囲: 画像全体 ({w}×{h} px)")
+    else:
+        x1, y1, x2, y2 = (
+            max(0, roi[0]), max(0, roi[1]),
+            min(w, roi[2]), min(h, roi[3]),
+        )
+        result_bgr = bgr.copy()
+        result_bgr[y1:y2, x1:x2] = _process_region(bgr[y1:y2, x1:x2].copy(), **kwargs)
+        print(f"処理 ROI : x={x1}-{x2}, y={y1}-{y2}  ({x2-x1}×{y2-y1} px)")
+
+    result_rgb = cv2.cvtColor(result_bgr, cv2.COLOR_BGR2RGB)
+    out = Image.fromarray(result_rgb)
+
+    if alpha is not None:
+        out = out.convert("RGBA")
+        out.putalpha(Image.fromarray(alpha))
+
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    out.save(str(dst))
+    print(f"保存完了: {dst}")
+    return dst
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="画像鮮明化ツール（全体 / ROI 指定）",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+パラメータ調整ガイド:
+  --denoise-h       ノイズ除去強度。上げるとJPEGノイズが消えるが細部もぼける。
+                    JPEGが荒い画像: 10〜15 / きれいな画像: 5 程度
+  --bilateral-d     バイラテラルフィルタ近傍径。上げると広域を平滑化するが遅くなる。通常: 9
+  --sigma-color     色シグマ。上げると色差を無視して広く平滑化。通常: 60〜80
+  --sigma-space     座標シグマ。上げると遠くのピクセルまでぼかしが広がる。通常: 60〜80
+  --unsharp-radius  アンシャープ半径。上げると太いエッジを強調。通常: 2
+  --unsharp-percent アンシャープ強度(%)。上げるほどシャープ。OCR前処理: 160〜200
+  --unsharp-threshold アンシャープ閾値。この輝度差以下のエッジは無視。ノイズ抑制: 2〜5
+""",
+    )
+    parser.add_argument("input", type=Path, help="入力画像パス")
+    parser.add_argument(
+        "-o", "--output", type=Path, default=None,
+        help="出力画像パス（省略時: 入力ファイル名に _clarified を付加）",
+    )
+    parser.add_argument(
+        "--roi", nargs=4, type=int, metavar=("X1", "Y1", "X2", "Y2"),
+        default=None, help="処理対象領域 (ピクセル座標)。省略時は全体を処理",
+    )
+    parser.add_argument(
+        "--denoise-h", type=int, default=10,
+        help="ノイズ除去強度 (デフォルト: 10)。上げると強くノイズを消すが細部がぼける",
+    )
+    parser.add_argument(
+        "--bilateral-d", type=int, default=9,
+        help="バイラテラルフィルタの近傍径px (デフォルト: 9)。上げると広範囲平滑化・処理が遅くなる",
+    )
+    parser.add_argument(
+        "--sigma-color", type=float, default=60.0,
+        help="色空間のシグマ値 (デフォルト: 60)。上げると色差を無視して平滑化、塗り絵的な質感になる",
+    )
+    parser.add_argument(
+        "--sigma-space", type=float, default=60.0,
+        help="座標空間のシグマ値 (デフォルト: 60)。上げると広域にぼかしが広がる",
+    )
+    parser.add_argument(
+        "--unsharp-radius", type=int, default=2,
+        help="アンシャープマスクの半径px (デフォルト: 2)。上げると太いエッジを強調、下げると細かいテクスチャが強調",
+    )
+    parser.add_argument(
+        "--unsharp-percent", type=int, default=200,
+        help="アンシャープマスクの強度%% (デフォルト: 200)。上げるほどシャープ、ノイズも強調されるので注意",
+    )
+    parser.add_argument(
+        "--unsharp-threshold", type=int, default=2,
+        help="アンシャープマスクの閾値 (デフォルト: 2)。この輝度差以下のエッジは無視してノイズ抑制",
+    )
+    args = parser.parse_args()
+
+    src = args.input.resolve()
+    if not src.exists():
+        print(f"エラー: ファイルが見つかりません: {src}", file=sys.stderr)
+        sys.exit(1)
+
+    dst = (
+        args.output.resolve()
+        if args.output
+        else src.with_stem(src.stem + "_clarified")
+    )
+
+    clarify(
+        src=src,
+        dst=dst,
+        roi=tuple(args.roi) if args.roi else None,
+        denoise_h=args.denoise_h,
+        bilateral_d=args.bilateral_d,
+        bilateral_sigma_color=args.sigma_color,
+        bilateral_sigma_space=args.sigma_space,
+        unsharp_radius=args.unsharp_radius,
+        unsharp_percent=args.unsharp_percent,
+        unsharp_threshold=args.unsharp_threshold,
+    )
+
+
+if __name__ == "__main__":
+    main()