@douyin-microapp/microapp-ar-three

microapp-ar-three

降低外部开发者在字节小程序中使用 ThreeJS 对 AI/AR 模型进行渲染的难度。目前支持两种功能：

• 根据 AI/AR 算法数据对模型进行抠除（例如试鞋场景下从鞋子模型中抠掉脚腕部分）
• 根据 AI/AR 算法数据调整模型的 position、scale 和 rotation

详细的使用方法介绍请参考字节跳动小程序开发文档 codelab 中的 microapp-ar-three 教程：https://microapp-codelabs.bytedance.com/

目录

• 使用方法
• ArMixer
  • ArMixer
  • render
• ArFootProcessor
  • ArFootProcessor
  • updateModels
• ArNailProcessor
  • ArNailProcessor
  • updateModels
• ArNailUtils
  • getNailModelGroupByColor
  • getNailModelGroupByTexture

使用方法

• 通过 npm 安装

npm install @douyin-microapp/microapp-ar-three

• 导入 ArMixer 和需要使用的 ArProcessor，以 ArFootProcessor 为例

import { ArMixer, ArFootProcessor } from '@douyin-microapp/microapp-ar-three'

• @douyin-microapp/microapp-ar-three/libs 下的 three.js 是解决了兼容性的 THREE，可以直接在字节小程序中使用，通过调用 getThree() 传入 canvas 来调用：

import { getThree } from '@douyin-microapp/microapp-ar-three/libs/three.js'
function init(canvas) {
  const THREE = getThree(canvas)
}

ArMixer

ArMixer

ArMixer 构造函数，创建一个 ArMixer 对象。ArMixer 根据 arProcessors 的配置混合 cameraTexture、modelTexture 以及 maskTexture，并通过 mixedTexture 属性获取混合结果。

语法

const arMixer = new ArMixer(options)

参数说明

属性名	类型	默认值	必填	说明
three	type of THREE	-	是	当前使用的 THREE 本身
processors	ArProcessor[]	-	是	arProcessor 数组
cameraTexture	THREE.Texture	-	是	保存了一帧相机画面数据的 THREE.Texture
modelTexture	THREE.Texture	-	是	绘制了所有模型的 THREE.Texture
mixedTextureWidth	number	-	是	指定保存混合结果的 mixedTexture 的宽度
mixedTextureHeight	number	-	是	指定保存混合结果的 mixedTexture 的高度

代码示例

const arMixer = new ArMixer({
      three: THREE,
      processors: [arProcessor0,...,arProcessorN],
      cameraTexture: cameraTexture,
      modelTexture: objectTarget.texture,
      mixedTextureWidth: width,
      mixedTextureHeight: height
    })

render

ArMixer 对象调用 render 进行一次混合，将结果渲染到 mixedTexture 上。

语法

arMixer.render(options)

参数说明

属性名	类型	默认值	必填	说明
renderer	THREE.Renderer	-	是	当前渲染使用的 renderer

代码示例

onFrame(renderer: THREE.WebGLRenderer, data: Image) {
    this.leftMaskTexture.needsUpdate = true;
    this.rightMaskTexture.needsUpdate = true;
    (this.plane.material as any).uniformsNeedUpdate = true;
    this.cameraTexture.needsUpdate = true;

    renderer.setSize(this.width, this.height);
    const savedTarget = renderer.getRenderTarget();
    renderer.setRenderTarget(this.objectTarget);
    renderer.render(this.objectScene, this.objectCamera);

    renderer.setRenderTarget(null);

    this.arMixer.render({
      renderer: renderer
    })

    renderer.render(this.scene, this.camera);
    renderer.setRenderTarget(savedTarget);
}

ArFootProcessor

ArFootProcessor

ArFootProcessor 的构造函数，创建一个 ArFootProcessor 对象。ArFootProcessor 负责根据算法数据更新足部模型信息。ArFootProcessor 的使用示例可参考字节跳动小程序 codelab

语法

const arFootProcessor = new ArFootProcessor(options)

参数说明

options 为 Object 类型，属性如下：

属性名	类型	默认值	必填	说明
three	type of THREE	-	是	当前使用的 THREE 本身

代码示例

const arFootProcessor = new ArFootProcessor({
  three: THREE,
})

AR Foot 的 demo 可通过下面的链接来获取，运行前需要修改一下模型获取地址，模型的朝向以及尺寸可参考 updateModels 以及 shoe_models 中的示例模型（本地测试的话可以使用 http-server）

updateModels

ArFootPrcesoor 类对象函数，根据算法数据对模型进行位移、旋转和缩放操作。

语法

arFootProcessor.updateModels(options)

