Files
vibemake/README.md
T

10 KiB
Raw Blame History

vibemake 网站(静态版)

纯静态页面,无需构建。three.js、urdf-loader、marked、DOMPurify 和字体都放在 vendor/(node scripts/vendor.mjs 下载),不依赖外部 CDN;3D 引擎只在需要的页面按需加载。

本地运行

浏览器不允许 file:// 读取 URDF,必须起一个本地服务器:

cd ~/vibemake-site
node scripts/server.mjs
# http://localhost:8091   后端接口数据(/api 转发到 dev 后端;线上也用这个服务器,按域名自动选 dev / 正式后端)
# http://127.0.0.1:8091   本地演示数据(最早的完整样子,作参考)

页面路由(不带 .html):/、/explore、/studio?robot=<id>、/cad、/pcb、/project/<编号>、/workspace、/workspace/<编号>;旧的 xxx.html 地址会 301 跳到新地址。/cad 和 /pcb 分别全屏嵌入 https://cadworld-studio.robotquan.com/cad 与 https://cadworld-studio.robotquan.com/pcb。 线上部署用同一个 server.mjs(在 dist 里 npm start),nginx / 1Panel 只需把整个站点反向代理到它,见 dist/DEPLOY.md。

目录

index.html            首页:精选项目 3D 轮播 → 本周热门 → 社区讨论 → 创客 → 发布引导
explore.html          发现:搜索(/ 聚焦)/ 类型筛选 / 我的收藏·Fork / 排序 / 网格-列表切换
project.html          项目页(类 GitHub):标题 + Star / Fork / 关注 → 大尺寸 3D 舞台 →
                      概览·文件·讨论·Fork·动态标签(?id=&tab=&path=),右侧关于/贡献者/语言/相关项目
workspace.html        「我的」:/workspace 我的项目;/workspace/<编号> 仓库页(代码浏览、在线编辑、上传、提交记录、发布、设置)
studio.html           工作台:左侧选机器人,底部「遥控 / 动作 / 爆炸图」切换、录制回放(纯仿真)
css/style.css         全部样式(:root 里是颜色变量)
js/layout.js          顶部导航 renderShell(active, {overlay, footer})、⌘K 搜索、页脚、图标、头像、toast
js/community.js       社区数据层:合并 robots.json + community.json,文件树、缩略图、本地 Star/评论状态
js/registry.js        机器人配置来源(ROBOTS_ENDPOINT)
js/viewer.js          3D 渲染:URDF 加载、取景、地面、关节拖拽、遥控跟随、爆炸图、离屏缩略图
js/motion.js          运动控制器 + 模板(generic/quadruped/hexapod/biped/arm/wheeled)
js/assistant.js       Maker AI(AI 项目助手)(右下角按钮 + 对话面板,⌘J 打开):找项目、创建空项目、Fork,接 /api/community/ai/chat;演示数据模式下播放示例对话
js/connection.js      实体机器人连接(Web Serial / WebSocket),控制台暂未使用,接硬件时再接回
robots/robots.json    机器人配置(URDF、jointMap、步态……)
data/community.json   社区演示数据(用户、Star 数、README、提交、讨论、Fork)
robots/phantomx/      PhantomX 六足(HumaRobotics/phantomx_description,BSD)
robots/xlerobot/      XLeRobot 轮式双臂(Vector-Wangel/XLeRobot,Apache-2.0)
robots/open-duck-mini/ Open Duck Mini v2 双足(apirrone/Open_Duck_Mini,Apache-2.0)
robots/so101/         SO-ARM101 机械臂(TheRobotStudio/SO-ARM100,Apache-2.0)
                      以上均从 GitHub 导入:只保留 <visual> 用到的网格,路径改为 meshes/<文件名>,
                      浮动根关节改为 fixed;版权归原作者,许可证见各项目 README
robots/demo-*/        早期用基础几何体生成的演示 URDF(已不在列表中,可作为写配置的参考)

演示环境下 Star / Fork / 关注 / 点赞 / 评论保存在浏览器 localStorage; 接后端后把这些操作换成接口调用即可(集中在 js/project.js 的事件处理里)。

添加一个机器人

  1. 把 URDF 和网格放到 robots/<id>/(或任意 CDN 地址)。 URDF 里网格写成相对路径 meshes/xxx.stl 即可;用了 package://xxx/ 的话配置 packages。
  2. 在 robots/robots.json 加一项:
{
  "id": "xlerobot",
  "name": "XLeRobot",
  "maker": "Vector Wang",
  "description": "双臂移动机器人",
  "urdf": "robots/xlerobot/xlerobot.urdf",
  "packages": { "xlerobot": "robots/xlerobot" },
  "thumbnail": "robots/xlerobot/thumb.webp",
  "upAxis": "z",
  "archetype": ["wheeled", "arm"],
  "jointMap": {
    "base.x": "root_x_axis_joint",
    "base.y": "root_y_axis_joint",
    "base.yaw": "root_z_rotation_joint",
    "arm.R.base": "Rotation",   "arm.R.shoulder": "Pitch",   "arm.R.elbow": "Elbow",
    "arm.R.wrist_pitch": "Wrist_Pitch", "arm.R.wrist_roll": "Wrist_Roll", "arm.R.gripper": "Jaw",
    "arm.L.base": "Rotation_2", "arm.L.shoulder": "Pitch_2", "arm.L.elbow": "Elbow_2",
    "arm.L.wrist_pitch": "Wrist_Pitch_2", "arm.L.wrist_roll": "Wrist_Roll_2", "arm.L.gripper": "Jaw_2",
    "head.yaw": "head_pan_joint", "head.pitch": "head_tilt_joint"
  },
  "jointSign": {},
  "stance": {},
  "gait": { "speed": 0.4, "turnRate": 1.2 },
  "view": { "yaw": 35, "pitch": 16, "distance": 1 },
  "stats": { "stars": 0, "mods": 0 },
  "hardware": { "connection": "usb-serial", "baudRate": 1000000, "servoIds": { "Rotation": 1 } }
}

