Go back

玩转小程序AR-基础篇

目录

Open 目录

背景

某天需求方扔了个链接：【原神官方】AR 立牌，询问小程序是否能够实现类似的AR效果。

预感AR会有很多坑的我，刚想婉拒，无奈被老大以技术调研为由，把项目接手下来。于是被迫补起：早已过了风口(bushi)的AR知识。

调研

实体 AR 立牌

斥巨资在闲鱼淘了个多莉的角色立牌，实际体验了下完整的交互流程，AR氛围感还是不错的。

AR在线制作平台

KIVICUBE 提供了可视化的3D场景搭建和动画编排系统：零基础也可创造和发布酷炫的AR作品。

3D场景搭建 动画编排系统

官方同时提供了大量创意模版供大家一键使用

技术方案

在微信小程序的技术体系下，官方提供了两种解决方案：

小程序也在基础库 2.20.0 版本开始提供了开发 AR 功能的能力，即 VisionKit。VisionKit 包含了 AR 在内的视觉算法

xr-frame是一套小程序官方提供的XR/3D应用解决方案，基于混合方案实现，性能逼近原生、效果好、易用、强扩展、渐进式、遵循小程序开发标准

简单来说：

虽然理论上我们完全可以基于 VisionKit 并结合 Three.js 或自研的 WebGL 渲染逻辑来实现 AR 效果，但这种方案开发成本较高：

开发者需要自行处理相机帧与渲染管线的衔接、追踪状态管理、姿态矩阵更新等底层逻辑，整体工程量大且维护复杂。（Kivicube 正是使用此方案，确保自研的 AR 可视化搭建平台的产物能兼容各大平台：微信小程序、原生网页H5）

而 XR-FRAME 在此基础上进一步封装了完整的 3D 渲染与交互体系，提供了大量开箱即用的能力，让开发者可以像写前端组件一样，以声明式方式快速构建 AR 场景，而不必深入到底层渲染细节。

因此最后决定：先用 XR-FRAME 快速交付第一版 MVP 小程序

XR-FRAME 指南

由于是小程序开发，所以学习 XR-FRAME 的前提，需要有小程序基础知识

而官方的两个在线文档，内容还是略显单薄，强烈建议直接参考官方 《xr-frame系统的示例集》 的源码进行实战学习

本教程配套代码：xr-frame-tutorial

XR 组件 模版代码

创建 XR 组件

创建 XR 组件

{
  "component": true,
  "usingComponents": {},
  "renderer": "xr-frame"
}components/demo1/index.json
<xr-scene>
  <xr-camera clear-color="0.4 0.8 0.6 1" />
</xr-scene>components/demo1/index.wxml

使用 XR 组件

使用 XR 组件

{
  "usingComponents": {
    "demo1": "../../components/demo1"
  },
  "disableScroll": true, 
  "renderer": "webview"
}pages/demo1/index.json
<view>
  <demo1
    disable-scroll
    id="main-frame"
    width="{{renderWidth}}"
    height="{{renderHeight}}"
    style="width:{{width}}px;height:{{height}}px;top:{{top}}px;left:{{left}}px;"
  />
</view>pages/demo1/index.wxml
Page({
  data: {
    left: 0,
    top: 0,
    width: 0,
    height: 0,
    renderWidth: 0,
    renderHeight: 0,
  },
  onLoad(options) {
    const info = wx.getSystemInfoSync()
    const width = info.windowWidth
    const height = info.windowHeight
    const dpi = info.pixelRatio

    this.setData({
      width, 
      height,
      renderWidth: width * dpi,
      renderHeight: height * dpi
    });
  },
})pages/demo1/index.js

渲染 XR 组件

渲染 XR 组件

渲染效果：绿色背景的画布 Canvas

绿色背景的画布 Canvas

3D 渲染

源码示例: 3D 渲染

最基础的 3D 渲染 思维导图

3D渲染思维导图

添加物体

添加一个 立方体 （Cube）物体

<xr-scene>
  <xr-mesh node-id="cube" geometry="cube" />
  <!-- 设置 target 指向 cube，让相机始终看向这个立方体--> 
  <xr-camera clear-color="0.4 0.8 0.6 1" position="1 3 4" target="cube" camera-orbit-control />
</xr-scene>components/demo1/index.wxml

物体黑色是因为在我们没有给xr-mesh指定材质时，用的是基于PBR效果的默认材质，需要光照

临时解决方案： 创建一个不需要光照的材质，并且使用这个材质

<xr-scene>
  <xr-asset-material asset-id="simple" effect="simple" uniforms="u_baseColorFactor:0.8 0.4 0.4 1" />
  <xr-mesh node-id="cube" geometry="cube" material="simple" />
  <xr-camera clear-color="0.4 0.8 0.6 1" position="1 3 4" target="cube" camera-orbit-control />
</xr-scene>components/demo1/index.wxml

不需要光照的材质

添加光照

<xr-scene>
  <xr-mesh node-id="cube" geometry="cube" uniforms="u_baseColorFactor:0.8 0.4 0.4 1" />
  <!-- 一个环境光 -->
  <xr-light type="ambient" color="1 1 1" intensity="1" />
  <!-- 一个主平行光 -->
  <xr-light type="directional" rotation="40 70 0" color="1 1 1" intensity="3" cast-shadow /> 
  <xr-camera clear-color="0.4 0.8 0.6 1" position="1 3 4" target="cube" camera-orbit-control />
</xr-scene>components/demo1/index.wxml

光照的材质

添加纹理

纹理 Texture 是 GPU 中的图像，供着色器采样使用。在框架中其一般被作为材质的一部分uniforms使用

<xr-scene>
  <xr-assets bind:progress="handleAssetsProgress" bind:loaded="handleAssetsLoaded">
    <!-- 加载纹理 -->
    <xr-asset-load type="texture" asset-id="waifu" src="https://mmbizwxaminiprogram-1258344707.cos.ap-guangzhou.myqcloud.com/xr-frame/demo/waifu.png" />
    <!-- 材质中使用纹理 -->
    <xr-asset-material asset-id="mat" uniforms="u_baseColorMap: waifu" />
  </xr-assets>

  <!-- 使用材质 -->
  <xr-mesh node-id="cube" geometry="cube" material="mat" cast-shadow />
  
  <!-- 一个环境光 -->
  <xr-light type="ambient" color="1 1 1" intensity="1" />
  <!-- 一个主平行光 -->
  <xr-light type="directional" rotation="40 70 0" color="1 1 1" intensity="3" cast-shadow /> 
  <xr-camera clear-color="0.4 0.8 0.6 1" position="1 3 4" target="cube" camera-orbit-control />
</xr-scene>components/demo1/index.wxml

图片纹理

我们继续新加一个 平面 (Plane) 物体

<xr-assets bind:progress="handleAssetsProgress" bind:loaded="handleAssetsLoaded">
    <xr-asset-load type="texture" asset-id="deepred" src="https://avatars.githubusercontent.com/u/13102815" />
    <xr-asset-material asset-id="mat2" uniforms="u_baseColorMap: deepred" />
</xr-assets>

<xr-mesh node-id="plane" geometry="plane" material="mat2" position="0 1 0" />components/demo1/index.wxml

平面物体

添加动画

{
  "setting": {
    "ignoreDevUnusedFiles": false,
    "ignoreUploadUnusedFiles": false
  }
}project.private.config.json

动画

添加一个无限旋转的动画

注意：旋转的值是弧度！！！

360度等于2π弧度，约等于 2 * 3.14

{
  "keyframe": {
    "logo": {
      "0": {
        "rotation": [0, 0, 0]
      },
      "100": {
         // 注意是弧度，360度等于2π，约等于6.28
        "rotation": [6.28, 0, 0]
      }
    }
  },
  "animation": {
    "logo": {
      "keyframe": "logo",
      "duration": 4,
      "ease": "linear",
      "loop": -1
    }
  }
}assets/animation.json
<!-- 加载动画资源 -->
<xr-asset-load asset-id="anim" type="keyframe" src="/assets/animation.json"/>

<xr-mesh node-id="plane" geometry="plane" material="mat2" position="0 1 0" anim-keyframe="anim" anim-autoplay="clip:logo" />components/demo1/index.wxml

动画

添加 3D 模型

支持 GLTF 格式模型

<!-- 加载 GLTF 模型 -->
<xr-asset-load type="gltf" asset-id="miku" src="https://mmbizwxaminiprogram-1258344707.cos.ap-guangzhou.myqcloud.com/xr-frame/demo/miku.glb" />

<!-- 渲染 GLTF 组件 -->
<xr-gltf model="miku" position="-0.15 0.75 1" scale="0.07 0.07 0.07" rotation="0 180 0" anim-autoplay />components/demo1/index.wxml

