Commit abd89172 authored by Jean-Yves TINEVEZ's avatar Jean-Yves TINEVEZ
Browse files

More documentation.

parent d1f1d1be
......@@ -2,7 +2,9 @@
DeProj is a MATLAB app made to yield accurate morphological measurements on cells in epithelia or tissues.
## What is DeProj useful for?
[TOC]
## What is DeProj useful for.
### Measuring cell morphologies on 2D projections.
......@@ -26,7 +28,7 @@ On this illustration, a cell (in red, top-left quadrant) is located on a region
**DeProj** is a tool made to correct for this distorsion. It takes 1) the results of the segmentation on the projection - the green contour on the bottom-right quadrant above - 2) the height-map that follows the shape of the tissue - the gray smooth line on the top-right quadrant above - and "de-project" the cell back on its original position in the tissue - in red, top-right quadrant. Then it yields corrected morphological measurements.
## How-to use DeProj.
## How to use DeProj.
DeProj requires two inputs:
......@@ -85,7 +87,7 @@ ans =
id: []
```
### Example analysis.
### Running the example.
The root folder of the DeProj repository has a [self-contained example](RunExample.m), that you can run with:
......@@ -138,20 +140,208 @@ We can also measure the cell size (area and perimeter) on the XY projection, and
![ExampleResults_fig5_Distorsion](static/ExampleResults_fig5_Distorsion.png)
## Documentation.
## Running DeProj from MATLAB prompt.
DeProj is mainly made of two classes, and running it from the MATLAB prompt should be convenient enough.
### From a segmentation mask and a height-map.
You need two images as input.
#### The segmentation mask.
It is the results of the segmentation step, and must be a black and white image where each object is white and separated from its neighbor by a black ridge. Importantly the ridge must be connected using 8-connectivity.
For instance, this is good (the ridges can be connected by the pixel diagonals):
![8-connectivity](/Users/tinevez/Development/Matlab/DeProj/static/8-connectivity.png)
The following is <u>not good</u> (the ridges only move east west north and south):
![4-connectivity](/Users/tinevez/Development/Matlab/DeProj/static/4-connectivity.png)
#### The height-map.
The height-map is an image <u>of the exact same size that the segmentation image</u>, and for which the pixel value reports the Z position of the tissue surface. For instance:
![HeightMap-2](/Users/tinevez/Development/Matlab/DeProj/static/HeightMap-2.png)
On this example the pixel value is an integer that gives the Z-plane from which the projection pixel was taken. Several academic softwares generate this height-map (under varying names) on top of the projection. We list some of them at the end of this documentation.
#### Running the analysis.
For this example, we use the images that are present in the `samples` folder of this repository. They are a small excerpt of a 3D image of a drosophila pupal notum labelled for E-cadherin, and projected with the LocalZProjector (courtesy of Léo Valon, [Romain Levayer lab](https://research.pasteur.fr/en/team/cell-death-and-epithelial-homeostasis/), Institut Pasteur).
You must first load the two images:
```matlab
% Path to the images.
root_folder = 'samples';
mask_filename = 'Segmentation-2.tif';
I = imread( fullfile( root_folder, mask_filename ) );
heightmap_filename = 'HeightMap-2.tif';
H = imread( fullfile( root_folder, heightmap_filename ) );
```
We can directly report all the measurements in physical units. To do so we need to specify what is the unit of length, and what is the pixel size in X & Y:
```matlab
pixel_size = 0.183; % µm
units = 'µm';
```
The height-map of this dataset reports the *Z plane* of interest in the original 3D image. But we need to know the position in physical units, so we need to specify the pixel size in Z, or the voxel-depth:
```matlab
voxel_depth = 1.; % µm
```
If your height-map already report the Z position and not the Z-plane, simply enter a value of `1` here.
Finally we have some options to deal with tissue orientation and missing tissue. When we have `value = 0` in a region of the height-map, this signals that the projection is not defined at this location, for instance if the tissue is not imaged in these regions. We can then extrapolate the height-map there, and/or remove cells that touch such a region.
```matlab
% If this flag is set to true, the height-map will be extrapolated in regions where its value is 0.
inpaint_zeros = true;
% Remove objects that have a Z position equal to 0. Normally this
% value reports objects that are out of the region-of-interest.
prune_zeros = true;
```
Often inverted microscopes are used to image these tissues. When the sample is arranged on its back, this leads the bottom of the tissue surface to have large Z value (this is the case for the sample data). The following flag is a convenience that flips it for better display.
```matlab
% Invert z for plotting.
invert_z = true;
```
Finally, we can run DeProj. Everything is done with a single call to:
```matlab
dpr = deproj.from_heightmap( ...
I, ...
H, ...
pixel_size, ...
voxel_depth, ...
units, ...
invert_z, ...
inpaint_zeros, ...
prune_zeros );
```
It can take some time, depending on the size of the images. You should see something like this in the MATLAB console:
```
Opening mask image: Segmentation-2.tif
Opening height-map image: HeightMap-2.tif
Converting mask to objects.
Converted a 282 x 508 mask in 1.2 seconds. Found 426 objects and 1840 junctions.
Typical object scale: 10.1 pixels or 1.84 µm.
Collecting Z coordinates.
Done in 0.1 seconds.
Removed 0 junctions at Z=0.
Removed 0 objects touching these junctions.
Computing tissue local curvature.
Computing morphological descriptors of all objects.
Done in 3.4 seconds.
```
What you get out this process is a `deproj` object:
```matlab
>> dpr
dpr =
deproj with properties:
epicells: [426×1 epicell]
junction_graph: [1×1 graph]
units: 'µm'
```
It manages mainly a collection of `epicell` objects, that store the data for one cell:
```matlab
>> o = dpr.epicells(4)
o =
epicell with properties:
boundary: [26×3 single]
center: [2.4705 11.1826 3.1008]
junction_ids: [5×1 double]
area: 8.0176
perimeter: 12.5227
euler_angles: [-2.0734 0.4195 -0.2500]
curvatures: [0.0110 -4.8103e-05 0.0240 -0.0020]
ellipse_fit: [2.2284 11.1114 3.1008 2.3848 1.1178 0.4528]
eccentricity: 0.8834
proj_direction: 1.2539
uncorrected_area: 7.3173
uncorrected_perimeter: 12.1116
id: 4
```
We give the definition and details about these properties later in this document.
The `deproj` object can be exported to a MATLAB table:
```matlab
>> T = dpr.to_table;
>> head(T)
ans =
8×23 table
id xc yc zc area perimeter euler_alpha ....
__ ______ ______ _______ ______ _________ ___________ ....
1 1.3039 22.669 0.61254 2.507 7.2365 0.71603 ....
2 2.4739 23.827 0.66689 8.0899 11.849 0.90395 ....
3 3.5615 3.6656 5.0947 12.317 15.599 -2.0397 ....
4 2.4705 11.183 3.1008 8.0176 12.523 -2.0734 ....
5 2.6884 26.749 0.24663 5.141 9.1999 -2.1016 ....
6 3.6096 14.773 2.7521 13.812 16.114 -2.1033 ....
7 5.0077 8.8491 4.6461 40.057 26.8 -2.0163 ....
8 3.9601 29.361 0.22428 7.6378 11.323 -2.0704 ....
```
then saved to a `csv` or Excel file:
```matlab
dpr.to_file( 'table.csv' )
dpr.to_file( 'table.xlsx' )
```
![ExampleExport](/Users/tinevez/Development/Matlab/DeProj/static/ExampleExport.png)
It can also be used to generate customisable plots. Several convenience methods are there:
```matlab
>> dpr.plot_sizes
```
![ExampleResults_fig1a_CellSize](/Users/tinevez/Development/Matlab/DeProj/static/ExampleResults_fig1a_CellSize.png)
## Launch the program
The method can both be called in a GUI and by the command line of MATLAB
1. To call the method using the GUI:
## Appendix.
start the DeProj_GUI app in MATLAB `>> DeProj_GUI`. The GUI will guide you to provide the proper inputs and outputs to the method as well as the method parameters. The app has been created under MATLAB R2017b version and using an older version may create unexpected behavior.
### Projection tools that yields the height-map.
2. To call the method using the command line: enter `>> surface3D_combine()`
DeProj requires the height-map along with the segmentation of the projection, in order t "deproject" the cells onto the actual tissue surface. Here are some of the open-source projection tool that can return this output:
* In case all arguments are provided, the method will continue with the desired inputs
* In case no arguments are provided, the method will revert to default parameters and only ask the user for inputs and output paths.
- [LocalZProjector](https://gitlab.pasteur.fr/iah-public/localzprojector). DeProj is the component part of the DProj toolbox, and LocalZProjector is the first one. It can generate a hight-map that can directly be used by DeProj.
- [StackFocuser](https://imagej.nih.gov/ij/plugins/stack-focuser.html), an ImageJ plugin.
- [PreMosa](https://academic.oup.com/bioinformatics/article/33/16/2563/3104469), a standalone C++ software.
- The [Extended-Depth-Of-Field](http://bigwww.epfl.ch/demo/edf/) ImageJ plugin.
- The [Min Cost Z Surface](https://imagej.net/Minimum_Cost_Z_surface_Projection) ImageJ plugin.
- The [Smooth Manifold Extraction](https://github.com/biocompibens/SME) MATLAB tool (a Fiji version is also distributed) and its recent, faster implementation: [FastSME](https://github.com/Shihav/FastSME).
## Side note: Segmenting the projection.
### Segmentation tools for the projection.
Several open-source tools can segment the projection and yield the cells contour or the mask displayed above. Some of them offer an intuitive user interface, allowing for immediate usage and user interaction. For instance:
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment