image-to-svg

画像からSVGへ

ラスター画像を、各視覚要素を個別に分解し、観察して再構築することで、高品質なSVGとして再現します。

基本原則

画像全体を一度に再現しようとしないでください。 品質を高めるには、各要素を切り分け、切り抜いた参照画像と照らし合わせて詳しく観察し、合成する前に単独のSVGとして作成します。

速度より正確さを優先してください。 このワークフローでの近道は、どれも最終出力の品質低下につながります。切り抜きの確認をまとめて行う、プログラムによるチェックを省略する、測定せず目視で座標を決める、差分を実行せず「だいたい合っている」で済ませる。どれも1分の節約にはなりますが、手戻りに10分かかったり、目に見えて品質の低い結果になったりします。このスキルの価値は、出力の品質にあります。各工程で時間をかけて確認してください。

使用する場面

• 画像（写真、イラスト、AI アート）をSVGに変換する
• ロゴ、マスコット、アイコン、アートワークのベクター版を作成する
• 画像から特定の要素を抽出し、拡大縮小可能なグラフィックにする
• ユーザーが参照画像を提示し、SVGでの再現を希望している

手順

ラスター画像をSVGとして再現します。以下のフェーズを順番に実行してください。

このスキルでは段階的な調査を行います。参照ファイルは、このスキルに隣接するサブディレクトリ（analysis/、features/、styles/、workflow/）にあります。特定のフェーズや条件で必要になった場合にのみ読み込んでください。すべての参照ファイルを最初にまとめて読み込まないでください。

フェーズ0：環境のセットアップ

workflow/workflow-dependencies.mdを読み、依存関係チェックのスクリプトを実行します。必要なツール（magick、rsvg-convert、xmllint）が利用可能であることを確認します。任意のツール（vtracer、svgo）の利用可否も確認し、どの機能強化が可能かを記録します。

vtracerがインストールされておらず、Pythonを利用できる場合は、仮想環境を作成する前に、どこに作成するかをユーザーに尋ねてください。3つの選択肢（プロジェクトローカル、共有スキル venv、ユーザー指定）については、依存関係のファイルを参照してください。

フェーズ1：画像を分析する

初期分析 — これらは互いに独立しています。各項目に集中できるよう、並列サブエージェントに委任してください。

1. アートスタイルを特定します。 サブエージェントを起動し、styles/styles-identification.mdを読んで画像を調査し、スタイルの分類とその根拠（線の描き方、形状の特徴、色の扱い、詳細度）を報告させます。特定したスタイルをもとに、後の工程で使う手法を決めます。
2. 観察の枠組みを作成します。 サブエージェントを起動し、analysis/analysis-asking-questions.mdを読んで画像を調査し、重要な観察項目への回答を報告させます。特に、複雑な物体の「構成」と「構造」に関する質問を重視してください。この報告を分解工程で活用します。
3. 透明度に対応します。 プログラムで確認します：magick identify -format "%[channels]" original.png。srgbaなどのアルファチャンネルが報告された場合、最終SVGでも透明な背景を維持するのか（絵文字やステッカーでよくあります）、単色で塗りつぶすのかを記録します。

分解 — 上記の観察の枠組みに基づいて行います。

4. 要素に分解します。 analysis/analysis-identifying-concepts.mdを読み、画像を独立した視覚要素に分解し、描画順（レイヤースタック）を決めます。

並列準備 — 以下の項目はすべて手順4で作成した要素リストに基づきますが、互いに独立しています。並列で実行してください。

5. 参照用の切り抜きを作成して確認します。 analysis/analysis-reference-crops.mdを読み、すべての要素のバウンディングボックスを記したfeature-locations.ymlを作成してから、すべての要素を一度に切り抜きます。すべての切り抜きに対し、プログラムで端の余白をチェックしてください — ここが最もよく失敗するポイントです。チェックに失敗した切り抜きは、YAMLを修正して再度切り抜いてください（画像を見て座標を推定し直さないでください）。次に、各切り抜きを1つずつ目視で確認します（まとめてではなく、Readを1回につき1つ）。切り抜きが欠けているものがある状態で、作成フェーズに進まないでください。

