TrackMate 类对象追踪 (TrackMate-like Object Tracker) 插件用户手册

TrackMate-like Object Tracker - User Manual

Dragonfly Prototype Apps · TrackMate-like Object Tracker...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

TrackMate 类对象追踪(TrackMate-like Object Tracker) 是一个 Dragonfly 原生的对象级追踪插件。它把一组按时间顺序排列的 Dragonfly MultiROI 当作对象检测结果:每一帧(每个 MultiROI)中的每个非零标签视为一个对象(detection)。插件计算每个对象的质心(centroid) 和 体积(volume),再用线性分配(LAP,Linear Assignment Problem) 算法把相邻帧中的对象连接成随时间延续的 track(轨迹),最终输出 tracks.csv 追踪表,并可将带有稳定 track ID 的结果按帧发布回 Dragonfly。

该插件的设计灵感来自 Fiji 中广为人知的 TrackMate 工作流(检测对象 → 连接检测 → 检查轨迹 → 发布 track ID),但它不依赖 Fiji、ImageJ 或 Java,而是在 Dragonfly 内直接使用一个轻量 Python 环境完成计算。

底层引擎与算法

• 检测(Detection): 每一帧 MultiROI 中的每个非零标签就是一个对象;插件计算其质心(体素坐标与物理坐标)、体素体积和包围盒(bounding box)。
• 连接(Linking): 使用 SciPy 的 scipy.optimize.linear_sum_assignment 在代价矩阵上做线性分配。代价 = 质心物理距离 + 可选的体积变化惩罚。
• gap closing(跨帧连接): 允许对象在若干帧中暂时消失后再被连接,由 Max frame gap 参数控制。
• 依赖库: numpy 与 scipy,均从 PyPI 安装。追踪核心 (trackmate_core.py) 与 Dragonfly 解耦,可独立运行与测试。

许可证要点

插件运行时仅依赖 numpy 与 scipy 两个广泛使用的科学计算库(均为宽松开源许可,BSD 风格)。插件本身不捆绑 Fiji / ImageJ / Java,因此没有 GPL 传染问题。首次使用时,这两个库会从 PyPI 下载到插件自建的独立环境中。

这是一个务实的第一版实现:它覆盖 Dragonfly 中最常见的 MultiROI 对象级追踪需求,但不是 Fiji TrackMate 的完整复制品。当前版本尚未推断对象的分裂/合并(split/merge)谱系——每个检测最多连接一个前驱。

2. 适用场景

本插件面向已经完成分割、现在需要追踪对象随时间或过程步骤移动的场景。它的输入是已存在的 MultiROI,而不是原始图像,因此适合放在分割流程之后作为分析步骤。典型应用包括:

• 追踪颗粒(particles) 在一系列时间点或工艺步骤中的位置变化。
• 追踪细胞(cells) 在延时序列(time-lapse)中的迁移。
• 追踪孔隙(pores)、缺陷(defects) 或其他材料对象在原位实验(in-situ)不同阶段的演化。
• 任何一组按顺序排列的 2D 或 3D 标签对象,需要给同一个物理对象赋予贯穿所有帧的稳定编号。

追踪成功后,你可以在 tracks.csv 中按 track ID 分析对象的位移、体积变化和轨迹长度,或在 Dragonfly 中直接查看以 track ID 上色的逐帧 MultiROI。

3. 安装与启用

本插件随 Prototype Apps 完整安装包(Full Package) 一起分发。安装与启用步骤如下:

1. 将完整安装包解压到一个较短的目录(例如 C:\PL\),避免路径过长错误(0x80010135)。

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

3. 在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),并在插件列表中勾选 TrackMate-like Object Tracker。注意:所有插件默认未勾选(OFF),必须手动勾选才会启用。

4. 点击 Install,等待控制台完成。

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

重启后,插件出现在菜单:Prototype Apps ▸ TrackMate-like Object Tracker...(位于 “Measurements & Analysis” 分组)。点击即可打开一个可停靠的 PyQt 面板(标题 “TrackMate-like Object Tracker”,默认浮动窗口,可拖动/停靠)。

以后修改启用状态

以后要启用或停用本插件,最方便的方式是在 Dragonfly 内打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部的 “Prototype Apps (Full Package)” 列表中勾选/取消勾选,然后重启 Dragonfly 生效。停用从不删除插件已搭好的运行环境,重新启用即可立即使用。

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

4. 运行环境与首次配置

