🌐 [English](TechnicalExplanation.en.md)|**日本語**
# 技術的な説明

Vectrace の処理は、単なる 2 値化（白黒変換）の延長ではなく、「色の集約」「レイヤー分離」「形状の正規化」「ベクター化」という 4 つのフェーズで構成されています。



## 1. 色の解析とクラスタリング (Color Clustering)

まず、画像に含まれる膨大な色を、計算可能な数（最大 256 色）に集約します。

- 色の走査: 画像の全ピクセルを確認し、アルファ値（透明度）や白色（背景）を除外します。

- 知覚的距離による統合: colorDistance 関数を用い、人間の目の感度（Luma: R=29.9%, G=58.7%, B=11.4%）に基づいた重み付けで色の近さを判定します。

- 平均色の算出: 似た色を 1 つの「クラスター」にまとめ、そのグループに含まれる全ピクセルの平均 RGB 値をレイヤーの代表色として決定します。これにより、元画像のニュアンスを維持します。



## 2. レイヤー分離とベース層の抽出 (Layer Separation)

抽出した色ごとに「ビットマップ（塗りつぶしエリアの情報）」を作成します。

- カラーレイヤー: 各ピクセルを、最も距離が近い代表色のビットマップへ振り分けます。

- ベースレイヤー（輪郭）: -k (閾値) フラグに基づき、画像内の暗い部分を抽出した特別なレイヤーを作成します。「抽出範囲の平均色」にする（または -K で黒にする）ことで、境界の馴染みを良くしています。

- 背景シルエット: 画像全体の不透明領域を網羅した「白い下地」を作成し、最背面に配置します。  
生のビットマップデータには「孤立点」や「ジャギー」が含まれるため、トレース前に形状を整えます。



## 3. モルフォロジー演算によるノイズ除去 (Image Enhancement)
生のビットマップデータには「孤立点」や「ジャギー」が含まれるため、トレース前に形状を整えます。
-  膨張 (Dilation) と 収縮 (Erosion): `dilateBitmap` と `erodeBitmap` を実行し、ビットマップの隙間を埋めたり、鋭利なノイズ（ジャギー）を抑制したりします。

- 適応型パス回数: レイヤーの面積比率に応じて処理回数を動的に変更します（面積が大きいほど平滑化を強くする）。  
これにより、細かいディテールを保護しつつ、大きな塗りつぶし面のノイズを除去します。



## 4. 並列トレースと SVG 合成 (Vectorization & Compositing)

最後に、各ビットマップをベクターパスに変換し、重ね合わせます。

- 並列処理: errgroup を使用し、全レイヤーのトレースを CPU スレッドをフル活用して並列実行します。

- Z-Order（重なり順）の制御:
  1. 最背面：白い背景シルエット
  2. その次：ベースレイヤー（輪郭線）
  3. 前面：カラーレイヤーを **面積が大きい順に描画**（大きな塗りの上に、小さなパーツを重ねることでディテールを維持）

- SVG 結合: 各レイヤーを vectrace.Render で SVG 断片化し、1 つの `<svg>` タグ内にグループ（`<g>`）として結合・出力します。


このように、「色の統計的な集約」と「レイヤーごとの形状補正」を組み合わせることで、複雑なカラー画像も破綻の少ないベクターデータへ変換しています。
