Skip to content

JSON_FORMAT.md

Latest commit

 

History

History
516 lines (406 loc) · 11.3 KB

JSON_FORMAT.md

File metadata and controls

516 lines (406 loc) · 11.3 KB
Raw

JSON 文件格式规范

本文档详细说明逆向运动学求解系统中使用的所有 JSON 文件格式规范。

目录

  1. 骨骼定义文件 (skeleton.json)
  2. 目标轨迹文件 (targets.json)
  3. 动画导出文件 (animation.json)

1. 骨骼定义文件 (skeleton.json)

1.1 文件用途

定义机械结构的拓扑与属性，包括关节类型、位置、约束等信息。

1.2 文件结构

{
  "root_name": "Root",
  "joints": [
    {
      "name": "关节名称",
      "type": "关节类型",
      "offset": [x, y, z],
      "parent": "父节点名称或null",
      // 其他字段根据关节类型而定
    }
  ]
}

1.3 字段说明

根级字段

  • root_name (String, 必需)

    • 根节点的名称
    • 必须在 joints 数组中存在对应的关节

  • joints (Array, 必需)

    • 关节列表，每个元素为一个关节对象

关节字段（所有关节类型共有）

  • name (String, 必需)

    • 关节名称，必须唯一
    • 用作关节的唯一标识符

  • type (String, 必需)

    • 关节类型，可选值：
      • "fixed": 固定关节（无自由度）
      • "revolute": 旋转关节（1自由度）
      • "prismatic": 移动关节（1自由度）
      • "spherical": 球形关节（3自由度）

  • offset (Array[Float, Float, Float], 必需)

    • 相对父级的静态位移（单位：米）
    • 格式：[x, y, z]
    • 根节点的 offset 通常为 [0, 0, 0]

  • parent (String | null, 必需)

    • 父节点名称
    • null 表示根节点（无父节点）
    • 必须指向 joints 数组中已存在的关节名称

1.4 关节类型特定字段

FixedJoint (固定关节)

固定关节无需额外字段。

示例：

{
  "name": "Root",
  "type": "fixed",
  "offset": [0, 0, 0],
  "parent": null
}

RevoluteJoint (旋转关节)

  • axis (Array[Float, Float, Float], 必需)

    • 旋转轴（局部坐标系，不能为零向量。程序会自动归一化）
    • 格式：[x, y, z]
    • 示例：[1, 0, 0] 表示绕局部 X 轴旋转

  • limits (Array[Float, Float] | null, 可选)

    • 角度约束范围（单位：弧度）
    • 格式：[min, max]
    • null 或省略表示无约束
    • 示例：[0.0, 3.14159] 表示角度范围 0 到 π 弧度

示例：

{
  "name": "Elbow",
  "type": "revolute",
  "offset": [0, 0, 2.0],
  "parent": "Shoulder",
  "axis": [1, 0, 0],
  "limits": [0.0, 2.5]
}

PrismaticJoint (移动关节)

  • axis (Array[Float, Float, Float], 必需)

    • 移动轴（局部坐标系，不能为零向量。程序会自动归一化）
    • 格式：[x, y, z]
    • 示例：[0, 0, 1] 表示沿局部 Z 轴移动

  • limits (Array[Float, Float] | null, 可选)

    • 位移约束范围（单位：米）
    • 格式：[min, max]
    • null 或省略表示无约束
    • 示例：[0.0, 0.5] 表示位移范围 0 到 0.5 米

示例：

{
  "name": "Piston",
  "type": "prismatic",
  "offset": [0, 0, 1.0],
  "parent": "Elbow",
  "axis": [0, 0, 1],
  "limits": [0.0, 0.5]
}

SphericalJoint (球形关节)

  • limits (Array | null, 可选)
    • 三个轴的约束范围
    • 格式：[[min, max] | null, [min, max] | null, [min, max] | null]
    • 每个元素对应一个轴的约束：
      • [min, max]: 该轴有约束（单位：弧度）
      • null: 该轴无约束
    • 整个 limits 字段可省略（等同于所有轴无约束）
    • 示例：[[-3.14, 3.14], null, [-0.5, 0.5]] 表示 X 轴和 Z 轴有约束，Y 轴无约束

示例：

