pixel-art-scaler

ピクセルアートの拡大

エッジ検出とパターンマッチングによって有効なサブピクセルを追加し、美しさを保ちながらピクセルアートを拡大する決定論的アルゴリズムです。

使用する場面

✅ 次の場合に使用します：

• レトロゲームのスプライト、アイコン、ピクセルアートの拡大
• エッジを考慮した補間による2倍、3倍、4倍の拡大
• 高解像度でもシャープなピクセルアートの美しさを維持
• Retinaディスプレイ向けに8x8、16x16、32x32、48x48のピクセルアートを変換
• 決定論的な手法とAI／MLによる手法の比較

❌ 次の場合には使用しません：

• 写真やリアルな画像（AI超解像を使用してください）
• 単純な幾何学的拡大（最近傍法を使用してください）
• ベクターアート（SVGを使用してください）
• テキストの描画（フォントヒンティングを使用してください）
• 任意の非整数倍の拡大（アルゴリズムは2倍、3倍、4倍で最も効果を発揮します）

主なアルゴリズム

1. EPX/Scale2x（最速、高品質）

最適な用途：すばやい反復、2倍／3倍の拡大、透過スプライト

仕組み：

• 各ピクセルと上下左右の4近傍（N、S、E、W）を調べます
• エッジ検出を使って1ピクセルを4ピクセル（2倍）または9ピクセル（3倍）に拡大します
• 元のパレットの色のみを使用します（新しい色は追加しません）
• 透過を正しく処理します

使用する場面：

• 高速な処理が必要な場合（アイコン100個以上）
• アンチエイリアスなしのくっきりしたエッジが必要な場合
• 元画像のピクセル境界が明瞭な場合
• 透過の維持が重要な場合

開発の経緯：LucasArtsのEric Johnstonが発明（約1992年）。Andrea Mazzoleniが再発見（2001年）

2. hq2x/hq3x/hq4x（高品質、低速）

最適な用途：最終レンダリング、複雑なスプライト、滑らかなグラデーション

仕組み：

• 3x3の近傍に対してパターンマッチングを行います（可能なパターンは256種類）
• エッジ検出にYUV色空間のしきい値を使用します
• パターンごとに高度な補間ルールを適用します
• 滑らかでアンチエイリアス処理されたエッジを生成します

使用する場面：

• 最終的な制作アセット
• 元画像にグラデーションやディザリングが含まれている場合
• 滑らかでアンチエイリアス処理された結果が必要な場合
• 処理時間を許容できる場合（EPXより約5～10倍低速）

開発の経緯：エミュレーター向けにMaxim Stepinが開発（2003年）

3. xBR/Super-xBR（最高品質、最も低速）

最適な用途：主要アセット、販促素材、精細なスプライト

仕組み：

• 重み付きブレンディングを用いた高度なエッジ検出
• 複数回の処理で滑らかな結果を生成します（Super-xBR）
• エッジを滑らかにしながら細部を保持します
• 3つのアルゴリズムの中で最も優れたアンチエイリアス処理を実現します

使用する場面：

• 最高品質が必要な場合
• 細部まで描き込まれた複雑なスプライト
• マーケティング／販促用途
• 処理時間に制約がない場合（EPXより約20倍低速）

開発の経緯：xBRはHyllianが開発（2011年）、Super-xBR（2015年）

アンチパターン

アンチパターン：表示に最近傍法を使用する

初心者の考え：「最近傍法で4倍にするだけで、ピクセルが保持されます」

実際には：最近傍法では、ディテールを追加せずにブロック状の繰り返しが生じます。各ピクセルが同じ色のN×Nブロックになるため、高DPIディスプレイでは粗雑に見えます。

決定論的アルゴリズムが行うこと：パターン認識によって有効なサブピクセルを追加します。斜めのエッジにはアンチエイリアス処理されたピクセルを加え、直線のエッジはくっきりと保ちます。

開発の経緯：

• 2000年代以前：最近傍法が唯一の選択肢でした
• 2001年以降：EPX/Scale2xにより、スマートな2倍拡大が可能になりました
• 2003年以降：hq2xにより、高度なパターンマッチングが加わりました
• 2011年以降：xBRが最先端になりました

最近傍法が正しい場合：ピクセルパーフェクトな環境（例：1:1の参照画像）で、ピクセルアートを整数倍の正確なサイズで表示する場合。

アンチパターン：ピクセルアートにAI／MLを使用する

初心者の考え：「Real-ESRGAN／Waifu2xなら、もっと良い結果が得られます」

実際には：写真やアニメで学習したAIモデルは、ピクセルアートに不適切なディテールを加えます。本来ないはずのテクスチャを作り、エッジを滑らかにするため、意図的に行われたピクセル単位の判断が損なわれます。

LLMの誤り：学習データに、写真編集の文脈で書かれた「拡大にはAIモデルを使う」というアドバイスが含まれています。

正しい方法：

ソースの種類	アルゴリズム
ピクセルアート（スプライト、アイコン）	EPX/hq2x/xBR（このスキル）
ピクセルアートの写真（スクリーンショット）	ハイブリッド：まずxBRを適用し、その後AIを軽く適用
写真／リアルなアート	AI超解像
混在するコンテンツ	両方を試し、結果を比較

コンテキストに合わないアルゴリズムの選択：アンチパターン

