name: glmv-grounding
description: 一个使用GLM-V原生定位能力进行坐标转换、边界框可视化等的技能。GLM-V原生定位可以在图像中定位提示指定的任何目标，并输出基于图像大小归一化到0-1000的相对坐标。坐标格式包括2D边界框（默认）、2D点和3D边界框。GLM-V还支持对视频中多个提示指定的目标进行时空定位与跟踪，每秒输出2D边界框。
metadata:
    openclaw:
        requires:
            env:
                - ZHIPU_API_KEY
                - GLM_GROUNDING_TIMEOUT
        primaryEnv: ZHIPU_API_KEY
        emoji: "\U0001F5BC️"
        source: https://github.com/zai-org/GLM-V/tree/main/skills/glmv-grounding
        homepage: https://github.com/zai-org/GLM-V/tree/main/skills/glmv-grounding

GLMV-Grounding 定位技能

提取并可视化 GLM-V 生成的定位结果。根据用户提示，模型输出中的定位坐标可能以不同形式出现，包括2D边界框、目标检测JSON、2D点、3D边界框以及目标跟踪JSON。

注意：GLM-V 输出的坐标中，**x 和 y 是相对坐标，根据像素坐标 x_pixel 和 y_pixel 归一化到图像宽度 W 和高度 H（范围 0-1000），即 x=round(x_pixel/W*1000), y=round(y_pixel/H*1000)**。像素坐标系的原点为左上角。

注意：如果提示中未明确指定定位格式（例如“找到 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 目标（拒绝本地主机/私有网络目标）。

运行时依赖

使用前安装依赖：

pip install -r scripts/requirements.txt

该技能使用的主要包：

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

视频可视化的系统依赖：

• ffmpeg

通用工作流程

	输入（图像或视频 + 提示）
		|
		▼
	运行 glm_grounding_cli.py 获取定位结果（自然语言）
		|
		▼
	返回结果（定位结果、可视化后的图像或视频）

如何使用

运行 glm_grounding_cli.py 获取定位结果

• 对图像中的任何目标进行定位

python scripts/glm_grounding_cli.py --image-url "用户提供的 URL" --prompt "待定位目标的描述"

• 对视频中的任何目标进行跟踪

python scripts/glm_grounding_cli.py --video-url /path/to/image.jpg --prompt "待跟踪目标的描述" --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 列表，每个对象包含一个类别标签和一个框
• _视频目标跟踪 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 对象，其键为视频帧索引，值为 JSON 对象的列表，每个对象包含一个类别标签和一个 2D 框

Python 示例

# 1. 用户的定位请求及你的回复
image=https://example.com/image.jpg
prompt="请框出图像中所有戴圣诞帽的人，并告诉我他们的坐标。使用红色框，线宽3，标签格式'SantaHat-i'。"


# 2. 获取定位结果
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,
#     }

工具函数快速参考

常见错误

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