EmoPy

EmoPy 是一个基于 Python 的工具包，包含深度神经网络类，能够根据人脸图像预测人类的情感表达类别。该项目的目标是利用现有的公开数据集探索 面部表情识别 (FER) 领域，并构建免费、开源、易于研究且便于集成到其他项目中的神经网络模型。

源自 [@Chen2014FacialER]

系统的性能高度依赖于可用的数据，而 EmoPy 的开发者仅使用公开可用的数据集来创建和测试该系统。

为了更好地了解该项目，您可以参考以下文章：

• 使用机器学习识别人类面部表情
• EmoPy：用于情感表达的机器学习工具包

我们希望扩大开发社区，并欢迎各种建议和贡献。通常这类算法多用于商业场景，因此我们致力于将其以最佳开源形式呈现，从而提升公众在这一领域的参与度和可及性。如需讨论，请联系 EmoPy 的维护者（见下文）。

概述

EmoPy 包含多个模块，这些模块相互连接以构建经过训练的 FER 预测模型。

• fermodel.py
• neuralnets.py
• dataset.py
• data_loader.py
• csv_data_loader.py
• directory_data_loader.py
• data_generator.py

其中，fermodel.py 模块使用预先训练好的模型进行 FER 预测，使其成为快速启动并运行训练模型的最简单入口。

除 neuralnets.py 外，每个模块都包含一个类；而 neuralnets.py 则包含一个接口和五个子类。这些子类分别实现了不同的神经网络架构，基于 Keras 框架与 TensorFlow 后端，允许您进行实验并找到最适合自身需求的模型。

EmoPy 文档 提供了关于各个类及其交互的详细信息。此外，下方还列出了本项目中包含的不同神经网络概述。

运行限制

商业化的 FER 项目通常会在数百万张带标签的图像上进行训练，这些数据往往来自庞大的私有数据集。相比之下，为了保持免费和开源，EmoPy 只能使用公开数据集进行训练，这对其获得准确结果构成了重大限制。

EmoPy 最初是为满足 RIOT 项目 的需求而设计的，在该项目中，观众的面部表情是在受控光照条件下被记录的。

基于以上两点，EmoPy 在输入图像满足以下条件时效果最佳：

• 光线均匀，阴影较少；或
• 图像风格、构图和裁剪与训练数据集中的图像有一定相似性。

截至目前，我们所找到的最佳公开数据集是 Microsoft FER+，约包含 3 万张图像。使用该数据集进行训练时，若输入图像与数据集中图像的风格较为接近，则效果更佳。

如需深入了解 EmoPy 的起源与运作方式，以便评估其对您需求的适用性，请阅读我们的 EmoPy 完整介绍。

数据集选择

您可以尝试使用自己的数据集，或使用我们在 Emopy/examples/image_data 子目录中提供的小型数据集来测试系统。虽然我们提供的示例数据集由于规模较小，可能无法产生理想效果，但它们却是入门的好方法。

理想的预测效果应在多种数据集、光照条件下，以及 FER 研究中常见的 7 种情绪标签（快乐、愤怒、恐惧、惊讶、厌恶、悲伤、平静/ neutral）的子集上表现良好。一些优秀的公开数据集包括 Extended Cohn-Kanade 和 Microsoft FER+。

环境设置

Python 兼容多种操作系统。如果您希望在其他操作系统上使用 EmoPy，请将以下说明调整为适合您的环境。请随时告知我们您的进展，我们将尽力为您提供支持并分享您的成果。

开始之前，如果尚未安装 Homebrew，请运行以下命令进行安装：

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

EmoPy 使用 Python 3.6 及以上版本运行，理论上可在任何兼容 Python 的操作系统上运行。我们已在 OSX 上使用 Python 3.6.6 对 EmoPy 进行了测试。

您可以通过以下两种方式安装 Python 3.6.6：

1. 直接从 Python 官网 下载，或
2. 使用 pyenv：

$ brew install pyenv
$ pyenv install 3.6.6

GraphViz 是可视化功能所必需的工具。

brew install graphviz

下一步是使用 virtualenv 设置虚拟环境。请以 sudo 权限安装 virtualenv。

sudo pip install virtualenv

创建并激活虚拟环境。运行：

python3.6 -m venv venv

或者，如果您使用 pyenv：

$ pyenv exec python3.6 -m venv venv

其中第二个 venv 是您的虚拟环境名称。要激活它，请在同一目录下运行：

source venv/bin/activate

此时，您的终端命令行前应显示 (venv) 前缀。

（要停用虚拟环境，请在命令行中输入 deactivate。当 (venv) 前缀消失时，即表示已成功停用。）

安装

从 PyPI 安装

虚拟环境激活后，您可以通过以下命令安装 EmoPy：

pip install EmoPy

从源代码安装

克隆仓库并在终端中打开。

git clone https://github.com/thoughtworksarts/EmoPy.git
cd EmoPy

使用 pip 安装剩余的依赖项。

pip install -r requirements.txt

现在您已经准备就绪！

运行测试

您可以运行以下命令来执行测试：

python EmoPy/tests/run_all.py

我们鼓励大家改进和补充这些测试！

运行示例

您可以在 examples 目录中找到当前每种神经网络类别的示例代码。您可以将示例目录下载到本地的任意位置，也可以直接使用安装包中包含的示例目录。

如果您选择使用已安装的包，可以从您创建的虚拟环境目录开始，输入以下命令来找到示例目录：

cd lib/python3.6/site-packages/EmoPy/examples

最佳的入门示例是 FERModel 示例。以下是该示例代码：

from EmoPy.src.fermodel import FERModel
from pkg_resources import resource_filename

target_emotions = ['calm', 'anger', 'happiness']
model = FERModel(target_emotions, verbose=True)

print('Predicting on happy image...')
model.predict(resource_filename('EmoPy.examples','image_data/sample_happy_image.png'))

print('Predicting on disgust image...')
model.predict(resource_filename('EmoPy.examples','image_data/sample_disgust_image.png'))

print('Predicting on anger image...')
model.predict(resource_filename('EmoPy.examples','image_data/sample_anger_image2.png'))

上述代码加载了一个预训练模型，并对一张示例图像进行情绪预测。正如您所见，这个示例只需要提供一组目标情绪和一张示例图像即可。

完成安装后，您可以在 examples 文件夹中通过运行示例脚本运行此示例：

python fermodel_example.py

示例首先加载并初始化模型。接着，它会打印出给定每张示例图像的情绪概率分布。输出应如下所示：

要训练您自己的神经网络，可以使用我们提供的 FER 神经网络类之一作为起点。例如，您可以尝试 convolutional_model.py 示例：

python convolutional_model.py

该示例首先初始化模型。随后会打印出模型架构的摘要信息，包括所有神经网络层及其输出形状的列表。我们的模型基于 Keras 框架构建，该框架提供了这一可视化功能。

在模型对每张示例图像进行训练的过程中，您会看到训练准确率和验证准确率不断更新。由于我们仅使用三张图像进行训练和验证，验证准确率会相对较低。输出应类似于以下内容：

神经网络模型比较

卷积神经网络 (ConvolutionalNN)

卷积神经网络（CNNs）目前被认为是图像分类领域的首选模型，因为它们能够捕捉图像中小区域内的模式，比如眉毛的弧度。EmoPy 中的 ConvolutionalNN 是基于静态图像进行训练的。

时延三维卷积神经网络 (TimeDelayConvNN)

时延三维卷积神经网络模型的灵感来源于伦敦布鲁内尔大学孟红英博士撰写的一篇论文[此处链接]。该模型在训练样本中引入了时间信息。与使用静态图像不同，它会利用序列中的历史图像来提供额外的上下文信息。每个训练样本将包含来自同一序列的 n 张图像，其情绪标签则取自最新的一张图像。这样做的目的是捕捉面部表情从初始状态逐渐发展至峰值情绪的过程。

Cohn-Kanade 数据库中的面部表情图像序列，来源：[@Jia2014]

卷积长短期记忆神经网络 (ConvolutionalLstmNN)

卷积长短期记忆神经网络是一种卷积神经网络与循环神经网络的混合模型。卷积神经网络通过卷积核或滤波器在图像的小区域内寻找模式；而循环神经网络（RNNs）则会考虑先前的训练样本，类似于时延神经网络，以获取上下文信息。因此，该模型既能提取图像中的局部特征，又能利用时间上下文。

时延模型与该模型在如何利用时间上下文方面有所不同。前者仅从单个面部的视频片段中获取上下文信息，如上图所示。而 ConvolutionalLstmNN 则接收彼此无关的静态图像，通过比较过去样本与当前样本之间的模式差异及其对应的情绪标签来进行学习。它不需要连续的同一面部表情序列，只需不同的人脸图像进行对比即可。

