Skip to content, Skip to search

Changes

Low Light Tracking Tool

56 bytes added, 12:23, 8 October 2015
Replace User links with Person template
{{Infobox Plugin
| name = Blob Tracking
| software = Fiji
| author = [[User:{{Person|Alex-krull | Alexander Krull]]}}, [[User:damienrj {{Person| Damien Ramunno-Johnson]]Damienrj}}| maintainer = [[User:{{Person|Alex-krull|Alexander Krull]]}}, [[User:damienrj {{Person| Damien Ramunno-Johnson]]Damienrj}}
| source = https://github.com/alex-krull/fiji
| released = May 22<sup>nd</sup>, 2013
This software is a tool for the tracking of low-light sub-resolution objects in fluorescent microscopy. It can be applied in other fields as well. The plugin implements the localization algorithm described in the following paper:
"A Divide and Conquer Strategy for the Maximum Likelihood localization of Low Intensity Objects" By by Alexander Krull et al, 2013 Optics Express, Vol. 22, Issue 1, pp. 210-228 (under preparation2014).
=Installation Of The Pluginof the plugin=
The plugin can be quickly installed via the projects update site. This is unfortunately may not possible if you are using a Fiji version installed via package management system. If you encounter this problem, please use the Fiji version obtainable [[Downloads | here]].
==Add the project's update site to your Fiji installation==
=The User Interface=
==The different windows==
When the plugin starts on a 2D image stack you have three windows and the control panel. The main data window lets you move through the slices like normal. On the sides you see the two kymographs, which make is makes it easier to see movement over time.
The control window will help you to organize your tracking activity.
[[Image:Controlwindownew.png]]
If you would like the windows to become larger or smaller, change the size of the main data window and then select '''Arrange Windows''', from the '''View''' menu. Alternatively you can use the [[Low_Light_Tracking_Tool#Hot-Keys | hot-key]] '''{{key|Ctrl-}}+{{key|W''' }} (when the focus is on the control panel) or '''{{key|W''' }} (when the focus is on one of the other windows). This will also organize the windows if they have become scattered.
If you close some of the windows you can bring them back using the '''Windows''' menu in the control panel.
* You can use ImageJ/Fiji slider controls below the main window.
* You can set frame number, slice number and channel number in the control window.
* You can use your middle mouse button to click directly click into one of the kymographs to set the frame number. If you are working with 3D data you can click into one of the side projections with your middle mouse button to set the slice number.
=Basic Trackingtracking===Create Sessionsession==
[[Image:LLTT ChooseSession.jpg]]
Click on the '''New Session ''' button, or select from the menu. The '''New session ''' window opens. Here you can pick a name for the session as well as the channel you want to track on. Finally you can choose your tracking method.
==Choose a tracking method==
There are currently two tracking algorithms available:
===GaussianML===
This algorithm implements the [http[wikipedia://en.wikipedia.org/wiki/Maximum_likelihood_estimator Maximum likelihood estimator|maximum likelihood estimator]] based on a [http[wikipedia://en.wikipedia.org/wiki/Shot_noise Shot noise|shot noise]] model. This means it considers the statistics of photon distribution in the image generation process to find the optimal location estimate. In our publication this is referred to as the inner loop.
===EMCCD-GaussianML===
This algorithm implements the maximum likelihood estimator based on a more sophisticated model which in addition includes the stochastic amplification process in an [http[wikipedia://en.wikipedia.org/wiki/Electron-multiplying_CCD multiplying CCD|EMCCD]] camera. We have shown, that it yields more accurate results in situations with low light levels. In our publication this algorithm is referred to as the '''Nested Maximum Likelihood Algorithm'''.
==Pick session options==
[[Image:SessionOptions.png]]
After clicking '''OkOK''', a new window will open. In this window you can choose a '''σ''' value, which denotes the standard deviation (in pixels) of the Gaussian used to approximate the [http[wikipedia://en.wikipedia.org/wiki/Point_spread_function Point spread function|Point Spread Function]] (PSF) of the tracked objects. If you select '''Automatic σ''', this value is used only as initialization. In this case '''Min''' and '''Max''' are used as bounds for the estimation. These values will be the default values for all new traces you make in this session.
You also can set your quality threshold. Smaller numbers are higher quality, while larger numbers are lower quality but faster.
Fixed '''σ ''' can be more stable and also faster, this is more so for 3D data.
All settings can later be altered by clicking on '''Session Options''', under '''Edit'''.
==Adding objects to track==
To add an object in order to track it, make sure the cross hair icon in the Fiji toolbar is selected and then double click roughly on the object you would like to track in the main window. This new object is represented as a circle. An accordant entry will appear in the table in the control panel representing the objects trace. You can select objects by clicking on them in the control panel or directly in the main window. You can then move them around, using drag and drop or edit them. Multiple Objects objects can be selected by holding '''{{key|Shift''' }} when selecting.
[[Image:CreateDots.png]]
You can change a trace's label by clicking on the text in the label field, or change the color by clicking on the colored area.
==Edit individual objects==
The default settings made in the session options dialog will only effect only new traces. If at this point you find that the parameters you picked were less ideal you can change the parameters with the '''Edit Object''' selection from the '''Edit''' menu.
[[Image:ObjectOption.png]]
The settings you make here will effect the selected object in the very frame you are looking at.
==Start Trackingtracking==
Only the highlighted objects will be tracked. So in the example above both are highlighted and will be tracked at the same time.
Objects which are far away from each other should be tracked in individually one after the other.
=Working With Tracking Resultswith tracking results=
[[Image:Result1.png]]
The table now contains more information, with the first frame of the trace, and the last frame. Double clicking on the ID# of the object will jump the frame number to the beginning and end of the trace.
==Saving and Loadingloading==
The tracking results are already saved automatically by default. You can turn that off by un-checking the '''Auto Save''' box. The results can than be saved using the '''Save''' button.
They are by default stored in the directory of the image stack you are working on.
==Deleting and manipulating traces and sessions==
Using the '''Merge''', '''Split''', '''Trim''', and '''Delete''' buttons allows you to edit your traces by combining or deleting them. Sessions can be deleted using the ''''Delete sessionSession'''' button.
;Merging
Changes done by '''Merge''', '''Split''' and '''Trim''' can also be undone in this way. They are made permanent only when you hit the '''Save''' button or start tracking with the '''Autosave''' option activated.
=Advanced Featuresfeatures=
==3D Datadata==The plugin can be used to track objects in 3D volumes, as well. When working with 3D data you will be asked upon startup to provide the '''ΔZ ratio''' in addition to the '''Intensity Offset''', '''EMCCD gain'''and '''Electrons per A/D count'''.
The '''ΔZ ratio''', is the slice thickness, divided by the pixel width. This value is only used for 3D data.Example: My pixel size for my data is 100 nm, and my slice thickness is 200 nm. I would then enter a value of 2.
[[Image:NewWindows.jpg]]
3D data is very similar to 2D data, there are just a few more windows that open when you start. The data window, and the kymographs appears, but a second set of windows appear. A max Z projection window, and max Y and X projects. The side projections are useful to place your starting tracking in the correct slice. So before clicking on the object in the data window, change the z to the correct plane first.
Otherwise, tracking function is the same. It is best to optimize the σvalue σ-value for 3D tracking, and then use a fixed value to increase speed.
[[Image:NewWithDot.jpg]]
==Using multiscale tracking for fast moving objects==
If you are tying trying to track fast moving objects that move over a big distance between two frames, the software might loose the target at some point. To avoid this you can use multiscale tracking, which uses iterative smoothing and down-sampling to find the target in each frame. To start tracking in multiscale mode hit the '''Multiscale'''.
You can change the default behavior in the edit menu.
[[Image:MScaleOptions.png]]
The algorithm builds a [http[wikipedia://en.wikipedia.org/wiki/Pyramid_Pyramid %28image_processing28image processing%29 |pyramid]] by repetitively smothing the image with a Gaussian kernel with the standard deviation given in the '''Smoothing σ''' field and than down-sampling it by a factor set in the '''Downscaling''' field. The pyramid's hight (i.e. the number of repetitions) can be set in the '''iterations''' field.Localization is than first performed on the top level of the pyramid, and repeated until its bottom, which is the original image.
=Tips=
* If you want to be able to see the original image data and find your tracking results get in the way, you use the hot-key '''{{key|P''' }} or '''{{key|Ctrl-}}+{{key|P''' }} respectively to hide all overlays (all circles lines and cross-hairs drawn on top of the image).
* If some of the windows appear to bright or to dark use '''View->Adjust Brightness/Contrast''' to correct them.
* You can use '''File->Export images''' to export a sequence of image with the tracking results drawn on top of them. You can use this to create a movie in order to demonstrate your tracking results. In your working directory a new folder named '''movieMain''' will be created and filled with images.
* If you have multichannel data, each channel needs its own session. You can select which sessions are visible by checking their boxes in the '''Visible Sessions ''' list. You can use the current session drop down menu to switch between sessions.* You can zoom into the kymographs by moving the cursor over the kymograph window and holding down '''{{key|Shift'''}}, while using the scroll wheel on the mouse.
* You can use the '''optimize''' button. This will perform the tracking of the selected objects on the single frame you are looking at. You can use this for example with '''Automatic σ''' turned on to determine the size of the target's PSF on a single frame.
=Hot-Keyskeys=There are several hot-keys you can use. You can find the key to press in the menus of the control panel. When the focus is on the control panel you have to press '''{{key|Ctrl''' }} to access hot-keyshotkeys. When the focus is on one of the other windows this is not necessary.
=File Formatformat=
The tracking results are stored in text files with the ending '.trcT'. Each file holds the result of one trace. The structure of the file name is the following:
'''<name of image file>_<name of session>_<label of trace>_<id of trace>.trcT'''
The files are created in the working directory. Each file begins with some lines starting with '#'. These lines store information for the tracking program they will be ignored by most programs like matlab [[MATLAB]] or gnuplot potentially used to further analyze the data.
This meta information is followed by columns of data holding the actual tracking results.
The columns have the following meaning:
* column 15 the fraction of flux in the considered window assumed to belong to the tracked object
* column 16 the total estimated flux in the considered window
 
= Example Data =
This link contains the data used to generate this tutorial, and a two channel 3D data set to try.
[[Media:Example_Data.zip‎]]
= License =
Packages hep.aida.*
Written by Pavel Binko, Dino Ferrero Merlino, Wolfgang Hoschek, Tony Johnson, Andreas Pfeiffer, and others. Check the FreeHEP home page homepage for more info. Permission to use and/or redistribute this work is granted under the terms of the LGPL License, with the exception that any usage related to military applications is expressly forbidden. The software and documentation made available under the terms of this license are provided with no warranty.
Bureaucrat, emailconfirmed, incoming, administrator, uploaders
12,213
edits