Particle Size Distribution (Hands-on Workshop)(粒度分布上手练习)

Particle Size Distribution (Hands-on Workshop) - User Manual

Dragonfly Prototype Apps · Particle Size Distribution...

版本 Version 1.0 · 2026-07-26

第一部分 中文手册

目录

1. 简介

2. 功能特点

3. 四个标签页

4. 使用步骤

5. 环境需求

6. 提示与常见坑

1. 简介

这是“上手练习（Hands-on Workshops）”类目下的第二个实操项目，用一个四标签页的教学向导，带你走完“从一张有很多颗粒的图像 → 每个颗粒的大小 → 整体粒度分布”的完整链条。四个标签页分别是：①概念（语义分割 vs 实例分割）；②实例分割方法（经典分水岭 / SNOW / Fast-split / Cellpose-SAM）；③MultiROI 测量（每个颗粒能测哪些量）；④粒度定义与计算（粒度的多种定义 + D10/D50/D90 分布统计）。

每个标签页都配有 📖 概念（Learn） 按钮（弹出可缩放、带 中文|EN 切换的教学窗口）与 🛠 动手（Try it） 按钮（在真实数据上执行）。核心的动手环节——生成合成颗粒、Otsu 二值分割、分水岭实例分割、逐颗测量、汇总分布——完全在 Dragonfly 进程内用自带的 numpy/scipy/skimage 运行，无需 venv、无需下载、无需联网。

适用场景：教学与自学（把概念与真实操作结合，边学边做）；培训新员工/学生掌握颗粒分析的标准流程与常见坑（过/欠分割、边界颗粒、体素尺寸、数量 vs 体积加权）；作为向导避免遗漏关键步骤；以及作为“可交互的教程”用于客户演示与市场推广。

2. 功能特点

• 四标签页教学向导：概念 → 实例分割 → 测量 → 粒度，边看文档边动手。
• 一键生成合成颗粒样本：可设定颗粒数量（默认 70）、平均半径（体素，默认 9）与“是否相互接触”，生成一张带模糊与噪声的灰度图并发布为 Channel——接触的颗粒在二值化后会粘连成一团，正好演示“为什么需要实例分割”。
• 语义分割（Otsu 二值 ROI）：用 Otsu 阈值把颗粒相取成一个二值 ROI，直观看到接触颗粒被合并、无法计数。
• 进程内分水岭实例分割 → MultiROI：距离变换 + peak_local_max 找种子 + 分水岭，把颗粒相切成一颗颗，发布为 MultiROI（每个 label 一颗颗粒）；可调 min_distance（种子最小间距）与“颗粒=高亮度”。
• 逐颗测量：对每个 label 计算体积、等效体积球直径（(6V/π)^(1/3)）与 Feret 包围盒近似（max/min），可填入体素尺寸换算为真实世界单位。
• 粒度分布统计：把逐颗直径汇总为分布，给出数量加权 D10/D50/D90 + 跨度 Span + 均值；若有体积数据，另给体积加权 Dv10/Dv50/Dv90，并输出直方图数据。
• 重活指引：较重的方法（SNOW、Cellpose-SAM）不在本插件内跑，而是弹窗指引到对应的 Prototype Apps 插件。

3. 四个标签页

4. 使用步骤

1. 在 Dragonfly 菜单栏打开 Hands-on Workshops ▸ Particle Size Distribution...（作为可停靠面板打开）。首次可点顶部 📘 Overview 看课程总览。

2. 标签页①：设定 N 颗粒、平均半径、勾选“Make particles touch（相互接触）”，点 🧪 Create synthetic particles 生成并选中样本；点 🔲 Semantic ROI (Otsu) 看语义二值分割为何数不出个数。（也可从顶部 Image 下拉选自己的图像，点 ✅ Use the selected image。）

3. 标签页②：设定 min_distance 与“Particle = high intensity（颗粒=高亮度）”，点 💧 Watershed instance segmentation → MultiROI，把颗粒切成一颗颗并发布为 MultiROI；肉眼核对是否过/欠分割。

4. 标签页③：填入正确的 Voxel size（体素尺寸），点 📏 Measure each particle，得到每颗颗粒的体积、等效直径与 Feret 近似的均值/中位数。

