px-asset-extract: 画像アセット抽出

機能説明

画像を個別の透明PNG アセットに分解し、分類と JSON マニフェストを生成します。 フルパイプラインはCPU上で2～6秒で実行され、MLモデルは不要です:

1. 背景検出 — 画像境界のメジアン色から背景を判定
2. 前景マスク — ユークリッド色距離閾値処理
3. 文字ブリッジング — 膨張処理で文字を単語に結合
4. 連結成分 — 8連結のUnion-Findアルゴリズム
5. 分類 — 10カテゴリへのヒューリスティック分類
6. テキスト行統合 — 単語フラグメントをテキスト行にグループ化
7. アルファ抽出 — アンチエイリアス処理による透明トリミング
8. 重複排除 — 重複および過度に大きなセグメントを削除

使用場面

シナリオ	px-asset-extract を使用?
スライド/ポスターのすべての要素を抽出	はい — これが主な用途です
イラストのみを取得し、テキストはスキップ	はい — --types illustration または --exclude-types text を使用
説明で特定のオブジェクトを抽出	--regions + グラウンディングモデル(例: Florence-2)と共に使用
単一の写真から背景を削除	いいえ — 背景除去モデルを使用してください
写真シーンをセグメント化	いいえ — 写真コンテンツにはSAM/FastSAMを使用してください
テクスチャ/写真背景を持つ画像	制限あり — クリーン/単色背景で最適に動作

インストール

git clone https://github.com/JadeLiu-tech/px-asset-extract.git
cd px-asset-extract
pip install .

使用方法

CLI

# 基本的な抽出
px-extract <image> -o <output_dir>

# イラストとアイコンのみを抽出
px-extract <image> -o <output_dir> --types illustration,icon

# テキスト、ドット、線を除くすべてを抽出
px-extract <image> -o <output_dir> --exclude-types text,dot,line

# 事前計算されたバウンディングボックスから抽出(例: px-groundから)
px-extract <image> -o <output_dir> --regions regions.json

# セグメンテーションのみ — JSON出力、PNGなし
px-extract <image> --segments-only

# バッチ処理
px-extract images/*.png -o output/ --batch

# JSON出力を標準出力へ
px-extract <image> -o <output_dir> --json --quiet

Python API

from px_asset_extract import extract_assets, load_regions

# フル抽出
result = extract_assets("slide.png", output_dir="assets/")
for asset in result.assets:
    print(f"{asset.id}: {asset.label} at ({asset.bbox.x}, {asset.bbox.y}) -> {asset.file_path}")

# タイプフィルタリング
result = extract_assets("slide.png", output_dir="icons/", types=["illustration", "icon"])
result = extract_assets("slide.png", output_dir="graphics/", exclude_types=["text", "line", "dot"])

# 事前計算されたリージョン(グラウンディングモデル出力から)
regions = load_regions("grounded.json")
result = extract_assets("slide.png", output_dir="targeted/", regions=regions)

# リージョン + タイプフィルタを組み合わせ
result = extract_assets("slide.png", output_dir="charts/", regions=regions, types=["chart"])

CLIオプション

オプション	デフォルト	説明
-o, --output	assets	出力ディレクトリ
--bg-threshold	22.0	背景色距離(低いほど敏感)
--min-area	60	セグメントの最小面積(ピクセル)
--dilation	2	文字ギャップブリッジングパス数
--padding	10	各アセット周辺の余白(ピクセル)
--max-coverage	0.5	セグメントが占める最大画像面積
--types		抽出するタイプのみ(カンマ区切り)
--exclude-types		スキップするタイプ(カンマ区切り)
--regions		バウンディングボックス付きJSONファイル(セグメンテーション省略)
--segments-only		PNGなしでセグメントJSONを出力
--no-visualization		ビジュアライゼーション画像をスキップ
--batch		画像ごとにサブディレクトリを作成
--json		結果をJSON形式で標準出力へ
--quiet		進捗メッセージを抑制

出力

実行ごとに以下が生成されます:

• asset_NNN_<type>.png — 個別の透明PNG
• manifest.json — すべてのアセットの位置、タイプ、メタデータ
• visualization.png — カラーコード化されたバウンディングボックス付きの入力画像

マニフェストフォーマット

{
  "source_image": "slide.png",
  "source_size": {"width": 1920, "height": 1080},
  "background_color": [255, 255, 255],
  "num_assets": 44,
  "assets": [
    {
      "id": "asset_000_illustration",
      "label": "illustration",
      "file": "asset_000_illustration.png",
      "position": {"x": 100, "y": 50, "width": 400, "height": 300},
      "pixel_area": 120000
    }
  ]
}

リージョン JSON フォーマット(--regions用)

[
  {"x": 100, "y": 50, "width": 400, "height": 300, "label": "chart"},
  {"x1": 600, "y1": 100, "x2": 800, "y2": 300, "label": "logo"}
]

{"regions": [...]} ラッパーにも対応しています。ラベルを省略した場合は "region" がデフォルトです。

アセットタイプ

タイプ	検出ロジック
text	dark_ratio > 0.4、均一なインク色
illustration	大型(>画像面積の1%)、カラフル
icon	小型(<3000px面積、<60px最大寸法)
graphic	中程度のサイズ、カラー
line	細い(最小寸法<=5px、極端なアスペクト比)
dot	非常に小型(<150px面積、<20px寸法)
diagram	低い塗りつぶし率(<0.25)
diagram_network	画像の>80%をカバー、非常に低い塗りつぶし
shadow	明るい(>200)、低コントラスト、低彩度
element	未分類オブジェクトのキャッチオール

パフォーマンス

画像タイプ	アセット数	処理時間
プレゼンテーションスライド	22-44	2-6s
ポスター	11	3.9s
科学図	43	4.2s
技術図	42	4.5s
データチャート	26	4.8s

依存関係

Pillow と numpy のみです。より良いアルファエッジには opencv-python がオプションです。