Commit 3c30bf9f authored by gonciarz's avatar gonciarz
Browse files

First increment of documentation

parent 67776825
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd
================
Changelog
================
* 1.0.19
- Discrete region sampling (DRS) is finally available in official release
* 1.0.18
- not supported anymore package ``javaml`` is not used in MosaicSuite anymore
* 1.0.17
- Results table in Region Competition is shown only in GUI or Macro mode (hidden in batch mode)
- Not mavenized external jars are now embedded in MosaicSuite repository
.. important::
For information about previous developments not listed here please refere to `old MosaicSuite site <http://mosaic.mpi-cbg.de/?q=downloads/imageJ>`_.
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'MosaicSuite'
copyright = '2020, MOSAIC Group, Sbalzarini Lab, mosaic.mpi-cbg.de'
author = 'MOSAIC Group, Sbalzarini Lab'
# The full version, including alpha/beta/rc tags
release = '1.0.19'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['recommonmark',
'sphinx_rtd_theme']
source_suffix = ['.rst', '.md']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
#html_theme = 'alabaster'
html_theme = "sphinx_rtd_theme"
html_theme_options = {
'navigation_depth': 6
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
#
# from sphinx.builders.latex import LaTeXBuilder
# LaTeXBuilder.supported_image_types = [
# 'image/svg+xml',
# 'image/tif',
# 'image/png',
# 'image/jpeg'
# ]
from sphinx.builders.html import StandaloneHTMLBuilder
StandaloneHTMLBuilder. supported_image_types = [
'image/svg+xml',
'image/gif',
'image/png',
'image/jpeg'
]
.. _mosaicsuite-development:
=======================
MosaicSuite development
=======================
Source code
===========
MosaicSuite code can be found on public `MOSAIC git server <https://git.mpi-cbg.de/mosaic/MosaicSuite/tree/master>`__.
Code can be downloaded by following git command:
.. code:: bash
git clone https://git.mpi-cbg.de/mosaic/MosaicSuite.git
If you'd like to contribute bug fixes or new functions to any of the plugins, or are interested in using the source code in your own projects, please make sure to first download the latest version. The code is constantly evolving. If you think your additions could be useful also for other users, please send them to us and we will include them in future releases. Your contributions are highly appreciated!
.. MosaicSuite documentation master file
MosaicSuite documentation
=========================
.. note ::
| This documentation is under development. Some parts might be not valid or incomplete.
| In a mean time please refere to `old MosaicSuite documentation <http://mosaic.mpi-cbg.de/MosaicToolboxSuite/MosaicToolsuiteTutorials.html>`__.
**MosaicSuite** is a plugin for popular image processing software *ImageJ2* and *Fiji*.
It provides image-processing algorithms developed at the `MOSAIC group <https://mosaic.mpi-cbg.de>`_.
The first plugin which is now part of MosaicSuite was a popular 2D/3D single-particle tracking tool which can be used to track bright spots in 2D/3D movies over time. As more plugins have been added, we decided to provide them in a single, coherent package, which will also group them under a common menu point ``Plugins->Mosaic`` in ImageJ2 and Fiji.
.. toctree::
:maxdepth: 6
:numbered:
:hidden:
:name: indextoc
:includehidden:
install
news
plugins
development
changelog
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
========================
Installation
========================
Required software
=================
MosaicSuite requires ImageJ2 or Fiji and Java 8 or greater to work.
- How to install Java?
Please download it and install from `official Java site <https://www.oracle.com/java/technologies/>`__.
- How to install Fiji/ImageJ2?
You can download it from `official Fiji site <http://fiji.sc/>`__.
Installation of MosaicSuite plugin
==================================
1. Open Fiji or ImageJ2
#. Run ``Help > Update Fiji`` command (or in case ImageJ2 ``Help > Update...``)
#. Click on ``Manage update sites``
#. Find there and mark ``MOSAIC ToolSuite``
#. Apply changes and Fiji should automatically download latest release of MosaicSuite
#. Restart Fiji (as required) and after restart all functionality by MosaicSuite can be found in ``Plugins > Mosaic`` menu.
.. important::
If you are using very old Java 6 or because any reason you need to install MosaicSuite manually
please refere for detailed instructions `old MosaicSuite site <http://mosaic.mpi-cbg.de/?q=downloads/imageJ>`_.
====
News
====
* **Discrete Region Sampling (DRS)**
Discrete Region Sampling is a sampling version of well known Region Competition algorithm.
It can be found in menu ``Segmentation > Discrete Region Sampling``.
.. admonition:: Citation
| *J. Cardinale*
| Unsupervised Segmentation and Shape Posterior Estimation under Bayesian Image Models. PhD thesis, Diss. ETH No. 21026, MOSAIC Group, ETH Zurich, 2013.
| `PDF <https://mosaic.mpi-cbg.de/docs/Cardinale2013.pdf>`__
*In order to ensure financial support for our project and allow further development of
this software, please cite above publications in all your documents and manuscripts that
made use of this software. Thanks a lot!*
* **Automatic optimal filament segmentation**
The plugin can be used for a globally optimal filament segmentation of 2D images with
previously unknown number of filaments. You can find plugin for segmentation in the menu
``Segmentation > Filament``. Presented solution can produce sub-pixel accuracy results
and handle different types of image data from different microscopy modalities.
The algorithm implemented in this plug-in is described in:
.. admonition:: Citation
| *X. Xiao, V. F. Geyer, H. Bowne-Anderson, J. Howard, and I. F. Sbalzarini.*
| Automatic optimal filament segmentation with sub-pixel accuracy using generalized linear models and B-spline level-sets. Med. Image Anal., 32:157–172, 2016.
| `PDF <https://mosaic.mpi-cbg.de/docs/Xiao2016.pdf>`__
*In order to ensure financial support for our project and allow further development of
this software, please cite above publications in all your documents and manuscripts that
made use of this software. Thanks a lot!*
* **Fast implicit curvature filters**
Curvature filters provide geometric means of image filtering, denoising, and restoration.
This amounts to solving a variational model, but the filters here implicitly do this, and
are much faster. You find the filters in the menu ``Enhancement > Curvature Filters``.
Currently, we implement Gauss curvature, Mean curvature, and Total Variation (TV) filters.
The only parameters is the number of iterations, i.e., how many passes of the filter should
be applied to the image. Else the filters are parameter free.
A C++ implementation of these filters is also available `here <https://mosaic.mpi-cbg.de/?q=downloads/curvaturefilters>`__.
The algorithms implemented in this plug-in are described in:
.. admonition:: Citation
| Y. Gong and I. F. Sbalzarini.
| Curvature filters efficiently reduce certain variational energies. IEEE Trans. Image Process., 26(4):1786–1798, 2017.
| `PDF <https://mosaic.mpi-cbg.de/docs/Gong2017.pdf>`__
*In order to ensure financial support for our project and allow further development of
this software, please cite above publications in all your documents and manuscripts that
made use of this software. Thanks a lot!*
* **Image Naturalization**
Image naturalization is an image enhancement technique that is based on gradient statistics
of natural-scence images. The algorithm is completely parameter free. Simply open an image
and choose ``Enhancement > Naturalization`` from the plugin menu. In fluorescence microscopy,
image naturalization can be used for blind deconvolution, dehazing (removing scatter light),
denoising, or contract enhancement. All just with one function! The "naturalness factor"
displayed at the end tells you how close your original image was to a natural-scene one
(1 meaning close, the farther from one the more different).
The algorithm implemented in this plug-in is described in:
.. admonition:: Citation
| Y. Gong and I. F. Sbalzarini.
| Image enhancement by gradient distribution specification. In Proc. ACCV, 12th Asian Conference on Computer Vision, Workshop on Emerging Topics in Image Enhancement and Restoration, pages w7–p3, Singapore, November 2014.
| `PDF <https://mosaic.mpi-cbg.de/docs/Gong2014.pdf>`__
*In order to ensure financial support for our project and allow further development of
this software, please cite above publications in all your documents and manuscripts that
made use of this software. Thanks a lot!*
.. important::
For information about previous news not listed here please refere to `old MosaicSuite site <https://mosaic.mpi-cbg.de/?q=downloads/imageJ>`_.
======================
Particle Tracker 2D/3D
======================
Particle Tracker (PT) is a ImageJ plugin for multiple particle detection and tracking from digital videos
.. figure:: resources/particleTracker/particleTracker.png
:scale: 75 %
:align: center
Particle Tracker in action
General Description
===================
This plugin presents an easy-to-use, computationally efficient, two- and three-dimensional, feature point-tracking tool for the automated detection and analysis of particle trajectories as recorded by video imaging in cell biology.
The tracking process requires no apriori mathematical modelling of the motion, it is self-initialising, it discriminates spurious detections, and it can handle temporary occlusion as well as particle appearance and disappearance from the image region.
The plugin is well suited for video imaging in cell biology relying on low-intensity fluorescence microscopy. It allows the user to visualize and analyze the detected particles and found trajectories in various ways:
* Preview and save detected particles for separate analysis
* Global non progressive view on all trajectories
* Focused progressive view on individually selected trajectory
* Focused progressive view on trajectories in an area of interest
It also allows the user to find trajectories from uploaded particles position and information text files and then to plot particles parameters vs. time - along a trajectory.
Tutorial
========
For detailed description and hints how to use Particle Tracker please refere to :ref:`particletracker-tutorial`.
.. toctree::
:hidden:
particleTrackerTutorial
Developer Resources
===================
Source code and helpful information about MosaicSuite development can be found in :ref:`mosaicsuite-development` section.
Citation
========
.. admonition:: Citation
| *I. F. Sbalzarini and P. Koumoutsakos*
| Feature point tracking and trajectory analysis for video imaging in cell biology. J. Struct. Biol., 151(2): 182-195, 2005.
| `PDF <http://mosaic.mpi-cbg.de/docs/Sbalzarini2005a.pdf>`__
*In order to ensure financial support for our project and allow further development of
this software, please cite above publications in all your documents and manuscripts that
made use of this software. Thanks a lot!*
\ No newline at end of file
.. _particletracker-tutorial:
=========================
Particle Tracker tutorial
=========================
This tutorial provides a basic introduction on how to select the right parameters for the algorithm of ParticleTracker and the right display and analysis options upon completion of it.
Basic Tracking
================
Preparation of data
-------------------
This tutorial is using a real experimental movie (image sequence) from
*Suomalainen et al., J. Cell Biol. 144 (4): 657-672* kindly provided by the Cell Biology group,
Institute of Zoology, University of Zurich.*
Fast minus and plus end-directed transport of endosomal ts1 virus labeled with Texas red.
Virus was added to TC7/MAP4/MTB-GFP cells and 72 TR-images were recorded with intervals
of 1.5 s starting 20 min p.i.. The GFP signal is indicated at the beginning. Bar = 10 µm.
1. Download a zipped file with images :download:`TransportOfEndosomalVirus.zip <resources/particleTracker/TransportOfEndosomalVirus.zip>`
#. After downloading the zip file, unzip it to your preferred folder and Start ImageJ.
#. Load the image sequence by selecting the ``Import > Image Sequence`` from the ``File`` menu.
#. In the first shown dialog, select one of the images in the folder (the one you unzipped) and click "Open".
#. In the second dialog specify which images in the folder to open and/or to have the images converted to 8-bits.
When working with RGB images like the files of the experimental movie sample it is highly recommended to convert them to 8-bits. This way the memory consumption is reduced significantly.
Check the Convert to 8-bit Grayscale box and click OK.
.. important::
Since the plugin also supports 3D images, it is necessary to correctly set the image properties. Select Image -> Properties... from the menu. Please verfiy that the number of slices (z) and the number of frames (t) are set correctly. For this tutorial, set the number of slices to 1 and the number of frames to 144.
Run Particle Tracker
--------------------
Now, that the movie is open you can start the plugin by selecting ParticleTracker from the ``Plugins > Mosaic > Particle Tracker 2D/3D`` menu.
.. figure:: resources/particleTracker/dialog_cropped.jpg
:scale: 75 %
:align: center
Particle Tracker with created sequence
Select particle detection parameters and preview
------------------------------------------------
The dialog showing now has 2 parts: Particle Detection and Particle Linking.
The parameters relevant for detection are:
* **Radius**: Approximate radius of the particles in the images in units of pixels. The value should be slightly larger than the visible particle radius, but smaller than the smallest inter-particle separation.
* **Cutoff**: The score cut-off for the non-particle discrimination
* **Per/Abs**: The percentile (r) (or absolute intensity value) that determines which bright pixels are accepted as Particles. All local maxima in the upper rth percentile of the image intensity distribution ( or absolute intensity value ) are considered candidate Particles. Unit: percent (%) (or absolute intensity value)
* **Absolute**: when enable it read the Per/Abs parameter as absolute intensity value
In the particle detection part you can "play" with different parameter and check how well the particles are detected by clicking the preview detected button.
**There are no right and wrong parameters; it all depends on the movie, type of data and what is looked for.**
Enter these parameters: radius = 3, cutoff = 0, percentile = 0.1(default) - click on preview detected.
Notice the 2 very close particles marked in the image
.. figure:: resources/particleTracker/2closeParticles_cropped.jpg
:scale: 100 %
:align: center
Check the detected particles at the next frames by using the slider in the dialog menu
With radius of 3 they are rightly detected as 2 separate particles.
If you have any doubt they are 2 separate particles you can look at the 3rd frame.
Change the radius to 6 and click the preview button.
Look at frame 1. With this parameter, the algorithm wrongfully detects them as one particle since they are both within the radius of 6 pixels.
Try other values for the radius parameter.
Go back to these parameters: radius = 3, cutoff = 0, percentile = 0.1(default) - click on preview detected.
It is obvious that there are more 'real' particles in the image that were not detected.
Notice, that the detected particles are much brighter then the ones not detected.
Since the score cut-off is set to zero, we can rightfully assume that increasing the percentile of particle intensity taken will make the algorithm detect more particles (with lower intensity).
The higher the number in the percentile field - the more particles will be detected.
Try setting the percentile value to 2.
After clicking the preview button, you will see that much more particles are detected, in fact too many particles - you will need to find the right balance.
In this movie, percentile value of 0.6 will give nice results.
**Remember! There is no right and wrong here - it is possible that the original percentile = 0.1 will be more suitable even with this film, if for example only very high intensity particles are of interest.**
Set the parameters to radius = 3, cutoff = 1, percentile = 0.6 - click on preview detected.
Change the cutoff parameters back to its default (3) and click preview again.
Notice the particles marked in the two pictures:
.. figure:: resources/particleTracker/cutoff1-3_cropped.jpg
:scale: 100 %
:align: center
With cutoff = 3 both particle are discriminated as non-particles and when cutoff = 1 only one gets discriminated.
The higher the number in the cutoff field the more suspicious the algorithm is of false particles.
This could be very helpful when one understand the method for non-particles discrimination as described in the original algorithm.
It can also lead to real particles discrimination when the value is too high.
After setting the parameters for the detection (we will go with radius = 3, cutoff = 0, percentile = 0.6) you should set the particle linking parameters.
The parameters relevant for linking are:
* **Displacement**: The maximum number of pixels a particle is allowed to move between two succeeding frames.
* **Link Range**: The number of subsequent frames that is taken into account to determine the optimal correspondence matching.
* **Dynamics**: Type of motion of the particles, Brownian is self explanatory, constant velocity introduce a penalization term if the particle change their velocity (module and direction), straight line put a penalization term only on the direction
* **Advanced options**: A set of option to change the weight of the linking cost in the feature space and the combinatorial optimizer. Appendix for more information
These parameters can also be very different from one movie to the other and can also be modified after viewing the initial results.
Generally, in a movie where particles travel long distance from one frame to the other - a large link range should be entered.
In this movie a link range of ~20 is appropriate. Set it to 20.
The linkrange value is harder to set before viewing some initial results since it is mainly designed to overcome temporary occlusion as well as particle appearance and disappearance from the image region and it is hard to notice such things at this stage.
Still an initial value has to be set, the default is 2 but we will continue with 3.
(We will return to these parameters later with a different movie.)
You can now go ahead with the linking by clicking OK.
The progress of the algorithm will be displayed in the main ImageJ Status Bar.
Viewing the results
-------------------
After completing the particle tracking, the result window will be displayed.
Click the Visualize all Trajectories button to view all the found trajectories.
.. figure:: resources/particleTracker/results_window_all_traj_view_cropped.jpg
:scale: 75%
:align: center
This window displays an overview of all 108 found trajectories
One way to reduce the displayed trajectories is to filter short trajectories.
Click on the Filter Options button to filter out trajectories under a given length.
Enter 144 and click OK. All the trajectories will disappear - you can also see the message in the results window "0 trajectories remained after filter".
Since the length of the movie is 144 frames there are no trajectories longer then 144 frames.
Filter again with 0 as input.
All trajectories are again displayed because by definition every trajectory length is at least 1 (spans over at least 2 frames).
Try other numbers for the filter option and notice the differences.
Set filter for 100, only 14 trajectories remained after filtering.
Select the yellow trajectory (the one shown here) by clicking it once with the mouse left button.
.. figure:: resources/particleTracker/selecting_yellow_traj_cropped.jpg
:scale: 75%
:align: center
A rectangle surrounding the selected trajectory appears on the screen and on the trajectory column of the results window the number 32 is now displayed - it indicates the number of this trajectory (from the 108 found).
Now that a specific trajectory is selected you focus on it or get its information.
Click on Selected Trajectory Info button - the information about this trajectory will be displayed in the results window
.. figure:: resources/particleTracker/selecting_yellow_traj_info_cropped.jpg
:scale: 75%
:align: center
Click on the Focus on S``elected Trajectory`` button - a new window with a focused view of this trajectory is displayed.
This view can be saved with the trajectory animation through the File menu of ImageJ.
Look at the focused view and compare it to the overview window - in the focused view the white trajectory that is close to the yellow is not displayed.
.. figure:: resources/particleTracker/yellow_focus_no_white.jpg
:scale: 75%
:align: center
The particle and the trajectory animation is displayed.
Close this focus view.
Now we what to focus on area for number of trajectories view, we will focus on the area of the yellow and white trajectories as shown here.
Select a rectangle region of interest around these trajectories - click and drag the mouse on the overview to include them.
Click on the Focus On Area button - a new window with a focused view of these trajectories is displayed.
This time the animation of both trajectories is displayed.
Generally, any unfiltered trajectory part that is in the selected area will be shown.
You may notice that some particles are showing but their trajectory is not animated, this is because they are filtered (remember we filtered for longer then 100).
Close the focus window and reset the filter. You can do that by closing the overview window and reopening it by clicking the Visualize all Trajectories button or you can click the filter button and set the min length to 0 (default).
The last option is better since this way your area selection will stay.
Click again on the Focus on Area button - now all trajectories within the selection area is displayed.
The size of the focus window for specific trajectory and area focus is determined by the magnification factor relative to the original movie window size.
Select the pink trajectory (the one shown here). The trajectory number is 44.
.. figure:: resources/particleTracker/selecting_pink_traj_cropped.jpg
:scale: 75%
:align: center
Notice that the rectangle surrounding the selected trajectory is fairly big.
If we focus on this trajectory with the default magnification factor (6) a large window will be created and may cause memory problems (especially in Mac Os).
For this reason and others - you can change the magnification factor.
Before clicking the Focus on Selected Trajectory button - go to View Preferences menu in the results window and select the Magnification Factor option.
Select magnification of 2-4.
Click on the Focus on Selected Trajectory button to see the size of the new window. Close the window.
Tracking segmented data
=======================
In order to track segmented data we will use the following :download:`Cell_track.zip <resources/particleTracker/Cell_track.zip>` as a test-case.
.. figure:: resources/particleTracker/Test_cell.*
:scale: 75%
:align: center
The first step is to segment this video to get the regions, for this purpose we will use Squassh. Open the Squassh plugin from ``Plugins > Mosaic > Segmentation > Squassh``.
.. figure:: resources/particleTracker/squassh.jpg
:scale: 75%
:align: center
For the segmentation option set Regularization Ch1=0.200, Minimum object channel1 intensity=0.300 and PSF XY=1.0 leave the others parameters to the default one, start the segmentation pressing OK on both the windows opened. Segmenting the video can take long time, but at the end you should get a result that look like this:
.. figure:: resources/particleTracker/segmented_data.*
:scale: 75%
:align: center
Now open again particle tracker. The plugin detects the presence of segmented data in the folder where the image is located, if this is the case, it ask if you want to use that information for tracking.
.. figure:: resources/particleTracker/use_seg.jpg
:scale: 75%
:align: center
In case more than one segmentation data is found a dialog will ask to choose which one to use.
.. figure:: resources/particleTracker/choose_seg.jpg
:scale: 75%
:align: center
After you choose the regions data, the particle tracker window appear without the detection stage because the detection stage has been already performed by the segmentation. For this tutorial we use link range 1 and displacement 80.0.
.. figure:: resources/particleTracker/pt_link.jpg
:scale: 75%
:align: center
Pressing OK A new window will appear asking to filter out the region that you want to track
.. figure:: resources/particleTracker/filter_part.jpg
:scale: 75%
:align: center
In case of segmented data and regions in general, we can decide to filter out regions by size and intensity, the following window ask for two thresholds on size and intensity, all the regions with value lower than the indicated will be removed. Set the size to 130.0 and press OK, 10 Trajectories are detected. To see the tracked regions Click on Visualize all trajectories
.. figure:: resources/particleTracker/atv_seg_trak.*
:scale: 75%
:align: center
This window show the tracked regions with trajectory, the sphere is centered on the center of mass of the regions and the circle size indicate the size (segmented) of the region.
Dynamic models of particle linker
=============================================