glmv-grounding

GLMV-Grounding スキル

GLM-V が生成したグラウンディング結果を抽出して可視化します。ユーザーのプロンプトに応じて、モデルの出力に含まれるグラウンディング座標は、2D バウンディングボックス、Objects Detection JSON、2D ポイント、3D バウンディングボックス、ターゲット追跡 JSON など、さまざまな形式で表されます。

注：GLM-V が出力する座標は、ピクセル座標 x_pixel と y_pixel を画像の幅 W と高さ H で正規化した相対座標です（範囲は 0～1000）。つまり、x=round(x_pixel/W1000)、y=round(y_pixel/H1000) です。ピクセル座標系の原点は左上隅です。 注：プロンプトでグラウンディング形式が明示されていない場合（例：「xxx の位置を探して」「xxx を囲むボックスを描いて」）、デフォルトで 2D バウンディングボックスとして扱います。

使用する場面

• GLM-V で画像内のターゲットをグラウンディングする：プロンプトで説明された任意のターゲットについて、デフォルトの 2D バウンディングボックス、2D ポイント、3D バウンディングボックスなどの形式で、画像内のグラウンディング結果を取得します。
• GLM-V で動画内のターゲットを追跡する：プロンプトで説明された任意のターゲットについて、{"0": [{"label": ..., "bbox_2d": ...}, ...], ...} のような形式で、動画内の追跡結果を取得します。
• 抽出、変換、可視化にユーティリティ関数を使用する：自然言語のテキストから座標、ポイント、JSON を抽出し、座標を正規化および逆正規化し、ボックス、ポイント、3D ボックス、動画の追跡結果を可視化します。

API キーのセットアップ

GLM-V API を呼び出すには、ZHIPU_API_KEY を設定します。

1. API キーを取得します：https://www.bigmodel.cn/usercenter/proj-mgmt/apikeys
2. 次のように設定します：

python scripts/config_setup.py setup --api-key YOUR_KEY

セキュリティと透明性

• 主な API キー環境変数：ZHIPU_API_KEY（必須）。
• タイムアウト環境変数：GLM_GROUNDING_TIMEOUT（任意、秒単位、デフォルトは 60）。
• API エンドポイント：CLI 実装では、公式の Zhipu Chat Completions エンドポイントに固定されています。
• キー名の動的な切り替えなし：このスキルでは、一貫して ZHIPU_API_KEY を使用します。
• URL／ローカルファイルの取り扱い：このスキルでは、ローカルファイルを読み込むか、ユーザーが指定した URL を取得して処理や可視化を行えます。URL 入力は公開された http/https の対象に制限されており、localhost／プライベートネットワークの対象は拒否されます。

ランタイム依存関係

使用前に依存関係をインストールしてください：

pip install -r scripts/requirements.txt

このスキルで使用する主なパッケージ：

• requests
• Pillow
• opencv-python
• numpy
• matplotlib
• decord

動画の可視化に必要なシステム依存関係：

• ffmpeg

一般的なワークフロー

	Input (image or video + Prompt)
		|
		▼
	Run glm_grounding_cli.py to get grounding results (natural language)
		|
		▼
	Return results (grounding results, visualized image or video)

使用方法

glm_grounding_cli.py を実行してグラウンディング結果を取得する

• 画像内の任意のターゲットをグラウンディングする

python scripts/glm_grounding_cli.py --image-url "URL provided by user" --prompt "description of target for grounding"

• 動画内の任意のターゲットを追跡する

python scripts/glm_grounding_cli.py --video-url /path/to/image.jpg --prompt "description of target for tracking" --visualize --visualization-dir "./vis"

グラウンディング結果を返す

ユーザーからグラウンディング用のプロンプトを受け取った後、直接の返信は、グラウンディング座標を含む自然な文章にしてください。座標 $x$ と $y$ は [0, 1000] の相対値で、次の式で計算します。

$$ x = round(x_{pixel} / W * 1000) \ y = round(y_{pixel}/H*1000) $$

ここで、$x_{pixel}, y_{pixel}$ は、画像の左上を原点 (0, 0) とするピクセル座標で、W/H は画像の幅と高さです。

特に指定がない限り、グラウンディング結果には次の Python データ形式を使用してください。

