Files
vibemake/docs/numbered-glb-assembly.md
T

13 KiB
Raw Blame History

从编号 GLB 文件夹生成装配步骤

本地网页工具用 npm run assembly:tool 启动,打开 http://127.0.0.1:8095/,选择整机 GLB 与分件文件夹。生成后下载装配 JSON 和核对报告,后台「拼装步骤」只需上传装配 JSON。文件在本机处理,首次使用需运行 npm ci。本地页面接受小于 256 MiB 的请求,较大模型可以用下面的命令行方式。

Mac 双击项目根目录的 生成装配步骤.command,选择源文件夹,整机不在根目录时再选择整机 GLB,然后选择“按目录和标记装配”或“部件预装后总装”。完成后 Finder 会打开新的输出目录。只把里面的 整机名-装配步骤.json 上传到后台“拼装步骤”。核对记录不用上传。也可从项目根目录运行:

npm run assembly:generate -- "/路径/机器人分组" "/路径/新的输出目录"

输入示例:

机器人分组/
  Microban.glb
  1机器人左腿/
    1-1-支架.glb
    1-2-舵机.glb
  2机器人右腿/
    2-1-支架.glb
    2-2-舵机.glb
  • 整机可以放在根目录,也可独立存放并用 --reference 指定。各一级部位目录从 1 连续编号;每组从 1 连续编零件号,一件一步。不读 Finder 排列、修改时间或 Blender 实例后缀。文件支持“组-步-名称.glb”或“步-名称.glb”。所属部位以目录为准,两条腿可复用同一套步骤前缀。组内缺号、重号和未编号会一起报出。
  • 整机单独选择时,零件也可以全部平铺在一个目录内。连续 组+步 文件组成独立展示段,接回常规步后恢复此前装好的零件。安装方向按该步可见的已装件检查。
  • 默认每个大组件独立展示。含小组件的目录按 5A、5B 等字母顺序单独预装,最后进入 !5 或 !5,显示本大组件的全部已装零件再安装合装散件。
  • 最外层 #11 目录先插入十个合装步骤,让第 1~10 个已完成大组件按编号逐个移入整机位置,再安装第 11 目录的散件,不一次性显示全部组件。组内的 #8-41 先保留第 8 组当前已装件,再让第 1~7 个组件逐个移入,最后安装第 41 件。连续的 #8-42 等沿用已合装状态,不重复合装;没有 # 的 8-47 恢复第 8 组范围,8+47 则从第 47 件开始独立显示。之后再次进入 # 段会重新播放逐组汇合。按数字步号排序,原始相对路径保留 #,下载地址编码为 %23。
  • 后台整机选根目录 GLB;零件选择包含全部编号部位的父目录。可以单独把部位文件夹放进一个“零件模型”目录再传,须保留组名、文件名与层级。文件更名、重新导出、调整顺序后请重新生成 JSON。
  • 程序支持普通和 Draco 压缩的自包含刚性三角 GLB;每个分件对应整机一个唯一网格节点,可含多种材质。优先按网格节点名匹配,再尝试文件名。核对解码后的三角面,按“整机世界变换 × 分件世界变换的逆”恢复最终位置。缺件、重复、几何变化、无法表示的变换均停止。原文件不被改写。这里不处理不同坐标系下重新烘焙的网格、蒙皮或多零件合成一个节点的整机。
  • 先按编号锁定顺序,再相对当前可见阶段的已装件检查进入方向:独立预装仅检查同组,总装检查已合装部件和已安装的总装散件。普通件尝试场景轴及零件局部轴,必要时试较短行程。识别到名称含螺丝、螺钉、screw、bolt 或 Microban 型号 STP39 / BTS2 的零件,会比较局部两端的宽度,仅沿可信的螺丝头侧轴线进入。无圆头特征或轴线未对齐导出局部坐标轴时可能需要人工复核。这里只处理平移,不合成工具或拧转动画。
  • 先用采样淘汰明显相交的路径,再用三角网格 BVH 与保守推进复核。偏移是起点相对终点,GLB 使用米,Y 向上。不在手机里计算碰撞。通过表示平移检查到离终点 0.15 mm,不能证明旋转、工具空间或最终配合无干涉。
  • 报告中 review-path 表示候选直线路径受阻或未能证明通过;review-head 表示无法可靠地区分螺丝头尾。普通零件的这两种步骤保留原位显示;整组总装的处理见下文。在“核对记录/轴向检查.json”的 review 列表查看步号与文件,交模型组确认。

