コンテンツにスキップ

既存画像へのテキスト追加 (AddTextToExistingImage)

概要 (What is it?)

AddTextToExistingImage ノードは、既存の画像の上にテキストをオーバーレイ配置します。アルファ値（透過度）を含むテキスト色や背景色、配置アライメント制御、辞書入力から展開される {key} 形式のシンプルなテンプレートプレースホルダーをサポートしています。

使用する場面 (When would I use it?)

以下のような場面でこのノードを使用します：

  • 画像にタイトル、キャプション、またはラベルを追加したい場合
  • メタデータ（ファイル名、タイムスタンプ、ID など）を画像にスタンプ（刻印）したい場合
  • 後続のステップ向けに注釈付きの画像出力を生成したい場合
  • 辞書から渡された値を使って動的なテキスト（{key} プレースホルダー）を描画したい場合

使い方 (How to use it)

基本セットアップ

  1. ワークフローに AddTextToExistingImage ノードを追加します
  2. 画像ソースを input_image に接続します
  3. text にテキストテンプレートを入力します
  4. （任意）{key} プレースホルダーを展開するために辞書を template_values に接続します
  5. アライメント、色、余白、フォントサイズを調整します
  6. ノードを実行して output を生成します

パラメータ一覧 (Parameters)

必須入力 (Required Inputs)

  • input_image: テキストを描画する対象の画像（ImageUrlArtifact / ImageArtifact / 辞書）

テキスト入力 (Text Inputs)

  • text（文字列）: 描画するテキストテンプレート
    • {key_name} 形式のプレースホルダーをサポートします
    • プレースホルダーの展開は画像上にレンダリングされるテキストにのみ適用され、text 出力パラメータには元のテンプレート文字列がそのまま保持されます
  • template_values（辞書、任意）: text 内のプレースホルダーを展開するために使用される値
    • プレースホルダーのキーが存在しない場合、レンダリングされたテキスト内にそのまま残ります
    • 不足しているキーはノード実行時に result_details にも報告されます

スタイルパラメータ (Styling Parameters)

  • text_color（16進数RGBA、デフォルト: #ffffffff）: アルファ値を含むテキストの色
  • text_background（16進数RGBA、デフォルト: #000000ff）: テキスト背後の背景矩形の色（アルファ値含む）
  • text_vertical_alignment（top | center | bottom、デフォルト: top）: テキストブロックの垂直方向の配置
  • text_horizontal_alignment（left | center | right、デフォルト: left）: テキストブロックの水平方向の配置
  • margin（整数、デフォルト: 10）: テキスト配置時の画像端からの余白（ピクセル単位）
  • font_size（整数、デフォルト: 36）: 描画に使用するフォントサイズ

出力 (Outputs)

  • output: テキストが追加された画像（ImageUrlArtifact）
  • text: 元のテキストテンプレート文字列（展開後の文字列ではありません）
  • was_successful: ノードが正常に実行されたかどうかを示すフラグ
  • result_details: 成功/失敗の詳細情報（不足しているプレースホルダーキーのメッセージなどを含む）

使用例 (Example)

メタデータをスタンプする典型的なワークフローの例：

  1. LoadImage を使用して画像を読み込みます
  2. AddTextToExistingImage ノードを追加します
  3. text に以下を設定します： "Photo: {name} | #{index}"
  4. template_values に辞書を提供します： 
    {"name": "Portrait", "index": 7}
  5. text_background を半透明の黒（例: #00000080）に設定します
  6. text_color を白（#ffffffff）に設定します
  7. ノードを実行し、output を DisplayImage に接続して結果を確認します

重要な注意点 (Important Notes)

  • 不足しているキー: template_values に {key} が存在しない場合、プレースホルダーは描画画像内にそのまま残り、key: key not found in dictionary input のようなメッセージが result_details に追加されます。
  • アルファチャンネルのサポート: テキスト色と背景色の両方で 8 桁の 16 進数（#RRGGBBAA）による透明度の指定が可能です。
  • 実行処理: ノードは process() 実行時に最終画像をアップロードし出力します。