6. 座標をプログラムで測定し、マッピングします。 測定パイプラインについては workflow/workflow-verification.md を読んでください。特徴の座標を目測してはいけません。小さな推定誤差が特徴ごとに積み重なり、プロポーションが崩れてしまいます。

   • キャンバスサイズを決定します（絵文字／アイコンの標準は512x512です。それ以外の対象では元画像のアスペクト比を使用してください）
   • ImageMagickを使用して元画像の寸法を測定し、キャンバスに合わせる拡大縮小率を計算します
   • プロポーションの基準点を特定します。測定する重要な点を3～5個選びます（例：「キャラクターの高さの35%に頭の中心、52%に顎、95%に足」）。絶対ピクセル数ではなく比率で表してください。比率ならキャンバスへのマッピング後も変わりません。
   • 元画像から測定し、キャンバス座標に拡大縮小して、各特徴のバウンディングボックスを計算します
   • 特徴間の関係を記録します。個々のバウンディングボックスだけでなく、特徴同士の関係も記録してください。「口の幅＝顔の幅の55%」「ブーツの間隔＝胴体の幅の15%」「耳が帽子のつばから20%はみ出す」など、こうした相対的な測定値が、特徴を個別に作成したときにも適切なプロポーションを実現します。
   • 測定した座標、プロポーション比、特徴間の関係、重ね順を含めて特徴マップを記録します。このマップは、スウォーム内のすべてのエージェントに共有されます。

7. 対象の概要を作成します。 対象の性格、表情、全体的な雰囲気を2～3文で説明します（「満面の笑みを浮かべ、腕を誇らしげに組んだ、いたずら好きで自信に満ちたゴブリン」など）。この定性的な説明は測定値とともにすべてのエージェントに共有されます。形状だけでなく、対象の雰囲気をエージェントに伝えるためです。これがないと、エージェントが技術的には正確でも、そのキャラクターらしさに欠ける特徴を作成してしまいます。

切り抜きの確認後（先に手順5を完了してください）：

8. 切り抜きからトレースメタデータを抽出します。 vtracer が使用可能な場合は、workflow/workflow-trace-metadata.md を読んでください。各特徴の切り抜きをポリゴンモードで自動トレースし、構造化メタデータ（カラーパレット、サブ要素の位置／サイズ、面積の割合、トポロジーのヒント）を抽出します。これにより、ラスタ画像から色や位置を目測する必要がなくなり、エージェントに正確な数値データ（特徴あたり約130トークン）を提供できます。トレースメタデータを特徴マップの各特徴の項目に追加してください。

   vtracer が使用できない場合は、ImageMagickによる色抽出に切り替えます：

   magick refs/{feature}.png -resize 200x200 -kmeans 10 -unique-colors txt: | tail -n +2 | tr -s ' ' | cut -d' ' -f3
   

   これにより正確な16進数カラー値を取得できますが、サブ要素の空間データは得られません。

フェーズ2：各特徴を構築する（エージェントスウォーム）

スタイルを特定し、参照用の切り抜きを確認し、特徴マップを作成したら、エージェントスウォームで特徴を構築します。各特徴は独立しているため、それぞれが独自の参照用切り抜きを使い、別々のエージェントが並行して構築できます。

キャラクター／顔の画像

キャラクターまたは顔の画像では、各要素を構築する前に、features/ にある該当する特徴リファレンスシートを読んでください。

特徴	リファレンスファイル
目	features/features-eyes.md
口	features/features-mouth.md
鼻	features/features-nose.md
耳	features/features-ears.md
顔の形	features/features-face-shape.md
髪	features/features-hair.md
体	features/features-body.md
アクセサリー	features/features-accessories.md
複雑なオブジェクト（持ち物、小道具）	features/features-objects.md

画像に含まれる特徴のリファレンスシートだけを読んでください。

キャラクター以外の画像（風景、ロゴ、オブジェクト、抽象表現）

features/ のリファレンスシートはキャラクターに特化しています。それ以外の題材では、代わりに視覚的なレイヤーごとに分解してください。

