852wa-ComfyUI-ColorshiftColor/README.md

ColorshiftColor & CsCPaletteEditor

これは何？

これはComfyUIのカスタムノードです。

このフォルダーをComfyUIの custom_nodes/ComfyUI-ColorshiftColor に配置し、ComfyUIが使用しているPython環境で依存パッケージをインストールしてからComfyUIを再起動してください。

python -m pip install -r requirements.txt

• 指定数で減色して色相/彩度/輝度の変更を行う
• 各パラメーターのランダム指定可能
• 色番号でマスク（色を変えない）のオンオフ可能
• マスクの反転がオンオフ可能
• カラーのマスク出力が可能
• 影をベタ塗りで潰し、影のみ透過画像で出力可能
• 影と塗りつぶしのペア指定可能

以上の機能を実装したシンプルなノードです。

• lock_color_num パレットのプレビューで割り振られた番号を,カンマで入力することでマスクに指定できます。

連番対応

operations に以下のように入力すると、パレットの色を指定できます。RGBは各成分0〜1です。複数の指定はカンマで区切ります。

[
  {"index": 0, "color": [0.0, 0.0, 1.0]},
  {"index": 1, "hsv": [0.5, 1.0, 1.0]}
]

hsv も各成分0〜1で、色相1周が1です。同じ指定に color と hsv がある場合は hsv を優先します。空欄または [] で個別指定を解除できます。行頭の ## でその行を無効化でき、付属ワークフローの記入例も使用できます。

lock_color_num は、mask_enable がオンのときに元画像を保護する色番号です。保護色には全体のHSV調整が適用されません。operations で明示した色は保護色でも出力パレットに反映されますが、保護された画像の画素は元のままです。指定色を画像にも反映したい場合は、その色を保護対象から外してください。

単色バック動画を作りたい場合video combineで出力するとエンコードでノイズが乗ることがあるのでsave imageで連番保存したほうが良いです。

減色・マスク・再現性

• ColorshiftColor に seed を追加しました。同じ入力・設定・実行環境では同じ減色結果を再現できます。CsCPaletteEditor のランダム設定にも既存の seed が正しく適用されます。ComfyUI側のseed設定を固定すると繰り返し実行でも同じ値になります。
• sampling_rate は元画像の画素を抽出する割合です。抽出数は最大262,144画素、最小は指定色数（画像の画素数を上限）です。サンプル内の色数が少なければ、パレットは color_count より少なくなります。単色画像や1ピクセル画像も処理できます。
• 自動パレットは画像全体での占有率の高い順です。palette_override を接続した場合は入力パレットの順序を保ちます。連番で色番号を揃えたい場合は、共通のパレットを palette_override に接続してください。
• lock_masks は通常の空間マスクです。白（1）は元画像を保持、黒（0）は減色、灰色はその割合で混合します。サイズが異なるマスクは画像サイズへ補間します。1枚のマスクは全画像へ適用し、バッチ枚数が不足する場合は最後のマスクを繰り返します。
• index_maps はパレット番号を格納した専用のマップです。既存接続との互換性のため端子型は MASK のままですが、通常の0〜1マスクとして扱ったり、ぼかし・補間を加えたりせず、編集・塗りつぶしノードへ直接接続してください。lock_masks には CsCPaletteEditor の通常の mask 出力を接続できます。
• 画像入力はRGBの [batch, height, width, 3] です。処理は入力画像のCPU/GPUと画像の浮動小数点型を維持します。パレットはfloat32、番号マップは整数型、プレビュー画像はCPUで生成します。パレットのクラスタリング自体はCPUで実行します。

CsCFill

塗りつぶしと影分離ノード
通常は近似値をペアにし、塗りつぶし色Aと影色Bを確定させますが、[]内に
{ "A": 0,"B": 1 }
という文字列を記載することで、AでBを塗りつぶすという指定挙動をします。数字はパレットプレビューの数字です。

手動指定では明暗にかかわらず BをAで置換します。空欄または [] のときだけ、近い色を自動で組み合わせて暗い色を明るい色で置換します。同じBを複数回指定した場合は最後の指定を採用し、AとBが同じならその色は変更しません。影画像はRGBAで、置換対象の元パレット色だけを不透明、それ以外を透明で出力します。

改善内容と互換性

• パレットを直接書き換えて、上流ノードや次回実行へ編集内容が残る不具合を修正しました（Issue #3）。
• seedの無視、他の処理への乱数状態の干渉、空間マスクの実行エラー、少数画素・少数色での減色失敗、GPUとCPUの混在によるエラーを修正しました。
• 最近傍色の検索を分割し、通常のパレットでは一時的な距離行列を最大約16MiBに抑えました。塗りつぶしも色の対応表を使って一括処理します。
• 明るいパレット色の番号を黒文字にし、番号の位置を調整しました。
• パレットプレビューで全色の番号が左上の1マスに重なって描画される不具合を修正しました。Arialがない環境（macOS / Linux）でも font_size が反映されます。
• 不正なJSON、色番号、色成分、番号マップは理由付きエラーで知らせます。以前のような黙った無視や、無効な手動指定から意図しない自動塗りつぶしへの切り替えは行いません。

ノード名、既存の入出力端子、既存ウィジェットの順序は維持しています。新しい減色seedを省略した既存の呼び出しでは0を使います。抽出方法と乱数処理の修正により、旧版と減色結果・パレット番号が変わることがあります。プレビューを確認し、必要なら保護色・手動ペアの番号を更新してください。

開発用テスト

python -m unittest discover -s tests -v

ComfyUI本体なしで実行できます。CUDAが利用できる環境ではGPU・float16・bfloat16も検証し、それ以外ではGPUテストのみスキップします。GitHub ActionsにLinux / WindowsのCPUテストを追加しています。

update

26.09.26 - パレットプレビューの番号表示を修正（全番号が0番のマスに重なっていた）、macOS/Linuxでのフォントサイズ対応、テスト用GitHub Actionsを追加
25.02.01 - mask機能の修正、CsCノードの高速化、exampleデータの見直し
25.02.01 - パレットインデックス順を画面占有率でソート、塗りつぶしと影分離のノードを追加、exampleの見直し