通知：苹果公司^©的律师于2019年8月21日威胁我们，称我们将因侵犯其知识产权而遭到投诉。因此，我们已将3D动画狐狸替换为浣熊。

确实，苹果公司^©拥有3D动画狐狸的知识产权（但目前尚未涉及浣熊）。感谢您的理解。

用于检测和重现面部表情的 JavaScript/WebGL 库

借助此库，您可以在自己的 Web 应用程序中构建并嵌入个性化的动画表情符号。整个视频处理过程完全在客户端进行。

您的 GPU 计算能力至关重要。如果您的 GPU 性能较强，每秒可以处理大量检测任务，从而确保结果流畅且准确。

即使光线条件不佳，面部检测功能也应能正常工作。不过，输入图像的质量越高，面部表情检测的效果就越好。以下是一些提升体验的建议：

• 面部应充分受光：鼻子和眼睛应清晰可辨；
• 避免逆光拍摄：背景应为墙面，而非窗户；
• 面部与摄像头的距离不宜过远或过近：理想情况下，面部应占据摄像头画面高度的约三分之一，并且需完全可见；
• 摄像头应正对用户放置，不建议采用侧拍角度；
• 胡须和络腮胡可能会使嘴部动作的检测更加困难，而眼镜则可能干扰眼部的检测。

目录

• 功能
• 架构
• 演示
  • 本地运行
  • 使用模块
• 集成
  • 使用打包工具
  • 使用 JavaScript 前端框架
  • 原生方式
• 托管
• 技术简介
  • 底层原理
  • 兼容性
• 文档
• 许可证
• 参考文献

功能

• 面部检测与跟踪，
• 可检测 11 种面部表情，
• 支持面部在三个轴上的旋转，
• 对光照条件具有较强的鲁棒性，
• 适合移动设备使用，
• 提供基于 SVG 和 THREE.js 的示例。

架构

• /assets/：包含 3D 和 2D 演示所需的资源文件（3D 网格、图片等）；
• /demos/：最精彩的部分——演示代码！
• /dist/：库的核心目录：
  • jeelizFaceExpressions.js：主压缩脚本，负责获取摄像头视频流，利用神经网络检测面部及表情，并对结果进行平滑处理；
  • jeelizFaceExpressionsNNC.json：由主脚本加载的神经网络模型；
• /doc/：附加文档；
• /helpers/：主脚本输出的数据较为原始，使用这些辅助工具可以更方便地通过 THREE.js 动画化 3D 模型，或借助 SVG 辅助工具操作 SVG 文件。所有演示均使用这些辅助工具；
• /libs/：一些 JavaScript 库；
• /meshConverter/：仅适用于 THREE.js 使用，用于从独立的 .OBJ 文件中提取数据并生成包含变形目标的 3D 模型文件。

演示

以下所有演示都包含在本仓库的 /demos 目录中。你可以尝试它们：

• 基于 THREE.js 的演示：

  • 可爱浣熊：源代码，在线演示
  • 来自 MP4 视频的可爱浣熊：源代码，在线演示
  • Ready Player Me！源代码，在线演示

• 基于 SVG 的演示：

  • 酷炫卡特曼：源代码，在线演示

• 原生演示：

  • 可爱浣熊：源代码及构建和运行说明 这个演示使用 Apache Cordova 作为原生应用运行。已在 iOS 上成功测试。其基础代码与 THREE.js 浣熊演示相同。

• 在 /demos/mediaStream 中，你可以运行一个基于现代 JavaScript 环境（React、Webpack、NPM）构建的演示，在其中多个动画化的 3D 浣熊可以相互交流。

• 第三方演示：

  • 钢琴精灵：用你的面部表情弹钢琴！这非常让人上瘾；）。在线演示 - ace-piano-genie.glitch.me，代码及更多详情

  • 无手浏览，由 Oz Ramos 开发：该演示提升了残疾人士的网页可访问性。你可以用头部控制鼠标光标（转动头部移动光标，微笑点击）。在线演示 - browsehandsfree.com - 点击相机图标开始，更多详情。代码可在 GitHub 上找到：handsfreejs/handsfree。

  • Vauta，由 Nono 开发：你可以在浏览器中为 .VRM 3D 角色头像赋予动画效果。这个 Web 应用仅提供日语版本。在线演示 - vauta.netlify.com，推文及视频

  • Laer，由 Yakumo 开发。一位漫画风格的角色会模仿你的面部表情。画风非常出色！该 Web 应用仅提供日语版本，但界面非常直观（选择头像，点击大红色按钮并同意摄像头访问请求）。GitHub 仓库 在线演示 Twitter 帖子

  • 困倦检测，由 Abhilash26 又名 Dinodroid 开发：有了这个 Web 应用，开车时再也不用担心打瞌睡了！你可以在这里试用：dont-drive-drowsy.glitch.me，查看源代码 或观看 演示视频

  • 表情读取器，由 Abhilash26 又名 Dinodroid 开发：它能根据本库提供的形变系数检测 5 种高级别表情（快乐、恐惧、愤怒、惊讶、悲伤），并以表情符号的形式显示出来。你可以在这里试用：emotion-reader.glitch.me 或 浏览源代码

