microapp-ar-three
降低外部开发者在字节小程序中使用 ThreeJS 对 AI/AR 模型进行渲染的难度。目前支持两种功能：
- 根据 AI/AR 算法数据对模型进行抠除（例如试鞋场景下从鞋子模型中抠掉脚腕部分）
- 根据 AI/AR 算法数据调整模型的 position、scale 和 rotation
详细的使用方法介绍请参考字节跳动小程序开发文档 codelab 中的 microapp-ar-three 教程：https://microapp-codelabs.bytedance.com/
目录
使用方法
- 通过 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。