microapp-ar-three

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

1. 根据 AI/AR 算法数据对模型进行抠除（例如试鞋场景下从鞋子模型中抠掉脚腕部分）
2. 根据 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

使用方法

1. 通过 npm 安装

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

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

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

3. @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。