• ロゴ／アイコン： 背景の形状、主要なシンボル、テキスト（トレースしたパスとして作成してください。フォントが一致しないため、<text> 要素は使用しないでください）、二次的な要素、境界線／フレーム
• 風景／場面： 空／背景、遠景、中景、前景、焦点となる題材、大気の効果（霧、光線）
• オブジェクト／製品： 構造的な分解について詳しくは features/features-objects.md を読んでください。オブジェクトには内部構造、複数の見える面、シルエット＋塗りつぶしをはるかに超える遠近感の複雑さがあります。色の領域だけでなく、構造パーツ（パネル、リブ、継ぎ目、ハンドル）ごとに分解してください。
• 乗り物／機械： features/features-vehicles.md を読んでください。乗り物はパネルの集合体です。車体パネル、ガラス、ホイール、ライト、トリムごとに分解してください。パネルの線と金属光沢のグラデーションが重要です。
• 食べ物／飲み物： features/features-food.md を読んでください。形状を組み立てる手法に加え、光沢のあるハイライト、層状の構造、蒸気／香りの効果を使用してください。
• 植物／花： features/features-plants.md を読んでください。<use> と rotate を使った放射状の花びらの対称性や、葉脈のクリッピングを使用します。
• 抽象表現／パターン： ベースレイヤー、繰り返しモチーフ（可能な場合は <pattern> または <use> を使用）、アクセント要素、オーバーレイ効果
• 複合画像： 画像に複数のカテゴリ（風景の中でキャラクターがオブジェクトを持っている場合など）が組み合わさっている場合は、焦点となる題材の分解を主軸とし、二次的な要素はより簡潔に扱ってください。

同じ原則が適用されます。要素ごとに切り抜きを1つ、レイヤーごとに独立したSVGを1つ用意し、合成表示と同じviewBoxを使用してください。各要素について analysis/analysis-asking-questions.md を読んでください。形状、色、位置に関する質問はどの要素にも共通です。

表情を左右する重要な特徴

キャラクターの個性やオブジェクトの識別性を決定するため、特に重要な特徴があります。これらは比較の厳密さをさらに高め、合成に進む前に、反復回数を増やし、プログラムによる差分検証を行い、並べて比較してください。

• 口／笑顔 — 表情を決定する最大の要素です。曲率、幅、口角の上がり具合を正確に合わせる必要があります。
• 視線 — 瞳孔の位置とハイライトの配置によって、キャラクターがどこを見ているか、どのような「印象」になるかが決まります。
• 全体のプロポーション — 頭と体の比率、立ち姿の幅、手足の長さです。ここがずれていると、どれだけ細部を描き込んでも結果は改善しません。
• 特徴的な要素 — 特定の題材を見分ける手がかりになるもの（特徴的な帽子、特定のロゴ、独自のシルエットなど）です。

これらの特徴については、必ずプログラムによる差分検証（下記の「レンダリングと比較のループ」を参照）を実行し、差分スコアが収束するまで反復してください。3回を超える場合も同様です。

各パーツの作成

各パーツについて、以下を行います。

1. 切り抜いた参照画像を単独で確認し、さらに全体の比率を把握するために元の画像全体も確認します
2. analysis/analysis-asking-questions.md の質問を自分に問いかけます
3. 隠れている部分を考慮します — パーツの一部が別のパーツに隠れている場合（帽子の下にある頭、髪の下にある顔など）、隠すパーツの下までレイヤーを延ばします。詳しくは以下の「隠れたコンテンツの処理」を参照してください。
4. parts/ に単独の SVG として作成します
5. 適切なアートスタイルのテクニックを適用します — イラスト／カートゥーンスタイルについては styles/styles-line-and-brush.md を、フラット／幾何学スタイルについては styles/styles-geometric.md を、写真風／リアルな画像については styles/styles-applying-to-lifelike.md を読みます。Phase 1 で特定したスタイルに対応するファイルのみを読んでください。
6. 必ず styles/styles-curves-and-shapes.md を読みます。曲線の構築テクニックは、すべてのスタイルに適用されます。適切な SVG パスコマンドを使った形状の作り方、塗りつぶしと線の使い分け、有機的な曲線の構築方法について説明しています。これは「どのように見せるか」と「SVG でどう構築するか」をつなぐものです。
7. レンダリングして比較します — 以下の「レンダリングと比較の反復」を参照してください