为避免与 Dragonfly 自带的 Python 冲突,本插件在首次使用时会构建一个独立的虚拟环境(venv),并在其中安装 numpy 与 scipy。这一步通过面板 Setup 分页里的 Setup Environment (numpy + scipy) 按钮完成。

Setup Environment 具体做什么

1. 在已安装的插件代码目录下创建一个 venv 文件夹(位于 %LOCALAPPDATA%\comet\<Dragonfly 版本>\pythonUserExtensions\GenericMenuItems\TrackMateDragonfly\venv)。

2. 升级该 venv 内的 pip。

3. 从 PyPI 安装 numpy 与 scipy(见 requirements.txt)。

4. 把新建 venv 的 python 路径写回面板的 Analysis venv python 字段并保存到配置。之后 Run Tracking 会用这个 python 运行追踪计算。

下载体积与联网要求

numpy 与 scipy 两个包体积中等(通常在数十至一百多 MB 量级,具体取决于平台与版本)。安装时需要联网以从 PyPI 下载;联网仅在这一步需要,追踪计算本身完全离线。

无需 GPU / Fiji / WSL / 外部软件

追踪计算是纯 CPU 的线性分配运算,不需要 GPU,也不需要 Fiji、ImageJ、Java 或 WSL,更不需要任何外部软件或令牌(token)。这正是本插件相对 Fiji TrackMate 的主要优势。

Base Python 与失败时的替代方案

Base Python 字段决定用哪个 Python 解释器来创建 venv。留空时插件会自动探测(Dragonfly 自带或系统 Python)。如果 Setup 失败(例如自动探测到的解释器缺少 ensurepip、无法创建 venv),可点击 Browse... 手动指定一个可用的系统 CPython(建议 3.10–3.12),再重试 Setup。控制台/日志区会显示失败原因。

Job root 字段是追踪作业的输出根目录,默认 C:\TrackMateDragonflyJobs。每次运行会在其下新建一个带时间戳的子目录(如 trackmate_df_20260704_153000)存放导出的标签、tracks.csv 与中间文件。

5. 界面说明

面板顶部是标题栏,底部是状态标签(绿色文字,显示当前状态)与一个只读日志框。中间是四个分页:Setup / Frames / Tracking / Summary。下面逐一说明每个控件。

5.1 Setup 分页

分页底部有提示:不使用 Fiji/ImageJ/Java;运行前请按时间顺序添加 MultiROI 帧。

5.2 Frames 分页

此页用于组装帧序列——即参与追踪的一组 MultiROI,按时间先后排列。

帧的时间顺序完全由你添加的先后决定。插件不会根据文件名或 Dragonfly 时间轴自动推断时间点,请务必按正确顺序 Add Frame。

5.3 Tracking 分页

此页设置连接参数(Linking)与输出选项(Output),并触发追踪。

5.4 Summary 分页

追踪完成后,插件自动跳到此页,以两列表格(Metric / Value)显示统计结果:帧数、检测总数、track 数、最短/最长/平均 track 长度等。

6. 使用步骤

下面是从零到追踪结果的端到端流程。前提:你已经在 Dragonfly 中准备好至少两个 MultiROI,每个对应一个时间点/步骤,并且同一物理对象在各帧中已被分割为标签。

1. 打开 Prototype Apps ▸ TrackMate-like Object Tracker...。

2. 首次使用: 切到 Setup 分页,点 Setup Environment (numpy + scipy),等待日志显示 “Environment ready.”(如失败,按第 4 章设置 Base Python 后重试)。

3. 切到 Frames 分页,点 Refresh 刷新 MultiROI 列表。

4. 在 MultiROI 下拉框中选择第一个时间点的 MultiROI,点 Add Frame;再选第二个时间点,点 Add Frame;依此类推,严格按时间顺序添加所有帧。

5. 核对帧序列表格:Frame 列应从 0 递增,Title/Shape/Labels 是否符合预期。可用 Remove Selected / Clear 调整。

6. 切到 Tracking 分页,设置 Max link distance(最重要:应略大于对象在相邻两帧间的最大真实位移)、必要时调整 Max frame gap、Volume penalty weight、Min object volume。

7. 设置输出选项:Output MultiROI prefix、是否 Publish one tracked MultiROI per frame、Publish frame limit。

8. 点 Run Tracking。运行期间日志区滚动显示进度(导出各帧、连接检测、写输出)。

