SCRFD 人脸检测 插件用户手册

SCRFD Face Detection - User Manual

Dragonfly Prototype Apps · SCRFD Face Detection...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

SCRFD 人脸检测是一个可在 Dragonfly 内直接运行的插件面板,用于对任意已加载的二维图像执行快速人脸检测。选择一张图像、选定一个应用场景,点击 Run 即可完成:统计人脸数量并以文字叠加显示在视图上、为每张人脸绘制白色方框、添加 5 点面部关键点,或对人脸区域进行模糊/匿名化处理。

底层算法是 SCRFD(Sample and Computation Redistribution for Efficient Face Detection),这是 InsightFace 项目提出的一种高效人脸检测网络。本插件不依赖 insightface 库,而是使用一个自带的、纯 numpy + OpenCV 实现的推理引擎,配合 onnxruntime 加载 ONNX 格式的检测模型。检测模型为 SCRFD 的 *_bnkps 变体,同时输出人脸检测框与 5 个面部关键点。

推理只使用 CPU,无需 GPU。检测模型体积很小(默认约 2.5 MB),运行迅速,适合在演示与日常处理中使用。

• 引擎/算法:SCRFD(InsightFace),ONNX 模型经 onnxruntime 推理;预处理与后处理均为纯 numpy 实现。
• 默认模型:scrfd_2.5g(约 2.5 MB,速度与精度均衡);另可选 scrfd_10g(约 17 MB,精度更高、CPU 上更慢)。
• 运行方式:全部在 Dragonfly 自带的 Python 中完成,不修改 Dragonfly 的安装环境。
• 许可证要点:检测模型来自 HuggingFace 上 immich-app 对 InsightFace buffalo 检测模型的公开镜像,可免登录下载。SCRFD 与 InsightFace 相关权重的原始许可以其上游项目为准,一般仅限非商业/研究用途,商业使用前请核实上游许可条款。

2. 适用场景

本插件适用于以下典型场景:

• 匿名化处理:在把报告、截图或数据集对外分享之前,对照片中出现的人物进行人脸模糊,保护隐私。
• 快速统计:对合影、人群照片或监控风格的图像快速统计人脸数量。
• 定位人脸:在图像上直观标出每张人脸的位置(方框)与关键点,便于后续检查或标注。
• AI 演示:作为在 Dragonfly 内演示 AI 目标检测能力的示例,直观展示检测框、关键点与叠加结果。

提示:本插件面向常规二维照片(人物面部)设计。它不是针对显微、CT 或工业图像的通用目标检测工具;这些图像中通常不含人脸,检测结果会为空。

3. 安装与启用

本插件作为 Full Package(完整安装包)的一部分分发。安装步骤如下:

1. 将完整安装包解压到任意较短的目录(例如 C:\PL\,桌面也可),避免路径过长。

2. 双击运行 `Install_FullPackage.bat`。

3. 在弹出的对话框中选择核心安装模式(Fresh 全新安装 / Compatible 兼容安装,只影响 Prototype Labs 核心的 block 与 recipe,不影响任何插件环境)。

4. 在插件列表中勾选 SCRFD Face Detection。注意:所有插件默认未勾选,必须手动勾选才会安装启用。

5. 点击 Install,等待控制台完成安装。

6. 完全退出并重启 Dragonfly(菜单只在启动时扫描)。

重启后,插件出现在菜单 Prototype Apps ▸ SCRFD Face Detection...(位于 Detection 分组)。点击该菜单项即可打开面板窗口。

以后如需修改勾选(启用或停用),最方便的方式是在 Dragonfly 内打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部的 “Prototype Apps (Full Package)” 列表里勾选/取消对应插件,然后重启 Dragonfly 生效。停用插件不会删除它已下载的模型或已安装的运行库,重新启用后立即可用。

全部内容都安装在当前用户目录(%LOCALAPPDATA%)下,不需要管理员权限。如需彻底移除,可运行安装包目录中的 Uninstall_FullPackage.bat。

4. 运行环境与首次配置

Dragonfly 自带的 Python(2025.1 / 2027.1,均为 Python 3.10)已经内置了 numpy、OpenCV(cv2)、Pillow 与 requests。本插件只额外需要一个组件:`onnxruntime`。因此首次使用需要做两件一次性的操作,都在面板内一键完成。

4.1 安装运行库(onnxruntime)