如果你使用本库开发了应用程序或有趣的演示，我们非常乐意查看并在此处添加链接！请通过 Twitter @Jeeliz_AR 或 LinkedIn 联系我们。

本地运行

你只需使用 HTTPS 服务器来服务此目录的内容即可。如果应用托管在非安全的 HTTP 服务器上，浏览器可能不会授权访问摄像头。例如，你可以使用 Docker 来运行 HTTPS 服务器：

1. 运行 docker-compose

docker-compose up

2. 打开浏览器并访问 localhost:8888

如果你还没有购买摄像头，这里提供卡特曼演示的截图视频：

使用模块

/dist/jeelizFaceExpressions.module.js 与 /dist/jeelizFaceExpressions.js 完全相同，只是它可以作为 JavaScript 模块使用，因此你可以直接通过以下方式导入：

import 'dist/jeelizFaceExpressions.module.js'

或者使用 require：

const faceExpressions = require('./lib/jeelizFaceExpressions.module.js')
//...

目前尚无使用模块版本的演示。

集成

使用打包工具

如果你使用打包工具（通常是 Webpack 或 Parcel）来集成本库，首先应使用 模块版本。

然后，对于标准库而言，我们会根据初始化参数 NNCPath 指定的路径，通过 AJAX 加载神经网络模型，原因如下：

• 如果用户拒绝共享摄像头，或者 WebGL 未启用，则无需加载神经网络模型；
• 我们假设库是部署在静态 HTTPS 服务器上的。

但在使用打包工具时，情况会稍微复杂一些。更简单的方法是使用传统的 import 或 require 语句加载神经网络模型，并将其作为 NNC 初始化参数传递：

const faceExpressions = require('./lib/jeelizFaceExpressions.module.js')
const neuralNetworkModel = require('./dist/jeelizFaceExpressionsNNC.json')

faceExpressions.init({
  NNC: neuralNetworkModel, // 替代 NNCPath
  //... 其他初始化参数
});

与 JavaScript 前端框架

我们在此不讨论与主流 JavaScript 前端框架（React、Vue、Angular）的集成。如果您提交包含样板代码或特定框架集成示例的 Pull Request，我们将非常欢迎并予以接受。当然，我们也可以将此类集成作为一项专门的开发服务提供给您（请通过这里与我们联系）。不过，您自己动手实现也并不困难。以下是一些关于 React 集成的已提交问题：其中大多数是针对 Jeeliz FaceFilter 的，但问题本质上是相似的：

• Angular 集成：Jeff Winder 已将该库与 Angular / Electron 集成。他的精彩工作已发布在 GitHub 上：JeffWinder/jeelizWeboji-angular-electron-example。
• React 集成：#74 和 #122。
• 是否可以在 React Native 项目中使用此库。
• 在 ReactApp 中使用 JeelizThreeHelper 遇到困难。

您也可以查看以下 GitHub 代码仓库：

• ikebastuz/jeelizTest：基于 CSS3D 的 FaceFilter React 示例。它基于 Create React App。
• CloffWrangler/facevoice：另一个基于 [Create React App] 的示例。
• nickydev100/FFMpeg-Angular-Face-Filter：Angular 样板工程。

原生应用

可以通过原生应用中的 Webview 来运行使用该库的 JavaScript 应用程序，从而实现原生集成。然而，在 iOS < 14.3 的版本中，Webview 内部会禁用摄像头访问权限。如果您希望您的应用程序能够在低于 iOS 14.3 的设备上运行，则需要通过 WebSocket 将摄像头视频流注入到 WKWebview 中，这是一种变通方案。

该变通方案已在以下仓库中实现：

• Apache Cordova iOS 演示（也适用于 Android）。
• 演示的 YouTube 视频。
• GitHub 上的相关问题。
• LinkedIn 上详细说明优缺点的帖子。

不过，这仍然是一种不太优雅的 hack，会引入性能瓶颈。尽管在高端设备上（如 iPhone XR）表现尚可，但最好还是直接在完整的 Web 环境中运行。

托管

该库需要通过 MediaStream API 获取用户的摄像头流。因此，您的应用程序必须部署在 HTTPS 服务器上（证书可以是自签名的）。即使在本地，某些浏览器也无法在非安全的 HTTP 协议下正常工作。