5. 标签页④：点 📈 Compute size distribution，得到数量加权 D10/D50/D90、跨度 Span、均值（如有体积数据还给体积加权 Dv10/Dv50/Dv90）。

6. 需要更强分离时，在标签页②点 ➡ SNOW 或 ➡ Cellpose-SAM，按弹窗指引改用对应的 Prototype Apps 插件；完整的 Feret / 球形度请用 Dragonfly 的 MultiROI 测量面板。

5. 环境需求

• 无需 venv、无需下载、无需 GPU、无需管理员权限。 核心动手环节完全在进程内运行。
• 分水岭实例分割、测量与分布统计使用 Dragonfly 自带的 numpy / scipy / skimage（在 Dragonfly 进程内），合成颗粒样本用 numpy 生成。
• 教学文档随时可看（不依赖 Dragonfly）；但 🛠 动手按钮需在 Dragonfly 内运行（要读取/发布对象）。若检测不到 Dragonfly 对象模型，面板会提示“文档可用、动手按钮需在 Dragonfly 内运行”。
• 较重的方法本插件不自带：SNOW 指引到 Prototype Apps 的 ROI to MultiROI (SNOW) 插件（porespy，需一次性 venv）；Cellpose-SAM 指引到 Cellpose 插件（Dragonfly 2025.1 / 2027.1 均自带 Cellpose 及 SAM 权重，深度模型建议 GPU）。

6. 提示与常见坑

• min_distance 是分水岭的关键旋钮：太小 → 过分割（一颗被切成几瓣）；太大 → 欠分割（几颗并成一颗）。过/欠分割都会直接扭曲粒度分布，务必肉眼核对。
• 体素尺寸决定一切长度量：体积随体素尺寸的三次方缩放、直径线性缩放；填错则所有带量纲的结果全错。面板会尽量读取图像的体素间距作为默认值。
• 数量加权 vs 体积加权：同一批颗粒，两种加权的 D50 可能相差数倍（体积 ∝ d³，大颗粒在体积加权里权重极大）。报告时务必写明加权方式。
• 边界与分辨率：被视场边缘截断的颗粒会偏小，统计时常需剔除接触边界的 label；只有几个体素大的颗粒测量误差极大（部分体积效应），一般要求直径 ≥ 3–5 体素。
• 颗粒数要够：颗粒太少分布统计不稳，一般希望有成百上千颗。本插件的逐颗测量给出的是等效体积直径与 Feret 包围盒近似；需要精确 Feret / 球形度请用 Dragonfly 的 MultiROI 测量面板。

Part II English Manual

Contents

1. Introduction

2. Features

3. The four tabs

4. How to use

5. Requirements

6. Tips & pitfalls

1. Introduction

This is the second Hands-on Project in the Hands-on Workshops category: a four-tab teaching wizard that walks the whole chain from an image full of particles → each particle's size → the overall size distribution. The four tabs are: (1) Concepts (semantic vs instance segmentation); (2) Instance-segmentation methods (classic watershed / SNOW / Fast-split / Cellpose-SAM); (3) MultiROI measurements (what can be measured per particle); (4) Particle size definitions & computation (the many size definitions + D10/D50/D90 statistics).

Every tab pairs 📖 Learn buttons (resizable, 中文|EN-switchable teaching pop-ups) with 🛠 Try it buttons that run on real data. The core actions — create synthetic particles, Otsu binary segmentation, watershed instance segmentation, per-particle measurement and distribution aggregation — run fully in-process on Dragonfly's bundled numpy/scipy/skimage: no venv, no download, no internet.

Use it for: teaching and self-study (couple concepts with real operations, learning by doing); onboarding new staff/students to the standard particle-analysis workflow and its pitfalls (over/under-segmentation, edge particles, voxel size, number- vs volume-weighting); as a guided SOP that prevents skipping key steps; and as an interactive tutorial for demos and marketing.

2. Features

