# 一、Queen Web SDK
Queen Web SDK是阿里云推出的一个Web端美颜特效组件，支持基础美颜、高级美颜、人脸美妆、人脸美型、头像贴纸、美体、背景抠图、滤镜、隔空写字、Animoji等美颜功能。
* SDK详细介绍：https://help.aliyun.com/document_detail/211047.html
* SDK在线演示：https://queen.aliyuncs.com
* SDK接入示范Demo：https://alivc-demo-cms.alicdn.com/versionProduct/sdk/queen_web/queen-web-samples_6.2.2.zip
* 当前Queen SDK版本：sdkVersion = 6.3.14
* 接入示例
```
import QueenEngine, {kQueenBeautyType, kQueenBeautyParams} from "aliyun-queen-engine"
//引擎初始化
queenEngine = new QueenEngine();
queenEngine.create({
SdkLicenseKey: sdkLicenseKey,
OnInit: function(result){
console.info("queen sdk initialized.", result)
},
Domain: '',//鉴权域名
OnProgress: function(progress){
console.info("queen sdk loading:", progress);
},
RenderCanvas: document.getElementById("canvas")
});
//设置美颜参数
queenEngine.setEngineParams({
basicBeauty:{
skinBuffing: 0.3,// 磨皮系数
sharpen: 0.4,// 锐化系数
whitening: 0.6,// 美白系数
},
advanceBeauty: {
pouch: 0,// 去眼袋系数
nasolabialFolds: 0.3,// 淡化法令纹系数
whiteTeeth: 0.2,// 设置白牙系数
lipstick: 0.3,// 设置口红系数
blush: 0.5,// 设置腮红系数
lipstickColorParam: 0.1,// 设置口红色相系数
lipstickGlossParam: 0.7,// 设置口红饱和度系数
lipstickBrightnessParam: 0.6,// 设置口红明度系数
brightenEye: 1,// 设置亮眼系数
skinRed: 0.3,// 设置红润系数
wrinkles: 0.2,// 设置去皱纹系数
brightenFace: 0.5 // 设置去暗沉系数
}
//.....其它参数配置
});
//基于摄像头美颜渲染
queenRender(){
queenEngine.openCameraAndRender().then((stream => {
const video = document.querySelector('video');
video.srcObject = stream;
video.play();
}))
}
```
# 二、准备工作
## 2.1、 前置条件
### 2.1.1、开发环境要求
| 浏览器 | 建议Chrome 84以上版本 |
| --- | --- |
| 开发环境 | Visual Studio Code |
| Node.js | 建议V14以上版本 |
### 2.1.2、申请试用LicenseKey
#### 获取方式：https://help.aliyun.com/document_detail/312036.htm
## 2.2、通过NPM导入使用SDK
### 2.2.1、安装Queen美颜组件
```
npm install aliyun-queen-engine
```
### 2.2.2、导入默认版本美颜
默认版本(Advance版本)支持基础美颜、高级美颜、美妆、美型、滤镜、贴纸美颜功能
> 不同的版本包大小和加载的资源文件不同，功能越全包大小越大，项目中请根据实际情况进行选择
```
import QueenEngine, {kQueenBeautyType, kQueenBeautyParams, kQueenBeautyMakeupType, kQueenBeautyFaceShapeType, kQueenBeautyBlend} from "aliyun-queen-engine"
queenEngine = new QueenEngine();
```
### 2.2.3、导入Lite版本美颜
Lite版本仅支持基础美颜功能
```
import {QueenEngineLite, kQueenBeautyType, kQueenBeautyParams} from "aliyun-queen-engine"
queenEngine = new QueenEngineLite();
```
### 2.2.4、导入Pro版本美颜
Pro版本支持基础美颜、高级美颜、美妆、美型、美体、滤镜、贴纸、隔空写字、抠图美颜功能
```
import {QueenEnginePro, kQueenBeautyType, kQueenBeautyParams, kQueenBeautyMakeupType, kQueenBeautyFaceShapeType, kQueenBeautyBodyShapeType, kQueenBeautyBlend} from "aliyun-queen-engine"
queenEngine = new QueenEnginePro();
```
### 2.2.5、导入Full版本美颜
Full版本支持基础美颜、高级美颜、美妆、美型、美体、滤镜、贴纸、隔空写字、抠图美颜、Animoji功能
```
import {QueenEngineFull, kQueenBeautyType, kQueenBeautyParams, kQueenBeautyMakeupType, kQueenBeautyFaceShapeType, kQueenBeautyBodyShapeType, kQueenBeautyBlend} from "aliyun-queen-engine"
queenEngine = new QueenEngineFull();
```
### 2.2.6、导入Worker版本美颜
Worker版本通过初始化时传入kQueenVersion指定Lite、Advance、Pro、Full版本
```
import {QueenEngineWorker, kQueenBeautyType, kQueenBeautyParams, kQueenBeautyMakeupType, kQueenBeautyFaceShapeType, kQueenBeautyBodyShapeType, kQueenBeautyBlend, kQueenVersion} from "aliyun-queen-engine"
queenEngine = new QueenEngineWorker(kQueenVersion.Pro);
```
## 2.3、HTML版本接入
```typescript
//Lite版：
//Advance版：
//Pro版：
//Full版：
//Worker版本
```
> HTML版本中SDK使用到的枚举需要增加QueenEngine前缀，如：queenEngine.setQueenBeautyParams(QueenEngine.kQueenBeautyParams.Wrinkles, 0.9);
## 2.4、微信小程序接入
* JS文件：https://g.alicdn.com/apsara-media-box/imp-web-queen-wasm/${sdkVersion}/dist/js/aliyun-queen-engine-wx.js
* WASM文件：https://g.alicdn.com/apsara-media-box/imp-web-queen-wasm/${sdkVersion}/dist/wasm/weixin/queen.wasm.bin
* 下载上述文件到微信小程序项目文件夹中，并将queen.wasm.bin改名为queen.wasm.br
* 调用方式：
```typescript
import QueenEngine, {kQueenBeautyType, kQueenBeautyMakeupType,kQueenBeautyBlend, kQueenBeautyParams} from '/assets/aliyun-queen-engine-wx'
let canvas = await new Promise((resolve) => {
wx.createSelectorQuery().select('#canvas1').fields({ node: true}).exec((res) => {
resolve(res[0].node);
})});
queenEngine = new QueenEngine();
queenEngine.setWasmUrl("/assets/")//queen.wasm.br文件目录
queenEngine.init("licenseKey", function(){
console.info("queen ready");
}, function(progress){
}, canvas);
```
> 1. canvas必须显式传入
> 2. 申请License试用时，需要提供微信appId，以进行认证授权。https://help.aliyun.com/zh/live/obtain-a-license-of-queen-sdk
> 3. 在微信小程序管理后台授权这2个域名访问：https://g.alicdn.com, https://vpp-license-proxy.aliyuncs.com
## 2.5、uni-app平台接入
```typescript
const canvasContainer = document.querySelector('.container') as HTMLElement;
const canvas = document.createElement('canvas') as HTMLCanvasElement;
canvas.setAttribute('type', 'webgl2');
canvasContainer.appendChild(canvas);
const queenEngine = new QueenEngine();
queenEngine.init(sdkLicenseKey, function(){
//初始化完成回调
}, function(progress){
//progress：加载进展条
}, canvas);
```
## 2.6、SDK Wasms本地导入(可忽略)
### 2.6.1、Wasm文件下载
* SDK核心的wasm文件存放于CDN上，一般不需要调整，即无需另外导入。如果项目原因需要将SDK文件放在项目内。你可以从下面链接进行下载，各版本对应目录为lite、advance、pro、full
* https://g.alicdn.com/apsara-media-box/imp-web-queen-wasm/${sdkVersion}/dist/wasm/advance/queen.wasm
* https://g.alicdn.com/apsara-media-box/imp-web-queen-wasm/${sdkVersion}/dist/wasm/advance/queen-simd.wasm
* https://g.alicdn.com/apsara-media-box/imp-web-queen-wasm/${sdkVersion}/dist/wasm/advance/queen.bin
### 2.6.2、本地Wasm使用
将下载的wasm文件复制项目中，然后调用setWasmUrl配置SDK目录。
```typescript
const sdkLicenseKey = ""; //queen sdk 授权licenseKey
const sdkUrl = "./" //存放queen.wasm、queen-simd.wasm、queen.bin 文件目录
let queenEngine = new QueenEngine();
queenEngine.setWasmUrl(sdkUrl);//可忽略，不设置sdkUrl时默认从CDN加载资源
queenEngine.init(sdkLicenseKey, function(){
//初始化完成回调
}, function(progress){
//progress：加载进展条
});
```
# 三、Queen Web SDK接入示例
## 3.1、初始化Queen引擎
### 3.1.1、初始化Queen引擎
```typescript
const sdkLicenseKey = ""; //queen sdk 授权licenseKey
const queenEngine = new QueenEngine();
//const queenEngine = new QueenEnginePro(); //Pro版本初始化
queenEngine.init(sdkLicenseKey, function(){
//初始化完成回调
}, function(progress){
//progress：加载进展条
});
```
> 本地调试可以不配置LicenseKey，但只能通过localhost域名进行测试
### 3.1.2、指定canvas初始化
```typescript
const canvasElement = document.getElementById("canvas");
const queenEngine = new QueenEngine();
queenEngine.init(sdkLicenseKey, function(){
//初始化完成回调
}, function(progress){
//progress：加载进展条
}, canvasElement);
```
> 需要指定的canvasElement type为webgl2类型 或 默认为空
### 3.1.3、指定推理模型初始化
```typescript
const queenEngine = new QueenEnginePro();
queenEngine.init(sdkLicenseKey, function(){
//初始化完成回调
}, function(progress){
//progress：加载进展条
}, canvasElement,{
"segment": kQueenModelShapeType.None,//初始化时不加载背景抠图模型
"pose": kQueenModelShapeType.None, //初始化时不加载美体变形模型
"backend": kBackendType.Auto //自动选择推理后端
});
```
#### 说明：
* kQueenModelShapeType.None 默认不加载背景抠图模型，使用抠图或美体时按需加载
* kQueenModelShapeType.Horizontal 引擎初始化时载入横向图模型
* kQueenModelShapeType.Vertical 引擎初始化时载入竖向图模型
* kQueenModelShapeType.Both 引擎初始化时载入时加载横向图模型和竖向图模型
* 横向图模型，即 width > height 源输入
* 竖向图模型，即 height > width 源输入
* kBackendType.Auto 自动选择推理后端
* kBackendType.WebGL 使用WebGL推理后端
* kBackendType.WebGPU 优先使用WebGPU推理后端
> 注意：模型加载会影响页面加载速度
### 3.1.4、Worker版本接入
```typescript
import {QueenEngineWorker, kQueenBeautyType, kQueenBeautyParams, kQueenBeautyMakeupType, kQueenBeautyFaceShapeType, kQueenBeautyBlend} from "aliyun-queen-engine"
const canvasElement = document.getElementById("canvas");
queenEngine = new QueenEngineWorker(kQueenVersion.Pro);
queenEngine.init(sdkLicenseKey, function(){
//初始化完成回调
}, function(progress){
//progress：加载进展条
}, canvasElement);
```
## 3.2、通过JSON配置美颜参数
```
queenEngine.setEngineParams({
basicBeauty:{
skinBuffing: 0.3,// 磨皮系数
sharpen: 0.4,// 锐化系数
whitening: 0.6,// 美白系数
},
advanceBeauty: {
pouch: 0,// 去眼袋系数
nasolabialFolds: 0.3,// 淡化法令纹系数
whiteTeeth: 0.2,// 设置白牙系数
lipstick: 0.3,// 设置口红系数
blush: 0.5,// 设置腮红系数
lipstickColorParam: 0.1,// 设置口红色相系数
lipstickGlossParam: 0.7,// 设置口红饱和度系数
lipstickBrightnessParam: 0.6,// 设置口红明度系数
brightenEye: 1,// 设置亮眼系数
skinRed: 0.3,// 设置红润系数
wrinkles: 0.2,// 设置去皱纹系数
brightenFace: 0.5 // 设置去暗沉系数
},
lutFilter:{
lutImageUrl: "https://g.alicdn.com/apsara-media-demo/amdemos-web-queen/6.2.1/queen_res/lookups/A1.png",//LUT滤镜图片地址
alpha: 0.8 //透明度
},
makeupBeauty:[
{
makeupType:3,//设置口红
alpha: 0.6,//透明度
makeupUrl:"https://g.alicdn.com/apsara-media-demo/amdemos-web-queen/6.2.1/queen_res/makeup/mouth_yaochun/chidousha.1.2.3.bin",//设置口红URL
isZip: true,//是否压缩包
zipImageName:"1.2.3.png"//压缩包中图片名称
}],
{
makeupType:6,//设置腮红
alpha:0.9,//透明度
makeupUrl:"https://g.alicdn.com/apsara-media-demo/amdemos-web-queen/6.2.1/queen_res/makeup/blush/blush_wugu.2.3.png",//图片地址
},
setSegmentBackgroundImage:{
type: 2,
backgroundImgUrl:"https://g.alicdn.com/apsara-media-demo/amdemos-web-queen/6.2.1/res/background/b1.png"//背景抠图
}
//其它美颜参数，详情查看BeautyParams类
});
```
## 3.3、通过API配置单项美颜参数
### 3.3.1、设置基础美颜
```typescript
// 开启基础美颜
queenEngine.setQueenBeautyType(kQueenBeautyType.SkinBuffing, true);
// 设置磨皮系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.SkinBuffing, 0.7);
// 设置锐化系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.Sharpen, 0.5);
// 打开美白功能开关
queenEngine.setQueenBeautyType(kQueenBeautyType.SkinWhiting, true);
// 设置美白系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.Whitening, 0.6);
// 设置红润系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.SkinRed, 0.2);
```
### 3.3.2、设置高级美颜
```typescript
//高级美颜
queenEngine.setQueenBeautyType(kQueenBeautyType.FaceBuffing, true);
// 设置去眼袋系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.Pouch, 0.9);
// 设置去法令纹系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.NasolabialFolds, 0.9);
// 设置白牙系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.WhiteTeeth, 0.9);
// 设置口红系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.Lipstick, 0.2);
// 设置腮红系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.Blush, 0.1);
// 设置口红色相系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.LipstickColorParam, 0.1);
// 设置口红饱和度系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.LipstickGlossParam, 0.1);
// 设置口红明度系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.LipstickBrightnessParam, 0.1);
// 设置亮眼系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.BrightenEye, 0.9);
// 设置红润系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.SkinRed, 0.2);
// 设置去皱纹系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.Wrinkles, 0.9);
// 设置去暗沉系数
queenEngine.setQueenBeautyParams(kQueenBeautyParams.BrightenFace, 0.3);
```
### 3.3.3、设置美型
```typescript
// 打开美型功能开关，美型参数详见kQueenBeautyFaceShapeType
queenEngine.setQueenBeautyType(kQueenBeautyType.FaceShape, true);
//颧骨，值的范围[0,1]，默认0
queenEngine.setFaceShape(kQueenBeautyFaceShapeType.CutCheek, 0.6);
// 削脸，值的范围[0,1]，默认0
queenEngine.setFaceShape(kQueenBeautyFaceShapeType.CutFace, 0.7);
//瘦脸，值的范围[0,1]，默认0
queenEngine.setFaceShape(kQueenBeautyFaceShapeType.ThinFace, 0.8);
//脸长，值的范围[0,1]，默认0
queenEngine.setFaceShape(kQueenBeautyFaceShapeType.LowerJaw, 0.8);
//下巴拉长，值的范围[-1,1]，默认0
queenEngine.setFaceShape(kQueenBeautyFaceShapeType.HigherJaw, 0.6);
```
### 3.3.4、设置美妆
#### 使用SDK 内置资源美妆
* 使用内置资源接口时，SDK会从CDN下载美颜素材
```typescript
//激活美妆
queenEngine.setQueenBeautyType(kQueenBeautyType.Makeup, true);
//设置美妆眉毛
await queenEngine.setMakeupEyeBrow(Assets.kResMakeupEyeBrow.BiaoZhunMei, 0.6);
//设置美妆睫毛
await queenEngine.setMackupEyeLash(Assets.kResMakeupEyeLash.ChenJing, 0.6);
//设置美妆眼影
await queenEngine.setMakeupEyeShadow(Assets.kResMakeupEyeShadow.DaDiSe, 0.5);
//设置美妆眼线
await queenEngine.setMakeupEyeLiner(Assets.kResMakeupEyeLiner.DaYan, 0.4);
//设置美妆美瞳
await queenEngine.setMakeupEyeBall(Assets.kResMakeupEyeBall.BiMuYu, 0.5);
//设置美妆口红
await queenEngine.setMakeupMouth(Assets.kResMakeupMouth.AnYeZi, 0.3);
//设置美妆腮红
await queenEngine.setMakeupBlush(Assets.kResMakeupBlush.BlushWuGu, 0.2);
//设置美妆高光
await queenEngine.setMakeupHighlight(Assets.kResMakeupHighLight.Highlight, 0.1);
//移除美妆效果 - 移除美妆美瞳
queenEngine.removeMakeupWithType(kQueenBeautyMakeupType.Eyeball);
//详细请参考QueenEngin.d.ts接口文件说明
```
#### 本地资源美妆
```typescript
const makeupPackage = "./mouth.zip"
const makeupName = "1.2.3.png";
const band = kQueenBeautyBlend.LabMix;
// 打开美妆功能开关，美妆参数详见kQueenBeautyMakeupType
queenEngine.setQueenBeautyType(kQueenBeautyType.Makeup, true);
// 设置美妆口红效果的透明度
queenEngine.setMakeupAlphaWithType(kQueenBeautyMakeupType.Mouth, true, 0.6);
// 设置口红效果
queenEngine.setMakeupWithPackage(kQueenBeautyMakeupType.Mouth, makeupPackage, makeupName, band).then(() => {
});
```
### 3.3.5、设置滤镜
#### 使用内置滤镜
```typescript
await queenEngine.setLutByType(Assets.kResLut.M1, 0.5);
```
#### 使用自定义滤镜
```typescript
const lutImageUrl = "./lut.png";
queenEngine.setLutImageUrl(lutImageUrl).then(function () {
queenEngine.setQueenBeautyType(kQueenBeautyType.LUT, true);
queenEngine.setQueenBeautyParams(kQueenBeautyParams.LUT, 0.5);
});
```
### 3.3.6、设置头像贴纸
#### 使用内置贴纸
```typescript
queenEngine.addMaterialWithType(Assets.kResSticker.ILoveChina);
//或
queenEngine.addMaterialWithIndex(0);
//同时设置多个
queenEngine.addMaterialWithIndexs([0,1]);
```
#### 使用自定义贴纸
```typescript
const stickerZip = "./sticker.zip";
queenEngine.addMaterialWithUrl(stickerZip).then(() => {
});
```
### 3.3.7、配置实景抠图
```typescript
const backgroundUrl = "./bg.png";
queenEngine.setSegmentBackgroundUrl(backgroundUrl).then(() => {
});
```
### 3.3.8、配置绿幕抠图
```typescript
const backgroundUrl = "./bg.png";
const isBlue = false;//是否蓝幕
queenEngine.setGreenScreenWithUrl(isBlue, backgroundUrl).then(() => {
});
```
### 3.3.9、配置背景处理
```typescript
//背景模糊
queenEngine.enableBokehBackground(true);
//背景透明
queenEngine.enableTransparentBackground(true);
```
## 3.4、美颜渲染
### 3.4.1、摄像头流渲染
```typescript
queenEngine.openCameraAndRender().then((stream=>{
const video = document.querySelector('video');
video.srcObject = stream;
video.play();
}))
```
### 3.4.2、渲染到Canvas
```typescript
const sourceVideo = document.querySelector('video');
queenEngine.renderMediaObjectToRenderCanvas(sourceVideo, sourceVideo.clientWidth, sourceVideo.clientHeight);
```
> 渲染的Canvas为初始化引擎时传入的Canvas
### 3.4.3、视频流渲染
```typescript
navigator.mediaDevices.getUserMedia(constraints)
.then(mediaStream => {
let renderMediaStream = queenEngine.renderMediaStream(mediaStream);
const video = document.querySelector('video');
video.srcObject = renderMediaStream;
video.play();
});
```
### 3.4.4、图片渲染
```typescript
fetch(图片地址)
.then(buffer => buffer.blob())
.then(createImageBitmap)
.then(img => {
queenEngine.renderWithMediaObject(img, img.width, img.height, function(imageBufferData, imageWidth, imageHeight){
const canvas = document.getElementById('playCanvas'); //canvas画布
const ctx = canvas.getContext("2d");
const imageBuffer = new Uint8ClampedArray(imageBufferData);
const imageData = new ImageData(imageBuffer, imageWidth, imageHeight);
ctx.clearRect(0, 0, imageWidth, imageHeight);
ctx.putImageData(imageData, 0, 0);
});
});
```
### 3.4.5、纹理渲染
```typescript
const canvas = document.getElementById("sourceCanvas");
let outTexture = queenEngine.renderMediaObjectToTexture(canvas, canvas.width, canvas.height);
queenEngine.drawOutTexture(outTexture);//纹理会绘制到初始化传入的canvas
```
### 3.4.6、纹理输入渲染
```typescript
let inputTexture = queenEngine.generateTextureId();
queenEngine.updateTexture(inputTexture, imageData);
let outTexture = queenEngine.renderTextureId(inputTexture, width, height);
queenEngine.drawOutTexture(outTexture)//纹理会绘制到初始化传入的canvas
```
### 3.4.7、管道流渲染
```typescript
const videoTrack = stream.getVideoTracks()[0];
const processor = new MediaStreamTrackProcessor({ track: videoTrack });
const readFrameStream = processor.readable;
const generator = new MediaStreamTrackGenerator({ kind: 'video' });
let writeFrameStream = generator.writable;
readFrameStream.pipeThrough(queenEngine.getTransformStream()).pipeTo(writeFrameStream);
```
# 四、Queen Web SDK接口说明
## 4.1、SDK初始化
```typescript
/**
* SDK初始化
* @param sdkUrl 初始化SDK
* @param sdkLicenseKey 授权licenseKey
* @param initCallback 初始后回调
* @param loaddingCallback 载入进度条
* @param renderCanvas 渲染使用的canvas 可不传，不传时自动创建
*/
init(sdkLicenseKey: string, initCallback:()=>void, loaddingCallback:(progress: number) => void, renderCanvas: HTMLCanvasElement)
```
## 4.2、美颜特效渲染
### 4.2.1、基于imageData对象渲染
```typescript
/**
* 图片美颜渲染
* 返回ImageBuffer RGBA对象
* @param imageData 图片ImageBuffer RGBA,
* 示例：const imageData = new Uint8Array(ImageData.data);
* @param imageWidth 宽
* @param imageHeight 高
* @param renderCallback 图片渲染回调
*/
render(imageData: Uint8Array, imageWidth: number, imageHeight: number, renderCallback: (outImageData:Uint8Array, imageWidth:number, imageHeight:number) => void)
```
### 4.2.2、开启摄像头并美颜
```typescript
/**
* 启用摄像头美颜
* @param constraints 摄像头参数
* @returns 美颜视频流
*/
openCameraAndRender(constraints?: MediaStreamConstraints): Promise
```
### 4.2.3、直接渲染到Canvas
```typescript
/**
* 美颜渲染媒体对象到RenderCanvas
* RenderCanvas为初始化时指定的Canvas
* @param mediaObject 媒体对象 TexImageSourceWebCodecs(ImageData | ImageBitmap | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | VideoFrame | OffscreenCanvas) | Uint8Array
*/
renderMediaObjectToRenderCanvas(mediaObject: TexImageSourceWebCodecs | Uint8Array, width?: number, height?: number): void
```
### 4.2.4、基于媒体对象渲染
```typescript
/**
* 媒体对象渲染
* 返回渲染后ImageData对象
* @param mediaElement 媒体对象 TexImageSourceWebCodecs(ImageData | ImageBitmap | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | VideoFrame | OffscreenCanvas) | Uint8Array
* @param width
* @param height
* @param renderCallback
*/
renderWithMediaObject(mediaObject: TexImageSourceWebCodecs | Uint8Array, width: number, height: number, renderCallback: (outImageData: Uint8Array, imageWidth: number, imageHeight: number) => void): void
```
### 4.2.5、基于纹理渲染
```typescript
/**
* 基于纹理ID渲染并返回纹理对象
* @param mediaElement 媒体对象 TexImageSourceWebCodecs(ImageData | ImageBitmap | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | VideoFrame | OffscreenCanvas) | Uint8Array
* @param width 对象width
* @param height 对象height
* @returns 纹理对象
*/
renderMediaObjectToTexture(mediaObject: TexImageSourceWebCodecs | Uint8Array, width?: number, height?: number): WebGLTexture | null
```
### 4.2.6、纹理渲染
```typescript
**
* 基于纹理id渲染
* 输入纹理id 返回纹理id
* @param inTextureId 输入纹理id，可以调用buildInputTexture创建纹理ID
* @param width 媒体对像宽度
* @param height 媒体对像高度
* @returns 纹理对象
*/
renderTextureId(textureId: number, imageWidth: number, imageHeight: number, useOutTextureId: number = 0) : WebGLTexture | null;
```
### 4.2.7、基于流渲染
```typescript
/**
* 视频流渲染 返回渲染视频流
* @param inputMediaStream 输入媒体流
*/
renderMediaStream(inputMediaStream: MediaStream): MediaStream
renderMediaStreamTrack(videoMediaStreamTrack: MediaStreamVideoTrack, width?: number, height?: number): MediaStreamVideoTrack
getTransformStream(): TransformStream;//返回美颜转换流处理器
```
### 4.2.8、美颜引擎注销
```typescript
**
* 美颜引擎注销
*/
engineDestory();
```
## 4.3、Animoji表情
### 4.3.1、Animoji初始化
```typescript
/**
* Animoji初始化
* @param animojiUrl animoji资源地址
* @param width 宽
* @param height 高
* @param scale 放大尺寸
* @returns
*/
animojiInitialize(animojiUrl: string, width: number, height: number, scale: number): Promise
```
### 4.3.2、图片Animoji渲染
```typescript
/**
* Animoji 图片渲染
* @param imageData 图片imageData
* @param imageWidth 宽
* @param imageHeight 高
* @param renderCallBack 渲染回调
*/
animojiRender(imageData: Uint8Array, imageWidth: number, imageHeight: number, renderCallback: (outImageData:Uint8Array, imageWidth:number, imageHeight:number) => void): void
```
### 4.3.3、媒体对象Animoji渲染
```typescript
/**
* Animoji渲染
* @param mediaSource 媒体对象 TexImageSourceWebCodecs(ImageData | ImageBitmap | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | VideoFrame | OffscreenCanvas) | Uint8Array
* @param imageWidth 宽
* @param imageHeight 高
* @param renderCallBack 渲染回调
*/
animojiRenderWithMediaObject(mediaObject: TexImageSourceWebCodecs | Uint8Array, width: number, height: number, renderCallback: (outImageData: Uint8Array, imageWidth: number, imageHeight: number) => void): void
```
### 4.3.4、媒体对象Animoji渲染纹理输出
```typescript
/**
* Animoji渲染
* @param mediaObject 媒体对象 TexImageSourceWebCodecs(ImageData | ImageBitmap | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | VideoFrame | OffscreenCanvas) | Uint8Array
* @param width 宽
* @param height 高
* @returns 渲染后纹理对象
*/
animojiRenderMediaObjectToTexture(mediaObject: TexImageSourceWebCodecs | Uint8Array, width?: number, height?: number): WebGLTexture | null
```
### 4.3.5、基于纹理IdAnimoji渲染
```typescript
/**
* Animoji渲染
* @param inTextureId 纹理ID
* @param width 宽
* @param height 高
* @returns 渲染后纹理对象
*/
animojiRenderTextureId(inTextureId: number, width: number, height: number): WebGLTexture | null
```
### 4.3.6、Animoji大小调整
```typescript
/**
* Animoji大小调整
* @param scale 推荐：0.8~1.5
*/
animojiResize(scale: number)
```
### 4.3.7、设置Animoji背景模式
```typescript
/**
* 设置Animoji背景模式
* @param mode 背景模式：0：无，1：摄像头背景 2：指定背景图片
* @param backgroundImgUrl 背景图片，如果mode=2时需要指定
*/
setAnimojiBackgroundWithMode(mode: kBackgroundProcessType, backgroundImgUrl: string)
```
### 4.3.8、Animoji引擎注销
```typescript
/**
* Animoji引擎注销
*/
animojiDestroy()
```
## 4.4、背景抠图
> 启用抠图模块需要增加以下依赖
> ```bash
> $ npm add @tensorflow/tfjs
> $ npm add @tensorflow/tfjs-backend-webgl
> $ npm add @tensorflow/tfjs-backend-webgpu
> ```
### 4.4.1、 绿幕/蓝幕抠图
```typescript
/**
* 绿幕/蓝幕抠图
* 开启此抠图功能，纯色背景抠图（setPureColorToBackground）会关闭。
* @param isBlue 绿幕:false，蓝幕:true
* @param backgroundImgUrl 背景图片
* @param threshold 幕布敏感度[1,10]，默认1
* @param autoThresholdEnabled 是否根据环境动态计算幕布敏感度，为true时调节参数threshold失效，为false时调节参数threshold生效
* @param outputGrayMask 输出灰色遮罩
* @param backgroundProcessType 背景处理方式。
*/
setGreenScreenWithUrl = function (isBlue: boolean, backgroundImgUrl: string, threshold: number, autoThreshold: boolean, outputGrayMask: boolean, backgroundProcessType:kBackgroundProcessType): Promise
```
### 4.4.2、实景抠图
```typescript
/**
* 实景AI抠图
* @param backgroundImgUrl 抠图背景图片url
* @returns
*/
setSegmentBackgroundUrl(backgroundImgUrl: string): Promise
```
### 4.4.3、纯色抠图
```typescript
/**
* 纯色背景抠图。
* 注意：开启此抠图功能，绿幕抠图（setGreenScreen）会关闭。
* @param backgroundImgPath 背景图片url
* @param threshold 幕布敏感度[1,10]，默认1
* @param colorType 需要被替换的颜色类型，0绿色(green)，1蓝色(blue)，2青色(cyan)，3紫色(purple)，4黄色(yellow)，5红色(red)，默认0。
*/
setPureColorBackgroundUrl(backgroundImgUrl: string, threshold: number, colorType: number): Promise
```
## 4.5、参数配置
### 4.5.1、配置美颜类型
```typescript
/**
* 配置美颜类型
* @param type 美颜类型kQueenBeautyType枚举
* @param enable 是否启用
*/
setQueenBeautyType(type: kQueenBeautyType, enable: boolean)
```
### 4.5.2、配置美颜参数值
```typescript
/**
* 配置美颜参数值
* @param param 美颜参数kQueenBeautyParams枚举
* @param value 参数值
*/
setQueenBeautyParams(param: kQueenBeautyParams, value: number)
```
### 4.5.3、配置LUT滤镜
```typescript
/**
* 使用内置Lut滤镜
* @param lutType Assets.kResLut枚举
* @returns
*/
setLutByType(lutType: Assets.kResLut): Promise
/**
* 设置Lut滤镜
* @param imageUrl 所要设置的滤镜图片Url
* @returns
*/
setLutImageUrl(imageUrl: string): Promise
```
### 4.5.4、设置美型类型
```typescript
/**
* 设置美型类型,设置前需要将kQueenBeautyType.FaceShape打开
* @param faceShapeType 需要设置美型的类型，kQueenBeautyFaceShapeType枚举
* @param value 需要设置的值
*/
setFaceShape(faceShapeType: kQueenBeautyFaceShapeType, value: number)
```
### 4.5.5、美妆API
#### 4.5.5.1、使用内置资源进行美妆
```typescript
/**
* 设置美妆眉毛
* @param eyeBrowType 眉毛类型,kResMakeupEyeBrow枚举
* @alpha 妆容透明度
* @param blend 混合类型,kQueenBeautyBlend枚举
* @returns
*/
setMakeupEyeBrow(eyeBrowType: Assets.kResMakeupEyeBrow, alpha: number, blend: kQueenBeautyBlend = kQueenBeautyBlend.LabMix): Promise
/**
* 设置美妆睫毛
* @param eyelashType 睫毛类型,kResMakeupEyeLash枚举
* @alpha 妆容透明度
* @param blend 混合类型,kQueenBeautyBlend枚举
* @returns
*/
setMackupEyeLash(eyelashType: Assets.kResMakeupEyeLash, alpha: number, blend: kQueenBeautyBlend = kQueenBeautyBlend.LabMix): Promise
/**
* 设置美妆眼影
* @param eyeShadowType 眼影类型,kResMakeupEyeShadow
* @alpha 妆容透明度
* @param blend 混合类型,kQueenBeautyBlend枚举
* @returns
*/
setMakeupEyeShadow(eyeShadowType: Assets.kResMakeupEyeShadow, alpha: number, blend: kQueenBeautyBlend = kQueenBeautyBlend.LabMix): Promise
/**
* 设置美妆眼线
* @param eyeLinerType 眼线类型,kResMakeupEyeLiner检举
* @alpha 妆容透明度
* @param blend 混合类型,kQueenBeautyBlend枚举
* @returns
*/
setMakeupEyeLiner(eyeLinerType: Assets.kResMakeupEyeLiner, alpha: number, blend: kQueenBeautyBlend = kQueenBeautyBlend.LabMix): Promise
/**
* 设置美妆美瞳
* @param eyeballType 美瞳类型,kResMakeupEyeBall枚举
* @alpha 妆容透明度
* @param blend 混合类型,kQueenBeautyBlend枚举
* @returns
*/
setMakeupEyeBall(eyeballType: Assets.kResMakeupEyeBall, alpha: number, blend: kQueenBeautyBlend = kQueenBeautyBlend.LabMix): Promise
/**
* 设置美妆口红
* @param mouthType 口红类型,kResMakeupMouth枚举
* @alpha 妆容透明度
* @param blend 混合类型,kQueenBeautyBlend枚举
* @returns
*/
setMakeupMouth(mouthType: Assets.kResMakeupMouth, alpha: number, blend: kQueenBeautyBlend = kQueenBeautyBlend.LabMix): Promise
/**
* 设置美妆整妆
* @param wholeType 美妆整妆类型 Assets.kResMakeupWhole枚举
* @alpha 妆容透明度
* @param blend 混合类型,kQueenBeautyBlend枚举
* @returns
*/
setMakeupWhole(wholeType: Assets.kResMakeupWhole, alpha: number, blend: kQueenBeautyBlend = kQueenBeautyBlend.LabMix): Promise
/**
* 设置美妆腮红
* @param blushType 腮红类型,kResMakeupBlush检举
* @alpha 妆容透明度
* @param blend 混合类型,kQueenBeautyBlend枚举
* @returns
*/
setMakeupBlush(blushType: Assets.kResMakeupBlush, alpha: number, blend: kQueenBeautyBlend = kQueenBeautyBlend.LabMix): Promise
/**
* 设置美妆高光
* @param highlightType 高光类型kResMakeupHighLight枚举
* @alpha 妆容透明度
* @param blend 混合类型,kQueenBeautyBlend枚举
* @returns
*/
setMakeupHighlight(highlightType: Assets.kResMakeupHighLight, alpha: number, blend: kQueenBeautyBlend = kQueenBeautyBlend.LabMix): Promise
```
#### 4.5.5.2、设置美妆类型和图片素材路径
```typescript
/**
* 设置美妆类型和图片素材路径，设置美妆需要将kQueenBeautyType.Makeup 打开
* @param makeupType 美妆类型 kQueenBeautyMakeupType枚举
* @param imageUrl 美妆素材Url地址
* @param blend 混合类型kQueenBeautyBlend枚举
*/
setMakeupWithUrl(makeupType: kQueenBeautyMakeupType, imageUrl: string, blend: kQueenBeautyBlend): Promise
```
#### 4.5.5.3、设置美妆类型和图片素材路径
```typescript
/**
* 设置美妆类型和图片素材路径，设置美妆需要将kQueenBeautyType.Makeup 打开
* @param makeupType 美妆类型
* @param packageUrl 资源压缩包url
* @param imageName 包内图片名称
* @param blend 混合类型 混合类型kQueenBeautyBlend枚举
*/
setMakeupWithPackage(makeupType: kQueenBeautyMakeupType, packageUrl: string, imageName: string, blend: kQueenBeautyBlend): Promise
```
#### 4.5.5.4、设置美妆透明度
```typescript
/**
* 设置美妆透明度，可指定性别
* @param makeupType 美妆类型
* @param isFeMale 是否是女性，女性:true，男性:false，（男性为接口预留，这里均传女性即true即可）
* @param alpha 妆容透明度
*/
setMakeupAlphaWithType = function (makeupType: kQueenBeautyMakeupType, isFeMale: boolean, alpha: number)
```
#### 4.5.5.5、设置美妆类型的混合类型
```typescript
/**
* 设置美妆透明度，可指定性别
* @param makeupType 美妆类型
* @param isFeMale 是否是女性，女性:true，男性:false，（男性为接口预留，这里均传女性即true即可）
* @param alpha 妆容透明度
*/
setMakeupAlphaWithType(makeupType: kQueenBeautyMakeupType, isFeMale: boolean, alpha: number)
```
#### 4.5.5.6、移除美妆效果
```typescript
/**
* 移除美妆效果
* @param makeupType 美妆类型
*/
removeMakeupWithType(makeupType: kQueenBeautyMakeupType): void
```
#### 4.5.5.7、清除所有美妆
```typescript
/**
* 清除所有美妆
*/
resetAllMakeupType()
```
### 4.5.6、贴纸API
#### 4.5.6.1、增加贴纸
```typescript
/**
* 设置内置资源贴纸
* @param stickerType 内置贴纸类型
* @returns
*/
addMaterialWithType(stickerType: Assets.kResSticker): Promise
/**
* 设置内置资源贴纸
* @param stickerIndex 内置贴纸索引值
* @returns
*/
addMaterialWithIndex(stickerIndex: number): Promise
/**
* 设置贴纸
* @param materialZipUrl 贴纸资源包Url
* @returns
*/
addMaterialWithUrl(materialZipUrl: string): Promise
```
#### 4.5.6.2、移除贴纸
```typescript
/**
* 删除贴纸/贴图/实景抠图需要替换的背景
* @param materialZipUrl
*/
removeMaterialWithUrl(materialZipUrl: string)
/**
* 移除贴纸
* @param stickerType 内置贴纸类型
* @returns
*/
removeMaterialWithType(stickerType: Assets.kResSticker);
/**
* 移除贴纸
* @param stickerIndex 内置贴纸索引值
* @returns
*/
removeMaterialWithIndex(stickerIndex: number)
```
### 4.5.7、功能调试
#### 4.5.7.1、展示人脸识别点位
```typescript
/**
* 展示人脸识别点位
* @param show 是否展示
*/
showFaceDetectPoint(show: boolean)
```
#### 4.5.7.2、展示人脸区域三角剖分线
```typescript
/**
* 展示人脸区域三角剖分线
* @param show 是否展示
*/
showMakeupLine(show: boolean)
```
#### 4.5.7.3、显示人体检测点
```typescript
/**
* 显示人体关键点
* @param show 是否显示
*/
showBodyDetectPoint(show: boolean)
```
### 4.5.8、美体美颜
#### 4.5.8.1、设置美体形变
```typescript
/**
* 设置美体美颜
* @param bodyShapeType 美体类型
* @param value 形变程度
*/
setBodyShape(bodyShapeType: kQueenBeautyBodyShapeType, value: number)
```
## 4.6、AR隔空写字
### 4.6.1、装载AR隔空写字模块
```typescript
/**
* 初始化AR写字模块
* @returns
*/
initArWriteResource(): Promise
```
### 4.6.2、开启Ar写字
```typescript
/**
* 开启Ar写字
* @param enable true： 开启
* @param mode 1: 写字, 2: 画画。
*/
setArWriting(enable: boolean, mode: number): void
```
### 4.6.3、清除AR写字痕迹
```typescript
/**
* 清除AR写字痕迹
*/
cleanScreenArWriting(): void
```
## 4.7、资源载入
参数配置中所有的url均需要转成path才能正常使用，需要通过下面的API将url资源文件载入到Queen引擎中生成path。
### 4.7.1、通过url载入资源
```typescript
/**
* 载入url资源到引擎
* @param url url链接
* @param needUnZip 是否需要解压
* @returns
*/
loadResourceFileWithUrl(url: string, needUnZip: boolean): Promise
/**
* 载入url资源到引擎
* @param url url链接
* @param saveFileName 保存的文件名
* @param needUnZip 是否需要解压
* @returns
*/
loadResourceFileWithUrlSaveAs(url: string, saveFileName: string, needUnZip: boolean): Promise
```
### 4.7.2、通过buffer写入
```typescript
/**
* 载入资源到引擎
* @param buffer 数据流buffer
* @param saveFileName 保存的文件名
* @param needUnZip 是否需要解压
* @returns
*/
loadResourceFileWithData(buffer: ArrayBuffer, saveFileName: string, needUnZip: boolean)
```
### 4.67.3、文件检查
```typescript
/**
* 验证资源文件是否存在
* @param fullFileName 完整的路径文件名
* @returns
*/
checkResourceFile(fullFileName: string)
```