Beauty SDK

概述

OrangeCloud Beauty SDK 是一套自研的商业级实时美颜开发工具包，提供高精度人脸关键点检测、实时美颜滤镜、瘦脸/大眼变形算法和AR贴纸引擎。支持 Flutter、iOS（Metal）、Android（OpenGL ES）三端统一接口。

核心能力

• AI98点人脸关键点实时检测（基于轻量级CNN模型）
• GPU商业级磨皮/美白滤镜（Metal / OpenGL ES Shader）
• GPUMLS移动最小二乘法瘦脸/大眼变形
• 实时AR贴纸引擎（2D/3D贴纸跟踪渲染）
• 实时30fps+ 全链路实时处理

架构总览

┌─────────────────────────────────────────────────────┐
│                   Flutter Dart API                    │
│         (BeautySDK unified interface)                │
├─────────────────────────────────────────────────────┤
│              Platform Channel Bridge                  │
├──────────────────────┬──────────────────────────────┤
│   iOS (Metal)        │   Android (OpenGL ES)         │
├──────────────────────┼──────────────────────────────┤
│  ┌────────────────┐  │  ┌────────────────┐          │
│  │ Face Detector   │  │  │ Face Detector   │          │
│  │ (CNN Model)     │  │  │ (CNN Model)     │          │
│  ├────────────────┤  │  ├────────────────┤          │
│  │ Beauty Filter   │  │  │ Beauty Filter   │          │
│  │ (Metal Shader)  │  │  │ (GLES Shader)   │          │
│  ├────────────────┤  │  ├────────────────┤          │
│  │ Face Deformer   │  │  │ Face Deformer   │          │
│  │ (MLS Mesh)      │  │  │ (MLS Mesh)      │          │
│  ├────────────────┤  │  ├────────────────┤          │
│  │ AR Sticker      │  │  │ AR Sticker      │          │
│  │ Engine          │  │  │ Engine          │          │
│  └────────────────┘  │  └────────────────┘          │
├──────────────────────┴──────────────────────────────┤
│              Camera Frame Input                       │
└─────────────────────────────────────────────────────┘

平台支持

快速集成（3步）

1. 添加 SDK 依赖到项目
2. 初始化 SDK 并配置美颜参数
3. 将相机帧接入 SDK 渲染管线

Flutter SDK

安装

在 pubspec.yaml 中添加依赖：

dependencies:
  orange_beauty_sdk:
    path: ./packages/orange_beauty_sdk

然后执行：

flutter pub get

初始化

import 'package:orange_beauty_sdk/orange_beauty_sdk.dart';

// 初始化 SDK
final beautySDK = OrangeBeautySDK();
await beautySDK.init(BeautyConfig(
  locale: 'zh_CN',           // 语言设置
  enableFaceDetect: true,    // 启用人脸检测
  enableBeautyFilter: true,  // 启用美颜滤镜
  enableDeformer: true,      // 启用变形
  enableSticker: true,       // 启用AR贴纸
  maxFaces: 5,               // 最大检测人脸数
));

相机接入

// 使用 BeautyTextureView 替代普通相机预览
BeautyTextureView(
  sdk: beautySDK,
  cameraFacing: CameraFacing.front,
  onFrameProcessed: (ProcessedFrame frame) {
    // 每帧处理完成回调
    print('FPS: ${frame.fps}, Faces: ${frame.faceCount}');
  },
)

美颜参数

// 设置美颜参数（所有参数范围 0.0 ~ 1.0）
await beautySDK.setBeautyParams(BeautyParams(
  smoothing: 0.7,    // 磨皮强度
  whitening: 0.5,    // 美白强度
  slimFace: 0.4,     // 瘦脸强度
  enlargeEye: 0.3,   // 大眼强度
));

// 单独调整某个参数
await beautySDK.setSmoothing(0.8);
await beautySDK.setWhitening(0.6);
await beautySDK.setSlimFace(0.5);
await beautySDK.setEnlargeEye(0.4);

AR贴纸

// 加载贴纸资源包
await beautySDK.loadSticker('assets/stickers/cat_ears.json');

// 移除当前贴纸
await beautySDK.removeSticker();

// 获取可用贴纸列表
final stickers = await beautySDK.getAvailableStickers();

完整示例

import 'package:flutter/material.dart';
import 'package:orange_beauty_sdk/orange_beauty_sdk.dart';

class LiveBeautyPage extends StatefulWidget {
  @override
  State<LiveBeautyPage> createState() => _LiveBeautyPageState();
}

class _LiveBeautyPageState extends State<LiveBeautyPage> {
  late OrangeBeautySDK _sdk;
  double _smoothing = 0.7;
  double _whitening = 0.5;

  @override
  void initState() {
    super.initState();
    _initSDK();
  }

