EBSD 晶粒分析(DefDAP)插件用户手册

EBSD Grains (DefDAP) - User Manual

Dragonfly Prototype Apps · EBSD Grains (DefDAP)...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

5.1 输入区(Input EBSD map (2D / one slice))

5.2 参数区(Grain segmentation)

5.3 输出选择区(Publish channels)

5.4 环境区、动作按钮与结果区

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

EBSD Grains (DefDAP) 是 Dragonfly Prototype Apps 中面向材料科学的 EBSD(电子背散射衍射)晶粒分析插件。它读取一张二维的、已标定(indexed)的 EBSD 取向图文件(或三维 EBSD 数据的单个切片),按照您设置的取向差容限自动检测晶界、把取向相近的相邻像素分割为一个个晶粒,然后计算逐像素的分析图并把它们作为 Channel(通道)发布到当前 Dragonfly 会话中,包括:

• Grain ID(晶粒编号) —— 每个像素一个整数标签(0 = 未标定像素/晶界),配合分类型(categorical)LUT 上色即可直观看到各个晶粒;
• KAM(核平均取向差,Kernel Average Misorientation) —— 单位为度(deg),反映局部取向梯度,常用于突出变形与亚结构;
• GROD(晶粒参考取向偏差,Grain Reference Orientation Deviation) —— 单位为度(deg),表示每个像素相对其所属晶粒平均取向的偏差;
• Image Quality / Confidence Index(图像质量 / 置信指数) —— 来自输入文件的标定质量指标(仅当文件中包含这些数据时才会发布)。

同时,面板内直接显示逐晶粒统计(晶粒数量、平均/中位晶粒尺寸、平均晶粒面积、平均 KAM)以及一张晶粒/IPF(反极图)预览图。

底层引擎是开源库 DefDAP(MechMicroMan/DefDAP,插件固定使用 defdap 1.2.1 版本),其许可证为 Apache-2.0(宽松许可,可安全分发)。配套依赖 numpy(BSD)、scipy(BSD)、scikit-image(BSD)、matplotlib(PSF/BSD 类)等均为宽松许可。分析计算在插件自己的独立 Python 虚拟环境(venv)中以子进程方式运行,不会影响 Dragonfly 自带的 Python 环境。

本插件仅接收二维图像(一张 EBSD 取向图,即一个切片)。DefDAP 只在单张图上工作;对于三维 EBSD 数据集,请逐切片运行。

2. 适用场景

• 晶粒尺寸与形貌统计:金属/合金等多晶材料的晶粒数量、平均及中位晶粒尺寸(像素)、平均晶粒面积等定量统计;
• 变形与取向梯度分析:KAM 与 GROD 图常用于评估局部塑性变形、位错密度分布与亚晶结构;
• EBSD 数据质检:通过 Image Quality / Confidence Index 通道检查标定质量,再结合 Dragonfly 的可视化与测量工具进一步分析;
• 与 Dragonfly 工作流衔接:结果以标准 Channel 形式发布,可继续使用 Dragonfly 的 LUT、直方图、ROI、测量等全部功能。

典型输入来源:Oxford/Bruker 系统导出的 .ctf / .cpr / .crc 文件,以及 EDAX 系统导出的 .ang 文件。

3. 安装与启用

本插件随 Prototype Labs & Apps Full Package(完整安装包)一起分发,通过统一安装器安装:

1. 把完整安装包 zip 解压到任意较短路径(如 C:\PL\,避免过深目录导致 Windows 260 字符路径限制);

2. 双击 `Install_FullPackage.bat`;

3. 在弹出的安装对话框中,于 Prototype Apps 列表里勾选 "EBSD Grains (DefDAP)..."。注意:所有插件默认不勾选,不勾选就不会安装该菜单项;

4. 点 Install 并等待控制台完成;

5. 完全重启 Dragonfly(彻底退出后重新打开)。

重启后,菜单项出现在 Prototype Apps ▸ EBSD Grains (DefDAP)...(位于菜单的 "EBSD & Crystallography" 分组)。点击后会打开一个可停靠的浮动面板,标题为 "EBSD Grains (DefDAP)"。

以后修改启用状态:最方便的方式是在 Dragonfly 里打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部 "Prototype Apps (Full Package)" 列表中勾选/取消勾选本插件,然后重启 Dragonfly 生效。停用不会删除插件已经搭建好的运行环境,重新启用后立即可用。也可以随时重跑安装器(上次的选择会作为默认值);即使删除了原始 zip,也可运行 %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat。

