One click tracing - UU-cellbiology/BigTrace GitHub Wiki

BigTrace has a one-click tracing mode that tries to find a curve based on one initial point.
In this mode, selecting a point on the canvas with the F shortcut initiates a tracing process first in one direction, and then the other:

Until the tracing is finished, the ROI manager is locked, but dataset navigation and zoom in/out shortcuts (D and C) are still available. The 'one-click' tracing button icon changes to the stop icon, and the button can be clicked to interrupt the tracing process. A small box is displayed around the active end to highlight the process.

As a result, it adds a new LineTrace3D ROI, that can be further edited/refined using Semi-auto-tracing mode.
Alternatively, when the ROI is selected, using shortcut R, it is possible to add straight segments at the end of the curve (no tracing is performed). Or delete end segments using shortcut G.

If LineTrace3D ROI is edited and selected, at any moment one can continue tracing from one end using the same shortcut F.

Settings

To show the parameters dialog, double-click on the icon.

The first tab shows common General tracing parameters. The second is specific to the one-click tracing mode.

Constrain directionality (0-1) instructs the auto-trace algorithm on how "straight" you expect the curve to be. Higher values correspond to the more straight curves, while lower values allow more bent, flexible curves.
Decrease it if the trace ends earlier than you expect, and increase it if it is too long.
In more detail, it is a minimum of a cosine of the angle between the curve's calculated direction in two neighboring voxels.

Use intensity threshold adds an extra constraint to stop the tracing, i.e., it cannot pass through voxels below the Minimum intensity value, specified by a user. This option can be helpful in case of "overtracing".

Ref points placement (px, >=3) How often intermediate points (vertices) will be placed in LineTrace3D during auto-tracing. Smaller values make tracing a bit slower, but they make further ROI editing easier.

Avoid (mask) existing ROIs option will stop the current one-click tracing, if it enters the volume of already existing ROIs. This option can be slow and memory-consuming (depending on your dataset size), it is still work in progress.

How does it work?

For a detailed "academic style" description (+ concepts introduction), please follow Chapter 4.3
of Carsten Steger dissertation "Unbiased Extraction of Curvilinear Structures from 2D and 3D Images".

The implemented algorithm was simplified and optimized compared to the original.
Here is a brief conceptual description.

After a click, a voxel with maximum intensity is located along the 3D click ray line.
This is the first point of the trace (with some modification, see below).

Then, in a small box around it (6*SD(xyz) defined by tracing),
the saliency and vector direction maps are calculated.

What are these? First, for each voxel of the box, we calculate Hessian matrix of second derivatives.
We do this by convolving volumetric data with the second derivative of the Gaussian in each dimension,
where Gaussian SD's are specified by General tracing parameters.

Then, for each voxel/matrix we calculate eigenvalues and eigenvectors, 3 for each dimension.
After that, we inspect eigenvalues. We will use them to fill the saliency map.

If the two largest (by absolute value) eigenvalues are negative,
the voxel's saliency becomes equal to their absolute sum.
In all other cases, the saliency map becomes zero.

Why is it so? Because eigenvalues characterize intensity change
in the vicinity of the voxel. Negative eigenvalue
means that intensity is "concave down" in the direction of the corresponding eigenvector.
So if one were to sit in the middle of the volumetric curve and inspect
how intensity changes in different directions, then the smallest change
would happen along the curve (the curve's tangent vector).
The largest changes will happen in the normal plane,
i.e. when you "step out of the curve", intensity drops.

This is reflected in the eigenvalues and corresponding eigenvectors.
Eigenvectors form an orthogonal basis (by definition),
and in the case of the curve point, the two largest eigenvalues (largest intensity drop)
correspond to the vectors forming a normal plane (perpendicular to the curve at that point).
While the eigenvector corresponding to the smallest eigenvalue will give us
tangent vector (the direction along the curve) at the point.
So this tangent vector is stored in the vector map (if saliency is non-zero),
it gives us a possible local curve direction.

Now that we have a saliency map (with zeros marking "non-curve" space)
and vector map, we inspect the direction of this tangent vector at the initial point (voxel).
In principle, a tangent vector and its negative value (reverse)
both lie along the curve. We start with any of them.
We want to find the next curve's voxel among all 26 neighbors of the current voxel.
For that, we inspect only neighbors that are "aligned" with the tangent vector.
All possible combinations of vector and neighbor inspection can be generalized into three cases
and are illustrated in this diagram:

The tangent vector is in orange, and all the neighbor voxels being inspected are shown in green.

The plugin cycles through the "neighbors" candidates and looks for the voxel with maximum saliency.

• If the absolute dot product between the inspected neighbor tangent vector
  and the initial one is less than Constrain directionality value,
  this candidate neighbor is skipped (saliency = 0).
  I.e., the cosine of the angle between vectors is too small, the vectors are not aligned enough.
• If Use intensity threshold is activated and the voxel's intensity
  is below Minimum intensity, the neighbor is skipped.
• If Avoid (mask) existing ROIs is on (always the case in Full auto tracing mode)
  and the voxel is marked as already traced in the mask, the neighbor is skipped.

If in the end the plugin finds a candidate neighbor with saliency above zero,
it is added to the curve as the next voxel, and the process is repeated.

If the final maximum saliency is equal to zero, the tracing stops.

The plugin returns to the very starting point and resumes another tracing
with the negative tangent vector (i.e., in the opposite curve direction).

Some technical details: after finding the initial maximum intensity voxel
along the mouse click 3D line, the box with saliency is calculated around it
and the voxel with maximum saliency (no matter the vector) is selected
as the true starting point of the curve. The "map box" is calculated again
around this voxel.

The calculation of maps is computationally heavy, so the box "slides along"
the tracing curve. The box dimensions, as mentioned above, are 6SD(xyz),
so if the tracing goes outside of the "internal box" of 4SD(xyz),
the new map box centered around the current curve voxel is calculated, and so on.