请注意为 JSON 和 JS 文件启用 gzip HTTP/HTTPS 压缩。实际上，位于 /dist/ 目录下的神经网络 JSON 文件体积较大，但经过 GZIP 压缩后效果非常好。您可以使用 checkgzipcompression.com 来检查服务器的 gzip 压缩情况。

神经网络 JSON 文件会在用户同意共享摄像头后，通过 AJAX 的 XMLHttpRequest 加载。我们采用这种方式是为了避免在用户拒绝共享摄像头或设备没有摄像头时加载这个较大的文件。如果您能在 HTML 页面加载完成后立即使用 Service Worker 或简单的原始 XMLHttpRequest 预加载该 JSON 文件，那么后续请求将会更快，因为文件已经缓存在浏览器中。

技术细节

内部原理

该库的核心是 JEELIZFACEEXPRESSIONS，由 /dist/jeelizFaceExpressions.js 脚本实现。它依赖于 Jeeliz 的 WebGL 深度学习技术，利用深度学习网络检测和跟踪用户面部，并同时评估表情因子。精度会根据硬件性能动态调整：硬件越强大，每秒处理的检测数量就越多。整个过程完全在客户端完成。

JEELIZFACEEXPRESSIONS 的文档以 PDF 文件的形式包含在本仓库中，路径为 /doc/jeelizFaceExpressions.pdf。在演示的主要脚本中，我们从不直接调用这些方法，而是始终通过辅助函数来操作。以下是该库返回的表情形态索引：

• 0：smileRight → 合嘴微笑（右侧）
• 1：smileLeft → 合嘴微笑（左侧）
• 2：eyeBrowLeftDown → 左眉下压
• 3：eyeBrowRightDown → 右眉下压
• 4：eyeBrowLeftUp → 左眉上扬（惊讶）
• 5：eyeBrowRightUp → 右眉上扬（惊讶）
• 6：mouthOpen → 张嘴
• 7：mouthRound → 圆形嘴
• 8：eyeRightClose → 闭合右眼
• 9：eyeLeftClose → 闭合左眼
• 10：mouthNasty → 露齿咧嘴（恶心）

兼容性

• 如果支持 WebGL2，则使用 WebGL2，无需任何额外扩展；
• 如果不支持 WebGL2 但支持 WebGL1，则需要 OES_TEXTURE_FLOAT 或 OES_TEXTURE_HALF_FLOAT 扩展；
• 如果既不支持 WebGL2，也不支持 WebGL1，且未实现 OES_TEXTURE_FLOAT 或 OES_TEXTURE_HALF_FLOAT，则该设备不兼容。

无论哪种情况，您的浏览器都必须支持 WebRTC，否则该库将无法获取摄像头视频流。兼容性表格可在 caniuse.com 上找到：WebGL1，WebGL2，WebRTC。

如果出现兼容性错误，请在本仓库中提交问题。如果是摄像头访问权限相关的错误，请先关闭所有可能占用您设备的应用程序（如 Skype、Messenger、其他浏览器标签页和窗口等），然后再重试。请附上：

• webglreport.com - WebGL1 的截图（关于您的 WebGL1 实现）；
• webglreport.com - WebGL2 的截图（关于您的 WebGL2 实现）；
• 浏览器控制台的日志；
• 复现问题的步骤及截图。

该库几乎可以在任何地方运行，并且在像 iPhone X 这样的高端设备上表现尤为出色。但如果您的设备过于廉价或老旧，每秒能处理的检测次数就会减少，导致应用运行缓慢。

文档

• JEELIZFACEEXPRESSIONS: 所有辅助工具都依赖这个库来获取面部变形系数。通过这份文档，您可以将该库与您自己的 3D 或 2D 引擎进行集成。点击此处阅读规格 PDF，
• 关于使用 meshConverter 的 README.md: 用于 THREE.JS 负鼠演示中

许可证

Apache 2.0。本应用可用于商业和非商业用途，且完全免费。

参考资料

• Jeeliz 官方网站
• Three.JS 官方网站，提供文档、演示、示例等
• Webgl Academy：关于 WebGL 和 THREE.JS 的教程

jeelizWeboji 快速上手指南

jeelizWeboji 是一个基于 JavaScript/WebGL 的库，用于在客户端检测并复现面部表情。它利用 GPU 算力实时处理摄像头视频流，可轻松为 Web 应用添加动画表情符号（如 3D 浣熊或 SVG 卡通形象）。

环境准备