卸载:双击 Uninstall_FullPackage.bat(installer 目录里也有一份),它会移除所有 Full Package 菜单项与插件,但会保留各插件已搭建的环境(venv 等),结束时列出这些路径供您手动删除以回收磁盘空间。

所有内容都安装在当前用户目录(%LOCALAPPDATA%)下,不需要管理员权限。菜单只在 Dragonfly 启动时扫描,因此每次修改勾选后都需要重启一次 Dragonfly。

4. 运行环境与首次配置

插件的计算引擎运行在自己的 Python 虚拟环境(venv)中。首次使用前必须点一次面板上的 "Setup Environment" 按钮来搭建这个环境,此步骤需要联网一次;搭建完成后日常使用不再需要联网。不需要 GPU,也不需要 WSL。

Setup Environment 具体做的事情:

1. 用基础 Python 创建一个 venv。默认基础 Python 是 Dragonfly 自带的 Python(完整的 CPython 3.10,自带可用的 venv 与 pip),因此无需另装 Python;面板的 "Base Python" 输入框可指定其他解释器(任何带 venv + pip 的 CPython 3.10 及以上版本均可);

2. 在 venv 中先升级 pip / setuptools / wheel,再从 PyPI 官方源安装 defdap==1.2.1 和 matplotlib(defdap 会自动带入 numpy、scipy、scikit-image、pandas、networkx 等依赖)。这些包在 CPython 3.10 上都是纯二进制轮子(pure wheel),体积不大,通常约一分钟完成;无 CUDA、无源码编译;

3. 运行一个自检(导入 numpy 与 defdap 并打印版本),成功后记录 venv 的 Python 路径,面板 Status 显示 Ready。

环境安装位置:venv 建在插件代码目录内,即 %LOCALAPPDATA%\comet\<Dragonfly 版本>\pythonUserExtensions\GenericMenuItems\DefDAPEbsd\venv。插件的配置(Base Python 与 venv 路径)保存在同目录的 defdap_config.json 中。Full Package 更新插件代码或停用/重新启用插件时,venv 与配置都会被保留,无需重新搭建。

再次点击 Setup Environment 是安全的:若现有 venv 的 pip 仍可用则直接复用,否则自动删除重建。

失败时的替代方案:若日志出现 venv creation failed 或 requirements install failed,请检查网络连通性(需要能访问 PyPI),或在 "Base Python" 中填入一个本机已安装的 CPython 解释器完整路径(例如 C:\Python312\python.exe)后重试;defdap 需要 CPython 3.10 及以上(Windows 上 3.10–3.12 有现成的 numpy/scipy 轮子)。

5. 界面说明

面板自上而下分为标题行、四个分组框、两个动作按钮、预览区、结果摘要与日志。多处带有圆形 "?" 帮助按钮,点击可弹出对应概念的英文说明(关于插件、分割参数、结果通道)。运行期间(搭环境或计算中)两个动作按钮会自动禁用,结束后恢复。

5.1 输入区(Input EBSD map (2D / one slice))

• 文件名标签:初始显示灰色 "(no file selected)",选择文件后显示所选文件名;
• Choose map file... 按钮:打开文件对话框,过滤器为 "EBSD maps (*.ctf *.cpr *.ang *.crc)"(也可切换为所有文件)。一次只能选择一个 2D EBSD 图文件。

5.2 参数区(Grain segmentation)

• Boundary tolerance(晶界取向差容限,带 "?" 帮助):数值框,范围 0.5–45.0,默认 8.0 deg。相邻像素取向差超过该值即判为晶界;典型取值 5–10°。调小 → 晶粒更多更小;调大 → 晶粒更少更大;
• Min grain size(最小晶粒尺寸):整数框,范围 1–100000,默认 10 px。小于该像素数的晶粒作为噪声/伪迹被舍弃;图像噪声大时可调高;
• In-plane spacing(面内间距):数值框,范围 0.0001–100000(4 位小数),默认 1.0。发布 Channel 时用作 X/Y 方向的体素间距,请填入 EBSD 图的实际扫描步长。

5.3 输出选择区(Publish channels)

"Choose result channels:"(带 "?" 帮助)下方有四个复选框,决定计算完成后发布哪些 Channel:

• Grain ID —— 默认勾选;
• KAM (kernel average misorientation) —— 默认勾选;
• GROD (grain reference orientation deviation) —— 默认不勾选;
• Image quality / confidence index —— 默认不勾选;勾选后会同时尝试发布 Image Quality 与 Confidence Index 两个通道(仅当文件中存在对应数据)。

5.4 环境区、动作按钮与结果区

• Environment (DefDAP venv) 分组:"Base Python" 输入框(占位提示:"blank = this Dragonfly's python; or a path",留空即使用 Dragonfly 自带 Python);"Status" 标签显示 Ready(环境就绪)或 Not set up - click 'Setup Environment'.(尚未搭建);
• Setup Environment 按钮:搭建/复用 venv(见第 4 章);
• Segment + Publish 按钮:对所选文件执行晶粒分割并发布所选 Channel;
• 预览区:初始显示 "Grain/IPF preview appears here after Compute.",计算完成后显示 IPF 图(带晶界)或晶粒编号图;
• 结果摘要标签:显示 "Grains: N | mean size: … px | mean grain area: … | mean KAM: … deg";
• 日志框(只读):滚动显示搭环境与计算过程中的进度和错误信息。

6. 使用步骤

首次使用(一次性):

1. 打开 Prototype Apps ▸ EBSD Grains (DefDAP)...;

2. (可选)在 "Base Python" 填入自定义 Python 路径,一般留空即可;

3. 点 Setup Environment,观察日志直到出现 "Environment ready: ...",Status 变为 Ready(约一分钟,需联网)。

日常分析流程:

1. 点 Choose map file...,选择一个已标定的 2D EBSD 图文件(.ctf / .cpr / .ang / .crc);若数据是三维的,请先在采集/前处理软件中导出单个切片;

2. 设置 Boundary tolerance(典型 5–10°,默认 8°)与 Min grain size(默认 10 px);

3. 在 In-plane spacing 中填入该图的扫描步长(用于结果 Channel 的 X/Y 间距);

4. 在 Publish channels 中勾选需要的结果通道;

5. 点 Segment + Publish。日志出现类似 "=== Segment: 文件名 (tol=8.0 deg, min=10 px) ===" 的行,计算在插件 venv 的子进程中进行,Dragonfly 界面不会被卡死;

6. 计算完成后:所选通道以 "文件名 - Grain ID"、"文件名 - KAM (deg)" 等名称发布到当前会话;面板显示晶粒统计摘要与晶粒/IPF 预览图;日志列出 "Published channels: ...";

7. 在 Dragonfly 中查看结果:把新 Channel 拖入视图;Grain ID 通道请配合分类型 LUT 上色才能清晰区分晶粒;KAM/GROD 用连续色标查看取向梯度分布。

若尚未搭建环境就点 Segment + Publish,日志会提示 "ERROR: environment not set up. Click 'Setup Environment' first.";未选文件则提示 "ERROR: choose an EBSD map file first."。

7. 参数说明

8. 输出结果

计算成功后,插件把所选结果作为 Dragonfly Channel 发布到当前会话(在对象列表中即可看到),命名规则为 "输入文件名 - 结果名":

所有结果通道为单切片(1 × 高 × 宽)的 float32 数据;X/Y 体素间距取自 "In-plane spacing",KAM/GROD 通道的数据单位被设为 deg,数据中的 NaN 会被替换为 0。

面板内还给出:结果摘要(晶粒数量、平均晶粒尺寸(像素)、平均晶粒面积(按步长平方换算)、平均 KAM)和预览图(优先为带晶界的 IPF 取向图,否则退回为晶粒编号彩图)。

中间文件(.npy 数组、results.json、status.json、预览 PNG)写在系统临时目录下一个 defdap_ 开头的作业文件夹中,仅供本次运行使用;持久结果是发布到 Dragonfly 的 Channel,请按需在 Dragonfly 中保存。

9. 常见问题与故障排除

问:菜单里找不到 "EBSD Grains (DefDAP)..."?
答:该插件在完整安装包中默认不勾选。请重跑 Install_FullPackage.bat 并勾选它,或在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 中勾选后重启 Dragonfly(菜单只在启动时扫描)。

问:点 Segment + Publish 提示 "ERROR: environment not set up"?
答:尚未搭建运行环境。先点 Setup Environment 并等待 Status 变为 Ready(首次需联网,约一分钟)。

