ai-pixel-art-converter

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

ai-pixel-art-converter

★ 20 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# AI Pixel-Art Converter

ローカルまたはホスト型の vision LLM に画像を見せて、16×16 のピクセルアートへ変換する評価アプリです。
推論は **1 モデルずつ** 実行し、結果は brushstroke として SQLite に保存します。後から複数 run を選んで、スクリーンショットのように side-by-side で同時再生できます。

## できること

- 画像アップロード、またはブラウザ上で絵文字を PNG 化して task 作成
- OpenAI公式 API、OpenAI互換 API、Gemini ネイティブ API で vision LLM を呼び出し
- 既定の `vision_plan` では、VLM が元画像そのものから特徴を抽出し、16×16ドラフトを自己修正
- 必要なら実用変換用の `grid`、まとめ塗りの `batch`、旧来の `stroke` 推論モードへ切り替え可能
- `vision_plan`/`vision_loop`/`batch`/`stroke` モードではモデルが同じピクセルを塗り直す「後悔」や、全体の書き直しも記録
- side-by-side replay、再生速度変更、途中停止、run/task 削除
- タイムラインのクリック / ドラッグでシーク、キーボード操作（Space 再生/停止、←/→ コマ送り、Shift+←/→ で±10、Home/End ジャンプ）
- 画像のドラッグ&ドロップや Ctrl+V 貼り付けでタスク作成、絵文字クイックチップでワンクリック作成
- 各 run の実行時間表示、操作成功のトースト通知
- SQLite 永続化: `data/pixel_showdown.db`

## 背景

このアプリは、BenchLocal の Pixelate テストと、次の公開投稿に着想を得た独立実装です。

https://x.com/stevibe/status/2070514425392681410

Pixelate や BenchLocal のソースコードは参照・利用していません。また、このプロジェクトは BenchLocal とは非提携です。

## セットアップ

```bash
cd ai-pixel-art-converter
uv sync
cp .env.example .env
```

`.env` を編集します。

```env
LLM_PROVIDER=openai
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-5.5
OPENAI_API_KEY=your-openai-api-key
INFERENCE_MODE=vision_plan
MAX_BRUSHSTROKES=256
VISION_PLAN_PASSES=0
VISION_PLAN_MAX_PAINTED_CELLS=256
BATCH_STROKES=16
```

OpenAI互換 API を使う場合は、`LLM_PROVIDER=openai-compatible` にして `OPENAI_BASE_URL` をローカルまたはホスト先の `/v1` endpoint にします。

```env
LLM_PROVIDER=openai-compatible
OPENAI_BASE_URL=http://127.0.0.1:8000/v1
OPENAI_MODEL=your-vision-model-name
OPENAI_API_KEY=not-needed
INFERENCE_MODE=vision_plan
```

Gemini API を直接使う場合は、`LLM_PROVIDER=gemini` にして `GEMINI_API_KEY` を環境変数または `.env` に定義します。

```env
LLM_PROVIDER=gemini
OPENAI_MODEL=gemini-3.1-flash-lite
GEMINI_API_KEY=your-google-ai-studio-key
INFERENCE_MODE=vision_plan
```

`OPENAI_MODEL` は現在のモデル名として使われ、UI で保存するモデル設定名や run 表示名の既定にもなります。Gemini でも同じ変数名を使えます。必要なら UI の **API / モデル設定** からプロバイダ、API key、モデル名を保存できます。

起動します。

```bash
uv run python -m app.main
```

ブラウザで `http://127.0.0.1:8000` を開きます。

このアプリはローカル実行を前提にしています。API キーをブラウザ UI から扱うため、認証やリバースプロキシなしでインターネットへ公開しないでください。必要な場合だけ `HOST=0.0.0.0` を指定できます。

テストを実行します。

```bash
uv run pytest
```

## 使い方

1. 画像をアップロードするか、`🐤`、`🪅`、`け` などを入力して **作成**。
2. **API / モデル設定** でプロバイダとモデルを確認し、必要なら保存する。
3. **1モデルずつ推論** で使うモデル設定を選び、**推論開始**。
4. 別モデルを試すときは **API / モデル設定** で別のモデル設定を保存してから、同じ task に対して run を追加。
5. run を選択して ▶ を押すとまとめて再生できます。

> 補足: この実装は `load_settings()` を run 作成時に呼ぶため、環境によっては server を再起動しなくても `.env` の変更が反映されます。ただしプロセス管理の混乱を避けるため、モデルを切り替えたら再起動する運用を推奨します。

## ローカル LLM API の期待形式

既定の `INFERENCE_MODE=vision_plan` は VLM 評価用です。バックエンドはまず **元画像そのもの** だけを渡し、VLMに特徴抽出と完成形の16×16設計をさせます。その後、各 refinement pass で **元画像** と **VLM自身が作った現在ドラフト画像** と **現在gridテキスト** を渡して、完全な `rows` を書き直させます。