像 4-10STP39-14.glb 也会读为第 4 组第 10 步。每组最多一个 组号-附加-名称.glb 可以保留文件名。运行时追加 --extra-before 13 放在该组原第 13 步之前,或用 --extra-before end 放在组末。各组需要不同位置时,请分别给附加件编号。

螺丝报告会区分原始网格平移检查和沿孔轴的展示。后者检查整个螺丝头的进入空间,并检查从入口到安装处是否有连续的孔。visual-thread-fit 在螺杆外圈留出配合余量,半径最多减 30% 且不超过 0.35 mm。visual-bore-axis 表示仅确认半径达到螺杆一半的中心通道及头部空间。两类都从实际螺丝头侧进入,不能用作螺纹尺寸或完整网格无干涉的认证。

分组预装与第八组总装

此次 Microban 命令(输出目录必须尚不存在):

npm run assembly:generate -- "/Users/jerry/Downloads/Microban-分散整体glb命名标注安装顺序 2" "/Users/jerry/Downloads/Microban-新的输出目录" --reference "/Users/jerry/Downloads/Microban.glb" --final-group 8

--final-group 指定最后一个目录的编号,不限于 8。前面的每个目录是一个独立预装部件,最后一组是合装后的散件。RP1 这类带小组件或 # 标记的目录用默认模式,直接按文件和文件夹的标记装配。

  • 各目录以及目录内按数字顺序,材料、几何、颜色不改动。
  • 从社区打开装配弹窗,加载完成后默认从第一步自动播放;暂停、拖动步骤滑块、查看整体或关闭弹窗会停止连续播放。只有模型没有步骤时默认显示整体。
  • 左上角显示五条悬浮进度胶囊,当前步骤固定居中并展开,上下各两步收短,名称超长省略。连续切换时同时滚动、伸缩;点击步骤可跳转重播,手机默认显示当前步骤与精简播放/滑条,点击当前步骤可展开五行进度,上下拖动胶囊或拖动细进度条定位。电脑播放与前后切换位于进度下方,其余工具位于右侧;手机工具收纳在底部小工具栏,展开步骤不改变模型画布或镜头。列表只保留五行及两个动画缓冲行,不随总步骤数增加 DOM。
  • 前七组独立展示:只显示当前组已安装的零件。镜头按已装零件和当前进入范围取景,不按尚未出现的整组取景;当前画面容得下后续零件时保持不动,需要调整时先平滑取景,再播放安装。左右部件从各自外侧观察,组内保持观察角度,不追随零件旋转。
  • 进入总装:增加七个合装步骤,按部位编号把完成的部件放到整机位置。整个部件共用一个平移,内部螺丝不会重拧。
  • 七个部件都到位后,按第八目录的顺序安装剩下的零件。
  • 上一步、滑块跳转、重播和查看整体都由当前步骤重建状态,不依赖此前是否播放过。
  • 路径无法确认的普通零件保留原位显示。总装部件仍播放整体就位动画;未通过碰撞确认的路线在步骤里标记 pathStatus: "presentation",报告仍保留 review-path,仅用于展示,不能作为无碰撞路线。已通过检查的步骤标记 pathStatus: "checked"。程序不保证所有装配都存在直线无碰撞轴向;卡扣、过盈、螺纹及需要转动/多段路线的配合可能要人工调整。待核对列表在 核对记录/待核对步骤.txt。

前后台约定

后台仍使用同一个拼装 JSON 上传字段,保留 JSON 内容即可,不需要增加字段或重新导出 GLB。线上需要部署支持本次分组协议的前端;旧版播放器不能播放这份 JSON。

仍使用 schemaVersion: 1,通过 playback: "grouped-v1" 声明新增能力:

{
  "playback": "grouped-v1",
  "groups": [{ "id": "group-1", "label": "左腿", "parts": ["p-1-1", "p-1-2"] }],
  "steps": [
    { "id": "s1", "groupId": "group-1", "parts": ["p-1-1"] },
    { "id": "s2", "groupId": "group-1", "parts": ["p-1-2"] },
    { "id": "join-1", "type": "join", "groupId": "group-1", "parts": ["p-1-1", "p-1-2"], "installOffset": [0, 0.1, 0] },
    { "id": "final-screw", "parts": ["p-2-1"] }
  ]
}

以上只是分组字段示意;完整资源清单、零件变换等仍由生成器写入。普通步骤每个零件只能出现一次;合装步骤必须引用整个已完成部件且每个部件只合装一次。总装散件步骤不带 groupId,必须放在全部合装步骤之后。installOffset 是装配坐标系中起点相对终点的向量,单位米。