参数说明

属性名	类型	默认值	必填	说明
algResult	FootAlgResult（Amazing 返回的算法数据）	-	是	Amazing 算法接口返回的算法数据
models	Object : {left: THREE.Object3D right: THREE.Object3D}	-	是	双脚的模型

模型朝向请参照代码示例中的模型进行调整，bounding box 的尺寸如下（Xcode 下）：

Left Shoe

width	height	depth
7.717	17.998	8.21

Right Shoe

width	height	depth
7.729	17.85	8.173

代码示例

onAlgorithmResult(algRes) {
    arFootProcessor.updateModels({
        algResult: algRes,
        models: {
            left: leftShoeModel,
            right: rightShoeModel
        }
    })
}

ArNailProcessor

ArNailProcessor

ArNailProcessor 的构造函数，创建一个 ArNailProcessor 对象，它负责根据算法数据更新指甲模型信息。ArNailProcessor 的示例教程可以参考字节跳动小程序 codelab

语法

const arNailProcessor = new ArNailProcessor(options)

参数说明

options 为 Object 类型，属性如下：

属性名	类型	默认值	必填	说明
three	type of THREE	-	是	当前使用的 THREE 本身

代码示例

const arNailProcessor = new ArNailProcessor({ three: THREE })

updateModels

ArNailProcessor 类对象函数，根据算法数据改变指甲模型位置，使其跟随相机中的指甲位置。

语法

arNailProcessor.updateModels(options)

参数说明

属性名	类型	默认值	必填	说明
algResult	NailAlgResult（Amazing 返回的指甲算法数据）	-	是	Amazing 算法接口返回的指甲算法数据
models	THREE.Group	-	是	包含了五个指甲模型的 Group
cameraWidth	number	-	是	相机画面宽度
cameraHeight	number	-	是	相机画面高度

代码示例

function onAlgorithmResult(algorithmResult) {
  arNailProcessor.updateModels({
    algResult: algorithmResult,
    models: nailModelGroup,
    cameraWidth: canvas_width,
    cameraHeight: canvas_height,
  })
}

ArNailUtils

目前的指甲算法数据不支持 3 维模型的移动，因此目前只支持更换指甲模型的纹理，不支持更换指甲模型。ArNailUtils 提供了 getNailModelGroupByColor 和 getNailModelGroupByTexture 两种类方法来返回指甲模型。

getNailModelGroupByColor

getNailModelGroupByColor 接受一个颜色参数，可以是 string，number 或者 THREE.Color 类型，返回一个带有默认高光贴图的模型，类型为 THREE.Group，包含五个指甲的模型。

语法

let nailModelGroup = ArNailUtils.getNailModelGroupByColor(options)

参数说明

options 为 Object 类型，属性如下：

属性名	类型	默认值	必填	说明
THREE	type of THREE	-	是	当前使用的 THREE 本身
renderer	THREE.Renderer	-	是	当前渲染使用的 renderer
color	THREE.Color | string | number	-	是	当前指甲高光贴图的背景颜色

代码示例

let nailModelGroup = ArNailUtils.getNailModelGroupByColor({
  THREE,
  renderer,
  color: 0x00ff00,
})

nailModelGroup = ArNailUtils.getNailModelGroupByColor({
  THREE,
  renderer,
  color: 'green',
})

nailModelGroup = ArNailUtils.getNailModelGroupByColor({
  THREE,
  renderer,
  color: new THREE.Color('red'),
})

getNailModelGroupByTexture

getNailModelGroupByTexture 接受一个 THREE.Texture 类型的纹理对象，返回一个带有默认高光贴图的模型，类型为 THREE.Group，包含五个指甲的模型。

语法

const nailModelGroup = ArNailUtils.getNailModelGroupByTexture(options)

参数说明

options 为 Object 类型，属性如下：

属性名	类型	默认值	必填	说明
THREE	type of THREE	-	是	当前使用的 THREE 本身
texture	THREE.Texture	-	是	当前指甲的高光贴图

代码示例

const nailModelGroup = ArNailUtils.getNailModelGroupByTexture({
  THREE,
  texture: highLightTexture,
})

Tip:

关于指甲纹理，getNailModelGroupByTexture 接口在生成模型时，为算法返回的 8 个坐标点都分配了对应的纹理坐标作为锚点。 实际上，能够显示出来的纹理要比由这 8 个点构成的多边形要小，为了使指甲边缘平滑，接口实现中的做法是计算上图这 8 个点构成的多边形的形心，并且将 8 个点沿着形心到这 8 个点的方向上移动，移动距离是形心到各点距离的 0.2 倍。详细用法可见 codelab。