diff --git a/doc/images/cross.png b/doc/images/cross.png new file mode 100644 index 00000000..af90d341 Binary files /dev/null and b/doc/images/cross.png differ diff --git a/doc/images/decision.png b/doc/images/decision.png new file mode 100644 index 00000000..98e2f139 Binary files /dev/null and b/doc/images/decision.png differ diff --git a/doc/images/linking_prediction.png b/doc/images/linking_prediction.png index 72614c01..c4b1c278 100644 Binary files a/doc/images/linking_prediction.png and b/doc/images/linking_prediction.png differ diff --git a/doc/images/search.png b/doc/images/search.png new file mode 100644 index 00000000..ed75ed18 Binary files /dev/null and b/doc/images/search.png differ diff --git a/doc/linking.rst b/doc/linking.rst index 6c3e840e..0f88226d 100644 --- a/doc/linking.rst +++ b/doc/linking.rst @@ -1,12 +1,32 @@ Linking ------- -Currently implemented methods for linking detected features into cloud tracks: +Currently implemented options for linking detected features into tracks: **Trackpy:** This method uses the trackpy library (http://soft-matter.github.io/trackpy). -This approach only takes the point-like position of the feature, e.g. determined as the weighted mean, into account and does not use any other information about the identified features into account. The linking makes use of the information from the linked features in the previous timesteps to predict the position and then searches for matching features in a search range determined by the v_max parameter. +This approach only takes the point-like position of the feature, e.g. determined as the weighted mean, into account. Features to link with are looked for in a search radius defined by the parameters v_max or d_max. The position of the center of this search radius is determined by the method keyword. method="random" uses the position of the current feature (:math:`t_i`), while method="predict" makes use of the information from the linked feature in the previous timestep (:math:`t_{i-1}`) to predict the next position. For a simple case the search radii of the two methods look like this: .. image:: images/linking_prediction.png :width: 500 px +If there is only one feature in the search radius, the linking can happen immediately. If there are none, the track ends at this timestep. If there are more options, trackpy performs a decision process. Assume there are :math:`N` features in the current and also :math:`N` in the next timeframe and they are all within each search radius. This means there are :math:`N!` options for linking. Each of these options means that :math:`N` distances between the center of the search radius of a current feature and a feature from the next time frame :math:`\delta_n, n=1, 2, ..., N` are traveled by the features. Trackpy will calculate the sum of the squared distances + +.. math:: + + \sum_{n=1}^{N} \delta_n^2. + +For every option the lowest value of this sum is used for linking. As an example, consider these two crossing features: + + .. image:: images/cross.png + :width: 500 px + +If the search radius is chosen large enough, each will contain two options, a horizontal and a diagonal feature: + + .. image:: images/search.png + :width: 500 px + +The linking will look differently for both methods in the end. The horizontal features are closer to the current position than the diagonal ones. This is why these are linked by the "random"-method. On the other hand, the diagonal features lie excatly on the guessed positions for the "predict"-method. This means, that the sum of squared distances is 0 and they are the optimal decision for linking in this case: + + .. image:: images/decision.png + :width: 500 px