问:Setup Environment 失败(日志出现 venv creation failed / requirements install failed)?
答:确认本机能访问 PyPI(公司网络可能需要代理);仍失败时,在 "Base Python" 填入一个本机已装的 CPython 3.10+ 完整路径(如 C:\Python312\python.exe)后重试。defdap 在 Windows 上需要 CPython 3.10–3.12(有现成 numpy/scipy 轮子)。再次点击 Setup Environment 是安全的:pip 可用的旧环境会被复用,损坏的会自动重建。

问:Grain ID 通道看起来只是一片灰度渐变,看不出晶粒?
答:Grain ID 是整数编号图,直接用连续灰度显示自然呈渐变。请给该通道套一个分类型(categorical)LUT,不同编号即显示为不同颜色。

问:可以直接分析三维 EBSD 数据吗?
答:不能。DefDAP 只在单张 2D 图上工作,本插件也只接收一个文件(一个切片)。三维数据请逐切片导出并逐张运行。

问:勾选了 Image quality / confidence index,却没有生成对应通道?
答:这两个通道来自输入文件本身;若您的 .ang/.ctf 等文件中不含该列数据,插件会自动跳过,不算错误。

问:晶粒数量明显偏多(碎)或偏少?
答:调节两个分割参数:晶粒太碎 → 调大 Boundary tolerance 或调大 Min grain size;晶粒被过度合并 → 调小 Boundary tolerance。典型容限为 5–10°。

10. 注意事项与已知限制

• 仅支持 2D:一次只能分析一张 EBSD 图(或 3D 数据的一个切片);
• 输入格式:文件选择器只列出 .ctf / .cpr / .crc(Oxford/Bruker)与 .ang(EDAX)的已标定图;
• Grain ID 以 Channel 形式发布,而非 MultiROI;将晶粒导出为可逐个选择的 MultiROI 对象是计划中的增强;
• 几何信息需手动填写:X/Y 间距取自 "In-plane spacing" 输入框,Z 间距固定为 1.0;请自行填入正确的扫描步长;
• KAM/GROD 单位为度(插件已把 DefDAP 的弧度输出换算为度);
• 每次点 Segment + Publish 都会发布新的 Channel;对同一文件反复运行会产生多个同名对象,请注意整理;
• 引擎版本固定为 defdap==1.2.1,以保证结果可复现;
• 首次搭环境需要联网;之后的日常计算完全离线,不需要 GPU,也不需要 WSL。

11. 参考资料

• DefDAP 官方文档:https://defdap.readthedocs.io(开源项目 MechMicroMan/DefDAP,Apache-2.0 许可;本插件使用 defdap 1.2.1);
• 依赖库:numpy(BSD)、scipy(BSD)、scikit-image(BSD)、matplotlib(PSF/BSD 类)、pandas、networkx(由 defdap 自动引入);
• Full Package 安装说明:完整安装包内附带的 README(中英双语),涵盖安装、启用/停用、卸载与 "路径过长" 问题的处理。

Part II English Manual

Contents

1. Overview

2. Use cases

3. Installation and enabling

4. Runtime environment and first-time setup

5. User interface

5.1 Input group (Input EBSD map (2D / one slice))

5.2 Parameter group (Grain segmentation)

5.3 Output group (Publish channels)

5.4 Environment group, action buttons and result area

6. Step-by-step usage

7. Parameters

8. Outputs

9. FAQ and troubleshooting

10. Notes and known limitations

11. References

1. Overview

EBSD Grains (DefDAP) is a materials-science plugin in Dragonfly Prototype Apps for EBSD (electron backscatter diffraction) grain analysis. It reads one 2D indexed EBSD orientation-map file (or a single slice of a 3D dataset), detects grain boundaries at the misorientation tolerance you set, segments neighbouring pixels of similar crystal orientation into distinct grains, and publishes per-pixel result maps into the current Dragonfly session as Channels:

• Grain ID - an integer label per pixel (0 = unindexed / boundary); colour it with a categorical LUT to see the individual grains;
• KAM (Kernel Average Misorientation) - in degrees; the local orientation gradient, highlighting deformation and sub-structure;
• GROD (Grain Reference Orientation Deviation) - in degrees; each pixel's deviation from its grain's mean orientation;
• Image Quality / Confidence Index - indexing-quality metrics taken from the input file (published only if present in the file).