• Four-tab teaching wizard: Concepts → Instance seg → Measure → Size, with docs and hands-on actions side by side.
• One-click synthetic particle sample: set the particle count (default 70), mean radius in voxels (default 9) and whether particles touch; it generates a blurred, noisy grayscale image and publishes it as a Channel — touching particles merge into a blob once binarised, which is exactly why instance segmentation is needed.
• Semantic segmentation (Otsu binary ROI): Otsu-threshold the particle phase into one binary ROI to see that touching particles are merged and cannot be counted.
• In-process watershed instance segmentation → MultiROI: distance transform + peak_local_max seeds + watershed splits the phase into individual particles and publishes a MultiROI (one label per particle); tunable min_distance (seed spacing) and a Particle = high intensity toggle.
• Per-particle measurement: for each label, compute volume, equivalent-volume sphere diameter ((6V/π)^(1/3)) and a Feret bounding-box approximation (max/min); enter a voxel size to convert to real world units.
• Size-distribution statistics: aggregate the per-particle diameters into a distribution — number-weighted D10/D50/D90 + span + mean; if volumes are available, also volume-weighted Dv10/Dv50/Dv90, plus histogram data.
• Guidance to heavier methods: the more demanding routes (SNOW, Cellpose-SAM) are not run in this plugin — a pop-up points you to the matching Prototype Apps plugin.

3. The four tabs

4. How to use

1. Open Hands-on Workshops ▸ Particle Size Distribution... from Dragonfly's menu bar (it opens as a dockable panel). Click 📘 Overview at the top for a course overview.

2. Tab 1: set N particles, mean radius, tick Make particles touch, then 🧪 Create synthetic particles to generate and select the sample; click 🔲 Semantic ROI (Otsu) to see why a binary segmentation cannot count them. (Or pick your own image from the top Image dropdown and click ✅ Use the selected image.)

3. Tab 2: set min_distance and Particle = high intensity, then 💧 Watershed instance segmentation → MultiROI to split the particles and publish a MultiROI; eyeball it for over/under-segmentation.

4. Tab 3: enter the correct Voxel size, then 📏 Measure each particle to get per-particle volume, equivalent diameter and Feret-approx mean/median.

5. Tab 4: click 📈 Compute size distribution for number-weighted D10/D50/D90, span and mean (plus volume-weighted Dv10/Dv50/Dv90 if volumes are available).

6. For stronger separation, use ➡ SNOW or ➡ Cellpose-SAM on Tab 2 and follow the pop-up to the matching Prototype Apps plugin; for full Feret / sphericity use Dragonfly's MultiROI measurement panel.

5. Requirements

• No venv, no download, no GPU, no admin. The core actions run fully in-process.
• Watershed instance segmentation, measurement and distribution statistics use Dragonfly's bundled numpy / scipy / skimage (inside the Dragonfly process); synthetic particle samples are generated with numpy.
• The teaching docs work anywhere (no Dragonfly needed), but the 🛠 Try it buttons must run inside Dragonfly (they read/publish objects). If the object model is not detected, the panel notes that the docs work while the action buttons run inside Dragonfly.
• Heavier methods are not bundled here: SNOW guides to the Prototype Apps ROI to MultiROI (SNOW) plugin (porespy, one-time venv); Cellpose-SAM guides to the Cellpose plugin (both Dragonfly 2025.1 and 2027.1 bundle Cellpose with SAM weights; a GPU is recommended for the deep model).

6. Tips & pitfalls

• min_distance is the key watershed knob: too small → over-segmentation (one particle cut into pieces); too large → under-segmentation (several merged). Both directly distort the PSD, so always eyeball the result.
• Voxel size drives every length: volume scales with the cube of voxel size, diameter linearly — a wrong value ruins every dimensioned quantity. The panel reads the image spacing as the default when it can.
• Number- vs volume-weighting: for the same particles the two D50s can differ several-fold (volume ∝ d³, so large particles dominate the volume-weighted stats). Always state the weighting when reporting.
• Edges & resolution: particles clipped by the field of view read too small — often exclude labels touching the boundary; particles only a few voxels across have huge measurement error (partial-volume), so require a diameter ≥ 3–5 voxels.
• Use enough particles: too few and the statistics are unstable — aim for hundreds to thousands. The per-particle measurement here gives the equivalent-volume diameter and a Feret bounding-box approximation; for exact Feret / sphericity use Dragonfly's MultiROI measurement panel.