来源：[@vanGent2016]

迁移学习神经网络 (TransferLearningNN)

该模型采用一种称为迁移学习的技术[此处链接]，即以预训练的深度神经网络模型作为起点。这些预训练模型原本是用于对物体进行分类的。随后，该模型会使用带有情绪标签的面部表情图像重新训练这些预训练模型，而不是继续进行物体分类。为了匹配我们要分类的目标情绪数量，它会在原始模型的基础上添加几层顶层，并使用一组面部表情图像再次运行训练算法。该模型仅使用静态图像，不涉及时间上下文。

卷积神经网络 Dropout 版本 (ConvolutionalNNDropout)

该模型是 EmoPy 中最新的成员。它是一种二维卷积神经网络，实现了 dropout、批量归一化和 L2 正则化技术。目前，在对 7 种情绪进行分类时，其训练准确率为 0.7045，验证准确率为 0.6536。后续还将进一步训练，以评估其在更小的情绪子集上的表现。

性能

在实现 ConvolutionalNNDropout 模型之前，ConvolutionalLstmNN 模型在对7种情绪进行分类时表现最佳，验证集准确率为47.5%。下表展示了该模型和 TransferLearningNN 模型分别在所有七种标准情绪以及三种情绪子集（恐惧、快乐、中性）上训练时的准确率。这两个模型均基于 [FER+]（https://github.com/Microsoft/FERPlus）数据集中的5,000张图像进行训练。

神经网络模型	7种情绪		3种情绪
	训练集准确率	验证集准确率	训练集准确率	验证集准确率
ConvolutionalLstmNN	0.6187	0.4751	0.9148	0.6267
TransferLearningNN	0.5358	0.2933	0.7393	0.4840

两种模型都存在过拟合现象，即训练集准确率远高于验证集准确率。这表明模型在识别和分类训练图像中的模式方面表现优异，但在泛化能力上有所不足，导致对新图像的情绪预测准确性较低。

如果您希望使用我们的神经网络类尝试不同的参数设置，我们推荐您使用 [FloydHub]（https://www.floydhub.com/about），这是一个用于在云端训练和部署深度学习模型的平台。请随时告诉我们您的模型表现如何！我们的目标是优化所有 FERPython 模型的性能和泛化能力。

指导原则

以下是我们指导项目开发及贡献所遵循的原则：

• FER向善。FER应用有可能被用于恶意目的。我们希望建立一个倡导诚信、透明与意识的社区来共同开发 EmoPy，并在开发过程中始终秉持这些价值观，同时提供一个易于使用且高质量的工具包。

• 用户友好性。EmoPy 将用户体验放在首位，旨在通过尽量减少基本用例所需的用户操作步骤，使用户能够轻松地搭建并运行 FER 预测模型。

• 以实验提升性能。实现 FER 预测的最佳性能是我们的首要目标。深度神经网络类的设计允许用户便捷地调整训练参数、图像预处理选项以及特征提取方法，期望通过开源社区的广泛实验，推动 FER 预测性能的不断提升。

• 模块化。EmoPy 包含四个基础模块（fermodel、neuralnets、imageprocessor 和 featureextractor），这些模块可以灵活组合使用，且限制较少。

贡献方式

1. 克隆仓库！
2. 创建你的功能分支：git checkout -b my-new-feature
3. 提交更改：git commit -am '添加新功能'
4. 推送到分支：git push origin my-new-feature
5. 发起拉取请求 :D

这是一个尚处于起步阶段的新库，未来还有很大的发展空间。请查看我们列出的待解决事项，欢迎大家一起参与贡献！

[@Chen2014FacialER]: https://www.semanticscholar.org/paper/Facial-Expression-Recognition-Based-on-Facial-Comp-Chen-Chen/677ebde61ba3936b805357e27fce06c44513a455 “基于面部组件检测与 HOG 特征的人脸表情识别”

[@Jia2014]: https://www.researchgate.net/figure/Fig-2-Facial-expression-image-sequence-in-Cohn-Kanade-database_257627744_fig1 “利用 PAD 模型为富有表现力的虚拟人物合成头部及面部动作”