単純な幾何学図形よりも複雑な構築を優先してください（幾何学／フラットスタイルと特定された画像を除きます。その場合は styles/styles-geometric.md に従ってください）。適切な幅の変化、パネルごとのライティング、構造的なディテールを加え、三次ベジェ曲線で作成した塗りつぶし形状は、線で囲んだ円よりも常に価値のある仕上がりになります。参照画像が本当に完全な幾何学形状を示している場合、またはスタイルが明確にフラット／幾何学的な場合にのみ、SVG のプリミティブ（<circle>、<rect>、<ellipse>）を使用してください。迷った場合は、より複雑なバージョンを作成してください。視覚的な品質には大きな差が生まれます。

エージェントの並列作業

1つの特徴 = 1つの SVG = 1つのエージェントです。例外はありません。 ごく単純な特徴（2つの点だけの鼻、きらめき、小さなバッジなど）にも、それぞれ専用のファイルと専用のエージェントを用意します。エージェントを追加するコストは低い一方、合成時や将来のアニメーションでパーツが結合していることによるコストは高くなります。

対になる特徴は必ず分けます。 左目と右目は、それぞれ別のエージェントが別々の SVG を作成します。左右の耳、左右のブーツ、左右の腕も同様です。整合性は配置調整フェーズ（フェーズ 3）で確認します。整合性を担保するのはそこであり、1つのエージェントに両方を作らせることではありません。

身体のパーツは独立させます。 腕は胴体とは別にします。脚もそれぞれ別にします。頭は首とは別にします。それぞれのパーツが後で個別に動く可能性があるものとして考えてください。たとえば、体が静止したまま腕が動いたり、片方の耳だけが揺れたりすることがあります。

特徴が5つあれば、5つのエージェントを起動します。特徴が50個あれば、50のエージェントを起動します。並列化することが目的です。各エージェントには次のものを渡します。

• 担当する特徴の参照画像の切り抜き
• 元画像全体 — 切り抜きは細部の確認用、元画像全体は比率を把握するためのものです。口を作るエージェントは、顔全体を見なければ笑みの幅が十分か判断できません。
• フェーズ 1 のステップ 7 で作成した 対象の概要 — 目標とする個性、表情、雰囲気
• 特定したアートスタイルの説明
• 関連する特徴のリファレンスシート（features/ 内）
• 関連するスタイル技法のファイル（styles/styles-line-and-brush.md、styles/styles-geometric.md、または styles/styles-applying-to-lifelike.md）
• 曲線の構築に関するリファレンス（styles/styles-curves-and-shapes.md）— 必ず含めます
• 検証パイプライン（workflow/workflow-verification.md）— 必ず含めます
• フェーズ 1 のステップ 6 で作成した 測定座標、比率の基準点、特徴間の関係を含む特徴マップ
• フェーズ 1 のステップ 8 で作成した、この特徴の トレースメタデータ（カラーパレット、サブ要素の位置とサイズ、トポロジー）— 利用できる場合

特徴は定性的ではなく、定量的に説明します。 エージェントに指示するとき、テキストによる説明では視覚的なニュアンスが失われます。「幅広い笑み」では正確な曲率が伝わらず、「厚いひさし」も曖昧です。代わりに測定値を使います。「口の幅 = 顔の幅の 55%」「ひさしの高さ = 帽子の高さの 5%、ドームの曲線に沿う」のように指定します。形容詞は曖昧ですが、比率は正確です。

• この特徴が 表情に不可欠かどうか（上記を参照）。該当する場合、エージェントはプログラムによる差分確認のループをすべて実行します。
• 単独の SVG を parts/{feature-name}.svg に書き出す指示

すべてのエージェントは、合成キャンバスと同じ viewBox を使用する必要があります（例：viewBox="0 0 512 512"）。各エージェントは、特徴マップのバウンディングボックスを使い、キャンバス全体の座標内に担当する特徴を配置します。これにより、合成時にサイズを変更しなくてもパーツを揃えられます。

