Files

T

るみなー先生 09e717ea00 仕様: 出力ディレクトリ処理とファイル連番の仕様書を追加し、関連するドキュメントを更新

機能: Windows形式のドライブ相対パスを拒否し、連番の予約処理を原子的に実装
テスト: 出力ディレクトリとファイル連番に関するユニットテストを追加
バージョン: 0.1.3に更新

2026-08-24 19:37:41 +09:00

9.1 KiB

Raw Permalink Blame History

ComfyUI-GMImageSaver

English | 日本語

ComfyUI用の、GraphicsMagickを利用した画像保存ノードです。

最初に収録されている GM Image JPEG Save は、JPEG保存に特化した出力ノードです。ComfyUIの IMAGE テンソルを中間PNGファイルへ書き出さず、GraphicsMagickへ直接ストリーミングしてJPEGへ変換します。プレビューや画像のパススルー出力は意図的に返しません。

特長

GraphicsMagickによるテンソルからJPEGへの直接変換
中間PNGファイルを作成しないため、不要なディスクI/Oを削減
JPEG専用、プレビューなしの出力ノード
JPEG品質、クロマサブサンプリング、プログレッシブ形式を設定可能
ファイル名やディレクトリ名へ任意のラベルを追加可能
日付、プレフィックス、ラベルを組み合わせたディレクトリ構成
任意の出力先ディレクトリに対応
長いプロンプトを含むUTF-8のJPEGコメントに対応
画像ごとにComfyUIのプログレスバーを更新
フロントエンド、localStorage、HandpickerSuiteへの直接依存なし

オプションの label 入力には ckpt_name_safe などのCheckpoint名を接続できます。HandpickerSuite自体へ依存せず、疎結合なワークフローを構成できます。

動作要件

GraphicsMagickを別途インストールし、ComfyUIを起動する環境の PATH から gm コマンドを実行できるようにしてください。

次のコマンドで確認できます。

gm version

GraphicsMagickのインストール後や PATH の変更後は、ComfyUIを再起動してください。

Windows

コマンドラインツールを有効にしてGraphicsMagickをインストールします。ComfyUIを起動する環境と同じPowerShellまたはコマンドプロンプトで、gm version が成功することを確認してください。

Linux

ディストリビューションのパッケージマネージャーからGraphicsMagickをインストールします。DebianまたはUbuntuの場合：

sudo apt install graphicsmagick
gm version

インストール

このリポジトリをComfyUIの custom_nodes ディレクトリへクローンし、ComfyUIを再起動してください。

cd ComfyUI/custom_nodes
git clone https://github.com/ruminar/ComfyUI-GMImageSaver.git

ノード：GM Image JPEG Save

JPEGファイルの保存のみを行うノードです。プレビューや入力画像のパススルーは返しません。プレビューが必要な場合は、画像テンソルを別のPreview Imageノードへ分岐してください。

必須入力

images: ComfyUIの IMAGE テンソルまたは画像バッチ
filename_prefix: ファイル名の接頭辞。既定値：image
directory_pattern: ディレクトリ構成。既定値：prefix/date
filename_date_format: ファイル名へ付加する日付形式。既定値：none
quality: 1～100のJPEG品質。既定値：80
subsampling: クロマサブサンプリング。既定値：4:2:2
progressive: プログレッシブJPEGを有効にするか。既定値：False

オプション入力

output_dir: 文字列ノードから接続する出力先のベースディレクトリ
label: Checkpoint名など、ファイル名とディレクトリ名へ追加するラベル
comment: JPEGのコメント領域へ保存する文字列

output_dir が未接続または空の場合は、ComfyUI標準のoutputディレクトリを使用します。相対パスは標準outputディレクトリの配下として解決され、絶対パスはその場所を直接使用します。親ディレクトリへの移動（..）を含む相対パスは拒否されます。C:foo や D:foo のようなWindows形式のドライブ相対パスも拒否されます。ComfyUIのoutput配下へ保存する場合は foo、絶対パスへ保存する場合は D:\foo のように指定してください。

JPEGコメントの処理

空でない comment が指定された場合、バッチごとにUTF-8の一時ファイルを1つ作り、GraphicsMagickへ -comment @<ファイル> の形式で渡します。これにより、GraphicsMagickのコマンドライン引数長制限や、Windowsの文字コード変換・コマンドライン長の問題を回避します。

