Third_Dev_Dept/Migu2.0
18
0
Fork 0
Code Issues 2 Pull Requests Packages Projects Releases Wiki Activity
Files
15405ba114271dcf870be2c12b2d134b4e3584fb
Migu2.0/SimpleLite/model/agv_glb/docs/AGV_GLB导出规范.md
T
ArtoriasWu 15405ba114 新增 WMS 搬运规则与任务管理 
支持搬运规则维护、候选预览、任务生成、预占、下发、取消和完成，并完善仓储管理前端交互。
2026-06-25 11:02:22 +08:00

10 KiB
Raw Blame History

AGV 数字孪生 GLB 导出规范

文档版本：1.1
适用对象：负责 AGV 三维建模与 GLB 导出的同事
对接系统：Web 查看器（Three.js）、PanguCanvas 桌面播放器
交付范围：仅需交付 GLB 模型文件；JSON 配置由程序同事在收到 GLB 后生成与维护

1. 背景与目标

我们使用 GLB 模型 驱动 AGV 数字孪生（轮子旋转/转向、举升、灯光、动作切换等）；配套的 JSON 配置由程序侧根据 GLB 自动生成，无需建模同事参与。

当前部分模型在导出时未统一层级与坐标，导致程序在运行时不得不：

  • 猜测轮子旋转轴与轴心位置
  • 动态插入临时空节点
  • 做复杂的世界坐标 ↔ 本地坐标换算
  • 兼容混乱的节点命名（中文、.001 后缀、空格等）

本规范的目标：把几何与运动语义在 Blender 导出阶段写进 GLB，程序侧只做「查节点 + 改 transform / 材质」，降低联调成本、减少 bug。

2. 交付物清单

每款 AGV 只需交付一个文件：

文件 说明
{车型名}.glb 按本规范导出的模型

可选（联调时有助于排查问题）：Blender 源文件（.blend）、各可动件行程与轴方向的简要说明。

导出前请自检（见第 10 节）。收到 GLB 后，程序同事会负责生成配置、绑定动作并完成验证。

3. 场景层级（必须遵守）

请在 Blender 中按以下结构组织，导出前建好空物体（Empty）层级

agv_root                         ← 唯一根节点（程序侧 root 固定为 "agv_root"）
├── body/                        ← 静态车体
│   └── chassis
├── wheels/
│   ├── wheel_fl/                ← 左前舵轮（命名按实际车型调整）
│   │   ├── steer                ← 转向节点：绕本地 Y 轴旋转
│   │   │   └── spin             ← 滚转节点：绕本地 X 轴旋转
│   │   │       └── mesh         ← 轮子网格
│   ├── wheel_fr/
│   └── ...
├── actuators/
│   └── lift_fork/               ← 举升机构：沿本地 Y 轴平移
│       └── mesh
├── lights/                  ← 可选分组，非必须
│   ├── light_status_l/
│   └── light_status_r/
└── sensors/
    └── lidar_top/

3.1 根节点

  • 名称固定为 agv_root（不要用 lux_root、Scene、StealthAGV 等）
  • 原点建议：车辆地面接触面几何中心，或后轴中心；Y = 0 贴地
  • 车头朝向建议统一为 +Z（见第 4 节）

3.2 轮子层级（最重要）

每个可动轮子必须包含三层空物体：

节点 作用 程序操作
wheel_xxx 轮子总成，固定在父级 程序按节点名绑定
steer 转向 rotation.y（或约定的转向轴）
spin 滚转 rotation.x（所有轮子统一）
mesh 视觉网格 不直接改 transform

所有轮子的滚转轴统一为 spin 节点的本地 X 轴，转向轴统一为 steer 节点的本地 Y 轴。
麦轮、舵轮等特殊情况也用独立命名的 wheel 节点表达，不要在不同轮子上使用不同旋转轴约定。

3.3 举升 / 执行机构

  • 举升件放在 actuators/ 下
  • 收回位置 = 本地 Y = 0（相对 actuators 父节点或 lift 节点自身约定）
  • 完全伸出位置 = 本地 Y = 行程米数（如 0.15 m = 15 cm）
  • 行程以 米 为单位，与 Blender 中 1 单位 = 1 米 保持一致（程序侧会据此配置）

3.4 灯光

  • 每个需独立控制的指示灯单独 命名节点（如 light_status_l），程序按节点名绑定
  • 节点下可有 mesh，材质 可与其他部件共用；程序运行时会 clone，无需刻意拆材质
  • 材质使用 PBR，支持 Emission 即可（亮灭由程序改 emissive 控制）
  • 不必强制放在 lights/ 分组下，但名称建议带 light_ 前缀便于识别

3.5 静态件

  • 不参与动作的零件合并进 body/chassis，减少零散节点
  • 仅保留需要单独隐藏、透明或换色的零件为独立节点

4. 坐标系与单位

项目 要求
坐标系 Y 轴向上（glTF 标准），右手系
单位 1 Blender 单位 = 1 米
朝向 车头 +Z，左右 ±X，上下 Y（全项目统一）
Transform 导出前对每个可动节点 Apply All Transforms（Ctrl+A），scale 应为 (1, 1, 1)
全局旋转 不要在模型根节点上留 ±90° 的「纠正旋转」；朝向在 Blender 里摆好再导出

说明：若导出时未 Apply Transform 或 scale ≠ 1，程序侧举升、轮子会出现位移异常或「部件飞出视野」。

5. 命名规范

