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 密钥

配置 ZHIPU_API_KEY 以调用 GLM-V API。

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 实现中固定为智谱官方 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"

回复 grounding 结果

收到用户的 grounding 提示词后，你的直接回复应使用自然语言，并包含 grounding 坐标。坐标 $x$ 和 $y$ 是 [0, 1000] 范围内的相对值，计算方式如下：

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

其中，$x_{pixel}, y_{pixel}$ 是像素坐标，原点 (0, 0) 位于图像左上角；W/H 是图像的宽度/高度。

除非另有说明，grounding 结果应使用以下 Python 数据格式：

• 2D 边界框：[[x1, y1, x2, y2], ...]，提取的 grounding 结果是一个框列表，每个框包含 4 个坐标值
• 2D 点：[[x, y], ...]，提取的 grounding 结果是一个点列表，每个点包含 2 个坐标值
• 2D 多边形：[[x1, y1], [x2, y2], ...]，提取的 grounding 结果是一个多边形坐标列表，每个顶点包含 2 个坐标值
• 3D 边界框：[{"bbox_3d":[x_center, y_center, z_center, x_size, y_size, z_size, roll, pitch, yaw],"label":"category"}, ...]，提取的 grounding 结果是一个 JSON 列表，其中每个对象都包含一个类别标签和一个包含 8 个坐标值的 3D 框
• 对象检测 JSON：[{'label': 'category', 'bbox_2d': [x1, y1, x2, y2]}, ...]，提取的 grounding 结果是一个 JSON 列表，其中每个对象都包含一个类别标签和一个框
• 视频对象跟踪 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]}]}，提取的 grounding 结果是一个 JSON 对象，其键为视频帧索引，值为 JSON 对象列表，每个对象都包含一个类别标签和一个 2D 框

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 检测结果（对象检测 JSON 格式）
parse_mot_from_response(response_str, max_context_window=-1)	从模型响应中解析并提取所有视频对象跟踪结果（视频对象跟踪 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)	在每个视频帧上绘制视频对象跟踪边界框并添加标签

常见错误

• 坐标值超过 1000：如果提取的坐标值大于 1000，模型可能因提示词影响而生成了未归一化的坐标。请从用户请求中提取目标短语（例如“戴着圣诞帽的人”），然后再次查询模型，并明确要求输出坐标为相对于图像尺寸归一化到 0–1000 的值（例如：“请框出图像中所有戴着圣诞帽的人，并告诉我他们的坐标。确保输出坐标为相对于图像尺寸归一化到 0–1000 的值。”）。