重要: `vision_plan` では、元画像から作った16×16 downsample、target grid、セル単位の参照情報はVLMへ渡しません。

モデルは次の形式を返します。

```json
{
  "analysis": "compact visual notes",
  "rows": [
    ["..", "..", "#F4C542", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", ".."]
  ]
}
```

実際の `rows` 応答では 16 行、各行に 16 セルが必要です。

`INFERENCE_MODE=vision_loop` は、より逐次的な VLM 評価用です。バックエンドは各 iteration で **元画像** と **現在の16×16キャンバス画像** と **現在グリッドの座標テキスト** を渡します。採点用の `target_grid` はプロンプトに出しません。

モデルは次のいずれかを返します。

```json
{"strokes":[{"action":"paint","x":7,"y":5,"color":"#C000FF"}]}
```

全体構造が間違っている場合は、ゼロからの書き直しとして完全な `rows` も返せます。

```json
{
  "rows": [
    ["..", "..", "#A020F0", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", ".."]
  ]
}
```

実際の `rows` 応答では 16 行、各行に 16 セルが必要です。

完了判断もモデル自身が行います。

```json
{"action":"done"}
```

`INFERENCE_MODE=grid` は実用変換用です。バックエンドがまず完成形の `16x16` 参照グリッドをプロンプトに渡し、feedback loop で改善します。VLM ベンチマークとしては答えに近い情報を渡すため、比較用途には `vision_plan` または `vision_loop` を使ってください。

```json
{
  "model": "your-vision-model-name",
  "messages": [
    {"role": "system", "content": "..."},
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "current 16x16 canvas..."},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
      ]
    }
  ],
  "temperature": 0,
  "max_tokens": 4096
}
```

`grid` モードのモデル応答は次の形式です。

```json
{
  "rows": [
    ["..", "..", "#A020F0", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", ".."]
  ]
}
```

アプリ側は最終的に採用したグリッドを stroke list に変換して保存するため、リプレイ UI は従来通り 1 ピクセルずつ再生できます。

`INFERENCE_MODE=batch` にすると、1 request で複数 brushstrokes を要求します。

```json
{"strokes":[{"action":"paint","x":7,"y":5,"color":"#C000FF"}]}
```

`INFERENCE_MODE=stroke` にすると旧来の 1 API call = 1 brushstroke 方式で動きます。

ローカルサーバが `response_format` をサポートする場合は、`.env` で `OPENAI_RESPONSE_FORMAT_JSON=true` にできます。

## 動作確認用 MOCK モード

LLM が未準備でも UI と replay を確認できます。

```env
MOCK_LLM=true
MOCK_DELAY_SECONDS=0.02
```

このモードでは downsampled target grid を元に、API を呼ばずに疑似 stroke を生成します。`vision_plan`/`vision_loop`/`batch`/`stroke` モードでは stroke 列、`grid` モードでは一括グリッドとして動きます。

## 注意

- vision 対応の model/API が必要です。text-only model では失敗します。
- `INFERENCE_MODE=vision_plan` が既定です。VLM には source-derived 16×16情報や scoring target を渡さず、元画像と自分のドラフトだけで改善させます。
- `INFERENCE_MODE=vision_loop` は逐次stroke寄りの評価モードです。元画像と現在キャンバスだけを見せますが、長いrunでは局所判断になりやすいです。
- `INFERENCE_MODE=grid` は実用変換用です。`GRID_FEEDBACK_PASSES` 回まで refinement を行い、低品質出力は失敗扱いにします。
- `INFERENCE_MODE=batch` は `BATCH_STROKES=16` などで複数 stroke をまとめて要求します。モデルの「迷い」を残しつつ、API call 数を減らせます。
- `INFERENCE_MODE=stroke` は旧方式です。`MAX_BRUSHSTROKES=256` でも最大 256 API calls になります。
- `SEND_IMAGE_EVERY_STEP=false` は `batch`/`stroke` モード用です。速くなりますが、2 request 目以降は画像を再送しないため品質が落ちることがあります。
- サーバは単一プロセス・単一 worker で動かしてください。内部 executor は `max_workers=1` で、推論を 1 run ずつ流します。

## ライセンス

このプロジェクトは MIT License で公開しています。詳細は [LICENSE](./LICENSE) を参照してください。

## 第三者アセット

絵文字から task を作成する際、ブラウザは Twemoji の SVG アセットを jsDelivr 経由で取得します。Twemoji のコードは MIT License、グラフィックは CC-BY 4.0 で公開されています。

https://github.com/twitter/twemoji

ai-pixel-art-converter

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README