9. 完成后面板跳到 Summary 分页显示统计;状态栏给出 tracks.csv 的完整路径。若勾选了发布,逐帧 track-ID MultiROI 会出现在 Dragonfly 对象列表中。

至少需要两帧才能运行;若未先完成 Setup(Analysis venv python 为空),点击 Run Tracking 会提示先运行 Setup。

7. 参数说明

下表汇总所有追踪参数及其含义,供调参参考。

距离与体积均基于 MultiROI 的物理间距(spacing)计算:质心先乘以各轴 spacing 得到物理坐标,再算欧氏距离。因此 Max link distance 使用的是物理单位而非体素数。

8. 输出结果

一次成功的追踪会产生以下结果:

8.1 追踪表 tracks.csv

写入本次作业目录(<Job root>\trackmate_df_<时间戳>\tracks.csv)。每一行是某一帧中的一个检测,列包括:

• frame、label、track_id —— 帧号、原始标签值、贯穿全序列的稳定 track ID。
• centroid_z / centroid_y / centroid_x —— 体素坐标质心。
• physical_z / physical_y / physical_x —— 物理坐标质心(已乘 spacing)。
• volume_voxels —— 该对象的体素体积。
• bbox_z0..bbox_x1 —— 包围盒的起止索引。
• link_cost —— 该检测被连接时的代价(新建轨迹为 0)。

8.2 逐帧 track-ID MultiROI

若勾选 Publish one tracked MultiROI per frame,插件会为每一帧发布一个新的 MultiROI(标题形如 Tracked objects t000、Tracked objects t001 …),其中每个对象的标签值即其稳定 track ID。这样同一物理对象在所有帧中的标签一致,便于在 Dragonfly 中用统一配色查看其轨迹。发布数量受 Publish frame limit 限制。

8.3 Summary 统计

Summary 分页显示的指标:n_frames(帧数)、n_detections(检测总数)、n_tracks(track 数)、min_track_length / max_track_length / mean_track_length(track 长度的最小/最大/平均值)。

8.4 中间文件

作业目录中还会保留导出的各帧标签 frame_###_labels.npy、每帧的 track-ID 标签体积 track_labels_t###.npy、export.json 与运行状态/结果文件,便于复查或二次分析。

如何查看结果: 打开 tracks.csv(Excel 或任意表格工具)分析位移/体积/轨迹长度;在 Dragonfly 对象列表中查看发布的逐帧 MultiROI,用统一配色跨帧对照同一 track。

9. 常见问题与故障排除

Q1. 点 Setup Environment 失败,提示无法创建 venv 或缺少 pip

自动探测到的基础 Python 可能缺少 ensurepip 或不适合建 venv。请在 Base Python 处点 Browse... 手动指定一个正常的系统 CPython(建议 3.10–3.12)后重试。同时确认这一步电脑能联网访问 PyPI。

Q2. 点 Run Tracking 提示 “Add at least two MultiROI frames first”

帧序列少于两帧。请回到 Frames 分页,用 Add Frame 至少加入两个 MultiROI。若提示 “Run Setup first”,说明 Analysis venv python 为空,需先在 Setup 分页完成环境搭建。

Q3. 对象没连上 / 一个物理对象被拆成了多条 track

多半是 Max link distance 太小,小于对象在相邻帧间的真实位移。适当调大;如果对象在某些帧漏检,可把 Max frame gap 设为 1 或更大以跨帧续接。

Q4. 相邻但不同的对象被错误连到了一起

Max link distance 可能偏大。可调小该阈值;若这些对象大小差异明显,增大 Volume penalty weight(如 0.1~0.5)可利用体积差异帮助区分。

Q5. 下拉框里看不到我的 MultiROI

点 Refresh 重新扫描;确认对象确实是 MultiROI 类型且已在当前会话中(而非仅在磁盘上)。分割碎片过多时,可用 Min object volume 过滤微小标签。

Q6. 没有生成逐帧 MultiROI

确认 Publish one tracked MultiROI per frame 已勾选,且 Publish frame limit 不小于你的帧数。无论是否发布,tracks.csv 都会照常写出。

10. 注意事项与已知限制