• 2D バウンディングボックス: [[x1, y1, x2, y2], ...]。抽出したグラウンディング結果はボックスのリストで、各ボックスは 4 つの座標値を持ちます。
• 2D ポイント: [[x, y], ...]。抽出したグラウンディング結果はポイントのリストで、各ポイントは 2 つの座標値を持ちます。
• 2D ポリゴン: [[x1, y1], [x2, y2], ...]。抽出したグラウンディング結果はポリゴン座標のリストで、各頂点は 2 つの座標値を持ちます。
• 3D バウンディングボックス: [{"bbox_3d":[x_center, y_center, z_center, x_size, y_size, z_size, roll, pitch, yaw],"label":"category"}, ...]。抽出したグラウンディング結果は JSON リストで、各オブジェクトにはカテゴリラベルと、8 つの座標値を含む 3D ボックスが含まれます。
• オブジェクト検出 JSON: [{'label': 'category', 'bbox_2d': [x1, y1, x2, y2]}, ...]。抽出したグラウンディング結果は JSON リストで、各オブジェクトにはカテゴリラベルと 1 つのボックスが含まれます。
• 動画オブジェクト追跡 JSON: {0: [{'label': 'car-1', 'bbox_2d': [1,2,3,4]}, {'label': 'car-2', 'bbox_2d': [2,3,4,5]}], 1: [{'label': 'car-2', 'bbox_2d': [4,5,6,7]}, {'label': 'person-1', 'bbox_2d': [10,20,30,40]}]}。抽出したグラウンディング結果は JSON オブジェクトで、キーは動画のフレームインデックス、値はカテゴリラベルと 1 つの 2D ボックスを含む JSON オブジェクトのリストです。

Python の例

# 1. User grounding request and your reply
image=https://example.com/image.jpg
prompt="Please box all people wearing Santa hats in the image and tell me their coordinates. Use red boxes, line thickness 3, and label format 'SantaHat-i'."


# 2. Get grounding results
python scripts/glm_grounding_cli.py --image-url $image --prompt $prompt --visualize --visualization-dir "./vis"

#  {
#         "ok": True,
#         "grounding_result": [[100, 200, 300, 400], [500, 600, 700, 800]],
#         "visualizations_result": (
#             {"visualized_image": "./vis/image_vis.jpg"}
#         ),
#         "raw_result": "1. Person 1: box [100, 200, 300, 400]\n2. Person 2: box [500, 600, 700, 800]. The box format is [x1, y1, x2, y2], where (x1, y1) is the top-left corner and (x2, y2) is the bottom-right corner.",
#         "error": None,
#         "source": source,
#     }

ユーティリティ関数のクイックリファレンス

関数	目的
parse_coordinates_from_response(response_str, coords_type='bbox', init_context_window=2000, max_context_window=-1)	モデルの応答からすべての座標結果を解析して抽出します（2D バウンディングボックス、ポイント、ポリゴンに対応）
parse_3d_boxes_from_response(response_str, max_context_window=-1)	モデルの応答からすべての3Dボックスとラベルを解析して抽出します（厳密一致および緩い一致）
parse_detection_from_response(response_str, max_context_window=-1)	モデルの応答からすべての2D検出結果を解析して抽出します（Objects Detection JSON 形式）
parse_mot_from_response(response_str, max_context_window=-1)	モデルの応答からすべての動画オブジェクト追跡結果を解析して抽出します（Video Objects Tracking JSON 形式）
visualize_boxes(img_path=None, img_bytes=None, boxes=[], labels=None, renormalize=False, save_path=None, return_b64=False, save_optimized=True, **kwargs)	ラベル、カスタムカラー、線の太さを指定して、画像に2Dボックスを描画します
visualize_points(img_path=None, img_bytes=None, points=[], labels=None, renormalize=False, diameters=None, save_path=None, return_b64=False, save_optimized=True, distinct_colors=False, colors=None)	ラベル、カスタムサイズ、色を指定して、画像にポイントを描画します
visualize_3d_boxes_glmv_simple(image_path, cam_params, bbox_3d_list, image_bytes=None, coord_format='xyzwhlpyr', save_path=None, save_optimized=False, return_b64=False, **kwargs)	カメラの内部パラメーターを使用して画像に投影された3Dボックスを描画します（回転と複数の座標形式に対応）
visualize_mot(video_path=None, video_bytes=None, mot_js=None, renormalize=False, save_path=None, return_b64=False, distinct_colors=True, **kwargs)	各動画フレームにラベル付きの Video Objects Tracking ボックスを描画します

よくあるエラー

• 座標値が1000を超える：抽出された座標値が1000を超える場合、プロンプトの影響により、モデルが正規化されていない座標を生成した可能性があります。ユーザーのリクエストから対象のフレーズ（例：「サンタ帽をかぶった人々」）を抽出し、画像サイズに基づいて0～1000に正規化した相対値で座標を出力するよう明示的に指定して、モデルに再度問い合わせてください（例：「画像内のサンタ帽をかぶった人々をすべてボックスで囲み、座標を教えてください。出力座標は画像サイズに基づいて0～1000に正規化した相対値にしてください。」）。