{
  "name": "Shoulder",
  "type": "spherical",
  "offset": [0, 1.5, 0],
  "parent": "Root",
  "limits": [[-3.14, 3.14], null, [-0.5, 0.5]]
}

1.5 完整示例

{
  "root_name": "Root",
  "joints": [
    {
      "name": "Root",
      "type": "fixed",
      "offset": [0, 0, 0],
      "parent": null
    },
    {
      "name": "Shoulder",
      "type": "spherical",
      "offset": [0, 1.5, 0],
      "parent": "Root",
      "limits": [[-3.14, 3.14], null, [-0.5, 0.5]]
    },
    {
      "name": "Elbow",
      "type": "revolute",
      "offset": [0, 0, 2.0],
      "parent": "Shoulder",
      "axis": [1, 0, 0],
      "limits": [0.0, 2.5]
    },
    {
      "name": "Piston",
      "type": "prismatic",
      "offset": [0, 0, 1.0],
      "parent": "Elbow",
      "axis": [0, 0, 1],
      "limits": [0.0, 0.5]
    },
    {
      "name": "EndEffector",
      "type": "fixed",
      "offset": [0, 0, 0.5],
      "parent": "Piston"
    }
  ]
}

1.6 注意事项

  1. 轴向量归一化：axis 字段不能为零向量。系统会自动归一化，但建议在 JSON 中提供归一化的值。

  2. 父子关系：必须形成有效的树形结构，不能出现循环引用。

  3. 约束范围：

    • limits 字段为可选，省略表示无约束
    • 对于 SphericalJoint，limits 数组长度必须为 3，每个元素可以是 [min, max] 或 null

  4. 单位：

    • offset: 米
    • RevoluteJoint limits: 弧度
    • PrismaticJoint limits: 米
    • SphericalJoint limits: 弧度

2. 目标轨迹文件 (targets.json)

2.1 文件用途

定义末端执行器的关键帧，系统会在关键帧之间进行插值生成完整的目标轨迹。

2.2 文件结构

[
  {
    "frame": 帧号,
    "pos": [x, y, z],
    "euler": [x, y, z]
  },
  {
    "frame": 帧号,
    "pos": [x, y, z],
    "euler": [x, y, z]
  }
]

2.3 字段说明

关键帧对象

  • frame (Integer, 必需)

    • 关键帧帧号（从 0 开始）
    • 必须按帧号顺序排列（系统会自动排序）

  • pos (Array[Float, Float, Float], 必需)

    • 世界坐标系中的位置（单位：米）
    • 格式：[x, y, z]
    • 示例：[1.0, 1.0, 1.0] 表示位置 (1, 1, 1) 米

  • euler (Array[Float, Float, Float], 必需)

    • 世界坐标系中的姿态欧拉角（单位：度，顺序：XYZ）
    • 格式：[x, y, z]
    • 旋转顺序：先绕 X 轴旋转，再绕 Y 轴，最后绕 Z 轴
    • 示例：[90.0, 0.0, 45.0] 表示绕 X 轴旋转 90 度，绕 Y 轴旋转 0 度，绕 Z 轴旋转 45 度

2.4 完整示例

[
  {
    "frame": 0,
    "pos": [0.0, 0.0, 0.0],
    "euler": [0.0, 0.0, 0.0]
  },
  {
    "frame": 80,
    "pos": [1.0, 1.0, 1.0],
    "euler": [90.0, 0.0, 45.0]
  },
  {
    "frame": 160,
    "pos": [1.0, -1.0, 1.0],
    "euler": [-90.0, 45.0, 0.0]
  },
  {
    "frame": 240,
    "pos": [2.5, 0.0, 1.0],
    "euler": [0.0, 0.0, 0.0]
  }
]

2.5 注意事项

  1. 欧拉角顺序：固定为 XYZ 顺序，不可更改。

  2. 单位：

    • pos: 米
    • euler: 度（系统内部会转换为弧度）

  3. 插值：

    • 系统会在关键帧之间进行线性插值（位置）和球面线性插值（姿态，SLERP）
    • 第一个关键帧之前和最后一个关键帧之后使用最近的关键帧值

  4. 帧号：建议从 0 开始，按递增顺序排列。

3. 动画导出文件 (animation.json)

3.1 文件用途

记录求解完成后的关节运动数据，按帧记录每个关节的局部变量。

3.2 文件结构