在面板的 “1 · Runtime (onnxruntime)” 分组中点击 Install onnxruntime。插件会使用 Dragonfly 自带的 Python,把 onnxruntime 以 pip install --target 的方式安装到一个插件专属的本地目录:

%LOCALAPPDATA%\ScrfdFace\deps

该目录被追加到 sys.path 的末尾(而非插入到前面),这样 Dragonfly 自带的 numpy 1.22.3(cv2 与之 ABI 绑定)始终保持优先级,只有真正缺失的 onnxruntime 及其独有依赖会从该目录解析。Dragonfly 自身的安装环境完全不受影响。安装完成后,面板会显示 onnxruntime 的版本号并变为可用状态。

4.2 下载检测模型

在 “2 · SCRFD model” 分组中选择模型(默认 scrfd_2.5g),然后点击 Download model。模型会从 HuggingFace 的公开镜像下载并保存到:

%LOCALAPPDATA%\ScrfdFace\models

下载体积:scrfd_2.5g 约 2.5 MB;scrfd_10g 约 17 MB。下载过程会在下方日志区显示进度百分比。若你已有本地的 SCRFD .onnx 文件,也可以点击 Use local .onnx… 直接选用,无需联网下载。

4.3 环境要求汇总

失败时的替代方案:若 onnxruntime 安装失败,通常是网络受限或代理问题——重试或更换网络后再点一次即可,插件会覆盖式重装。若模型下载失败,可改用 Use local .onnx… 载入一个已有的 SCRFD 模型文件。安装库不会破坏 Dragonfly,可反复尝试。

5. 界面说明

面板顶部有一句蓝色提示:选择图像对象、选择场景、点击运行,结果会叠加显示在 2D XY 视图上。下方依次为 5 个分组、一个 Run 按钮和一个日志文本区。

1 · Runtime (onnxruntime)

• 状态标签:显示 onnxruntime 是否就绪及其版本;未安装时以红色提示,已就绪时以绿色显示版本号。
• Install onnxruntime 按钮:一键把 onnxruntime 安装到插件本地目录(已就绪时该按钮自动禁用)。

2 · SCRFD model

• Model 下拉框:选择检测模型(scrfd_2.5g 或 scrfd_10g),每项后附带简短说明。
• 状态标签:显示所选模型是否已下载及其文件路径与大小,或提示尚未下载。
• Download model 按钮:下载当前所选模型(已下载时自动禁用)。
• Use local .onnx… 按钮:打开文件选择框,直接指定一个本地 .onnx 模型文件。

3 · Detection settings

• Confidence threshold(置信度阈值):数值框,范围 0.05–0.95,步长 0.05,默认 0.5。
• NMS (overlap) threshold(非极大值抑制/重叠阈值):数值框,范围 0.1–0.9,步长 0.05,默认 0.4。
• Detector input size (px)(检测器输入尺寸):整数框,范围 160–1280,步长 32,默认 640。
• Max faces (0 = unlimited)(最大人脸数):整数框,范围 0–10000,默认 0(不限)。

4 · Target image object

• 图像对象下拉框:列出当前 Dragonfly 场景中的所有图像通道(Channel),条目后显示其尺寸(如 [1920x1080])。选择一个对象会自动把场景切换为单一 2D XY 视图,使其可见并适配缩放到视图中。
• Refresh 按钮:在 Dragonfly 中(重新)载入图像后,点此刷新列表。
• Show & fit in 2D XY view 按钮:手动将当前所选对象在 2D XY 视图中显示并适配缩放。

5 · Application scenario

• 场景下拉框,四个选项均可用:Count faces in the picture(统计人脸数量)、Detect & draw face boxes(检测并绘制人脸框)、Detect faces + 5-point landmarks(检测人脸并添加 5 点关键点)、Blur / anonymize faces(模糊/匿名化人脸)。

Run 按钮与日志区

• Run 按钮(蓝底白字):对所选图像执行当前场景。检测在后台工作线程中进行,界面不会卡顿。
• 日志区:显示读取图像、检测人脸数、结果通道名称、错误信息等运行过程。

6. 使用步骤

下面是一次完整的端到端流程(以“统计人脸数量”为例,其他场景步骤相同,仅第 6 步选择的场景不同):

1. 准备图像:在 Dragonfly 中打开/载入一张包含人脸的二维照片(可通过 Dragonfly 的常规图像导入)。

2. 打开面板:菜单 Prototype Apps ▸ SCRFD Face Detection...。