GLTF 模型

AR 系统

AR 能力，需要调用摄像头权限

微信开发者工具无法模拟，请使用真机预览模式

真机预览模式

Plane 识别

源码示例: Plane 模式

Plane 模式是 AR 中的平面检测与追踪功能

常见的交互流程：

  1. 扫描阶段
  1. 检测阶段
  1. 放置阶段
<!-- AR system 系统开启 Plane 模式 -->
<xr-scene ar-system="modes:Plane" bind:ready="handleReady">
  <xr-assets bind:loaded="handleAssetsLoaded">
    <xr-asset-load type="gltf" asset-id="anchor" src="https://mmbizwxaminiprogram-1258344707.cos.ap-guangzhou.myqcloud.com/xr-frame/demo/ar-plane-marker.glb" />
    <xr-asset-load type="gltf" asset-id="miku" src="https://mmbizwxaminiprogram-1258344707.cos.ap-guangzhou.myqcloud.com/xr-frame/demo/miku.glb" />
    <xr-asset-load type="texture" asset-id="deepred" src="https://avatars.githubusercontent.com/u/13102815" />
    <xr-asset-material asset-id="mat" uniforms="u_baseColorMap: deepred" />
  </xr-assets>
  <xr-light type="ambient" color="1 1 1" intensity="1" />
  <xr-light type="directional" rotation="40 70 0" color="1 1 1" intensity="3" cast-shadow />
  <!-- AR 追踪器 对应也要开启 Plane 模式 -->
  <xr-ar-tracker mode="Plane">
    <!-- 找到平面后，显示视觉指示器 -->
    <xr-gltf model="anchor"></xr-gltf>
  </xr-ar-tracker>
  <!-- 首先隐藏虚拟物体 -->
  <xr-node node-id="setitem" visible="false">
    <xr-gltf model="miku" anim-autoplay scale="0.07 0.07 0.07" rotation="0 180 0" />
    <xr-mesh node-id="plane" geometry="plane" material="mat" scale="0.3 0.3 0.3" />
  </xr-node>
   <!-- camera 的 background 设置成 ar -->
  <xr-camera clear-color="0.4 0.8 0.6 1" background="ar" is-ar-camera />
</xr-scene>components/demo3/index.wxml
Component({
  methods: {
    handleAssetsLoaded: function ({ detail }) {
      wx.showToast({ title: '点击屏幕放置模型' });
      this.scene.event.add('touchstart', () => {
        // 虚拟物体被"放置"到现实世界的平面
        this.scene.ar.placeHere('setitem', true);
      });
    },
    handleReady: function ({ detail }) {
      this.scene = detail.value;
    },
  }
})pages/demo3/index.js

Marker 识别

源码示例: Marker 模式

