4D Drift Correction（4D 漂移校正）
4D Drift Correction - User Manual
Dragonfly Prototype Apps · Correct 4D Drift (Time-lapse)...
版本 Version 1.0 · 2026-07-31
第一部分 中文手册
目录
1. 简介
2. 参考帧:第一帧还是前一帧
3. 精度:亚体素与两个已量化的默认值
4. 位移方式:插值还是整体素
5. 通道对齐(第 2 页)
6. 操作步骤与建议
7. 环境需求与限制
1. 简介
4D Drift Correction 去除时间序列 3D 图像在采集过程中累积的漂移 —— 载物台爬移、热胀冷缩、样品沉降。做法是：把每个时间点压成强度投影,用相位相关测出它相对参考帧的位移,再把体数据按相反方向移回去。
沿 z 投影 → 得到横向 (x, y) 漂移;沿 y（或 x）投影 → 得到轴向 (z) 漂移。两次投影各自只取自己最擅长的分量。
本插件实现 Fast4DReg 的方法（Pylvänäinen 等,J Cell Sci 2023,https://github.com/CellMigrationLab/Fast4DReg）。代码是独立实现,不是移植:该仓库同时附带 NanoJ-Core（GPL-3.0）,其漂移估计在历史上源自 NanoJ,而 GPL-3.0 与本插件的分发方式不兼容。相位相关本身是教科书方法。方法学请引用 Fast4DReg 论文。
2. 参考帧:第一帧还是前一帧
第一帧（默认）:每一帧都直接与第 0 帧比较。不累积误差,但当样品已经漂离起始位置很远、与第 0 帧几乎不重叠时会失效。
前一帧:比较相邻两帧,再把逐帧位移累加成总位移。能跟踪很大的总漂移,代价是每一帧的小误差会被累加进去。
选择原则:总漂移小于视野的十分之一 → 用第一帧;样品明显走出原位置 → 用前一帧。
3. 精度:亚体素与两个已量化的默认值
亚体素精化默认为 10,即精确到十分之一体素。注意：Fast4DReg 本身在估计和应用两端也是亚像素的，亚体素精度并不是本插件相对它的优势；本插件的优势是跑在 Dragonfly 内部、直接处理已发布的 Channel。设为 1 则只估计整体素。
轴向投影默认用「最大值」而不是「平均值」,这是量出来的结论:样品沿 z 漂移时,结构会从顶部或底部移出体积,这会改变平均值投影的幅度,把相位相关偏低 —— 真值 1.0 / 2.0 / 4.8 体素的漂移被估成 0.2 / 2.3 / 4.6;而最大值投影在同一份数据上恢复出 1.00 / 2.00 / 4.80。若改用完全不丢数据的环绕位移,两种投影都精确,这也正是把偏差定位到「内容移出体积」而非估计器本身的依据。
轴向估计只对横向轴加窗:沿短短的 z 轴加 Hann 窗即使在完全不丢数据时也会损失精度。
平滑默认关闭。漂移在物理上是平滑的,所以平滑能压制估计噪声;但它同样会抹掉真实的快速运动 —— 对快速采集而言那是在悄悄破坏数据,因此必须由你显式开启。
4. 位移方式:插值还是整体素
默认用样条插值（线性/三次）做亚体素位移,残留漂移最小,但插值会让数据略微模糊,并且会产生原图中不存在的中间灰度值。
勾选「仅整体素位移」则把位移四舍五入到整数并用整体素搬移:每个数值完整保留（对后续定量分析或分割更安全）,代价是残留最多半个体素的漂移。做强度定量时通常首选这一项。
两种方式都会在边缘留下填 0 的空白 —— 这不可避免,原始数据在那里本来就没有内容。
5. 通道对齐(第 2 页)
测量两个通道之间的固定偏移(色差、双相机未对准),可以用标定片测,也可以直接用数据本身测。给出 dz/dy/dx（体素与世界单位）,并可一键把该偏移应用到该通道的每个时间点并发布对齐后的通道。
做任何共定位分析之前都应该先做这一步:哪怕只错开一个体素,也足以让共定位结果失真。
6. 操作步骤与建议
1. 先把时间序列发布到会话里（插件只列出已发布对象,并标注每个通道有多少个时间点）。
2. 建议第一次先不发布:取消勾选「发布校正后的通道」,只估计。到第 3 页看漂移表和曲线,确认量级合理（例如总漂移不应该超过视野尺寸）。
3. 若曲线在个别帧出现孤立跳变,通常是那几帧信噪比过低。把「投影」改成最大值,或适度开启平滑。
4. 确认无误后勾选发布,再跑一次。校正后的 4D 通道会作为新对象发布,整数数据仍保持整数,不会变成 float 而让体积翻倍。
5. 第 3 页可导出漂移表（体素 + 世界单位,原始值与实际应用值都在,便于日后核对到底应用了什么）和曲线图。
7. 环境需求与限制
无需 GPU、无需联网、无需管理员权限,也不需要安装环境:全部在 Dragonfly 内部用自带的 numpy/scipy/scikit-image 运行。
限制:输入必须是带时间轴的已发布 Channel（至少 2 个时间点)；插件逐时间点读取,峰值内存约为两份体积;只校正整体平移,不校正旋转、缩放或形变（那属于非刚性配准,见 Slice Registration 插件)。
Part II English Manual
Contents
1. Introduction
2. Reference: first frame or previous frame
3. Accuracy: sub-voxel, and two measured defaults
4. Shifting: interpolated or whole-voxel
5. Channel alignment (tab 2)
6. How to use it
7. Requirements and limits
1. Introduction
4D Drift Correction removes drift that accumulated while a time-lapse 3D image was acquired - stage creep, thermal expansion, specimen settling. Each time point is reduced to intensity projections, its shift relative to a reference frame is measured by phase correlation, and the volume is shifted back.
A projection along z gives the lateral (x, y) drift; a projection along y (or x) gives the axial (z) drift. Each projection contributes only the component it measures best.
This implements the METHOD of Fast4DReg (Pylvänäinen et al., J Cell Sci 2023, https://github.com/CellMigrationLab/Fast4DReg). The code is an independent implementation, not a port: that repository also ships NanoJ-Core (GPL-3.0) and its drift estimation historically derived from NanoJ, which is incompatible with how this plugin is distributed. Phase correlation itself is a textbook technique. Please cite Fast4DReg for the method.
2. Reference: first frame or previous frame
First time point (default): every frame is compared with frame 0. No error accumulation, but it fails once the specimen has drifted so far that it barely overlaps frame 0.
Previous time point: consecutive frames are compared and the per-step shifts are summed cumulatively. This tracks very large total drift, at the cost of accumulating each frame's small error.
Rule of thumb: total drift under a tenth of the field of view - use the first frame; the specimen visibly leaves its starting position - use the previous frame.
3. Accuracy: sub-voxel, and two measured defaults
Sub-voxel refinement defaults to 10, i.e. a tenth of a voxel - note that Fast4DReg is itself sub-pixel in BOTH estimation and application, so sub-voxel accuracy is NOT an advantage of this plugin over it; the advantage is running in-process inside Dragonfly on published Channels. Set it to 1 for whole-voxel estimates.
The axial projection uses MAXIMUM, not average, and that is a measured result: as the specimen drifts along z, structure leaves the volume through the top or bottom slice, which changes an average projection's amplitude and biases phase correlation low - a true 1.0 / 2.0 / 4.8-voxel drift came back as 0.2 / 2.3 / 4.6, while a maximum projection recovered 1.00 / 2.00 / 4.80 on the same data. With a pure wrap-around shift, where no data is lost, both are exact - which is how the bias was traced to content leaving the volume rather than to the estimator.
The axial estimate windows only the lateral axis: a Hann window along the short z axis costs accuracy even when no data is lost at all.
Smoothing is off by default. Drift is physically smooth, so smoothing suppresses estimation noise - but it equally removes genuine fast motion, which on a fast acquisition means silently degrading the data. You have to switch it on deliberately.
4. Shifting: interpolated or whole-voxel
By default a spline (linear or cubic) performs the sub-voxel shift, leaving the least residual drift - but interpolation slightly blurs the data and invents intermediate grey values that were not in the original.
Ticking whole-voxel shifts only rounds the drift to integers and moves whole voxels: every value is preserved exactly (safer for downstream quantification or segmentation), at the cost of up to half a voxel of residual drift. Prefer this for intensity quantification.
Either way, zero-filled margins appear at the edges - unavoidable, because the original data has no content there.
5. Channel alignment (tab 2)
Measures the constant offset between two channels (chromatic aberration, two-camera misalignment), from a calibration slide or from the data itself. It reports dz/dy/dx in voxels and world units, and can apply that offset to every time step of the channel and publish the aligned result.
Do this before any colocalisation analysis: even a single voxel of offset is enough to distort the result.
6. How to use it
1. Publish the time-lapse into the session (the plugin lists published objects only, and labels how many time steps each channel has).
2. Estimate without publishing first: untick "Publish the corrected channel". Look at the drift table and plot on tab 3 and confirm the magnitude is plausible (total drift should not exceed the field of view).
3. Isolated jumps in the curve usually mean those frames had poor signal. Switch the projection to maximum, or enable modest smoothing.
4. When it looks right, tick publish and run again. The corrected 4D channel is published as a new object, and an integer source stays integer instead of becoming float and doubling in size.
5. Tab 3 exports the drift table (voxels + world units, with both the raw and the as-applied drift, so it is always possible to check afterwards what was actually applied) and the plot.
7. Requirements and limits
No GPU, no internet, no admin rights and nothing to install: everything runs inside Dragonfly on the bundled numpy/scipy/scikit-image.
Limits: the input must be a published Channel with a time axis (at least 2 time steps); time points are read one at a time, so peak memory is roughly two copies of the volume; only rigid translation is corrected - not rotation, scaling or deformation (that is non-rigid registration; see the Slice Registration plugin).