相互に関係する特徴（例：顔と耳、髪と帽子）は記録しておきますが、別々に作成します。相互の調整はフェーズ 4 で行います。密接に関係する特徴（耳と顔の輪郭、髪と帽子のひさし）については、境界の位置がわかるよう、隣接する特徴のバウンディングボックスも含めます。

レンダリングと比較の反復ループ

検証パイプラインの全容については、workflow/workflow-verification.md をお読みください。重要なのは、視覚的な比較だけに頼らないことです。LLM は致命的なエラーを見つけるのは得意ですが、微妙な比率や曲率の違いを検出するのは苦手です。プログラムによる差分でエラーを正確に見つけ、その解釈と修正に LLM を活用してください。

SVG を変更するたびに、次の手順を実行します。

1. レンダリング前に SVG XML を検証します。

   xmllint --noout parts/{feature}.svg
   

   閉じていないタグ、不正な属性、名前空間の不足を明確なエラーメッセージで検出できます。rsvg-convert の不可解なエラーよりも、はるかに役立ちます。

2. SVG を PNG にレンダリングします。

   rsvg-convert -w 512 -h 512 parts/{feature}.svg -o parts/{feature}.png
   

   rsvg-convert がインストールされていない場合は、インストールしてください（macOS では brew install librsvg、Linux では apt install librsvg2-bin）。

3. プログラムによる差分 — レンダリングした特徴部分と参照画像の切り抜きを比較する、視覚的な差分画像と数値スコアを生成します。ImageMagick のコマンドについては、workflow/workflow-verification.md を参照してください。差分画像では、SVG の相違箇所が正確にハイライトされます。赤い領域は、最も大きな違いを示します。

4. 差分画像を読み取る — ハイライトされた違いを参考に修正箇所を決めます。これは、見た目が似ている 2 つの画像を比べるよりもはるかに効果的です。ImageMagick がエラーを正確に検出し、それを解釈して SVG の修正方法を判断できます。

5. 目視による確認 — 定性的な評価（色、全体的な印象、細部）のために、レンダリングした PNG と参照画像の切り抜きも確認します。

6. 反復 — 差分でハイライトされた最優先の問題を修正し、再レンダリングして、もう一度差分を取ります。これを繰り返します。

反復を終了するタイミング： 通常の特徴部分では、調整を 3～5 回までにします。表現上重要な特徴部分（口、目、全体の比率）では、最大 10 回まで続けてください。キャラクターを形作る部分であり、追加の反復を行う価値があります。

収束の目標（RMSE、0～1 に正規化）：

• 表現上重要な特徴部分：RMSE < 0.15 を目標とします
• 標準的な特徴部分：RMSE < 0.25 で許容範囲です
• 背景／単純な塗りつぶし：RMSE < 0.30 で許容範囲です
• 連続する 2 回の反復で改善幅が 0.02 未満になったら停止します。改善効果が薄れている状態です

これらはガイドラインであり、厳密な合格基準ではありません。RMSE 0.18 でも見た目が正しければ完了です。RMSE 0.12 でも見た目が違うなら、別の方法を試してください。数値よりも差分画像を信頼してください。

隠れた部分の扱い

ある特徴部分が別のレイヤーに部分的に隠れている場合：

• 下にある形を想像します。 帽子をかぶった頭にも頭頂部はあります。最終的な合成画像では見えなくても、帽子の下に隠れる位置まで頭の形を伸ばしてください。
• 簡略化しても、省略はしません。 隠れた部分に細部をすべて描く必要はありませんが、形状は連続させてください。これにより、合成時にレイヤーがずれた場合でも、鋭い縁や隙間が生じるのを防げます。
• 完全な形として考えます。 顔のパスは完全に閉じた曲線にしてください。帽子のつばの位置で途切れる形にはしません。

フェーズ 3：クラスの整合性調整（エージェントの群れ）

すべての特徴を個別に作成したら、対になる特徴や繰り返し登場する特徴の一貫性を確認します。エージェントの群れで対応します — 類似した特徴のクラスごとにエージェントを 1 つ割り当てます。

「クラス」とは、同じ構築スタイルを共有するべき特徴のグループです。

