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

Document deproj.from_heightmap

I simply copied the part from the README.md.
parent 90ae4819
......@@ -2,8 +2,240 @@
We document here the methods of the two DeProj classes `deproj` and `epicell`. We separate methods in the ones that are useful for users of DeProj and the secondary ones that are used by other methods.
But the really important methods are those who create a `deproj` analysis results from the images. You can directly jump to the `deproj.from_heightmap` method.
[TOC]
## The `deproj` class methods.
A `deproj` instance has several interesting methods, that let you export and display the analysis results. In particular the plotting routines: you will most likely be adapting them to your needs with a bit of MATLAB.
### Main `deproj` methods.
#### Static method `from_heightmap`
This is the most important method of DeProj. It generates analysis results in the shape of a `deproj` object from a segmentation mask and a height-map image.
```matlab
obj = deproj.from_heightmap( ...
I, ...
H, ...
pixel_size, ...
voxel_depth, ...
units, ...
invert_z, ...
inpaint_zeros, ...
prune_zeros )
```
Returns a `deproj` object built from segmentation and height-map.
You need two images as input.
The **segmentation mask image** 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):
![img](/Users/tinevez/Development/Matlab/DeProj/static/8-connectivity.png)
The following is **not good** (the ridges only move east west north and south):
![img](/Users/tinevez/Development/Matlab/DeProj/static/4-connectivity.png)The height-map.The height-map is an image of the exact same size that the segmentation image, and for which the pixel value reports the Z position of the tissue surface. For instance:
![img](/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.
We now explain the meaning of other parameters in an example using 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).
```matlab
% You must first load the two images.
% 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:
>> pixel_size = 0.183; % µm
>> units = 'µm';
>> voxel_depth = 1.; % µm
% 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.
% 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.
% Invert z for plotting.
>> invert_z = true;
% The method call itself.
>> dpr = deproj.from_heightmap( ...
I, ...
H, ...
pixel_size, ...
voxel_depth, ...
units, ...
invert_z, ...
inpaint_zeros, ...
prune_zeros );
____
Opening mask image: Segmentation-2.tif
Opening height-map image: HeightMap-2.tif
Converting mask to objects.
Converted a 282 x 508 mask in 2.7 seconds. Found 426 objects and 1840 junctions.
Typical object scale: 10.1 pixels or 1.84 µm.
Collecting Z coordinates.
Done in 0.4 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.3 seconds.
____
>> dpr
dpr =
deproj with properties:
epicells: [426×1 epicell]
junction_graph: [1×1 graph]
units: 'µm'
```
In the following we suppose that `dpr` is an instance of `deproj` created by this example.
#### `to_table`
`T = to_table( obj )`
Export masurements 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 ...
```
The table also stores the physical units of each columns:
```matlab
>> T.Properties.VariableUnits
ans =
1×23 cell array
Columns 1 through 7
{0×0 char} {'µm'} {'µm'} {'µm'} {'µm²'} {'µm'} {'radians'} ...
```
A short description of the columns is present:
```matlab
>> T.Properties.VariableDescriptions{7}
ans =
'First Euler angle for the cell plane (rotation around Z)'
```
And a table description:
```matlab
>> T.Properties.Description
ans =
'Data generated from DeProj software, exported on 21-Jul-2020 23:07:02.'
```
#### `to_file`
`to_file( obj, file_name, include_header )`
Exports results to a spreadsheet file.
If `file_name` has `.csv` as extension, the data is saved as a CSV file. If it has `.xlsx` as an extension, it is saved as an Excel spreadsheet. The boolean flag `include_header` specifies whether the file will have a header with column names and units.
```matlab
dpr.to_file( 'table.csv' )
dpr.to_file( 'table.xlsx' )
```
![ExampleExport](/Users/tinevez/Development/Matlab/DeProj/static/ExampleExport.png)
#### `plot_sizes`
`[ hf, ax1, ax2 ] = plot_sizes( obj, scale_bar_length )`
Generate a figure with the cells area and perimeter. All the plots generated by the `plot_*` methods are 3D plots. The cells are drawn with their 3D coordinates and you can zoom, rotate, pan to make the curvature of the tissue appear.
The `scale_bar_length` parameter specifies what should be the length (in physical units) of the scale bar added to the bottom left of the plot. By default it is 10. The output arguments `[ hf, ax1, ax2 ]` are respectfully the handles to the figure created, to the top axes and to the bottom axes.
```matlab
>> dpr.plot_sizes
```
![ExampleResults_fig1a_CellSize](/Users/tinevez/Development/Matlab/DeProj/static/ExampleResults_fig1a_CellSize.png)
#### `plot_fit_plane`
`[ hf, ax1, ax2, ax3 ] = plot_fit_plane( obj, scale_bar_length )`
Generate a figure with the local plane orientation for each cell. This orientation is given as 3 Euler angles in the [ZX'Z'' convention](https://en.wikipedia.org/wiki/Euler_angles#Chained_rotations_equivalence).
- The first one, `alpha` is the orientation of the cell plane (top panel below). As an analogy, imaging you are facing a hill, the slope going up. The direction (south, west…) in which the slope is the largest is given by the angle `alpha`. On these figures we wrap the angle between 0º and 180º to and because of MATLAB convention, this angle is measured counterclockwise from the Y axis (so 90º corresponds to a slope going up in the east-west direction).
- The second one, `beta` measures the slope of this plane with XY plane (middle panel). A value of 0º indicates that the cell plane is parallel to XY.
- The third one , `gamma` measures the cell main orientation in the cell plane (bottom panel). Because the cell plane was rotated a first time by `alpha`, this angle does not give a result immediately usable.
```matlab
>> dpr.plot_fit_plane
```
![ExampleResults_fig2_EulerAngles](/Users/tinevez/Development/Matlab/DeProj/static/ExampleResults_fig2_EulerAngles.png)
### Secondary `deproj` methods.
## The `epicell` class methods.
In the following we suppose that `o` is an instance of `epicell`, for instance obtained by executing the a [self-contained example](RunExample.m) in this repository and for instance:
......@@ -181,7 +413,7 @@ The second output argument `Q` contains the parametric ellipse parameter. It is
*A x² + B x y + C y² + D x + E y + F = 0*
### Static method `fit_ellipse_3d`
#### Static method `fit_ellipse_3d`
`[ f3d, R ] = fit_ellipse_3d( p, E, method )`
......@@ -201,131 +433,3 @@ The first output arguments `f3d` contains the ellipse parameter in cartesian for
The second argument `R` is the rotation matrix computed from the Euler angles.
## The `deproj` class methods.
A `deproj` instance has several interesting methods, that let you export and display the analysis results. In particular the plotting routines: you will most likely be adapting them to your needs with a bit of MATLAB.
In the following we suppose that `dpr` is an instance of `deproj`, for instance obtained by executing the a [self-contained example](RunExample.m) in this repository:
```matlab
>> dpr
dpr =
deproj with properties:
epicells: [426×1 epicell]
junction_graph: [1×1 graph]
units: 'µm'
```
### Main `deproj` methods.
#### `to_table`
`T = to_table( obj )`
Export masurements 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 ...
```
The table also stores the physical units of each columns:
```matlab
>> T.Properties.VariableUnits
ans =
1×23 cell array
Columns 1 through 7
{0×0 char} {'µm'} {'µm'} {'µm'} {'µm²'} {'µm'} {'radians'} ...
```
A short description of the columns is present:
```matlab
>> T.Properties.VariableDescriptions{7}
ans =
'First Euler angle for the cell plane (rotation around Z)'
```
And a table description:
```matlab
>> T.Properties.Description
ans =
'Data generated from DeProj software, exported on 21-Jul-2020 23:07:02.'
```
#### `to_file`
`to_file( obj, file_name, include_header )`
Exports results to a spreadsheet file.
If `file_name` has `.csv` as extension, the data is saved as a CSV file. If it has `.xlsx` as an extension, it is saved as an Excel spreadsheet. The boolean flag `include_header` specifies whether the file will have a header with column names and units.
```matlab
dpr.to_file( 'table.csv' )
dpr.to_file( 'table.xlsx' )
```
![ExampleExport](static/ExampleExport.png)
#### `plot_sizes`
`[ hf, ax1, ax2 ] = plot_sizes( obj, scale_bar_length )`
Generate a figure with the cells area and perimeter. All the plots generated by the `plot_*` methods are 3D plots. The cells are drawn with their 3D coordinates and you can zoom, rotate, pan to make the curvature of the tissue appear.
The `scale_bar_length` parameter specifies what should be the length (in physical units) of the scale bar added to the bottom left of the plot. By default it is 10. The output arguments `[ hf, ax1, ax2 ]` are respectfully the handles to the figure created, to the top axes and to the bottom axes.
```matlab
>> dpr.plot_sizes
```
![ExampleResults_fig1a_CellSize](static/ExampleResults_fig1a_CellSize.png)
#### `plot_fit_plane`
`[ hf, ax1, ax2, ax3 ] = plot_fit_plane( obj, scale_bar_length )`
Generate a figure with the local plane orientation for each cell. This orientation is given as 3 Euler angles in the [ZX'Z'' convention](https://en.wikipedia.org/wiki/Euler_angles#Chained_rotations_equivalence).
- The first one, `alpha` is the orientation of the cell plane (top panel below). As an analogy, imaging you are facing a hill, the slope going up. The direction (south, west…) in which the slope is the largest is given by the angle `alpha`. On these figures we wrap the angle between 0º and 180º to and because of MATLAB convention, this angle is measured counterclockwise from the Y axis (so 90º corresponds to a slope going up in the east-west direction).
- The second one, `beta` measures the slope of this plane with XY plane (middle panel). A value of 0º indicates that the cell plane is parallel to XY.
- The third one , `gamma` measures the cell main orientation in the cell plane (bottom panel). Because the cell plane was rotated a first time by `alpha`, this angle does not give a result immediately usable.
```matlab
>> dpr.plot_fit_plane
```
![ExampleResults_fig2_EulerAngles](static/ExampleResults_fig2_EulerAngles.png)
### Secondary `deproj` methods.
\ No newline at end of file
Markdown is supported
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