初心者の考え：「常に最高品質のアルゴリズムを使うべきです」

実際のところ：アルゴリズムはそれぞれ異なる用途に適しています。

コンテキスト	アルゴリズム	理由
イテレーション／プロトタイピング	EPX	10 倍高速で、品質も十分です
本番用アセット（Web）	hq2x	品質とサイズのバランスが取れています
ヒーロー画像（マーケティング）	xBR	最高品質です
透過スプライト	EPX	透過の処理に最適です
複雑なグラデーション	hq4x	グラデーションの補間に最適です

検証：出力は必ず目視で比較してください。hq4x より EPX 2x のほうが見栄えがよい場合もあります。

使用方法

クイックスタート

# Install dependencies
cd ~/.claude/skills/pixel-art-scaler/scripts
pip install Pillow numpy

# Scale a single icon with EPX 2x (fastest)
python3 scale_epx.py input.png output.png --scale 2

# Scale with hq2x (high quality)
python3 scale_hqx.py input.png output.png --scale 2

# Scale with xBR (maximum quality)
python3 scale_xbr.py input.png output.png --scale 2

# Batch process directory
python3 batch_scale.py input_dir/ output_dir/ --algorithm epx --scale 2

# Compare all algorithms side-by-side
python3 compare_algorithms.py input.png output_comparison.html

アルゴリズム選択ガイド

判断ツリー：

Need to scale pixel art?
├── Transparency important? → EPX
├── Fast iteration needed? → EPX
├── Complex gradients/dithering? → hq2x or hq4x
├── Maximum quality for hero asset? → xBR
└── Not sure? → Run compare_algorithms.py

一般的なワークフロー

1. EPX 2x でプロトタイプを作成：すべてのアセットをすばやく処理します
2. 結果を確認：より高品質が必要なものを特定します
3. ヒーロー画像を hq4x または xBR で再処理：主要なアセットのみに適用します
4. 出力を比較：compare_algorithms.py を使って横並びで比較します
5. 最適化：4x より 2x のほうが見栄えがよい場合もあります（両方試してください）

スクリプト一覧

すべてのスクリプトは scripts/ ディレクトリにあります。

スクリプト	用途	速度	品質
scale_epx.py	EPX／Scale2x の実装	高速	良好
scale_hqx.py	hq2x／hq3x／hq4x の実装	中速	優秀
scale_xbr.py	xBR／Super-xBR の実装	低速	最高
batch_scale.py	ディレクトリを処理	変動	変動
compare_algorithms.py	比較用 HTML を生成	該当なし	該当なし

各スクリプトには、次の機能が含まれています。

• --help による CLI インターフェース
• 透過情報の保持
• 破損した入力に対するエラー処理
• バッチ処理の進捗表示

技術的な詳細

色空間に関する考慮事項

EPX：RGB で処理し、二値のエッジ検出を行います
hq2x／hq4x：しきい値（Y=48、Cb=7、Cr=6）を使用する YUV 色空間で処理します
xBR：輝度を考慮した、RGB での高度なエッジ重み付けを行います

透過の処理

すべてのアルゴリズムでアルファチャンネルが保持されます。

• 透過ピクセルはエッジ検出に影響しません
• 半透明ピクセルは正しく処理されます
• 入力にアルファチャンネルがある場合、出力も RGBA 形式で保持されます

パフォーマンスのベンチマーク（M4 Max、入力 48x48）

アルゴリズム	時間（画像 1 枚）	バッチ処理（画像 100 枚）
EPX 2x	0.01s	1s
EPX 3x	0.02s	2s
hq2x	0.10s	10s
hq4x	0.30s	30s
xBR 2x	0.15s	15s
xBR 4x	0.50s	50s

目安：EPX は hq2x より約 10 倍、xBR より約 20 倍高速です。

出力の検証

拡大処理後、結果を確認します。

# Check output dimensions
identify output.png  # Should be exactly 2x, 3x, or 4x input

# Visual inspection
open output.png  # Look for artifacts, incorrect edges

# Compare algorithms
python3 compare_algorithms.py input.png comparison.html
open comparison.html  # Side-by-side comparison

よくある問題：

• 斜めの線がギザギザになる → EPX の代わりに hq2x または xBR を試してください
• エッジがぼやける → 入力がすでに拡大済みでないか確認してください（元画像に適用してください）
• 色が正しくない → 入力が RGB／RGBA であることを確認してください（インデックスカラー／パレット形式の PNG ではありません）

参考資料

詳細解説

• /references/algorithm-comparison.md - 視覚的な例とトレードオフ
• /references/epx-algorithm.md - EPX／Scale2x の実装に関する詳細
• /references/hqx-patterns.md - hq2x のパターンマッチング表の解説
• /references/xbr-edge-detection.md - xBR のエッジ重み付けの数式

研究論文と情報源

• ピクセルアートのスケーリングアルゴリズム - Wikipedia
• Scale2x と EPX の公式サイト
• hqx：ピクセルアート向け画像スケーリングアルゴリズム
• py-super-xbr GitHub

アセットの例

• /assets/test-sprites/ - アルゴリズムのテスト用スプライトのサンプル
• /assets/expected-outputs/ - 検証用の出力例

変更履歴

• 2026-02-05：EPX、hq2x、xBR の実装を含む初回のスキル作成