{
  "frames": [
    {
      "frame": 帧号,
      "joints": {
        "关节名称": {
          "type": "关节类型",
          // 其他字段根据关节类型而定
        }
      }
    }
  ]
}

3.3 字段说明

根级字段

  • frames (Array, 必需)
    • 按帧号顺序排列的帧数据

帧对象

  • frame (Integer, 必需)

    • 帧号（从 0 开始）

  • joints (Object, 必需)

    • 关节名称到关节数据的映射
    • 仅包含有自由度的关节（FixedJoint 不参与导出）

关节数据（根据关节类型）

RevoluteJoint (旋转关节)
{
  "type": "revolute",
  "angle": 角度值
}
  • type (String): "revolute"
  • angle (Float): 角度（单位：弧度）

示例：

{
  "type": "revolute",
  "angle": 1.571
}
PrismaticJoint (移动关节)
{
  "type": "prismatic",
  "displacement": 位移值
}
  • type (String): "prismatic"
  • displacement (Float): 位移（单位：米）

示例：

{
  "type": "prismatic",
  "displacement": 0.25
}
SphericalJoint (球形关节)
{
  "type": "spherical",
  "euler": [x, y, z],
  "quaternion": [w, x, y, z]
}
  • type (String): "spherical"
  • euler (Array[Float, Float, Float]): 欧拉角（单位：弧度）
  • quaternion (Array[Float, Float, Float, Float]): 四元数（格式：[w, x, y, z]）

示例：

{
  "type": "spherical",
  "euler": [0.523, 0.0, 0.785],
  "quaternion": [0.924, 0.383, 0.0, 0.0]
}

3.4 完整示例

{
  "frames": [
    {
      "frame": 0,
      "joints": {
        "Shoulder": {
          "type": "spherical",
          "euler": [0.523, 0.0, 0.785],
          "quaternion": [0.924, 0.383, 0.0, 0.0]
        },
        "Elbow": {
          "type": "revolute",
          "angle": 1.571
        },
        "Piston": {
          "type": "prismatic",
          "displacement": 0.25
        }
      }
    },
    {
      "frame": 1,
      "joints": {
        "Shoulder": {
          "type": "spherical",
          "euler": [0.628, 0.087, 0.890],
          "quaternion": [0.918, 0.396, 0.0, 0.0]
        },
        "Elbow": {
          "type": "revolute",
          "angle": 1.623
        },
        "Piston": {
          "type": "prismatic",
          "displacement": 0.27
        }
      }
    }
  ]
}

3.5 注意事项

  1. 单位：

    • RevoluteJoint angle: 弧度
    • PrismaticJoint displacement: 米
    • SphericalJoint euler: 弧度

  2. 四元数格式：[w, x, y, z]，其中 w 是标量部分。

  3. FixedJoint：固定关节不参与导出（无变量）。

  4. 帧顺序：frames 数组按帧号顺序排列，从 0 开始。

4. 文件位置建议

建议将 JSON 文件放置在以下位置：

  • skeleton.json: data/skeleton.json
  • targets.json: data/targets.json
  • animation.json: data/animation.json（导出文件）

打包时的默认文件导入

打包为可执行程序时，如果 data/ 目录下存在以下文件，它们会被自动包含到可执行文件中，作为默认文件：

  • skeleton.json - 骨骼定义文件
  • targets.json - 目标轨迹文件

如果这些文件不存在，打包仍可正常进行，用户可以在运行时通过GUI界面自行导入文件。

5. 验证与错误处理

5.1 常见错误

  1. JSON 格式错误：确保文件是有效的 JSON 格式
  2. 缺少必需字段：检查所有必需字段是否存在
  3. 类型错误：确保字段类型正确（如 frame 必须是整数）
  4. 父子关系错误：确保 parent 字段指向存在的关节
  5. 轴向量非单位向量：系统会自动归一化，但建议提供单位向量

5.2 验证工具

可以使用 JSON Schema 验证工具验证文件格式，或使用系统提供的加载函数进行验证（加载失败时会抛出异常）。

6. 版本历史

  • v1.0.0 (2024-11-13): 初始版本，基于 SPEC.md 规范

7. 参考文档

  • docs/SPEC.md: 完整的设计规范文档
  • docs/QUICKSTART.md: 快速开始指南
  • docs/PROJECT_STRUCTURE.md: 项目结构说明