• 操作系统：支持 Windows、macOS、Linux 及移动端（iOS/Android）。
• 浏览器：支持现代浏览器（Chrome, Firefox, Safari, Edge），必须支持 WebGL 和 MediaStream API。
• 服务器要求：
  • 必须使用 HTTPS 协议托管应用（本地开发可使用自签名证书），否则浏览器将禁止访问摄像头。
  • 建议开启 Gzip 压缩以提升 JSON 模型加载速度。
• 硬件建议：
  • 需要性能较好的 GPU 以获得流畅的检测帧率。
  • 摄像头应正对用户，光线充足，避免逆光。面部最好占据摄像头画面的 1/3。
  • 注意：浓密胡须可能影响嘴部检测，眼镜可能干扰眼部检测。

安装步骤

你可以通过下载源码或使用模块包的方式集成。

方式一：克隆仓库运行演示（推荐新手）

如果你希望直接运行官方提供的演示项目（如 3D 浣熊）：

1. 克隆仓库：

   git clone https://github.com/jeeliz/jeelizWeboji.git
   cd jeelizWeboji
   

2. 启动本地 HTTPS 服务器（使用 Docker）：

   docker-compose up
   

3. 在浏览器中访问：

   http://localhost:8888
   

   注：若不使用 Docker，需自行配置任意支持 HTTPS 的静态文件服务器。

方式二：通过 NPM 安装（用于项目开发）

虽然官方主要提供直接引用的脚本，但你也可以将文件放入项目中。若使用打包工具（如 Webpack/Vite）：

1. 下载核心文件到项目目录（例如 lib/）：

   • jeelizFaceExpressions.module.js
   • jeelizFaceExpressionsNNC.json (神经网络模型)

2. 或者直接使用 CDN 链接（需确保你的构建工具能处理非 npm 资源）。

基本使用

以下示例展示如何在原生 JavaScript 环境中初始化库并获取面部数据。

1. HTML 结构

创建一个用于显示视频预览和结果的容器：

<canvas id="canvas"></canvas>
<!-- 可选：用于显示 3D 模型或 SVG 的容器 -->
<div id="output-container"></div>

2. JavaScript 初始化

引入库文件并调用初始化函数。

注意：如果使用打包工具（Webpack 等），请直接 import 或 require 模型文件；如果是传统脚本标签引入，则使用 NNCPath 指定模型 URL。

场景 A：使用打包工具 (Webpack/Vite/Rollup)

import faceExpressions from './lib/jeelizFaceExpressions.module.js';
import neuralNetworkModel from './lib/jeelizFaceExpressionsNNC.json';

faceExpressions.init({
  canvasId: 'canvas',
  NNC: neuralNetworkModel, // 直接传入导入的 JSON 对象
  callbackReady: function(errCode, spec) {
    if (errCode) {
      console.log('AN ERROR HAPPENS. ERROR CODE =', errCode);
      return;
    }
    console.log('INFO: JEELIZFACEEXPRESSIONS IS READY');
    
    // 开始检测循环
    function detect() {
      const detections = faceExpressions.detect();
      
      if (detections.length > 0) {
        const det = detections[0];
        // det.expressions 包含 11 种表情系数 (0.0 - 1.0)
        // det.rotation 包含 3 轴旋转数据
        console.log('表情数据:', det.expressions);
        
        // 在此处更新你的 3D 模型 (Three.js) 或 SVG 属性
        // updateMyAvatar(det); 
      }
      
      requestAnimationFrame(detect);
    }
    
    detect();
  },
  callbackTrack: function(detects) {
    // 每一帧的追踪回调
  }
});

场景 B：传统 script 标签引入

<script src="dist/jeelizFaceExpressions.js"></script>
<script>
  JeelizFaceExpressions.init({
    canvasId: 'canvas',
    NNCPath: 'dist/jeelizFaceExpressionsNNC.json', // 指向模型文件的路径
    callbackReady: function(errCode, spec) {
      if (errCode) {
        console.log('初始化失败，错误代码:', errCode);
        return;
      }
      
      function loop() {
        const detects = JeelizFaceExpressions.detect();
        if (detects.length > 0) {
          // 获取第一个检测到的人脸数据
          const face = detects[0];
          // face.expressions: [眉毛, 眼睛, 嘴巴等 11 个数值]
          // face.rotation: [x, y, z]
          
          // 在这里驱动你的动画逻辑
          // animateCharacter(face);
        }
        requestAnimationFrame(loop);
      }
      loop();
    }
  });
</script>

3. 驱动动画

库本身只输出原始数据（表情系数和旋转角度）。要看到效果，你需要结合 Three.js（用于 3D 模型）或 SVG 操作来映射这些数据。官方在 /helpers/ 目录下提供了 JeelizThreeHelper 和 JeelizSVGHelper 辅助工具，可简化将检测数据绑定到模型形态键（Morph Targets）的过程。