# 逐组汇合协议

按目录标记生成且含 # 时,使用 playback: "scoped-v1"。所有零件和步骤都有所属大组,所有步骤都有完整的 visibleParts 快照。生成器在每段 # 开头自动添加 type: "join" 步骤,每步引用一个完整的已装好大组件,并提供共同的 installOffset。组内零件保持相对位置整体移入,组内的螺丝和工具动作不重播。原编号零件仍只安装一次;同一个完整组件可在不同 # 段再次汇合。

例如 #11 前的十个合装步骤分别显示:第 1 组;第 1、2 组;……;第 1~10 组。之后再安装 #11-1 等散件。新增的合装步骤计入播放进度,但不改源文件编号。组内 # 则以当前已安装的部分为固定参照,让此前大组按编号进入。A…! 的小组件显隐规则、+ / - 的局部隔离恢复规则保持不变。前后跳步、拖动进度、重播都按目标快照恢复,不要求从头播放。

后台仍只保存原装配 JSON;线上播放器须支持 scoped-v1。本地生成器、网页生成工具和社区播放器共用此规则。仅上传新 JSON 不会更新线上前端代码。整组进入的路线仍区分 checked 与 presentation,后者是展示动画,未证明无碰撞。

可选的零件字段 focusDirection 为父级装配坐标系中的单位向量,指向已识别的螺丝头外侧,用于特写镜头;它不改变零件姿态或材质。相机取景、平滑过渡和分辨率由前端控制,不需要逐步写相机 JSON。详情与装配继续使用原生像素比和抗锯齿,不自动降低清晰度。

普通播放也会检查当前螺丝头是否朝向镜头,不需要打开“特写”。旧 JSON 没有方向字段时,播放器仅对名称明确的螺丝按几何两端宽度推断头部,结果按文件缓存,不修改文件。形状不明确时保留视角,不猜头尾。正反面的大角度变化先小幅拉远,沿最短水平转角绕到安装侧后推近,模型全程可见;同侧连续步骤沿用原视角。相机采用缓入缓出曲线,停稳后才开始安装,插入期间镜头保持固定。此观察方向与碰撞路径独立,不会修改未确认零件的安装位移。

播放器统一使用起止速度、加速度均为零的缓动曲线:普通件进入约 1.25 秒,整组就位约 1.8 秒;小幅镜头调整约 1.05 秒,镜头稳定后再开始安装。螺丝和工具的短促阶段也会适当延长,保留 JSON 中更慢的时长。每步完成后至少停留 0.55 秒。只调整播放节奏,不改路径、轴向、最终坐标或模型材质,不需要重新上传 JSON;系统“减少动态效果”开启时仍直接就位。

临时隐藏已装零件

每个步骤可以额外提供 visibleParts,列出本步可见的全部零件 ID。未列出的零件暂时隐藏,安装历史仍保留。清单必须包含本步正在安装的零件,不能包含未来零件;显示子零件时也必须包含它的父零件。省略此字段时沿用原来的累计显示或分组显示规则。查看整体始终显示全部零件,回退或拖动进度直接恢复目标步骤的显隐状态。

Sesame 的本次文件按以下规则生成:1-1、1-2 正常安装;1+3 只显示第 3 件;1+4 显示第 3、4 件;依此累计到 1+8,期间第 1、2 件隐藏。1-9 不设置显示覆盖,恢复第 1~8 件并播放第 9 件的安装,后续继续累计。文件名中的 + 保留原样,下载地址在 OSS 路径中编码为 %2B。

例如,第 4 步可写为 {"id":"step-1-4","parts":["p-1-4"],"visibleParts":["p-1-3","p-1-4"]}。第 9 步恢复正常写法 {"id":"step-1-9","parts":["p-1-9"]}。这是显示范围调整,不会对恢复显示的旧零件重复播放安装动画。新版 JSON 需要同时部署支持 visibleParts 的播放器。

内六角扳手

网页选择「内六角扳手 GLB」,或在命令行加 --hex-key "/路径/内六角扳手.glb"。工具 GLB 的工作端应朝局部 -Z,生成器测量工作端的六角尺寸。对已确认进入方向的内六角螺丝,匹配孔的轮廓和对边尺寸后,写入工具轴、对接点和旋转配置。工具与螺丝旋转的扫掠空间需要另行复核。

报告列出匹配数量和跳过原因。JSON 引用了工具时,将原工具 GLB 放在零件上传目录的根层,使用原文件名一起上传。工具不占用装配步号。