一時ファイルはUTF-8、BOMなしで書き込みます。
BOM文字、NUL文字、不要な制御文字、不正なUnicodeサロゲート文字を除去します。
タブ、LF、CR、日本語、アクセント付き文字、絵文字は保持します。
コメントはUTF-8で最大65,000バイトとし、正しい文字境界で切り詰めます。
同じバッチの全画像で同じ一時ファイルを再利用します。
正常終了、失敗、タイムアウトのいずれでも削除を試みます。
コメントが未設定、空、または正規化後に空となる場合は一時ファイルを作りません。

GraphicsMagickはファイルから読み込んだコメントの改行をCRLFへ正規化し、末尾にもCRLFを追加します。行構造は保持されますが、入力とJPEG内コメントの完全なバイト一致は保証されません。

詳細な決定事項は .spec/comment-handling.md に記録しています。

ディレクトリパターン

directory_pattern は、output_dir の下に作成するディレクトリ構成を指定します。日付ディレクトリは常に yyyyMMdd 形式です。

選択可能なパターン：

none
date
prefix
prefix_date
prefix/date
label
label_date
label/date
prefix_label
prefix/label
prefix_label_date
prefix/label/date
prefix_date_label
prefix/date/label

入力例：

output_dir: D:\ComfyJPEG
filename_prefix: image
label: meinamix_v11
date: 20260601

生成されるディレクトリ：

none                -> D:\ComfyJPEG
date                -> D:\ComfyJPEG\20260601
prefix              -> D:\ComfyJPEG\image
prefix_date         -> D:\ComfyJPEG\image_20260601
prefix/date         -> D:\ComfyJPEG\image\20260601
label               -> D:\ComfyJPEG\meinamix_v11
label_date          -> D:\ComfyJPEG\meinamix_v11_20260601
label/date          -> D:\ComfyJPEG\meinamix_v11\20260601
prefix_label        -> D:\ComfyJPEG\image_meinamix_v11
prefix/label        -> D:\ComfyJPEG\image\meinamix_v11
prefix_label_date   -> D:\ComfyJPEG\image_meinamix_v11_20260601
prefix/label/date   -> D:\ComfyJPEG\image\meinamix_v11\20260601
prefix_date_label   -> D:\ComfyJPEG\image_20260601_meinamix_v11
prefix/date/label   -> D:\ComfyJPEG\image\20260601\meinamix_v11

label を含むパターンを使用する場合は、空でない label 入力が必要です。

ファイル名の日付形式

filename_date_format は、ディレクトリパターンとは独立してファイル名へ追加する日付部分を指定します。

none
yyyyMMdd
yyyyMMdd_HHmm

出力例：

image_0001.jpg
image_20260601_0001.jpg
image_20260601_1423_0001.jpg
image_meinamix_v11_0001.jpg
image_meinamix_v11_20260601_1423_0001.jpg

日時はノード実行時に一度だけ取得するため、同じバッチ内の画像には同じ日時部分が使用されます。連番は最低4桁になるようゼロ埋めされ、9999を超えて継続します。出力名は原子的に予約されるため、同時に保存する処理があっても既存JPEGを上書きせず、次の空き番号を使用します。

JPEG設定

既定値は画質とファイルサイズのバランスを重視しています。

quality: 80
subsampling: 4:2:2
progressive: False

保存・比較用途で高画質を優先する場合：

quality: 95
subsampling: 4:4:4

大量のCheckpointを確認する際にファイルサイズを抑える場合：

quality: 75～85
subsampling: 4:2:0

プレビューを使用する場合

このノードは意図的にプレビューを返しません。必要な場合は保存前に画像を分岐してください。

VAE Decode / IMAGE
  ├─ Preview Image
  └─ GM Image JPEG Save

開発・テスト

Python 3.10以降で次のコマンドを実行します。

python -m unittest discover -s tests -v

合意済みの仕様と退行防止条件は .spec ディレクトリに記録しています。

プロジェクトの範囲

将来的にGraphicsMagickを用いた他の保存ノードを追加できるよう、プロジェクト名をGMImageSaverとしています。現在のノードは意図的に次の範囲へ絞っています。

JPEG出力のみ
プレビューおよび画像パススルーなし
PNGサポートなし
ワークフローメタデータの自動注入なし
外部プロジェクトへの直接依存なし

PNGで保存する場合は、ComfyUI標準のSave Imageノードを使用してください。

ライセンス

GPL-3.0。LICENSE を参照してください。

9.1 KiB Raw Permalink Blame History Unescape Escape