バウンディングボックスの追加 (AddBoundingBoxes)

概要 (What is it?)

AddBoundingBoxes ノードは、座標辞書データに基づいて画像上にバウンディングボックス（境界枠）を描画します。画像上に色付きの矩形と任意のラベルをオーバーレイ表示することで、物体検出の結果を可視化するように設計されています。YOLO、顔検出、その他の検出システムの出力結果を表示するのに最適です。

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

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

YOLO、SSD、その他の物体検出モデルからの検出結果を可視化したい場合
顔検出のバウンディングボックスと信頼度スコアを表示したい場合
座標に基づいた関心領域（ROI）を画像に注釈付けしたい場合
コンピュータビジョンワークフローの視覚的なフィードバックを作成したい場合
検出モデルの出力結果をデバッグおよび検証したい場合
単一の画像上に複数の検出結果を組み合わせて表示したい場合

使い方 (How to use it)

基本セットアップ

ワークフローに AddBoundingBoxes ノードを追加します
画像ソースを "input_image" 入力に接続します
バウンディングボックスデータ（辞書または辞書のリスト）を "bounding_boxes" 入力に接続します
必要に応じて色、ラベル、線の太さをカスタマイズします
アノテーションが追加された画像が "output" パラメータから出力されます

パラメータ一覧 (Parameters)

必須入力 (Required Inputs)

input_image: バウンディングボックスを描画する対象の画像（ImageUrlArtifact または ImageArtifact）
bounding_boxes: ボックス座標を含む単一の辞書または辞書のリスト
- 各辞書には必須キーとして x, y, width, height（整数または変換可能な文字列）が必要です
- ラベルテンプレートで使用する追加のキー（例: confidence, class など）を含めることができます
- 例: {"x": 100, "y": 50, "width": 200, "height": 150, "confidence": 0.95}

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

box_color（16進数カラーコード、デフォルト: "#FF0000"）: バウンディングボックスの輪郭線の色
- カラーピッカー（ColorPicker）を使用して簡単に色を選択できます
- 16進数形式をサポート（例: 赤なら "#FF0000"、緑なら "#00FF00"）
line_thickness（1〜10、デフォルト: 2）: バウンディングボックスの線の太さ（ピクセル単位）
- 小さい値は繊細な注釈に適しています
- 大きい値は太く目立つボックスに適しています

ラベルパラメータ (Label Parameters)

show_labels（真偽値、デフォルト: True）: ラベル表示のオン/オフ切り替え
- True に設定するとバウンディングボックスの上にラベルを表示します
- False に設定するとラベルを非表示にし、ボックスのみを表示します
label_key（文字列テンプレート）: バウンディングボックスのラベル用テンプレート
- デフォルト: "{x}, {y}, width: {width}, height: {height}"
- {key} 構文を使用してバウンディングボックス辞書の値を挿入します
- 例: "Class: {class}, Conf: {confidence}"
- 例: "{x}, {y} - Size: {width}x{height}"
- 辞書に存在しないキーは、出力内で {key} のまま残ります

出力 (Outputs)

output: バウンディングボックスとラベルが描画された画像

使用例 (Example)

一般的な物体検出の可視化ワークフローの例：

LoadImage を使用して画像を読み込みます
物体検出を実行します（例: YOLO やカスタム検出モデルを使用）

検出結果を辞書のリスト形式に整形します：

[
  {"x": 100, "y": 50, "width": 200, "height": 150, "class": "person", "confidence": 0.95},
  {"x": 350, "y": 120, "width": 180, "height": 200, "class": "car", "confidence": 0.87}
]

画像を AddBoundingBoxes の "input_image" に接続します
検出結果を "bounding_boxes" に接続します
ラベルテンプレートを設定します: "Class: {class}, Conf: {confidence}"
ボックスの色を選択します: "#00FF00"（緑）
視認性を高めるため線の太さを 3 に設定します
"output" を DisplayImage に接続して注釈付きの結果を確認します

重要な注意点 (Important Notes)

座標系: バウンディングボックスは左上隅を (x, y) とし、幅（width）と高さ（height）が右方向および下方向に伸びる座標系を使用します
文字列の変換: 座標値が文字列の場合、ノードは可能であれば自動的に整数に変換します
- 例: {"x": "100", "y": "50"} も正常に動作します
ラベルの位置: ラベルはスマートな間隔で配置されます：
- デフォルト: ボックスの上に、ラベルの高さの半分の隙間を空けて配置
- 画像の上端に近い場合: ボックスの内側上部に配置
ラベルサイズ: フォントサイズは画像高さの 4% に自動スケーリングされ、画像サイズに応じた見やすい比率で描画されます
入力の検証: 処理前にすべての入力が検証されます：
- 座標は負でない値（x ≥ 0, y ≥ 0）である必要があります
- 寸法は正の値（width > 0, height > 0）である必要があります
- 問題がある場合はわかりやすいエラーメッセージが表示されます
RGBA のサポート: RGBA 画像の透過チャンネルはそのまま保持されます

よくある問題 (Common Issues)

必須キーの不足: 各バウンディングボックス辞書に x, y, width, height が含まれていることを確認してください（不足しているキーがエラーメッセージに表示されます）
文字列座標: 文字列で渡された座標値は自動変換されますが、数値に変換できない文字列の場合はエラーメッセージが表示されます
負の座標値: バウンディングボックスの座標は 0 以上である必要があります（x ≥ 0, y ≥ 0 を確認してください）
寸法が 0 または負: 幅と高さは 0 より大きい必要があります（width > 0, height > 0 を確認してください）
ラベルが表示されない:
- show_labels が True に設定されているか確認してください
- label_key に有効なテンプレートが指定されているか確認してください
- テンプレート内のキーがバウンディングボックス辞書に存在するか確認してください
ラベルテキストが正しくない: テンプレート内の {key} 名がバウンディングボックス辞書のキーと正確に一致しているか確認してください

技術的な詳細 (Technical Details)

ノードは以下の処理を順次実行します：

入力検証:
- バウンディングボックスの形式（辞書またはリスト）を検証
- 必須キー（x, y, width, height）の存在を確認
- 必要に応じて文字列値を整数に変換
- 座標範囲の妥当性を検証
色の解析: 描画処理のために16進数カラーコードを RGB タプルに変換
フォント読み込み: 画像高さの 4% のサイズでフォントを動的に読み込み（LABEL_HEIGHT_PERCENT 定数で設定可能）
ボックスの描画: 各バウンディングボックスについて：
- x, y, width, height から矩形の角の座標を計算
- 指定された色と線の太さで矩形の輪郭線を描画
ラベルのレンダリング（有効な場合）：
- {key} パターンを値に置換してテンプレート文字列を処理
- 適切な配置のためにテキストの寸法を計算
- テキストの視認性を確保するため黒い背景の矩形を描画
- 背景の上に白いテキストを描画
スマート配置: ボックスの上に比例した間隔でラベルを配置（画像の上端に近い場合はボックスの内側に配置）

このノードはすべてのレンダリング操作に PIL（Pillow）の ImageDraw を使用しており、標準的な画像フォーマットと互換性のある高品質な出力を保証します。