Emotilyt Engine Wrapper

Emotilyt.Engine.Wrapper 是 Emotilyt 原生引擎的 .NET 封装，用于在 C# 项目中接入摄像头采集、核心算法处理、心率数据、图像回调、测量流程和摄像头控制能力。

该包面向内部业务系统和 GUI 项目使用，NuGet 包内会携带对应平台的 native 运行时文件和模型文件，应用侧通常不需要手动复制动态库。

支持平台

• .NET 10.0
• Windows x64
• Linux x64

安装

从内部 NuGet 源安装：

dotnet add package Emotilyt.Engine.Wrapper --version 1.8.4

快速开始

using Emotilyt.Engine.Wrapper;
using Emotilyt.Engine.Wrapper.Enums;
using Emotilyt.Engine.Wrapper.Models;

var config = new EngineConfig
{
    DeviceIndex = 0,
    Width = 1920,
    Height = 1080,
    InputFps = 30,
    Format = 2,
    CoreTargetFps = 8,
    TargetFaceHeight = 400,
    Orientation = VideoOrientation.NORMAL
};

config = config.Subscribe(ImageType.EM_IMG_HEATMAP, ImageType.EM_IMG_AURA_AMP);
config = config.AddInitialCameraControl(CameraControlId.Exposure, -4);

using var engine = new EmotilytEngine(config);

engine.StatusChanged += (status, message) =>
{
    Console.WriteLine($"{status}: {message}");
};

engine.MeasureStateChanged += state =>
{
    Console.WriteLine($"{state.Phase}: {state.FailureReason}, faces={state.FaceCount}, score={state.QualityScore:F1}");
};

engine.FrameReceived += (frame, typeId) =>
{
    // frame 的生命周期由 wrapper 管理，业务侧不要缓存内部指针。
};

if (!engine.Start())
{
    throw new InvalidOperationException("Failed to start Emotilyt engine.");
}

测量状态

MeasureStateChanged 用于接收测量启动和校准阶段的结构化状态。业务侧应优先使用 Phase 和 FailureReason 判断流程，不要解析 Message 文本。

engine.MeasureStateChanged += state =>
{
    if (state.FailureReason == MeasureFailureReason.MEASURE_FAILURE_NO_FACE)
    {
        Console.WriteLine("未检测到人脸，请正对摄像头。");
    }
    else if (state.FailureReason == MeasureFailureReason.MEASURE_FAILURE_MULTIPLE_FACES)
    {
        Console.WriteLine("检测到多张人脸，请保持单人入镜。");
    }
};

摄像头能力

查询设备、格式和控制能力：

EngineConfig.Format 使用 0 = MJPG、1 = YUY2、2 = NV12。建议先通过设备格式列表确认目标摄像头实际支持的格式、分辨率和帧率。

var devices = EmotilytEngine.GetDeviceDescriptors();

foreach (var device in devices)
{
    Console.WriteLine($"{device.Index}: {device.Name}");

    foreach (var format in device.Formats)
    {
        Console.WriteLine($"  {format.Width}x{format.Height} {format.PixelFormat} {format.MaxFps}fps");
    }

    foreach (var control in device.Controls)
    {
        Console.WriteLine($"  {control.Id}: {control.Min}..{control.Max}, default={control.DefaultValue}");
    }
}

初始化摄像头时预置控制参数：

config = config
    .AddInitialCameraControl(CameraControlId.Exposure, -4)
    .AddInitialCameraControl(CameraControlId.Focus, 120);

运行中调整控制参数：

if (engine.ApplyCameraControl(CameraControlSetting.Manual(CameraControlId.Zoom, 100), out var result))
{
    Console.WriteLine($"{result.Id}: {result.Status}, actual={result.ActualValue}");
}

if (engine.GetCameraControlValue(CameraControlId.Exposure, out var exposure, out var autoMode))
{
    Console.WriteLine($"Exposure={exposure}, Auto={autoMode}");
}

曝光值在所有平台保持 Windows CameraControl 语义，即以 log2(seconds) 表示。Linux 下会由 camera 模块转换为 V4L2 100us 单位，例如 -3 对应 1250。

打包

当前平台打包：

dotnet pack Emotilyt.Engine.Wrapper.csproj -c Release

在 Windows 上同时打包 Windows 和 Linux native 运行时：

dotnet pack Emotilyt.Engine.Wrapper.csproj -c Release -p:BuildAllNativeRuntimes=true

Linux 环境只能编译 Linux native 运行时；如需生成同时包含 win-x64 和 linux-x64 的 NuGet 包，请在 Windows 环境中安装 WSL 后使用 BuildAllNativeRuntimes=true。

版本记录

版本变更记录请查看 CHANGELOG.md。