  Future<void> _initSDK() async {
    _sdk = OrangeBeautySDK();
    await _sdk.init(BeautyConfig(locale: 'zh_CN'));
    await _sdk.setBeautyParams(BeautyParams(
      smoothing: _smoothing,
      whitening: _whitening,
      slimFace: 0.4,
      enlargeEye: 0.3,
    ));
  }

  @override
  void dispose() {
    _sdk.release(); // 释放所有GPU资源
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
          // 美颜相机预览
          BeautyTextureView(sdk: _sdk, cameraFacing: CameraFacing.front),
          // 美颜参数调节面板
          Positioned(
            bottom: 100,
            left: 20,
            right: 20,
            child: Column(
              children: [
                _buildSlider('磨皮', _smoothing, (v) {
                  setState(() => _smoothing = v);
                  _sdk.setSmoothing(v);
                }),
                _buildSlider('美白', _whitening, (v) {
                  setState(() => _whitening = v);
                  _sdk.setWhitening(v);
                }),
              ],
            ),
          ),
        ],
      ),
    );
  }

  Widget _buildSlider(String label, double value, ValueChanged<double> onChanged) {
    return Row(
      children: [
        Text(label, style: TextStyle(color: Colors.white)),
        Expanded(child: Slider(value: value, onChanged: onChanged)),
        Text('${(value * 100).toInt()}%', style: TextStyle(color: Colors.white)),
      ],
    );
  }
}

iOS SDK (Metal)

安装

使用 Swift Package Manager，在 Package.swift 中添加：

dependencies: [
    .package(path: "./packages/OrangeBeautySDK")
]

初始化

import OrangeBeautySDK

let config = BeautyConfig(
    locale: "zh_CN",
    enableFaceDetect: true,
    enableBeautyFilter: true,
    enableDeformer: true,
    enableSticker: true,
    maxFaces: 5
)

let beautySDK = try OrangeBeautySDK(config: config)

相机接入

// 实现 BeautyFrameDelegate 协议
class LiveViewController: UIViewController, BeautyFrameDelegate {

    func setupCamera() {
        beautySDK.frameDelegate = self
        beautySDK.startCapture(position: .front)
    }

    // 处理后的帧回调
    func beautySDK(_ sdk: OrangeBeautySDK, didProcess frame: ProcessedFrame) {
        // frame.texture 为处理后的 Metal 纹理
        // frame.landmarks 为检测到的人脸关键点
        metalView.currentTexture = frame.texture
    }
}

美颜参数

// 设置美颜参数
beautySDK.setBeautyParams(BeautyParams(
    smoothing: 0.7,
    whitening: 0.5,
    slimFace: 0.4,
    enlargeEye: 0.3
))

// 单独调整
beautySDK.setSmoothing(0.8)
beautySDK.setWhitening(0.6)

AR贴纸

// 加载贴纸
try beautySDK.loadSticker(bundlePath: "stickers/cat_ears.json")

// 移除贴纸
beautySDK.removeSticker()

完整示例

import UIKit
import OrangeBeautySDK

class LiveBeautyViewController: UIViewController, BeautyFrameDelegate {
    private var beautySDK: OrangeBeautySDK!
    private var metalView: MetalPreviewView!

    override func viewDidLoad() {
        super.viewDidLoad()
        setupSDK()
        setupUI()
    }

    private func setupSDK() {
        let config = BeautyConfig(locale: "zh_CN")
        beautySDK = try! OrangeBeautySDK(config: config)
        beautySDK.frameDelegate = self
        beautySDK.setBeautyParams(BeautyParams(
            smoothing: 0.7, whitening: 0.5,
            slimFace: 0.4, enlargeEye: 0.3
        ))
        beautySDK.startCapture(position: .front)
    }

    func beautySDK(_ sdk: OrangeBeautySDK, didProcess frame: ProcessedFrame) {
        metalView.currentTexture = frame.texture
    }

    deinit {
        beautySDK.release()
    }
}

Android SDK (OpenGL ES)

安装

在模块级 build.gradle.kts 中添加依赖：

dependencies {
    implementation(project(":orange-beauty-sdk"))
}

初始化

import com.orangecloud.beauty.OrangeBeautySDK
import com.orangecloud.beauty.BeautyConfig

val config = BeautyConfig(
    locale = "zh_CN",
    enableFaceDetect = true,
    enableBeautyFilter = true,
    enableDeformer = true,
    enableSticker = true,
    maxFaces = 5
)

val beautySDK = OrangeBeautySDK(context, config)

相机接入

// 使用 BeautyGLSurfaceView
val beautyView = BeautyGLSurfaceView(context)
beautyView.setSDK(beautySDK)
beautyView.setCameraFacing(CameraFacing.FRONT)
beautyView.setFrameCallback { frame ->
    // frame.textureId 为处理后的 OpenGL 纹理ID
    // frame.landmarks 为检测到的人脸关键点
    Log.d("Beauty", "FPS: ${frame.fps}, Faces: ${frame.faceCount}")
}

美颜参数