• 输入必须是已分割的 MultiROI,插件不做分割;它把每个非零标签当成一个对象。
• 帧顺序由你手动决定: 插件不从文件名或时间轴推断时间点,务必按时间顺序 Add Frame。
• 尚不支持分裂/合并谱系: 每个检测最多连接一个前驱,细胞分裂等一分为二的情形会被记为新 track。
• 基于质心/平移的追踪: 仅使用质心距离(可选体积惩罚),不使用外观特征;对旋转或形变剧烈的对象可能不适用。
• 首次 Setup 需要联网 下载 numpy/scipy;之后离线可用。
• 距离与体积基于 MultiROI 的物理 spacing;若各帧 spacing 不一致,请注意 Max link distance 的取值语义。
• 帧数极多时用 Publish frame limit 控制发布量,避免生成过量对象拖慢 Dragonfly。

11. 参考资料

• Fiji TrackMate(灵感来源,本插件不依赖它):https://imagej.net/plugins/trackmate/
• SciPy linear_sum_assignment(线性分配求解器):https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.linear_sum_assignment.html
• NumPy 官方文档:https://numpy.org/doc/
• Dragonfly MultiROI 与对象模型:参见 Dragonfly 自带帮助文档。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation and Enabling

4. Environment and First-Run Setup

5. User Interface

6. Step-by-Step Usage

7. Parameter Reference

8. Outputs

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

1. Overview

TrackMate-like Object Tracker is a Dragonfly-native, object-level tracker. It treats an ordered sequence of Dragonfly MultiROIs as detection results: each nonzero label in each frame (each MultiROI) is one object (detection). The plugin computes each object's centroid and volume, links objects across adjacent frames with a Linear Assignment Problem (LAP) solver into time-continuous tracks, and writes a tracks.csv table. It can also publish the result back into Dragonfly, one MultiROI per frame, with labels set to stable track IDs.

Its design is inspired by the well-known TrackMate workflow in Fiji (detect objects, link detections, inspect tracks, publish track IDs), but it does not depend on Fiji, ImageJ, or Java. Instead it runs a small Python environment directly inside Dragonfly.

Underlying engine and algorithm

• Detection: every nonzero label in a frame's MultiROI becomes one object; the plugin computes its centroid (voxel and physical coordinates), voxel volume, and bounding box.
• Linking: uses SciPy scipy.optimize.linear_sum_assignment over a cost matrix. Cost = physical centroid distance plus an optional volume-change penalty.
• Gap closing: allows an object to disappear for a few frames and still be linked, controlled by Max frame gap.
• Dependencies: numpy and scipy, installed from PyPI. The tracking core (trackmate_core.py) is decoupled from Dragonfly and runs and tests standalone.

Licensing notes

At runtime the plugin depends only on numpy and scipy, two widely used scientific libraries under permissive (BSD-style) licenses. It bundles no Fiji / ImageJ / Java, so there is no GPL entanglement. These two libraries are downloaded from PyPI into the plugin's own isolated environment on first use.

This is a pragmatic first version: it covers the most common MultiROI object-tracking need in Dragonfly but is not a full clone of Fiji TrackMate. The current version does not yet infer split/merge lineage - each detection is linked to at most one predecessor.

2. Use Cases

The plugin targets objects that are already segmented and now need to be tracked as they move across time or process steps. Its input is existing MultiROIs, not raw images, so it fits after a segmentation step as an analysis stage. Typical applications:

• Track particles across a series of time points or process steps.
• Track cells migrating in a time-lapse sequence.
• Track pores, defects, or other material objects evolving across stages of an in-situ experiment.
• Any ordered set of 2D or 3D labeled objects where the same physical object needs a stable ID across all frames.

Once tracking succeeds you can analyze object displacement, volume change, and track length by track ID in tracks.csv, or inspect the per-frame MultiROIs colored by track ID directly in Dragonfly.

3. Installation and Enabling

This plugin ships in the Prototype Apps Full Package. Install and enable it as follows:

1. Unzip the Full Package into a short folder (e.g. C:\PL\) to avoid the path-too-long error (0x80010135).

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, pick the core install mode (Fresh / Compatible) and tick TrackMate-like Object Tracker in the app list. Note: all plugins are OFF by default and must be ticked to be installed.

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

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

After the restart the plugin appears under Prototype Apps ▸ TrackMate-like Object Tracker... (in the "Measurements & Analysis" group). Clicking it opens a dockable PyQt panel titled "TrackMate-like Object Tracker" (floating by default, movable/dockable).

Changing the enabled state later

To enable or disable the plugin later, the easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager, tick/untick it in the "Prototype Apps (Full Package)" list at the bottom, then restart Dragonfly. Disabling never deletes the plugin's environment; re-enabling is instant.