The panel additionally shows per-grain statistics (grain count, mean/median grain size, mean grain area, mean KAM) and a grain / IPF (inverse pole figure) preview picture.

The engine is the open-source DefDAP library (MechMicroMan/DefDAP; the plugin pins defdap 1.2.1), licensed Apache-2.0 (permissive, safe to distribute). Its dependencies - numpy (BSD), scipy (BSD), scikit-image (BSD), matplotlib (PSF/BSD-like) - are all permissive. Computation runs as a subprocess in the plugin's own isolated Python virtual environment (venv), leaving Dragonfly's bundled Python untouched.

This plugin accepts 2D input only (one EBSD map, i.e. one slice). DefDAP works on a single map; for a 3D EBSD dataset, run it one slice at a time.

2. Use cases

• Grain size and morphology statistics: grain count, mean and median grain size (pixels), and mean grain area for polycrystalline materials such as metals and alloys;
• Deformation and orientation-gradient analysis: KAM and GROD maps are commonly used to assess local plastic deformation, dislocation-density distribution and sub-grain structure;
• EBSD data quality checks: inspect the Image Quality / Confidence Index channels, then continue with Dragonfly's visualization and measurement tools;
• Integration with Dragonfly workflows: results are ordinary Channels, so all of Dragonfly's LUTs, histograms, ROIs and measurements apply.

Typical inputs: .ctf / .cpr / .crc files exported from Oxford/Bruker systems and .ang files from EDAX systems.

3. Installation and enabling

The plugin ships with the Prototype Labs & Apps Full Package and is installed by its unified installer:

1. Unzip the Full Package to any short path (e.g. C:\PL\; avoid deep folders that hit the Windows 260-character path limit);

2. Double-click `Install_FullPackage.bat`;

3. In the installer dialog, tick "EBSD Grains (DefDAP)..." in the Prototype Apps list. Note: all plugins are unticked by default - if you leave it unticked it will not be installed;

4. Click Install and wait for the console to finish;

5. Fully restart Dragonfly (quit completely, then reopen).

After the restart, the menu entry appears at Prototype Apps > EBSD Grains (DefDAP)... (in the "EBSD & Crystallography" group of the menu). It opens a dockable floating panel titled "EBSD Grains (DefDAP)".

Changing your choice later: the easiest way is inside Dragonfly - open Developer > Prototype Labs... > Menu Item Manager and tick/untick this plugin in the "Prototype Apps (Full Package)" list at the bottom, then restart Dragonfly. Disabling never deletes the plugin's built environment; re-enabling is instant. Alternatively re-run the installer anytime (your previous choices are the new defaults); even after deleting the zip you can run %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat.

Uninstall: double-click Uninstall_FullPackage.bat (also kept in the installer folder above). It removes all Full Package menu items and plugins but keeps every plugin environment (venv etc.); the paths are listed at the end so you can delete them manually to reclaim disk space.

Everything is per-user (%LOCALAPPDATA%); no admin rights are needed. Menus are discovered only at Dragonfly startup, so every enable/disable change needs one restart.

4. Runtime environment and first-time setup

The compute engine runs in the plugin's own Python virtual environment (venv). Before first use you must click the panel's "Setup Environment" button once; this step needs internet access once. Everyday use afterwards is fully offline. No GPU and no WSL are required.

What Setup Environment actually does:

1. Creates a venv from a base Python. The default base is Dragonfly's own bundled Python (a full CPython 3.10 with working stdlib venv + pip), so no separate Python install is needed; the panel's "Base Python" field can point to another interpreter (any CPython 3.10+ with venv + pip works);

2. Upgrades pip / setuptools / wheel inside the venv, then pip-installs defdap==1.2.1 and matplotlib from the default PyPI index (defdap pulls in numpy, scipy, scikit-image, pandas, networkx). All are pure wheels on CPython 3.10 - no CUDA, no source builds - and the install typically takes about a minute;

3. Runs a smoke test (imports numpy and defdap, prints their versions); on success the venv's Python path is recorded and the panel's Status shows Ready.

Where the environment lives: the venv is created inside the plugin's code folder, i.e. %LOCALAPPDATA%\comet\<Dragonfly version>\pythonUserExtensions\GenericMenuItems\DefDAPEbsd\venv. The plugin's settings (Base Python and venv path) are stored next to it in defdap_config.json. Full Package code updates and disable/re-enable cycles preserve the venv and the settings - no rebuild needed.

