Skip to content

configuring laplinker

Jump to bottom
Jian Tay edited this page Jun 15, 2021 · 4 revisions

Configuring LAPLinker

This document lists the different configuration parameters for the LAPLinker class. The parameters are implemented as properties of a LAPLinker object.

Property values can be changed using dot notation.

Example:

L = LAPLinker;

%Change the linking cost to use the number of overlapping pixels
L.LinkCostMetric = 'pxintersect';

[[TOC]]

Solver

Solver specifies the algorithm used to solve the linear assignment problem.

Valid options are:

Notes:

  • lapjv uses the MATLAB implementation shared by Yi Cao on the MathWorks File Exchange.
  • munkres was developed in-house using the outline described by Bob Pilgrim at Murray State University.
  • In internal testing, we found that lapjv performs about 10x faster than munkres.

LinkedBy

LinkedBy specifies the fieldname of the input struct that contains data to be used when computing the linking costs. You can use any value for LinkedBy as long as the field exists in the input struct.

For example, to track objects by their centroid positions:

L = LAPLinker;
L.LinkedBy = 'Centroid';

for iT = 1:numFrames
    %Read in image and process to get a mask
    
    %Use regionprops to get the centroid of each object. The function 
    %outputs a struct with a field 'Centroid'.
    data = regionprops(mask, 'Centroid');

    L = assignToTrack(L, iT, data);
end

Another common use case is to use the pixel locations in the mask to determined linked objects. This is best used for objects which do not move much from frame to frame (e.g. non-motile bacteria - see example).

L = LAPLinker;
L.LinkedBy = 'PixelIdxList';

for iT = 1:numFrames
    %Read in image and process to get a mask
    
    %Use regionprops to get the location of each pixel in the 
    %mask for each object.
    data = regionprops(mask, 'PixelIdxList');

    L = assignToTrack(L, iT, data);
end

LinkCostMetric

LinkCostMetric specifies the method to compute the cost matrix. Currently, there are two built-in methods:

  • 'euclidean' - Compute straight-line (Euclidean) distance.

    This option is most suitable for coordinates and is used for nearest-neighbor tracking.

  • 'pxintersect' - Compute the ratio of intersecting pixels

    This option requires a list of pixel locations for each object (e.g. PixelIdxList from regionprops).

You can also define your own function for computing the linking cost.

  • The function must have the following signature: function(previousData, newData) where previousData is a struct array containing data from the previous frame and newData is a struct array containing data from the current frame.
  • The output must be an MxN matrix where M is the number of objects in the previous frame (i.e. M = numel(previousData) and N is the number of objects in the current frame (i.e. N = numel(newData)).
  • The function file should be on the MATLAB search path.

LinkScoreRange

LinkScoreRange is a 1x2 vector specifying the [min, max] values of acceptable scores for linking two objects. In other words, objects whose linking scores are below min or above max should never be linked with each other.

If using the built-in methods, appropriate values depend on the LinkCostMetric defined:

  • For euclidean, LinkCostMetric is the acceptable range of distances in pixels.
  • For pxintersect, LinkCostMetric is the acceptable range of ratio of overlapping pixels.

MaxTrackAge

MaxTrackAge is a number specifying how many frames an object is allowed to go untracked before tracking stops. This parameter is useful if the movie contains objects that drift in and out of the field of view or if objects can travel behind or in front of other objects.

TrackDivision

TrackDivision is a logical value (i.e. true or false) that specifies if division events should be identified.

The code tests for division events when an object is not linked to an object in a previous frame (i.e. a new track should be created). Division events are identified using a similar metric to linking cells.

DivisionParameter

DivisionParameter specifies the fieldname in the input data structure to be used to determine if a division event has occured (similar to LinkedBy).

DivisionScoreMetric

DivisionScoreMetric specifies the type of method to use to compute division likelihood scores (similar to LinkCostMetric)

DivisionScoreRange

DivisionScoreRange specifies the range of acceptable scores when deciding if a division event has occured. This is similar to LinkScoreRange.

MinFramesBetweenDiv

MinFramesBetweenDiv is a number that specifies the minimum number of frames between division events. An example use case for this parameter is in tracking crowded movies where objects are close together. In this case, the tracker might erroneously detect many division events since objects are too close to each other.

If you are seeing many false division events, you can try increasing this value to see if it helps.

< Back to User Guide

Clone this wiki locally