Files
vibemake/docs/assembly-screw-animation.md

6.1 KiB

装配 JSON:螺丝与扳手动画

本次扩展在现有 schemaVersion: 1 装配包中增加可选 tools 和零件的 installation。没有这些字段的旧步骤仍按原方式平移安装。前端不根据机器人名称、零件文件名或 GLB 节点名判断动画;后台保存并原样返回配置即可。

上传

本次完整上传目录:/Users/jerry/Downloads/小鸭子-扳手装配/。

  1. “零件模型”选择 零件模型 整个文件夹:原 292 个零件 + 内六角扳手.glb,共 293 个 GLB。
  2. “拼装步骤”上传 鸭子-拼装步骤-带扳手.json。
  3. 使用更新后的前端,打开 AI 装配、逐步装配、播放装配。整体视图中工具隐藏。

工具也通过现有 modelPartsFiles 资源清单上传,步骤仍使用 assemblyJsonUrl。不用新增后端字段,但若后台有 JSON 白名单/重新序列化逻辑,应保留下方新增字段。工具列在 files、tools,不列在 parts 或 steps,也不计入需安装的零件。后台编辑器须将被 tools 引用的文件归为工具,避免自动生成“安装扳手”的步骤。后台替换零件绑定时请发送完整文件清单,不能仅上传一个工具把其他零件绑定覆盖。

清单里的路径、字节数、SHA-256 必须与上传文件一致。工具必须是包含材质与贴图的自包含 GLB,单位为米。加载工具使用与零件相同的校验和资源地址解析流程。

JSON 示例

下面的工具声明放在根节点,installation 放在需要拧紧的那颗零件内;示例省略原有 files、位置、最终四元数等字段,不能单独作为完整包上传。

{
  "tools": [{
    "id": "hex-key-1-5",
    "file": "内六角扳手.glb",
    "tipPosition": [0.005250010406598449, -0.000000003587008764, 0.03276707977056503],
    "tipAxis": [0, 0, -1]
  }],
  "parts": [{
    "id": "duck-part-084",
    "file": "标准杯头内六角螺钉_M2x4.008.glb",
    "installation": {
      "type": "screw",
      "toolId": "hex-key-1-5",
      "axis": [0, 0, -1],
      "socketPosition": [0, 0, -0.0009],
      "toolQuaternion": [0, 0, 0.25881904510252074, 0.9659258262890683],
      "direction": "clockwise",
      "turns": 3,
      "travel": 0.0012,
      "approachDuration": 0.45,
      "engageDuration": 0.3,
      "tightenDuration": 2.4,
      "retractDuration": 0.35,
      "toolClearance": 0.012
    }
  }]
}
字段 含义
tools[].tipPosition 工具工作端中心,相对 GLB 场景根坐标;须包含 GLB 内部节点变换。不要用包围盒中心代替端点。
tools[].tipAxis 可选单位向量,工具从工作端朝螺丝孔内的方向,使用工具 GLB 场景根坐标。本扳手是 -Z,手柄在 +Z 一侧;不是 +Z。播放器将此方向对齐 installation.axis,同时保持 toolQuaternion 指定的绕轴姿态。旧 JSON 未声明时,在加载时从端点附近的端面法向测量一次。
socketPosition 工具插入后的端点位置,相对螺丝 GLB 场景根坐标;此处在头部表面下 0.9 mm。也是旋转轴经过的点。
axis 螺丝局部坐标下的插入方向,必须是单位向量。本批螺丝轴是局部 -Z;经零件自身和父级四元数转换,不是写死世界 -Z。
toolQuaternion 工具 GLB 坐标到螺丝局部坐标的旋转,[x,y,z,w]。本工具绕局部 Z 转 30°,让六角边对齐孔口。
toolScale 可选工具显示比例,默认 1。缩放后播放器重新计算端点位置,使工具尖端仍与对接点重合。
direction 从工具一侧朝孔内看,clockwise 为顺时针,counterclockwise 为逆时针。
turns 旋转整数圈,1–20。以整数圈结束,保证回到原 JSON 的最终朝向。
travel 最后边转边拧入的距离,单位米。与已有 installOffset 分开:后者是零件起始偏移,使用父级坐标。
四个 Duration 就位、扳手插入、旋转拧紧、扳手退出的秒数。旋转时间 0.5–20 秒,其他阶段 0.1–5 秒。
toolClearance 工具插入/退出沿轴移动的距离,单位米,默认 0.012。

必填:type、toolId、axis、socketPosition、direction、turns、travel。toolQuaternion 默认单位四元数;时间与退出距离有默认值。螺丝及其祖先必须等比缩放,避免工具旋转变形。

播放规则

  • 零件先按现有偏移就位,再插入工具、一起转动并向最终位置移动,最后工具退出消失。
  • 同一步里的螺丝按 steps[].parts 顺序逐颗处理。非螺丝不带 installation,保持原有平移。
  • 工具是临时展示节点,贴合螺丝运动;不参与整机包围盒、最终装配结果,不改模型文件或材质。
  • 切换步骤、拖动进度、查看整体会清理上一动画的工具与旋转;暂停会停住拧紧动画,关闭弹窗释放资源。
  • 旧 JSON、其他机器人均无需增加工具字段。新配置不能依赖旧版前端显示效果,需先部署更新后的播放器。

本次 144 颗 M2 杯头内六角螺钉(4/5/6/8 mm 长度)采用该效果。原 292 个零件的最终变换与 91 个步骤完全保留,所有 GLB 字节及材质未改写。这里是视觉装配示意,未做工具与周边零件的碰撞检测、真实工序或紧固扭矩验证。

本地效果:http://localhost:8090/examples/screw-assembly.html。生成命令:node scripts/package-microduck-screw.mjs。

2026-10-30 修正

239 步新版中 165 颗杯头螺丝的工具旋转曾错误地将 +Z 当作扳手工作轴,导致工具翻到螺丝头背面。现改为 -Z,并添加工作轴声明;不翻转原螺丝打入方向、不改最终姿态或材质。已对 165 颗逐个核对头部端面更宽、孔口深度、起始偏移与头部方向一致。此检查不等于整机所有轨迹无碰撞认证。

旧 JSON 运行时也会对齐工具工作轴,避免此类反向错误。零件文件名、字节数和哈希仍须与后台绑定版本一致;压缩版和未压缩版的清单不能混用。模型资源已取消单文件 50 MB、合计 200 MB 的大小限制;JSON 文本限额和路径、完整性校验继续保留。