# KANGOO COLOR STUDIO 編集ガイド

このアプリは HTML・CSS・JavaScript で動く静的なWebアプリです。Reactやビルド作業は不要です。

## ファイル構成

| ファイル | 変更する内容 |
| --- | --- |
| index.html | ページの文章、見出し、操作欄の構造 |
| style.css | 色・余白・文字サイズ・スマホの配置 |
| colors.js | 色名、メーカー、塗装コード、画像採色値、出典 |
| options.js | グレード別の外観、用品、画像のパスと切り出し範囲 |
| paint.js | 黄系の塗装部分を抽出し、陰影を残して色を置き換える処理 |
| paint-gpu.js | GPUによる2D画像の色変換。色変更はuniformのみ更新 |
| paint-worker.js | GPU非対応時に使う色変換Worker。連続した選択は最新へ集約 |
| app.js | 色検索、背景写真、ドラッグ・ピンチ、画像読み込み |
| assets/kangoo-front-v4.webp | 透過背景の車体画像 |
| color-candidates.json | 調査した未採色の候補。選択画面には出ません |

読み込み順は colors.js → options.js → paint.js → paint-gpu.js → app.js です。HTMLの末尾に指定しています。

## ローカルで確認する

編集用ソース ZIP を展開し、そのフォルダーで `python -m http.server 8000` を実行します。ブラウザで `http://localhost:8000` を開いてください。HTMLを直接ダブルクリックすると、ブラウザによってCanvasの画像処理に制限が出るため、ローカルサーバーを使います。

## 色を追加する

colors.js の既存の1項目をコピーし、重複しないキーを付けます。name（色名）、maker（メーカー）、code（塗装コード。未確認なら null）、hex（採色した #RRGGBB）、family（色系統）、finish（仕上げ）、scope（車種・世代）、source（掲載ページ）を変更します。メーカー・色系統の選択肢と色数は自動生成されます。

sample.image に画像URL、sample.box に採色矩形 [左,上,右,下]、sample.imageSize に元の幅と高さ、sample.method に採色方法を記録します。写真は塗装部分の中間的な明るさの領域を選び、窓・タイヤ・白い反射・強い影を避け、矩形のRGB各成分の中央値を使用しています。SVGの色見本はfillを抽出しています。PDFは指定幅で画像化したページの座標です。正確な色合わせには撮影条件を揃えた実車資料で再採色してください。

塗装コードと画面のHEXは別の情報です。コードをRGBへ換算した値ではありません。現在の39色は採色を実施した色のみで、カングーIIの歴代色32色と他メーカー7色を含みます。全色がIIフェーズ2に設定されたという意味ではありません。phase1限定色もscopeに分けて記録しています。codeSourceがある項目は塗装コードの確認資料です。code未確認の色に推測のコードを補わないでください。

## 車の画像を交換する

assets に新しい画像を入れ、index.html の car-fallback と options.js の base / bases / mask の該当パスを変更します。現在の処理は黄色い車体を対象にしています。別色の車体を使う場合、paint.js の色抽出範囲も変更するか、別途塗装マスクを作る必要があります。画像は同じサイト内へ置き、外部への直リンクは避けてください。

現在は標準5人乗りカングーIIフェーズ2をモチーフにしたAI生成画像です。実車写真のトレースや特定会社の車両を忠実に複製したものではありません。後席以降の窓は暗く、前側ガラスは透過感を残しています。3D回転やARは未対応です。

## 画像が表示されないとき

- assetsの画像名と大文字・小文字、HTMLとJavaScriptのパスを確認します。
- スマホでは style.css の viewer / canvas-wrap の高さが0にならないようにします。現在は最小高さを指定しています。
- ページの再読み込みとキャッシュ更新を試します。ファイルを変更したら index.html の `?v=8` を新しい番号に更新できます。
- Canvas準備前は通常のimgを表示します。色処理が失敗した場合も元の車体画像を表示します。

## 確認と公開

構文と操作ロジック（全色切替、検索、メーカー絞り込み、背景、倍率、画像処理失敗時）を確認済みです。iPhone / Android実機での操作確認は未実施です。公開前に実機で画面・ピンチ操作を確認してください。

このZIPには公開用の静的ファイルだけを含み、認証情報は含みません。変更後はこのSiteに反映するよう依頼するか、利用する静的ホスティングの手順で公開します。参考写真そのものの再配布は行っていません。採色元はリンクから確認できます。


## 前後・用品の追加（今回の更新）

options.js がグレード外観と用品の設定ファイルです。詳しくは EXTERIOR.md を参照してください。画像は assets/options/front と rear に分けます。同じ視点内では1536×1024の座標を揃えておきます。色は前後で共通です。HTML末尾の読み込み順は colors.js → options.js → paint.js → paint-gpu.js → app.js に更新しました。キャッシュ番号も ?v=8 です。

## 軽量化と画質（2026-09-29）

塗装範囲は画像ごとに一度抽出し、色変更時は再利用します。Web Workerで画素処理を別スレッドへ移し、対応しない環境では同じ計算をメインスレッドで実行します。画像のキャッシュは8点、色変換済み画像は2点が上限です。

用品は必要な範囲だけ切り出した画像をロスレスWebPで配信します。options.js のpositionは元画像座標 [x,y,width,height]、clipは元の1536×1024座標です。ミラーの透過マスクも元画像座標で適用します。画像を交換する際にpositionとclipを一緒に確認してください。

モデルの元解像度は1536×1024です。Retina表示は最大2倍のCanvas、高品質な縮小描画に対応します。無劣化圧縮へ変更しましたが、画像自体を4K化したわけではないため、大幅な拡大では元解像度の制約が残ります。iPad実機での速度・画質確認は未実施です。

## 応答速度の再改善

標準経路はWebGLによるGPU色変換です。色を選んだ時にCPUへ画素を読み戻したり、別スレッドへ画像全体を送り直したりせず、色のパラメーターのみ変更します。車体は従来と同じ2D画像です。WebGLが使えない、またはコンテキストが失われた場合はWorker／Canvasへ切り替えます。大きな性能問題があるWebGL実装は初期化時に避けます。

現ビューのルーフ用品3点を空き時間に先読みします。初回通信・画像デコードの時間は回線と端末に依存します。GPU処理はEGL上で実画像を描画し、CPU版との差が8bit値で最大2以内、alpha一致を確認しました。この環境はソフトウェア描画のため、iPad等の実GPU速度の測定値ではありません。

共有・外部公開についてはSHARING.mdを参照してください。source.zipは一般の静的Webサーバーへ配置できるHTML一式です。