action-remote-call
需要通过 HTTP 控制 OpenGeoLab 时使用 — 创建几何体、截取视窗、控制相机、管理选择、生成网格,或通过 REST API 远程调用任意 Action
- License 许可
- GPL-3.0
- 最近更新
- 2026-08-19
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- action-remote-call
- description
- 需要通过 HTTP 控制 OpenGeoLab 时使用 — 创建几何体、截取视窗、控制相机、管理选择、生成网格,或通过 REST API 远程调用任意 Action
03 SKILL.md 正文
Action Remote Call — 渐进式发现
OpenGeoLab 暴露统一的 HTTP REST API(POST /api/v1/action)用于远程控制。
所有操作共享同一 JSON 信封格式;使用内置 schema 发现 action 在运行时查询精确参数,而不是死记硬背。
启动 opengeolab 时使用 --start-http-server 参数自动启动 http server,以便你使用 http remote call actions。
快速开始
URL=http://127.0.0.1:8080/api/v1/action
# 健康检查
curl -s http://127.0.0.1:8080/api/v1/health
# 执行任意 action
curl -s -X POST $URL -H "Content-Type: application/json" \
-d '{"module":"geometry","action":"create_box","param":{"width":2}}'
请求格式: {"module": "<模块名>", "action": "<动作名>", "param": {...}}
成功响应: {"ok": true, ...结果字段...}
失败响应: {"ok": false, "summary": "...", "errors": [...]}
默认地址:http://127.0.0.1:8080(端口可在 UI 中配置)。
已启用 CORS(Access-Control-Allow-Origin: *)。
Schema 发现(执行前必须)
执行任何 action 之前,必须先通过 system 模块查询其精确参数。
这是唯一权威来源 — 不要猜测参数名或类型。
第一步:获取模块的 action 列表
根据下方模块概览,选择目标模块并查询其所有 action:
curl -s -X POST $URL -d '{"module":"system","action":"describe_module","param":{"module":"geometry"}}'
返回:{"ok":true, "module":"geometry", "description":"...", "actions":[{"name":"create_box","description":"..."}, ...]}
第二步:获取具体 action 的精确参数
curl -s -X POST $URL -d '{"module":"system","action":"describe_action","param":{"module":"geometry","action":"create_box"}}'
返回完整参数 schema,包含类型、默认值和必填标记 — 依据此构造请求。
完整系统 schema(高级,一次性获取)
curl -s -X POST $URL -d '{"module":"system","action":"describe","param":{}}'
返回所有模块、所有 action、所有参数/返回值 schema。适合批量内省。
模块概览
每个模块负责一个独立领域。使用 system.describe_module 发现模块内的所有 action。
| 模块 | Action 数 | 职责 |
|---|---|---|
geometry |
14 | 创建基元体(长方体、球体、圆柱、圆环)、导入外部 CAD 文件(STEP、BRep)、查询形状拓扑/包围盒、列出子拓扑(面、边、顶点)、描述拓扑结构、查询单实体详情与邻接、删除形状、细分可视化 |
mesh |
3 | 从几何面/体生成有限元网格(三角形/四边形,可配置算法)、查询网格节点/边/单元信息、清除网格数据 |
scene |
22 | 截取视窗截图(PNG 文件 + 元数据 + 可选拓扑)、控制相机(位置/预设/适配/对准实体/最佳视角)、选择/取消选择实体、标注几何实体、管理可见性和场景树、重置工作区 |
io |
1 | 文件读取操作(部分实现) |
system |
5 | capabilities、describe、list_modules、describe_module、describe_action — 运行时内省 |
模块名区分大小写,仅以上 5 个名称有效。
关键 Action(代表性示例)
以下展示几个重要 action 的用法。完整参数请使用 system.describe_action 查询。
geometry.create_box — 创建长方体
curl -s -X POST $URL -d '{"module":"geometry","action":"create_box","param":{"width":3,"height":2,"depth":1}}'
返回:{"ok":true, "shapeId":0, "name":"Box", "topology":{"solids":1,"faces":6,"edges":12,"vertices":8}}
⚠️ 易错点: create_sphere 使用 center(不是 origin)。导入操作使用 path(不是 filePath)。
scene.capture_viewport — 截图与场景分析
# 保存到文件(filePath 必填)
curl -s -X POST $URL -d '{"module":"scene","action":"capture_viewport","param":{"filePath":"C:/test/viewport.png"}}'
# 包含拓扑信息
curl -s -X POST $URL -d '{"module":"scene","action":"capture_viewport","param":{"filePath":"C:/test/viewport.png","includeTopology":true}}'
返回元数据(相机、可见形状及屏幕包围盒/世界包围盒、选择状态、标签)和 PNG 截图路径。
includeTopology: true 时,每个可见形状附带面/边/顶点拓扑数据。
⚠️ filePath 是必填参数。不再支持 base64 图片模式。
scene.select — 选择实体
curl -s -X POST $URL -d '{"module":"scene","action":"select","param":{"entities":[{"shapeId":0,"type":"GeoFace","localId":1}]}}'
⚠️ 选择/取消选择使用 type,标签操作使用 entityType。localId 是 1-based — 必须先用 geometry.list_sub_shapes 查询。
mesh.generate_mesh — 生成网格
curl -s -X POST $URL -d '{"module":"mesh","action":"generate_mesh","param":{"entities":[{"shapeId":0,"type":"GeoFace","localId":1}],"elementSize":0.5}}'
⚠️ 使用 system.describe_action 发现 dimension、elementType、algorithm、advanced 等选项。
实体引用格式
所有涉及实体引用的 action 使用此结构:
{"shapeId": 0, "type": "GeoFace", "localId": 1}
| 字段 | 说明 |
|---|---|
shapeId |
0-based 形状 ID(来自 create_* / list_shapes) |
type 或 entityType |
选择/悬停用 type;标签操作用 entityType |
localId |
1-based 拓扑 ID(来自 list_sub_shapes) |
几何类型: GeoVertex、GeoEdge、GeoWire、GeoFace、GeoSolid
网格类型: MeshNode、MeshEdge、MeshElement
典型工作流
建模 → 查看 → 截图
curl -s -X POST $URL -d '{"module":"geometry","action":"create_box","param":{"width":3,"height":2,"depth":1}}'
curl -s -X POST $URL -d '{"module":"scene","action":"fit_to_scene","param":{}}'
curl -s -X POST $URL -d '{"module":"scene","action":"set_view_preset","param":{"preset":"Isometric"}}'
curl -s -X POST $URL -d '{"module":"scene","action":"capture_viewport","param":{"filePath":"C:/test/shot.png"}}'
拓扑分析 → 定位圆柱面 → 网格剖分
curl -s -X POST $URL -d '{"module":"geometry","action":"describe_topology","param":{"shapeId":0}}'
# 从返回的 faces 中找到 surfaceType="cylinder" 的 localId
curl -s -X POST $URL -d '{"module":"geometry","action":"query_entity_info","param":{"shapeId":0,"entityType":"face","localId":2}}'
curl -s -X POST $URL -d '{"module":"scene","action":"best_view_for_entity","param":{"shapeId":0,"entityType":"face","localId":2}}'
curl -s -X POST $URL -d '{"module":"mesh","action":"generate_mesh","param":{"entities":[{"shapeId":0,"type":"GeoFace","localId":2}],"elementSize":5}}'
curl -s -X POST $URL -d '{"module":"scene","action":"capture_viewport","param":{"filePath":"C:/test/mesh.png"}}'
选择 → 标注 → 分析
curl -s -X POST $URL -d '{"module":"geometry","action":"list_sub_shapes","param":{"shapeId":0}}'
curl -s -X POST $URL -d '{"module":"scene","action":"select","param":{"entities":[{"shapeId":0,"type":"GeoFace","localId":1}]}}'
curl -s -X POST $URL -d '{"module":"scene","action":"add_label","param":{"shapeId":0,"entityType":"GeoFace","localId":1}}'
curl -s -X POST $URL -d '{"module":"scene","action":"capture_viewport","param":{"filePath":"C:/test/labeled.png"}}'
常见错误
| 错误做法 | 正确做法 |
|---|---|
| 猜测参数名 | 先用 system.describe_action 查询 |
localId 从 0 开始 |
localId 是 1-based,先用 list_sub_shapes 查 |
用 filePath 导入文件 |
导入操作参数名是 path |
sphere 用 origin |
sphere 使用 center |
add_label 用 type |
标签操作使用 entityType |
把 pick_area 当同步 |
pick_area 是异步 — 需后续调用 query_selection |
| 文件路径用单反斜杠 | 使用 C:/path 或 C:\\path |
| 未启动 HTTP Server 就调用 | 需先在 OpenGeoLab UI 中启动 HTTP Server 插件 |
| capture_viewport 不带 filePath | filePath 是必填参数 |
camera 动作用 GeoFace |
look_at_entity/best_view_for_entity 的 entityType 用短名 face/edge/vertex |
04 同仓库更多 Skills
viewport-operations
OpenGeoLab 3D 视口操作完整参考:capture_viewport, camera, selection, labels, visibility, pick_area; enforce describe_action then execute_action with exact schema
opengeolab-commands
OpenGeoLab 命令协议与完整 action 参数参考;先 describe_action 再 execute_action,涵盖 geometry mesh scene 三大模块
viewport-operations
暂无简介