• 目のクラス — 左目 + 右目
• 耳のクラス — 左耳 + 右耳
• ブーツ／靴のクラス — 左ブーツ + 右ブーツ
• 腕のクラス — 左腕 + 右腕（ポーズに両方が描かれている場合）
• その他の繰り返し要素 — 例：自転車の両輪、建物の複数の窓

複数の被写体が写っている画像では、クラスは被写体ごとに分けます。「キャラクター A の目」と「キャラクター B の目」は別々のクラスです。

各整合性調整エージェントには、両方の SVG、両方の参照画像の切り抜き、元画像全体を渡し、次の点を確認させます。

1. 輪郭の線幅 — 対になる特徴に同じ線幅またはオフセット手法を使用していますか？（個別のエージェント間で最もずれやすい点です）
2. 絶対的なサイズ — 同じサイズですか、それとも参照画像に合わせて意図的に異なっていますか？
3. 塗りつぶし色 — 両方でまったく同じ 16 進数の値を使用していますか？
4. 構築手法 — 一方は楕円を使い、もう一方はパスを使っていませんか？寸法が同じでも、見た目に一貫性がなくなります。
5. ハイライトの数と位置 — ハイライトは最も「創造的」な部分であり、エージェント間でばらつきやすい要素です。
6. 位置の比例関係 — 「両目が顔の中心から等距離にあるべき」といった確認です。

整合性調整エージェントは、意図しない不一致を正規化し、対になる特徴を一致させます。その際、参照画像にある意図的な非対称性は維持します（例：参照画像で実際に目の大きさが異なる場合は、そのままにします）。

フェーズ 4：合成と反復

workflow/composition-bringing-layers-together.md を読んでください。

このフェーズは必須です。 最初の組み立てが最終成果物になることはありません。個別に作成した特徴には、必ず比率や位置合わせの問題があり、コンテキストに配置して初めて明らかになります。

1. 組み立て — 個別の SVG を合成画像にまとめます
2. エフェクトの適用 — 必要に応じて、<clipPath>、<mask>、<filter> について styles/styles-effects.md を読んでください
3. 合成画像と元画像の差分を確認 — workflow/workflow-verification.md に記載されている、画像全体を対象にしたプログラムによる差分を使用します。これにより、合成画像が元画像と異なる箇所を正確に確認できます。
4. 差分から上位 3 件の不一致を特定 — 通常は比率の誤り（頭が小さすぎる、特徴がずれている）、表情の不一致（口のカーブ、視線の方向）、または重なりの問題（帽子の位置が不適切、手足の重なりが正しくない）です。
5. 各不一致を修正 — 対象を絞った修正を特徴のエージェントに依頼するか、合成 SVG を直接修正します。修正のたびに再レンダリングして差分を再確認します。
6. 合成画像の差分が安定するまで繰り返す — 少なくとも 2 回は合成画像を反復し、表情に関わる重要な特徴に問題がある場合はさらに繰り返します。
7. 最終的な小サイズでの確認：

   rsvg-convert -w 64 -h 64 final.svg -o /tmp/small-check-64.png
   rsvg-convert -w 128 -h 128 final.svg -o /tmp/small-check-128.png
   

   両方のレンダリング結果を確認してください。アイコンサイズでも明瞭に見えますか？512px では問題なく見えた特徴も、重なってひとつになったり、消えたりすることがあります。

フェーズ 5：納品

想定されるプロジェクトの構成については、workflow/workflow-file-structure.md を読んでください。

1. 最終 SVG を最適化します。 svgo が利用できる場合は、名前付きグループを保持するために cleanupIds を無効にして実行してください。

   svgo final.svg -o final.svg \
     --config='{"plugins":[{"name":"preset-default","params":{"overrides":{"cleanupIds":false,"collapseGroups":false,"convertShapeToPath":false}}}]}'
   

   通常、見た目を変えずにファイルサイズを 25～40% 削減できます（数値精度、デフォルト属性、パスコマンドの最適化）。svgo が利用できない場合は、この手順を省略してください。SVG はそのままでも有効です。

2. 今後の編集に備えて、個別の SVG を含む parts/ ディレクトリを保持します

3. 最終的な合成 SVG を提供します

4. 比較用に、指定の解像度で PNG をレンダリングします