5.1 必须

  • 仅使用 ASCII 英文字母、数字、下划线
  • 使用 snake_case：wheel_fl、lift_fork、light_status_l
  • 按角色加前缀：
前缀 用途 示例
body_ / 放在 body/ 下 静态车体 body/chassis
wheel_ 轮子 wheel_fl, wheel_rl
lift_ / 放在 actuators/ 下 举升 lift_fork
light_ 指示灯 light_status_l
sensor_ 传感器 sensor_lidar_top

5.2 禁止

  • 中文节点名（如 前座、雷达、柱体）
  • Blender 自动后缀（如 主体.001、平面.003）
  • 空格、全角字符、不可见字符（含 NBSP）
  • 无语义的编号（如仅有 light_1、light_2 而不说明用途）
  • 多个不相关含义的节点重名

5.3 推荐命名示例（舵轮 AGV）

agv_root
body/chassis
wheels/wheel_fl/steer/spin/mesh
wheels/wheel_fr/steer/spin/mesh
wheels/wheel_rl/spin/mesh          ← 从动轮可无 steer 层，spin 下挂 mesh
actuators/lift_fork/mesh
lights/light_status_l
lights/light_status_r
sensors/lidar_top

6. 材质要求

项目 要求
材质类型 PBR Principled BSDF → 导出为 glTF Standard Material
车体 正常 albedo / roughness / metalness，贴图嵌入 GLB
指示灯 PBR 材质，支持 Emission；可与车体共用材质
材质实例 无特殊要求；程序侧会对需动画的部件 clone 材质
法线 导出时包含 Normals；有贴图时包含 Tangents

7. Blender 导出设置

File → Export → glTF 2.0 (.glb/.gltf)

选项 设置
Format glTF Binary (.glb)
Include Selected Objects 关闭（导出整场景）
Transform +Y Up
Geometry 勾选 Apply Modifiers、UVs、Normals；有 normal map 时勾选 Tangents
Material Export 开启
Compression 开发联调阶段 关闭 Draco（上线可按体积需求再开）
层级 保持层级，不要勾选 Flatten / 合并为单 mesh

导出后请确认文件大小合理，并用 glTF 查看器预览，确认模型显示正常。

8. 节点命名与程序侧映射（供参考，无需建模同事配置）

程序会根据 GLB 节点名自动绑定逻辑组件。请按第 5 节规范命名，便于程序识别；以下类型说明仅供理解命名意图，JSON 配置由程序同事完成。

8.1 组件类型（程序侧配置）

type 用途 motion.role
static / body 静态件 无
wheel 轮子 wheel
actuator 举升等 lift
light 指示灯 light
sensor 传感器（可选动画） lidar / camera 等

8.2 命名与用途对照

节点示例 程序侧用途 建模侧要求
wheel_fl 轮子旋转/转向 含 steer → spin → mesh 层级
lift_fork 举升平移 收回 Y=0，伸出 Y=行程（米）
light_status_l 指示灯 emissive 单独命名节点，材质支持 Emission
body/chassis 静态车体 不参与 transform 动画

9. 常见问题对照（旧模型 vs 规范）

以现有「英招」模型为例，以下做法请避免：

现状问题 规范做法
根节点名 lux_root 改为 agv_root
节点 柱体.003、主体.001 语义命名如 wheel_rl
同车型轮子 axis 有的 y、有的 z 统一预置 spin/steer，axis 统一 x/y
6 个 light 节点对应 3 盏灯 合并为 3 个 light_* 节点
19 个零散 static 组件 合并 body，仅保留可动件独立节点
举升行程不清晰或为负值 在 Blender 摆好 0 ~ 行程（米），并附简要说明

10. 导出前自检清单

请在交付前逐项确认：

  • 根节点名为 agv_root，Y=0 贴地，车头朝 +Z
  • 所有可动节点已 Apply All Transforms，scale = (1,1,1)
  • 每个舵轮含 steer → spin → mesh 层级
  • 所有轮子滚转轴为 spin 的 本地 X，转向轴为 steer 的 本地 Y
  • 举升行程在 Blender 中以米制摆好（如收回 0 m、伸出 0.15 m）
  • 节点名全部为 ASCII snake_case，无中文、无 .001 后缀
  • 需独立控制的指示灯有单独命名节点（light_*）
  • 静态件已合并到 body，无多余零散 mesh
  • glTF 导出：+Y Up、保留层级、Apply Modifiers
  • 用任意 glTF 查看器预览 GLB，确认无错位、无缩放异常

11. 联调流程

建模同事：

  1. 按本规范完成 Blender 场景
  2. 导出 {车型名}.glb 并交付给程序同事
  3. （建议）一并提供 .blend 源文件及可动件行程说明

程序同事（建模同事无需参与）：

  1. 将 GLB 放入项目 agv/ 目录
  2. 生成 JSON 配置、绑定动作并在查看器 / PanguCanvas 中验证

如有疑问，请提供：Blender 源文件 + GLB + 各可动件行程与轴方向说明，便于对照排查。

12. 附录：层级示意图

                    agv_root (原点贴地, 车头 +Z)
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
      body/           wheels/           actuators/
        │                 │                 │
    chassis          wheel_fl           lift_fork
                        │                 │
                     steer ── spin       mesh
                        │      │
                       spin   mesh
                        │
                      mesh

文档维护：数字孪生开发组 · 如有规范变更请同步更新本文档版本号

Reference in New Issue View Git Blame Copy Permalink