Everything installs under the current user profile (%LOCALAPPDATA%); no admin rights are needed. Each enable/disable change requires one Dragonfly restart.

4. Environment and First-Run Setup

To avoid clashing with Dragonfly's own Python, the plugin builds an isolated virtual environment (venv) on first use and installs numpy and scipy into it. This is done with the Setup Environment (numpy + scipy) button on the panel's Setup tab.

What Setup Environment does

1. Creates a venv folder inside the installed plugin code directory (%LOCALAPPDATA%\comet\<Dragonfly version>\pythonUserExtensions\GenericMenuItems\TrackMateDragonfly\venv).

2. Upgrades pip inside that venv.

3. Installs numpy and scipy from PyPI (per requirements.txt).

4. Writes the new venv's python path back into the Analysis venv python field and saves it. Run Tracking then uses this python for the tracking computation.

Download size and internet

numpy and scipy are moderate in size (typically tens to a bit over a hundred MB, depending on platform and version). Internet is required for this step only, to download from PyPI; the tracking computation itself is fully offline.

No GPU / Fiji / WSL / external app

The tracking computation is a pure-CPU linear-assignment operation. It needs no GPU, and no Fiji, ImageJ, Java, or WSL, no external software, and no tokens. This is the main advantage over Fiji TrackMate.

Base Python and the fallback if setup fails