Clicking Setup Environment again is safe: an existing venv whose pip still works is reused; a broken one is deleted and rebuilt automatically.

If setup fails: if the log shows venv creation failed or requirements install failed, check that the machine can reach PyPI (corporate networks may need a proxy), or enter the full path of a locally installed CPython interpreter (e.g. C:\Python312\python.exe) in "Base Python" and retry; defdap needs CPython 3.10+ (numpy/scipy wheels exist for 3.10-3.12 on Windows).

5. User interface

From top to bottom the panel contains a title row, four group boxes, two action buttons, a preview area, a summary line and a log. Several round "?" help buttons open explanations of the key concepts (about the plugin, the segmentation parameters, the result channels). While a job is running (setup or compute) both action buttons are disabled and re-enabled when it finishes.

5.1 Input group (Input EBSD map (2D / one slice))

• File label: initially the grey text "(no file selected)"; shows the chosen file name afterwards;
• Choose map file... button: opens a file dialog filtered to "EBSD maps (*.ctf *.cpr *.ang *.crc)" (an All-files filter is also available). Exactly one 2D EBSD map file can be selected.

5.2 Parameter group (Grain segmentation)

• Boundary tolerance (with a "?" help button): spin box, range 0.5-45.0, default 8.0 deg. An orientation jump between neighbouring pixels larger than this counts as a grain boundary; typical values are 5-10 degrees. Lower = more, smaller grains; higher = fewer, larger grains;
• Min grain size: integer spin box, range 1-100000, default 10 px. Grains smaller than this are discarded as noise/artefacts; raise it for noisy maps;
• In-plane spacing: spin box, range 0.0001-100000 (4 decimals), default 1.0. Used as the X/Y voxel spacing of the published Channels; enter the map's real scan step size.

5.3 Output group (Publish channels)

Under "Choose result channels:" (with a "?" help button) four checkboxes select which Channels are published after the compute:

• Grain ID - checked by default;
• KAM (kernel average misorientation) - checked by default;
• GROD (grain reference orientation deviation) - unchecked by default;
• Image quality / confidence index - unchecked by default; when ticked, both an Image Quality and a Confidence Index channel are published (only if the file contains the data).

5.4 Environment group, action buttons and result area