Marker 模式，能够识别预先设定的目标物体(定义为 Marker，包括2D平面物体和3D物体），进行视觉跟踪与定位，通过在目标物体周围渲染虚拟物体，从而实现AR功能。

模型与现实物体保持空间位置关系(即：3D 层级 效果)。

Marker 分类

  1. 2D Marker，仅适用于平面类物体，用户上传一张平面物体的俯视图像作为目标物体，算法运行时识别该平面物品，并渲染出相关虚拟物体。2D Marker可以理解为特殊的 3D Marker。
  2. 3D Marker，相比于2D Marker，能够识别3D物体，不局限于平面物体，具有更广的使用范围，算法运行前，需要手动制作3D Marker的识别目标文件（.map文件），然后算法运行时载入该文件用于识别
<xr-scene ar-system="modes:Marker" bind:ready="handleReady">
  <xr-assets bind:loaded="handleAssetsLoaded">
    <xr-asset-load type="video-texture" asset-id="hikari" options="loop:true" src="https://assets.papegames.com/resources/cdn/20250925/1c85f5b5ecde29ea.mp4" />
    <xr-asset-load type="texture" asset-id="deepred2" src="https://assets.papegames.com/resources/cdn/20250925/c737cf37d083d543.png" />
    <xr-asset-material asset-id="mat" effect="simple" uniforms="u_baseColorMap: video-hikari" />
    <xr-asset-material asset-id="mat3" effect="simple" uniforms="u_baseColorMap: deepred2" />
  </xr-assets>
  <xr-node wx:if="{{loaded}}">
    <xr-ar-tracker mode="Marker" bind:ar-tracker-switch="handleTrackerSwitch" src="https://assets.papegames.com/resources/cdn/20250925/fe8dad0e9800ef81.jpg">
      <xr-mesh node-id="mesh-plane" geometry="plane" material="mat" scale="1.7778 1 1" position="0 0.1 0" />
      <xr-mesh node-id="plane" geometry="plane" material="mat3" position="0.1 0.8 0.1" scale="0.12 0.12 0.12" />
    </xr-ar-tracker>
  </xr-node>
  <xr-camera clear-color="0.4 0.8 0.6 1" background="ar" is-ar-camera />
</xr-scene>components/demo4/index.wxml
Component({
  methods: {
    handleReady: function ({ detail }) {
      this.scene = detail.value;
    },
    handleAssetsLoaded: function ({ detail }) {
      this.setData({ loaded: true });
    },
    handleTrackerSwitch: function ({ detail }) {
      // 获取追踪状态
      const active = detail.value;
      const video = this.scene.assets.getAsset('video-texture', 'hikari');
      // 识别到物体，播放视频
      // 识别中，暂停视频
      active ? video.play() : video.stop();
    }
  }
})components/demo4/index.js

OSD 识别

源码示例: OSD 模式

OSD（One-shot Detection）Marker 识别模式，可以看成是一种特殊的 Marker 模式 ：在摄像头画面上“贴图叠加”的模式，主要以 屏幕坐标系（2D） 为主，不真正感知空间深度

<xr-scene ar-system="modes:OSD" bind:ready="handleReady">
  <xr-assets bind:loaded="handleAssetsLoaded">
    <xr-asset-material asset-id="mat" effect="simple" states="alphaMode:BLEND" />
    <xr-asset-material asset-id="text-simple" effect="simple" />
  </xr-assets>
  <xr-node>
    <xr-ar-tracker mode="OSD" src="https://assets.papegames.com/resources/cdn/20250925/fe8dad0e9800ef81.jpg">
      <xr-node rotation="0 180 0">
        <xr-mesh node-id="text-wrap" geometry="plane" material="mat" position="0 1 0" scale="1 1 0.5" rotation="90 0 0" uniforms="u_baseColorFactor:0.875 0.616 0.624 1" />
        <xr-text node-id="text-name" position="-0.25 1.05 0" scale="0.1 0.1 0.1" material="text-simple" value="美食家蜜蜂" />
      </xr-node>
    </xr-ar-tracker>
  </xr-node>
  <xr-camera clear-color="0.4 0.8 0.6 1" background="ar" is-ar-camera />
</xr-scene>components/demo5/index.wxml

人脸识别

源码示例: 人脸识别

<!-- AR system 系统开启 Face 模式 同时开启前置摄像头 -->
<xr-scene ar-system="modes:Face;camera:Front">
  <xr-assets>
    <xr-asset-load type="gltf" asset-id="mask" src="https://mmbizwxaminiprogram-1258344707.cos.ap-guangzhou.myqcloud.com/xr-frame/demo/jokers_mask_persona5.glb" />
  </xr-assets>
  <!-- AR 追踪器 对应也要开启 Face 模式 -->
  <!-- auto-sync 是一个数字数组，用于将对应顺序的子节点绑定到某个特征点上 -->
  <xr-ar-tracker mode="Face" auto-sync="43">
    <!-- 包含识别成功后需要展示的场景 -->
    <xr-gltf model="mask" rotation="0 180 0" scale="0.5 0.5 0.5" />
  </xr-ar-tracker>
  <xr-light type="ambient" color="1 1 1" intensity="1" />
  <xr-light type="directional" rotation="40 70 0" color="1 1 1" intensity="3" />
  <!-- AR 相机 -->
  <xr-camera background="ar" is-ar-camera />
</xr-scene>components/demo2/index.wxml

除了人脸识别（Face），还有 人体识别（Body），人手识别（Hand），可以参考官方文档学习

总结

到这里，我们已经把 XR-FRAME 的基础能力都过了一遍：从创建场景、添加物体、设置光照，到加载模型和动画，再到四种 AR 识别模式（Plane、Marker、OSD、Face）。理论上，你已经可以做出一个简单的 AR 效果了。

但理论和实际总是有差距的。在下一篇实战篇中，我会分享更高阶的知识点和实际项目中的经验：

Share this post on:
Share this post via WhatsAppShare this post on FacebookShare this post on XShare this post via TelegramShare this post on PinterestShare this post via email
Next Post
Hexo迁移Astro