3. 安装运行库(仅首次):在 “1 · Runtime” 中点击 Install onnxruntime,等待日志显示 OK。

4. 下载模型(仅首次):在 “2 · SCRFD model” 中选好模型,点击 Download model(或用 Use local .onnx… 载入本地模型)。

5. 选择目标图像:在 “4 · Target image object” 的下拉框中选择你的照片;若列表为空或缺项,先点 Refresh。选择后场景会自动切到 2D XY 视图并适配显示。

6. 选择场景:在 “5 · Application scenario” 中选择 Count faces in the picture(或其他场景)。

7. (可选)调整参数:在 “3 · Detection settings” 中按需调整置信度、NMS、输入尺寸、最大人脸数。

8. 运行:点击 Run。日志会显示读取到的图像形状、检测到的人脸数量。

9. 查看结果:视图上会以文字叠加显示人脸计数(如 Faces: 6);若选择的是绘框/关键点/模糊场景,还会生成一张结果图像并在视图中显示。

输入要求:目标必须是已加载到 Dragonfly 场景中的图像通道(Channel)。彩色照片会被读取为 RGB;若图像被 Dragonfly 折叠为灰度,引擎会自动把灰度提升为 3 通道后再检测,因此灰度图同样可用。

7. 参数说明

参数会随插件配置自动保存,下次打开面板时沿用你上一次的设置。

8. 输出结果

根据所选场景,插件在 Dragonfly 中生成的结果如下:

• Count faces(统计):不生成新对象,仅在当前 2D XY 视图上以文字叠加(overlay text box)显示人脸计数,例如 Faces: 6(金黄色文字框)。
• Detect & draw face boxes(绘框):生成一张灰度结果通道(Channel),名为 `SCRFD_boxes`,在每张人脸上绘制白色方框,并在 2D XY 视图中显示、适配缩放,同时叠加人脸计数。
• Detect faces + 5-point landmarks(关键点):生成灰度结果通道 `SCRFD_landmarks`,在方框基础上叠加 5 个白色关键点。
• Blur / anonymize faces(模糊):生成灰度结果通道 `SCRFD_blurred`,把每张人脸区域就地模糊处理。

三种图像场景生成的结果通道均为灰度图(与 Dragonfly 显示照片的方式保持一致),会自动在 2D XY 视图中显示并适配到视图。每个场景复用同一个结果通道——再次运行同一场景会替换上一次的结果,不会堆叠出多个对象;文字叠加同样会在每次运行前清除旧的再显示新的。

结果通道是标准的 Dragonfly Channel,出现在对象浏览器(Object browser)中,可像其他通道一样查看、另存或进一步处理。

9. 常见问题与故障排除

问:菜单里找不到 “SCRFD Face Detection...”?

答:确认安装时已在插件列表中勾选该插件(默认未勾选),并且安装后完全退出并重启了 Dragonfly。也可在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 中勾选后重启。

问:点击 Run 提示 onnxruntime 未安装 / 模型不可用?

答:请先在 “1 · Runtime” 点击 Install onnxruntime,并在 “2 · SCRFD model” 点击 Download model(或用 Use local .onnx… 指定本地模型)。这两步都完成后再运行。

问:目标图像下拉框是空的,或看不到我刚载入的图像?

答:在 Dragonfly 中载入图像后,点击 “4 · Target image object” 里的 Refresh 刷新列表。列表只包含图像通道(Channel)对象。

问:检测结果为 0 张人脸,或漏检了明显的人脸?

答:可尝试调低 Confidence threshold(如 0.3)以检出更弱的人脸;对小人脸可调大 Detector input size(如 800 或更高)。若图像根本不含人脸(如显微/CT 图),结果为空属正常。

问:onnxruntime 安装或模型下载失败怎么办?

答:多为网络/代理限制。请检查网络后重试(安装为覆盖式,可反复点击);模型下载失败时可改用 Use local .onnx… 载入已有模型。整个过程不会影响 Dragonfly 自身环境。

10. 注意事项与已知限制