• Environment (DefDAP venv) group: the "Base Python" text field (placeholder: "blank = this Dragonfly's python; or a path"; leave blank to use Dragonfly's own Python) and a "Status" label showing Ready or Not set up - click 'Setup Environment'.;
• Setup Environment button: builds / reuses the venv (see chapter 4);
• Segment + Publish button: runs grain segmentation on the chosen file and publishes the selected Channels;
• Preview area: initially "Grain/IPF preview appears here after Compute."; after a run it shows the IPF map (with grain boundaries) or a grain-ID picture;
• Summary label: shows "Grains: N | mean size: ... px | mean grain area: ... | mean KAM: ... deg";
• Log box (read-only): scrolling progress and error messages for setup and compute.

6. Step-by-step usage

First use (one-time):

1. Open Prototype Apps > EBSD Grains (DefDAP)...;

2. (Optional) enter a custom interpreter path in "Base Python"; normally leave it blank;

3. Click Setup Environment and watch the log until "Environment ready: ..." appears and Status turns Ready (about a minute; internet required).

Everyday analysis workflow:

1. Click Choose map file... and select one indexed 2D EBSD map (.ctf / .cpr / .ang / .crc); for 3D data, first export a single slice from your acquisition/pre-processing software;

2. Set Boundary tolerance (typically 5-10 degrees; default 8) and Min grain size (default 10 px);

3. Enter the map's scan step size in In-plane spacing (used as the X/Y spacing of the result Channels);

4. Tick the desired result channels under Publish channels;

5. Click Segment + Publish. The log prints a line like "=== Segment: file (tol=8.0 deg, min=10 px) ==="; the computation runs as a subprocess in the plugin venv, so the Dragonfly UI stays responsive;

6. When it finishes: the selected channels are published as "file name - Grain ID", "file name - KAM (deg)", etc.; the panel shows the grain-statistics summary and the grain/IPF preview; the log lists "Published channels: ...";

7. View the results in Dragonfly: drag the new Channels into a view; colour the Grain ID channel with a categorical LUT to distinguish the grains; view KAM/GROD with a continuous colormap.

Clicking Segment + Publish before the environment is set up logs "ERROR: environment not set up. Click 'Setup Environment' first."; with no file chosen it logs "ERROR: choose an EBSD map file first.".

7. Parameters

8. Outputs

On success the plugin publishes the selected results as Dragonfly Channels into the current session (visible in the object list), named "input file name - result name":

All result channels are single-slice (1 x height x width) float32 data; the X/Y voxel spacing comes from "In-plane spacing", the data unit of the KAM/GROD channels is set to deg, and NaN values are replaced by 0.

The panel also shows a summary (grain count, mean grain size in pixels, mean grain area converted with the step size squared, mean KAM) and a preview picture (preferably the IPF orientation map with grain boundaries, otherwise a coloured grain-ID map).

Intermediate files (.npy arrays, results.json, status.json, the preview PNG) are written to a job folder starting with defdap_ in the system temp directory and are only used for that run; the durable output is the Channels published into Dragonfly - save them in Dragonfly as needed.

9. FAQ and troubleshooting

Q: I cannot find "EBSD Grains (DefDAP)..." in the menu.
A: The plugin is unticked by default in the Full Package installer. Re-run Install_FullPackage.bat and tick it, or tick it in Developer > Prototype Labs... > Menu Item Manager, then restart Dragonfly (menus are scanned only at startup).

Q: Segment + Publish logs "ERROR: environment not set up".
A: The runtime environment has not been built yet. Click Setup Environment first and wait until Status shows Ready (needs internet once; about a minute).

Q: Setup Environment fails (the log shows venv creation failed / requirements install failed).
A: Make sure the machine can reach PyPI (corporate networks may need a proxy). If it still fails, enter the full path of a locally installed CPython 3.10+ (e.g. C:\Python312\python.exe) in "Base Python" and retry; on Windows, numpy/scipy wheels exist for CPython 3.10-3.12. Clicking Setup Environment again is safe: a venv with working pip is reused, a broken one is rebuilt automatically.

Q: The Grain ID channel looks like a smooth grey gradient - I cannot see grains.
A: Grain ID is an integer label map, so a continuous grey LUT naturally renders as a gradient. Apply a categorical LUT to that channel and each label becomes a distinct colour.

Q: Can I analyse a 3D EBSD dataset directly?
A: No. DefDAP works on a single 2D map, and the plugin accepts one file (one slice). Export the slices of a 3D dataset and run them one at a time.

Q: I ticked Image quality / confidence index but no such channels appeared.
A: These channels come from the input file itself; if your .ang/.ctf file does not contain those columns, the plugin silently skips them - this is not an error.

Q: I get far too many small grains, or too few large ones.
A: Tune the two segmentation parameters: too fragmented - raise Boundary tolerance or Min grain size; over-merged - lower Boundary tolerance. Typical tolerance is 5-10 degrees.

10. Notes and known limitations

• 2D only: one EBSD map (or one slice of a 3D dataset) per run;
• Input formats: the file picker lists indexed maps in .ctf / .cpr / .crc (Oxford/Bruker) and .ang (EDAX);
• Grain ID is published as a Channel, not a MultiROI; exporting grains as individually selectable MultiROI objects is a planned enhancement;
• Geometry is entered manually: the X/Y spacing comes from the "In-plane spacing" field and the Z spacing is fixed at 1.0 - enter the correct scan step yourself;
• KAM/GROD are in degrees (the plugin converts DefDAP's radian output to degrees);
• Every Segment + Publish creates new Channels; repeated runs on the same file produce multiple objects with the same names - tidy up as needed;
• The engine version is pinned to defdap==1.2.1 for reproducible results;
• Internet is needed once for the environment setup; everyday computation is fully offline, with no GPU and no WSL required.

11. References

• DefDAP documentation: https://defdap.readthedocs.io (open-source project MechMicroMan/DefDAP, Apache-2.0 license; this plugin uses defdap 1.2.1);
• Dependencies: numpy (BSD), scipy (BSD), scikit-image (BSD), matplotlib (PSF/BSD-like), pandas, networkx (pulled in by defdap);
• Full Package installation guide: the bilingual README shipped inside the Full Package zip, covering install, enable/disable, uninstall and the Windows "path too long" issue.