只填 id / name / urdf 也能显示,会用 generic 模板让所有关节在限位内摆动。

字段说明

字段 说明
archetype generic / quadruped / hexapod / biped / arm / wheeled,可组合成数组
jointMap 语义名 → URDF 关节名。语义名见下表
jointSign 方向不对就设 -1,支持通配符:{"leg.*.knee": -1}
stance 初始姿态(弧度),键可以是语义名(支持通配符)或 URDF 关节名
gait 步态参数:stepLen 步幅、lift 抬脚、cadence 步频 Hz、speed m/s、turnRate rad/s、wheelRadius、track 轮距
view 相机:yaw / pitch(角度)、distance(倍率)
upAxis URDF 一般是 z(默认),网格本身 Y 轴向上时填 y
facing 模型正面朝向修正(度)。我们的「前进」是 +x,模型正面朝 -x 就填 180
paint 按材质名包含匹配:颜色字符串,或 { "preset": "plastic / metal / rubber", "color": "#16181b", "roughness": 0.45 }。也支持 metalness、envMapIntensity、clearcoat、clearcoatRoughness、emissive、emissiveIntensity;没有 PBR 数据的 URDF / STL 材质默认使用统一的展示金属表面,GLTF PBR 材质保留原参数。
extras 给模型补几何体,如眼珠:[{"link": "head_assembly", "shape": "cylinder", "radius": 0.0115, "xyz": [x, y, z], "axis": "z", "color": "#07080a"}]
gait.footComp 双足脚掌补偿系数,默认 {"hip": 1, "knee": 1}(踝 = -(髋·hip + 膝·knee)),髋膝转向相反的机器人填 -1
gait.armAmp 展示动画里手臂摆动幅度倍率,装在移动底盘上的手臂建议 0.3~0.5
hardware connection: usb-serial / pi-ws;baudRate、url、servoIds、direction
thumbnail 不填会自动离屏渲染一张

语义关节名

类型 语义名
quadruped leg.{FL,FR,RL,RR}.{hip,knee,ankle,yaw}
hexapod leg.{L1,L2,L3,R1,R2,R3}.{hip,knee,ankle}(hip 为水平摆动的 coxa)
biped leg.{L,R}.{hip,knee,ankle}、arm.{L,R}.shoulder
arm arm.{base,shoulder,elbow,wrist_pitch,wrist_roll,gripper},多臂用 arm.L.* / arm.R.*
wheeled wheel.{FL,FR,RL,RR} 或 wheel.{L,R}(名字含 L 为左轮)
通用 head.yaw、head.pitch;base.x / base.y / base.yaw(URDF 自带虚拟底盘关节时)

模板的方向约定:hip 正值脚往后、knee 正值屈膝、wheel 正值向前滚。和你的 URDF 相反就用 jointSign 翻转。

打包部署

npm install                            # 第一次打包前装一次(只是打包工具:模型压缩)
node scripts/build.mjs                 # 生成 dist/ 和 dist.zip;STL 网格会转成 Draco 压缩的 GLB(47 MB → 3 MB)
SITE_ROOT=dist PORT=8093 node scripts/server.mjs   # 本地预览打包结果

dist 里附带 nginx.conf.example(/api 转发、页面路由、缓存、gzip)和 DEPLOY.md。

接入后端(Community API)

node scripts/server.mjs                                    # http://localhost:8091,/api 代理到 https://dev-vibemake-api.robotquan.com
API_TARGET=http://localhost:8993 node scripts/server.mjs   # 换成本机后端
  • 页面数据只来自后端接口,接口出错(如 502)就在页面上直接显示错误,不会换成演示数据。 地址栏写 ?source=mock 才使用本地演示数据(data/community.json),只对当前这次打开有效。
  • 接口封装在 js/api.js(全部接口、统一错误、Token、SSE);登录、发布、Fork 弹窗在 js/auth.js。
  • 线上同样由 server.mjs 转发 /api:dev-*、localhost、局域网 → dev 后端,其他域名 → 正式后端 vibemake-api.robotquan.com。
  • 3D 模型:项目字段 urdfMainUrl 有值就显示,在「我的 → 项目 → 设置 → 3D 模型」上传 URDF 文件夹(直传 OSS)。 文件夹里只有 .xacro 时,浏览器先用 xacro-parser 展开成 .urdf(js/xacro.js),和原文件一起上传;$(find 包名)、package://包名/ 按 package.xml 找目录。
  • 后端暂缺的接口和字段见 docs/api-gaps.md。

演示数据 / 硬件

  • 机器人列表:修改 js/registry.js 的 ROBOTS_ENDPOINT,接口返回同结构的数组(或 { robots: [...] })。
  • 硬件协议:修改 js/connection.js 的 encode()。默认每行一条 JSON: {"type":"joints","t":1712345678901,"q":{"joint":0.12},"servo":{"1":0.12}}
  • 校准零位保存在浏览器 localStorage(vm.cal.<id>),录制片段可导出 JSON。

社区数据(data/community.json)

projects 以机器人 id 为键:slug、owner、stars、forks、watchers、license、updated、topics、 languages、contributors、featured(true,或写数字决定首页轮播顺序,越小越靠前)、readme(Markdown)、commits([消息, 作者, 时间])、 discussions(含 replies)、forkList([作者, 名称, 收藏, 说明, 时间])。 users 以 handle 为键:name、color、bio。接后端时替换 js/community.js 的 COMMUNITY_ENDPOINT。