The Base Python field chooses which interpreter builds the venv. Left blank, the plugin auto-detects (Dragonfly's bundled or a system Python). If setup fails (e.g. the auto-detected interpreter lacks ensurepip or cannot create a venv), click Browse... to point at a working system CPython (3.10-3.12 recommended) and retry. The log area shows the failure reason.

The Job root field is the output root for tracking jobs, default C:\TrackMateDragonflyJobs. Each run creates a timestamped subfolder under it (e.g. trackmate_df_20260704_153000) holding the exported labels, tracks.csv, and intermediate files.

5. User Interface

The panel has a title bar at the top and, at the bottom, a green status label (current state) and a read-only log box. In the middle are four tabs: Setup / Frames / Tracking / Summary. Each control is described below.

5.1 Setup tab

A note at the bottom reminds you: no Fiji/ImageJ/Java is used; add MultiROI frames in temporal order before running.

5.2 Frames tab

This tab assembles the frame sequence - the set of MultiROIs to track, ordered in time.

Frame order is entirely determined by the order you add them. The plugin does not infer time points from file names or a Dragonfly time axis, so Add Frame in the correct order.

5.3 Tracking tab

This tab sets the linking parameters and output options, and launches tracking.

5.4 Summary tab

When tracking finishes, the plugin switches here automatically and shows a two-column table (Metric / Value): number of frames, total detections, number of tracks, and min/max/mean track length.

6. Step-by-Step Usage

This is the end-to-end flow from zero to tracking results. Prerequisite: you already have at least two MultiROIs in Dragonfly, each for one time point/step, with the same physical object segmented into labels in each frame.

1. Open Prototype Apps ▸ TrackMate-like Object Tracker....

2. First use: go to the Setup tab, click Setup Environment (numpy + scipy), and wait until the log shows "Environment ready." (If it fails, set Base Python per Chapter 4 and retry.)

3. Go to the Frames tab and click Refresh to list MultiROIs.

4. Select the first time point's MultiROI in the MultiROI dropdown and click Add Frame; then the second time point, Add Frame; and so on, adding all frames strictly in temporal order.

5. Check the frame sequence table: Frame should increment from 0; verify Title/Shape/Labels. Use Remove Selected / Clear to adjust.

6. Go to the Tracking tab and set Max link distance (most important: slightly larger than the object's largest real displacement between adjacent frames), then adjust Max frame gap, Volume penalty weight, and Min object volume as needed.

7. Set output options: Output MultiROI prefix, whether to Publish one tracked MultiROI per frame, and Publish frame limit.

8. Click Run Tracking. The log scrolls through progress (exporting frames, linking detections, writing outputs).

9. When done, the panel switches to Summary with statistics; the status bar shows the full path to tracks.csv. If publishing was enabled, per-frame track-ID MultiROIs appear in Dragonfly's object list.

At least two frames are required. If Setup was not run (Analysis venv python is empty), clicking Run Tracking prompts you to run Setup first.

7. Parameter Reference

The table below summarizes every tracking parameter and its meaning, as a tuning reference.

Distance and volume are computed from the MultiROI's physical spacing: centroids are multiplied by per-axis spacing to get physical coordinates before the Euclidean distance is taken. So Max link distance is in physical units, not voxel counts.

8. Outputs

A successful run produces the following:

8.1 The tracks.csv table

Written into the job folder (<Job root>\trackmate_df_<timestamp>\tracks.csv). Each row is one detection in one frame; columns include:

• frame, label, track_id - frame index, original label value, and the stable track ID that spans the whole sequence.
• centroid_z / centroid_y / centroid_x - centroid in voxel coordinates.
• physical_z / physical_y / physical_x - centroid in physical coordinates (already multiplied by spacing).
• volume_voxels - the object's voxel volume.
• bbox_z0..bbox_x1 - bounding-box start/stop indices.
• link_cost - the cost at which this detection was linked (0 for a newly started track).

8.2 Per-frame track-ID MultiROIs

If Publish one tracked MultiROI per frame is checked, the plugin publishes a new MultiROI for each frame (titles like Tracked objects t000, Tracked objects t001, ...) where each object's label value is its stable track ID. The same physical object then has a consistent label across all frames, making it easy to inspect its trajectory in Dragonfly with a single color scheme. The number published is capped by Publish frame limit.

8.3 Summary statistics

Metrics shown on the Summary tab: n_frames, n_detections, n_tracks, and min_track_length / max_track_length / mean_track_length.

8.4 Intermediate files

The job folder also keeps the exported per-frame labels frame_###_labels.npy, the per-frame track-ID label volumes track_labels_t###.npy, export.json, and run status/result files for review or downstream analysis.

How to view results: open tracks.csv (Excel or any spreadsheet tool) to analyze displacement, volume, and track length; in Dragonfly's object list, view the published per-frame MultiROIs and use a single color scheme to follow the same track across frames.

9. FAQ and Troubleshooting

Q1. Setup Environment fails, saying it cannot create the venv or pip is missing

The auto-detected base Python may lack ensurepip or be unsuitable for building a venv. Click Browse... next to Base Python and select a normal system CPython (3.10-3.12 recommended), then retry. Also confirm the machine can reach PyPI over the internet for this step.

Q2. Run Tracking says "Add at least two MultiROI frames first"

The frame sequence has fewer than two frames. Go back to the Frames tab and add at least two MultiROIs with Add Frame. If it says "Run Setup first," the Analysis venv python is empty - complete the environment setup on the Setup tab first.

Q3. Objects fail to link / one physical object is split into several tracks

Usually Max link distance is too small, smaller than the object's real displacement between adjacent frames. Increase it. If the object is missed in some frames, set Max frame gap to 1 or more to bridge the gap.

Q4. Nearby but distinct objects were wrongly linked together

Max link distance may be too large. Lower the threshold; if those objects differ noticeably in size, increase Volume penalty weight (e.g. 0.1-0.5) to use the volume difference as a separator.

Q5. My MultiROI does not appear in the dropdown

Click Refresh to rescan; confirm the object is really a MultiROI and present in the current session (not only on disk). If there are many segmentation fragments, use Min object volume to filter tiny labels.

Q6. No per-frame MultiROIs were created

Confirm Publish one tracked MultiROI per frame is checked and Publish frame limit is at least your number of frames. tracks.csv is written regardless of whether publishing is enabled.

10. Notes and Known Limitations

• Input must be already-segmented MultiROIs; the plugin does no segmentation - it treats each nonzero label as one object.
• Frame order is set by you: the plugin does not infer time points from file names or a time axis, so Add Frame in temporal order.
• Split/merge lineage is not yet supported: each detection is linked to at most one predecessor, so a cell division into two is recorded as a new track.
• Centroid/translation-based tracking: it uses centroid distance (with an optional volume penalty) only, not appearance features; it may not suit objects that rotate or deform strongly.
• First-run Setup needs internet to download numpy/scipy; afterwards it works offline.
• Distance and volume are based on the MultiROI's physical spacing; if frames have inconsistent spacing, be mindful of the units of Max link distance.
• With very many frames, use Publish frame limit to control how many are published and avoid overloading Dragonfly with objects.

11. References

• Fiji TrackMate (inspiration; this plugin does not depend on it): https://imagej.net/plugins/trackmate/
• SciPy linear_sum_assignment (the LAP solver): https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.linear_sum_assignment.html
• NumPy documentation: https://numpy.org/doc/
• Dragonfly MultiROI and object model: see Dragonfly's built-in Help documentation.