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):
The following is **not good** (the ridges only move east west north and south):
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:
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).
'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.
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.
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.
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:
'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.
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.
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.
