新增 WMS 搬运规则与任务管理
支持搬运规则维护、候选预览、任务生成、预占、下发、取消和完成，并完善仓储管理前端交互。
This commit is contained in:
ArtoriasWu
@@ -0,0 +1,283 @@
|
||||
# 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
Block a user