// 设置美颜参数
beautySDK.setBeautyParams(BeautyParams(
    smoothing = 0.7f,
    whitening = 0.5f,
    slimFace = 0.4f,
    enlargeEye = 0.3f
))

// 单独调整
beautySDK.setSmoothing(0.8f)
beautySDK.setWhitening(0.6f)

AR贴纸

// 加载贴纸
beautySDK.loadSticker("stickers/cat_ears.json")

// 移除贴纸
beautySDK.removeSticker()

完整示例

import com.orangecloud.beauty.*

class LiveBeautyActivity : AppCompatActivity() {
    private lateinit var beautySDK: OrangeBeautySDK
    private lateinit var beautyView: BeautyGLSurfaceView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val config = BeautyConfig(locale = "zh_CN")
        beautySDK = OrangeBeautySDK(this, config)
        beautySDK.setBeautyParams(BeautyParams(
            smoothing = 0.7f, whitening = 0.5f,
            slimFace = 0.4f, enlargeEye = 0.3f
        ))

        beautyView = BeautyGLSurfaceView(this)
        beautyView.setSDK(beautySDK)
        beautyView.setCameraFacing(CameraFacing.FRONT)
        setContentView(beautyView)
    }

    override fun onDestroy() {
        super.onDestroy()
        beautySDK.release()
    }
}

核心模块

人脸关键点检测

基于轻量级CNN模型（MobileNet架构），支持移动端实时推理。使用 300W、WFLW 开源数据集训练，检测98个人脸关键点。

技术指标

美颜滤镜

基于GPU Shader管线实现的实时美颜效果，iOS使用Metal Shader，Android使用OpenGL ES Shader。

滤镜类型

瘦脸/大眼变形

基于MLS（Moving Least Squares）移动最小二乘法的Mesh变形算法，通过控制人脸关键点实现自然的面部变形效果。

变形类型

算法特性

• 单人脸变形计算 ≤5ms
• Mesh三角形边界无撕裂/不连续
• 帧间时间平滑，防止抖动
• 多人脸独立变形参数

AR贴纸引擎

支持2D/3D贴纸的实时渲染与人脸跟踪，贴纸跟随人脸位置、角度、缩放实时更新。

功能特性

• 2D贴纸：基于关键点锚定，支持旋转/缩放/透明度
• 3D贴纸：透视投影渲染，跟随人脸姿态
• 贴纸加载：资源包解析 ≤500ms
• 跟踪同步：30fps+ 无延迟跟踪
• 人脸进出：退出1帧移除，进入3帧内重新附着

贴纸资源包格式

贴纸资源使用JSON格式定义，包含锚点、动画序列和渲染层级信息。

资源包结构

{
  "name": "cat_ears",
  "version": "1.0.0",
  "type": "2d",
  "anchors": [
    {
      "id": "left_ear",
      "landmarkIndex": 68,
      "offset": { "x": -0.1, "y": -0.3 },
      "scale": 1.2
    },
    {
      "id": "right_ear",
      "landmarkIndex": 54,
      "offset": { "x": 0.1, "y": -0.3 },
      "scale": 1.2
    }
  ],
  "layers": [
    {
      "id": "ears_layer",
      "resource": "cat_ears.png",
      "anchor": "left_ear",
      "zIndex": 1,
      "blendMode": "normal"
    }
  ],
  "animations": [
    {
      "id": "idle",
      "frames": ["frame_01.png", "frame_02.png", "frame_03.png"],
      "fps": 12,
      "loop": true
    }
  ]
}

制作贴纸

1. 准备贴纸素材图片（PNG格式，支持透明通道）
2. 确定锚点对应的关键点索引（参考98点关键点图）
3. 编写JSON配置文件，定义锚点、层级和动画
4. 将所有资源打包到同一目录

加载与卸载

// 加载贴纸（异步，≤500ms完成）
await beautySDK.loadSticker('path/to/sticker.json');

// 切换贴纸（自动卸载旧贴纸）
await beautySDK.loadSticker('path/to/another_sticker.json');

// 移除贴纸
await beautySDK.removeSticker();

// 释放所有贴纸缓存
await beautySDK.clearStickerCache();

多语言支持

Beauty SDK 支持6种语言，与OMS平台保持一致。所有用户可见文本（错误提示、滤镜名称、参数标签等）均支持本地化。

支持的语言

配置语言

// 初始化时设置
await beautySDK.init(BeautyConfig(locale: 'zh_CN'));

// 运行时切换（无需重新初始化）
await beautySDK.setLocale('ko_KR');

// 不设置时自动匹配设备系统语言，不匹配则回退到 en_US

性能指标

基准测试（中端设备）

优化建议

• 低端设备可关闭AR贴纸模块，仅保留美颜滤镜
• 减少 maxFaces 到1可显著降低CPU开销
• 应用进入后台时SDK会自动暂停GPU操作
• 设备低电量模式下检测频率自动降至15fps

错误码

初始化错误

GPU错误

模型错误