[@vanGent2016]: http://www.paulvangent.com/2016/04/01/emotion-recognition-with-python-opencv-and-a-face-dataset/ “使用 Python、OpenCV 和人脸数据集进行情绪识别。一篇关于 Python 与嵌入式电子技术的趣味技术博客。”

贡献者

感谢以下各位优秀的朋友（表情键）：

angelicaperez37 💻 📝 📖	sbriley 💻	Sofia Tania 💻	Andrew McWilliams 📖 🤔	Webs 💻	Sara GW 💻	Megan Sullivan 📖
sadnantw 💻 ⚠️	Julien Deswaef 💻 📖	Tanushri Chakravorty 💻 💡	Linas Vepštas 🔌	Emily Sachs 💻	Diana Gamez 💻	dtoakley 📖 💻
Anju 🚧	Satish Dash 🚧

本项目遵循 all-contributors 规范。欢迎任何形式的贡献！

基于 EmoPy 构建的项目

• RIOT AI
• EmoPy 的 ROS 封装

希望在此列出您的项目吗？请提交一个 issue（或 pull request），并告诉我们 EmoPy 是如何帮助您的。

EmoPy 快速上手指南

EmoPy 是一个基于 Python 和深度神经网络的面部表情识别（FER）工具包。它利用公开数据集训练模型，能够根据人脸图像预测人类的情绪表达（如快乐、愤怒、悲伤等）。本项目旨在提供免费、开源且易于集成的神经网络模型。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：支持 macOS、Linux 或 Windows（本文档以 macOS/Linux 为例，Windows 用户请相应调整命令）。
• Python 版本：Python 3.6 或更高版本（推荐 3.6.6+）。
• 前置依赖：
  • GraphViz：用于模型可视化功能。
  • virtualenv：用于创建独立的 Python 虚拟环境。

安装系统依赖 (macOS 示例)

如果您使用 macOS 且未安装 Homebrew，请先安装：

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

安装 Python 管理工具 pyenv（可选，推荐）和 GraphViz：

brew install pyenv
brew install graphviz

安装 virtualenv：

sudo pip install virtualenv

设置虚拟环境

建议创建一个虚拟环境以避免依赖冲突：

# 创建虚拟环境 (名为 venv)
python3.6 -m venv venv
# 如果使用 pyenv
# pyenv exec python3.6 -m venv venv

# 激活虚拟环境
source venv/bin/activate

激活成功后，终端命令行前缀应显示 (venv)。

国内开发者提示：在安装 Python 包时，建议使用国内镜像源（如清华源或阿里源）以加速下载。例如：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <包名>。

安装步骤

您可以通过 PyPI 直接安装，也可以从源码安装。

方式一：通过 PyPI 安装（推荐）

在激活的虚拟环境中运行：

pip install EmoPy

(国内加速版)

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple EmoPy

方式二：从源码安装

git clone https://github.com/thoughtworksarts/EmoPy.git
cd EmoPy
pip install -r requirements.txt

(国内加速版)

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

基本使用

EmoPy 提供了预训练的模型，最简单的入口是使用 FERModel 类。以下示例展示了如何加载预训练模型并对样本图片进行情绪预测。

代码示例

创建一个名为 quick_start.py 的文件，写入以下代码：

from EmoPy.src.fermodel import FERModel
from pkg_resources import resource_filename

# 定义需要预测的目标情绪类别
# 支持的类别包括：'happiness', 'anger', 'fear', 'surprise', 'disgust', 'sadness', 'calm'
target_emotions = ['calm', 'anger', 'happiness']

# 初始化模型，verbose=True 会输出详细日志
model = FERModel(target_emotions, verbose=True)

print('Predicting on happy image...')
# 预测示例图片（此处使用包内自带的示例图片路径）
model.predict(resource_filename('EmoPy.examples','image_data/sample_happy_image.png'))

print('Predicting on disgust image...')
model.predict(resource_filename('EmoPy.examples','image_data/sample_disgust_image.png'))

print('Predicting on anger image...')
model.predict(resource_filename('EmoPy.examples','image_data/sample_anger_image2.png'))

运行结果

在终端运行脚本：

python quick_start.py

程序将加载预训练模型，并输出每张输入图片对应各情绪类别的概率分布。

注意：EmoPy 主要基于公开数据集（如 Microsoft FER+）训练，因此在光线均匀、阴影较少且人脸构图与训练集相似的图片上表现最佳。对于复杂光照或非标准角度的人脸，识别准确率可能会受到影响。