• 仅二维图像 / 单张切片:对图像栈或含 Z 轴的对象,插件会取第一张切片进行检测。
• 仅 CPU 推理:不使用 GPU;scrfd_10g 在 CPU 上会明显慢于默认的 scrfd_2.5g。
• 结果通道为灰度:绘框/关键点/模糊场景生成的结果图像为灰度图,标注绘制为白色。
• 结果会被覆盖:同一场景每次运行都替换上一次的结果通道与文字叠加;若要保留旧结果,请在重跑前先另存或重命名。
• 首次需联网:安装运行库与下载模型需要联网;之后可离线使用。
• 面向人脸:模型只检测人脸,不适用于通用目标检测。
• 许可:模型权重的商业使用请以 SCRFD / InsightFace 上游许可为准。

11. 参考资料

• SCRFD / InsightFace 项目(算法与原始模型来源):https://github.com/deepinsight/insightface
• 默认模型 scrfd_2.5g(HuggingFace 公开镜像):https://huggingface.co/immich-app/buffalo_s
• 高精度模型 scrfd_10g(HuggingFace 公开镜像):https://huggingface.co/immich-app/buffalo_l
• ONNX Runtime(推理运行库):https://onnxruntime.ai

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation & Enabling

4. Runtime Environment & First-Run Setup

5. Interface Reference

6. Step-by-Step Usage

7. Parameter Reference

8. Outputs

9. FAQ & Troubleshooting

10. Notes & Known Limitations

11. References

1. Overview

SCRFD Face Detection is a plugin panel that runs directly inside Dragonfly to perform fast face detection on any 2D image loaded in the scene. Pick an image, choose an application scenario, and click Run to: count the faces (shown as a text overlay on the view), draw white boxes around each face, add 5-point facial landmarks, or blur/anonymize the face regions.

The underlying algorithm is SCRFD (Sample and Computation Redistribution for Efficient Face Detection), an efficient face-detection network from the InsightFace project. The plugin does not depend on the insightface library; instead it ships a self-contained inference engine written in pure numpy + OpenCV, using onnxruntime to run an ONNX detection model. The models are SCRFD *_bnkps detectors, which output both face boxes and 5 facial keypoints.

Inference is CPU-only and requires no GPU. The detection model is very small (about 2.5 MB by default), so it runs quickly and is well suited to demos and everyday use.

• Engine/algorithm: SCRFD (InsightFace), ONNX model run via onnxruntime; pre- and post-processing are pure numpy.
• Default model: scrfd_2.5g (~2.5 MB, balanced speed/accuracy); optional scrfd_10g (~17 MB, higher accuracy, slower on CPU).
• Execution: everything runs in Dragonfly's own bundled Python; the Dragonfly installation is never modified.
• Licensing: model weights come from the public immich-app HuggingFace mirror of the InsightFace buffalo detection models (no login needed). Original licensing of SCRFD / InsightFace weights follows the upstream project — typically non-commercial/research use — so verify the upstream license before any commercial use.

2. Use Cases

The plugin is useful in the following typical scenarios:

• Anonymization: blur people's faces in photos before sharing reports, screenshots, or datasets, protecting privacy.
• Quick counting: rapidly count the number of faces in group photos, crowd images, or surveillance-style pictures.
• Locating faces: visually mark the position of each face (box) and its keypoints for later inspection or annotation.
• AI demonstration: a hands-on example of AI object detection inside Dragonfly, showing detection boxes, landmarks, and overlaid results.

Note: this plugin is designed for ordinary 2D photographs of human faces. It is not a general-purpose object detector for microscopy, CT, or industrial images; such images usually contain no faces and will return empty results.

3. Installation & Enabling

The plugin ships as part of the Full Package installer. Install it as follows:

1. Unzip the Full Package to any short folder (e.g. C:\PL\; the Desktop is fine) to avoid path-length issues.

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, choose the core install mode (Fresh = clean install / Compatible = keep your own blocks & recipes; this only affects the Prototype Labs core, not any plugin's environment).

4. In the plugin list, tick SCRFD Face Detection. Important: all plugins are unchecked by default and must be ticked to be installed.

5. Click Install and wait for the console to finish.

6. Fully quit and restart Dragonfly (menus are scanned only at startup).

After the restart, the plugin appears under Prototype Apps ▸ SCRFD Face Detection... (in the Detection group). Click it to open the panel window.

To change your choices later (enable or disable), the easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager, tick/untick the plugin in the bottom "Prototype Apps (Full Package)" list, then restart Dragonfly. Disabling a plugin never deletes its downloaded model or installed runtime — re-enabling is instant.

Everything is installed per-user under %LOCALAPPDATA%; no admin rights are needed. To remove completely, run Uninstall_FullPackage.bat from the installer folder.

4. Runtime Environment & First-Run Setup

Dragonfly's bundled Python (2025.1 / 2027.1, both Python 3.10) already ships numpy, OpenCV (cv2), Pillow, and requests. The plugin needs only one extra component: `onnxruntime`. So first use requires two one-time actions, both done with one click in the panel.

4.1 Install the runtime (onnxruntime)

In the "1 · Runtime (onnxruntime)" group, click Install onnxruntime. The plugin uses Dragonfly's own Python to install onnxruntime via pip install --target into a plugin-local folder:

%LOCALAPPDATA%\ScrfdFace\deps

That folder is appended to the end of sys.path (not inserted at the front), so Dragonfly's own numpy 1.22.3 (which cv2 is ABI-bound to) keeps priority and only the genuinely missing onnxruntime and its unique dependencies resolve from that folder. Dragonfly's own installation is left completely untouched. After installation the panel shows the onnxruntime version and marks it ready.

4.2 Download the detection model

In the "2 · SCRFD model" group, choose a model (default scrfd_2.5g) and click Download model. The model downloads from the public HuggingFace mirror and is saved to:

%LOCALAPPDATA%\ScrfdFace\models

Download size: scrfd_2.5g is about 2.5 MB; scrfd_10g is about 17 MB. Progress percentages appear in the log area below. If you already have a local SCRFD .onnx file, you can click Use local .onnx… to use it directly, with no download needed.

4.3 Environment requirements at a glance

If something fails: onnxruntime install failures are usually network/proxy related — retry (the install is overwrite-safe) or switch networks. If a model download fails, use Use local .onnx… to load an existing SCRFD model file. Neither action can harm Dragonfly, so it is safe to retry.

5. Interface Reference

The top of the panel shows a blue hint: pick an image object, choose a scenario, and run — the result is overlaid on the 2D XY view. Below it are 5 groups, a Run button, and a log text area.

1 · Runtime (onnxruntime)

• Status label: shows whether onnxruntime is ready and its version; red if not installed, green with the version when ready.
• Install onnxruntime button: one-click install into the plugin-local folder (disabled once ready).

2 · SCRFD model

• Model dropdown: choose the detection model (scrfd_2.5g or scrfd_10g); each entry has a short description.
• Status label: shows whether the selected model is downloaded, its file path and size, or a prompt to download it.
• Download model button: download the currently selected model (disabled once downloaded).
• Use local .onnx… button: opens a file picker to point at a local .onnx model file.

3 · Detection settings

• Confidence threshold: spin box, range 0.05–0.95, step 0.05, default 0.5.
• NMS (overlap) threshold: spin box, range 0.1–0.9, step 0.05, default 0.4.
• Detector input size (px): spin box, range 160–1280, step 32, default 640.
• Max faces (0 = unlimited): spin box, range 0–10000, default 0 (unlimited).

4 · Target image object

• Image-object dropdown: lists every image Channel in the current Dragonfly scene, with its size shown after the name (e.g. [1920x1080]). Selecting an object automatically switches the scene to a single 2D XY view, makes it visible, and fits it to the view.
• Refresh button: reload the list after (re)loading images in Dragonfly.
• Show & fit in 2D XY view button: manually display and fit the currently selected object in the 2D XY view.

5 · Application scenario

• Scenario dropdown, all four options enabled: Count faces in the picture, Detect & draw face boxes, Detect faces + 5-point landmarks, and Blur / anonymize faces.

Run button & log area

• Run button (blue): runs the current scenario on the selected image. Detection runs on a background worker thread, so the UI never freezes.
• Log area: shows progress such as image read, detected face count, result-channel name, and any errors.

6. Step-by-Step Usage

Here is one complete end-to-end flow (using "Count faces" as the example; other scenarios are identical except for the scenario chosen in step 6):

1. Prepare an image: open/load a 2D photo containing faces into Dragonfly (via Dragonfly's normal image import).

2. Open the panel: menu Prototype Apps ▸ SCRFD Face Detection....

3. Install the runtime (first time only): in "1 · Runtime", click Install onnxruntime and wait for the log to show OK.

4. Download the model (first time only): in "2 · SCRFD model", pick a model and click Download model (or use Use local .onnx… for a local model).

5. Select the target image: in "4 · Target image object", choose your photo; if the list is empty or missing an entry, click Refresh first. Selecting it auto-switches to the 2D XY view and fits it.

6. Choose a scenario: in "5 · Application scenario", choose Count faces in the picture (or another scenario).

7. (Optional) adjust settings: in "3 · Detection settings", tune confidence, NMS, input size, and max faces as needed.

8. Run: click Run. The log shows the image shape read and the number of faces detected.

9. View the result: the view shows the face count as a text overlay (e.g. Faces: 6); for the box/landmark/blur scenarios a result image is also created and displayed.

Input requirements: the target must be an image Channel already loaded into the Dragonfly scene. Color photos are read as RGB; if the image was collapsed to grayscale by Dragonfly, the engine automatically promotes grayscale to 3 channels before detecting, so grayscale images work too.

7. Parameter Reference

Settings are saved with the plugin configuration and reused the next time you open the panel.

8. Outputs

Depending on the chosen scenario, the plugin produces the following results in Dragonfly:

• Count faces: creates no new object; it only shows the face count as a text overlay (overlay text box) on the current 2D XY view, e.g. Faces: 6 (gold-colored text box).
• Detect & draw face boxes: creates a grayscale result Channel named `SCRFD_boxes` with white boxes drawn on each face, displayed and fitted in the 2D XY view, with the face count overlaid.
• Detect faces + 5-point landmarks: creates a grayscale result Channel `SCRFD_landmarks` with 5 white keypoints on top of the boxes.
• Blur / anonymize faces: creates a grayscale result Channel `SCRFD_blurred` with each face region blurred in place.

All three image scenarios produce a grayscale result Channel (consistent with how Dragonfly displays a photo), automatically shown and fitted in the 2D XY view. Each scenario reuses a single result Channel — re-running the same scenario replaces the previous result rather than stacking multiple objects; likewise the text overlay is cleared before each run and re-created.

The result Channel is a standard Dragonfly Channel that appears in the Object browser and can be viewed, saved, or further processed like any other channel.

9. FAQ & Troubleshooting

Q: I can't find "SCRFD Face Detection..." in the menu.

A: Make sure you ticked the plugin during installation (all plugins are unchecked by default) and that you fully quit and restarted Dragonfly afterward. You can also tick it under Developer ▸ Prototype Labs... ▸ Menu Item Manager and restart.

Q: Clicking Run says onnxruntime is not installed / the model is unavailable.

A: First click Install onnxruntime in "1 · Runtime", and Download model in "2 · SCRFD model" (or point to a local file with Use local .onnx…). Run only after both are done.

Q: The target-image dropdown is empty, or I don't see the image I just loaded.

A: After loading an image in Dragonfly, click Refresh in "4 · Target image object". The list only contains image Channel objects.

Q: Detection returns 0 faces, or misses obvious faces.

A: Try lowering the Confidence threshold (e.g. 0.3) to catch weaker faces, and increasing the Detector input size (e.g. 800 or higher) for small faces. If the image contains no faces at all (e.g. microscopy/CT), an empty result is expected.

Q: onnxruntime installation or model download fails — what do I do?

A: This is usually a network/proxy restriction. Check your connection and retry (the install is overwrite-safe, so repeated clicks are fine); if a download fails, use Use local .onnx… to load an existing model. None of this affects Dragonfly's own environment.

10. Notes & Known Limitations

• 2D images / single slice only: for image stacks or objects with a Z axis, the plugin detects on the first slice.
• CPU-only inference: no GPU is used; scrfd_10g is noticeably slower on CPU than the default scrfd_2.5g.
• Grayscale result channels: the box/landmark/blur scenarios produce grayscale result images, with annotations drawn in white.
• Results are overwritten: each run of a scenario replaces its previous result Channel and text overlay; save or rename an earlier result before re-running if you need to keep it.
• Internet needed on first use: installing the runtime and downloading a model require internet; offline use is possible afterward.
• Faces only: the model detects faces only and is not a general-purpose object detector.
• Licensing: for commercial use of the model weights, follow the upstream SCRFD / InsightFace license.

11. References

• SCRFD / InsightFace project (algorithm and original models): https://github.com/deepinsight/insightface
• Default model scrfd_2.5g (public HuggingFace mirror): https://huggingface.co/immich-app/buffalo_s
• High-accuracy model scrfd_10g (public HuggingFace mirror): https://huggingface.co/immich-app/buffalo_l
• ONNX Runtime (inference runtime): https://onnxruntime.ai