Kivicube文档

简体中文

English

主题

身体AR ​

身体 AR 对应 body 类型。

它主要用于人体追踪和虚拟试衣类体验，例如衣服、配饰、身体贴纸或与人体姿态绑定的 3D 内容。

体验流程 ​

典型流程如下：

  1. 打开场景
  2. 下载素材
  3. 请求摄像头权限
  4. 加载场景
  5. 开始检测人体
  6. 检测到人体后触发 tracked
  7. 丢失人体时触发 lostTrack

身体 AR 不依赖识别图。这里的“扫描”更接近“请把全身放入画面”的引导。

摄像头 ​

身体 AR 可以根据业务选择前置或后置摄像头：

  • 自拍试衣：建议使用 cameraPosition: 'front'
  • 他人拍摄或展陈互动：可以使用默认的后置摄像头

示例：

js
await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  cameraPosition: 'front',
});

如果场景配置允许切换摄像头，也可以使用 switchCamera() 在体验中切换前后摄。

关键事件 ​

身体 AR 场景最常用的几个事件是：

  • ready
  • downloadAssetProgress
  • loadSceneEnd
  • sceneStart
  • tracked
  • lostTrack
  • error

其中：

  • sceneStart 表示场景已经开始运行，此时会展示找人引导
  • tracked 表示检测到人体，默认扫描 UI 会隐藏，拍照能力可用
  • lostTrack 表示当前画面中暂时未稳定检测到人体

扫描 UI ​

你可以通过属性 hideScan 隐藏默认扫描 UI，然后在宿主层自己渲染人体检测提示。

例如：

js
await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  hideScan: true,
});

iframe.addEventListener('sceneStart', () => {
  showBodyGuide('请将全身放入画面');
});

iframe.addEventListener('tracked', () => {
  hideBodyGuide();
});

iframe.addEventListener('lostTrack', () => {
  showBodyGuide('请后退一点，保持全身完整入镜');
});

相比“扫描中”，身体 AR 更建议使用明确的人体姿态提示，例如“请露出肩膀和全身”“请站到光线更充足的位置”。

人体遮挡与服装贴合 ​

身体 AR 会在场景内部加入默认的人体遮挡/服装贴合模型，用来辅助虚拟衣物与全身位置对齐。

宿主页面不需要直接管理这个默认模型。通常只需要关注：

  • iframe 容器尺寸是否稳定
  • 摄像头是否成功授权
  • 用户是否能按提示保持全身完整入镜
  • tracked / lostTrack 状态下 UI 是否清晰

手势交互 ​

身体 AR 支持场景配置中的旋转、缩放手势。

当前手势主要作用在身体内容对象上，不建议把核心体验设计成拖拽对象。更推荐的交互方式是：

  • 用户移动身体或调整距离完成对齐
  • 宿主层提供切换款式、颜色、尺码等按钮
  • 用户通过拍照/录屏保存效果

推荐搭配 ​

适用业务 ​

  • 虚拟试衣、上衣试穿
  • 服饰、配饰、IP 形象贴合人体展示
  • 展会互动大屏或手机自拍玩法
  • 需要拍照分享的穿搭营销活动

接入建议 ​

  1. 自拍试衣优先设置 cameraPosition: 'front'，否则用户可能需要他人协助拍摄。
  2. 引导用户保持全身完整入镜，肩膀、胸口区域被遮挡时追踪会更不稳定。
  3. 身体 AR 对距离、光线和背景复杂度比较敏感，建议在真实手机环境中验证。
  4. 如果隐藏默认扫描 UI，宿主层要在 sceneStart / tracked / lostTrack 之间维护清晰的找人提示。
  5. 拍照或录屏前，最好确认已经触发过 tracked，避免保存到未完成贴合的画面。