diff --git a/DeProjMethods.md b/DeProjMethods.md
index 7c6a5a6f763e9d1296f5bb07b2af58ee5249c02d..605de943ad20def400971ad0363e431f5dc55df8 100644
--- a/DeProjMethods.md
+++ b/DeProjMethods.md
@@ -97,11 +97,11 @@ The height-map is an image of the exact same size that the segmentation image, a
-On this example the pixel value is a float number that gives the Z position from which the projection pixel was taken.
+On this example the pixel value is a float number that gives the Z position from which the projection pixel was taken.
##### Example.
-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).
+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.
@@ -114,20 +114,20 @@ We now explain the meaning of other parameters in an example using the images th
>> 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,
+% 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.
+% 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
+% If this flag is set to true, the height-map will be extrapolated in regions
% where its value is 0.
>> inpaint_zeros = true;
@@ -135,8 +135,8 @@ We now explain the meaning of other parameters in an example using the images th
% 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
+% 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.
@@ -171,7 +171,7 @@ ____
>> dpr
-dpr =
+dpr =
deproj with properties:
@@ -185,7 +185,7 @@ ____
#### Static method `from_bellaiche`
-It is possible to create a `deproj` object from completely different inputs. In this case, we take the segmentation results generated by the MATLAB analysis sofware created by the [lab of Yohanns Bellaïche](https://science.institut-curie.org/research/biology-cancer-genetics-and-epigenetics/developmental-biology-and-genetics/team-bellaiche/) and a mesh generated elsewhere.
+It is possible to create a `deproj` object from completely different inputs. In this case, we take the segmentation results generated by the MATLAB analysis software created by the [lab of Yohanns Bellaïche](https://science.institut-curie.org/research/biology-cancer-genetics-and-epigenetics/developmental-biology-and-genetics/team-bellaiche/) and a mesh generated elsewhere.
##### The segmentation from the software of Y.B. lab.
@@ -198,14 +198,14 @@ See the following paper for its reference use:
This tool goes beyond the segmentation of the tissue cells. Its complete execution yields the local deformation of the tissue. However DeProj only works on its first step. The first step of this tool generates segmentation results, stored in 4 variables: `CELLS`, `FRAME`, `VERTICES` and `SIDES` as `struct` MATLAB objects. You will find in `samples/AdultZebrafishBrainSeg.mat ` folder of this repo, a *minimal subset* of such a segmentation result. We give below a tentative description of how the results are organized and what each variable should contain. We only document the parts needed by DeProj, and this documentation is limited by and based solely on our understanding of the format.
-Each of the four variables listed above is organized as follow:
+Each of the four variables listed above is organized as follow:
-- `CELLS` contains the invidiual cell segmentation results. In this `struct`, DeProj requires at least:
+- `CELLS` contains the individual cell segmentation results. In this `struct`, DeProj requires at least:
- the variable `numbers`, a `Ncells x 1` array that specifies the ID of the cell (we will import in the `id` field of the corresponding `epicell` )
- the variable `vertices`, a `Ncells x 1` cell array. In each cell array is listed the indices of the junctions that a cell touches.
- the variable `contour_indices`, a `Ncells x 1` cell array. Each cell array contains the linear indices of the pixels of the cell contour. You can transform them into X, Y coordinates by knowing the width of the source image.
- `SIDES` is a `struct` that contains information about the cell-to-cell borders. We only use the:
- - `vertices` variable, which is a `Nedges x 2` array containing the indices of the junctions joinsed by such a border.
+ - `vertices` variable, which is a `Nedges x 2` array containing the indices of the junctions joined by such a border.
- `VERTICES`, a struct array containing the information about the cell junctions.
- the variable `numbers`, a `Njunctions x 1` array that specifies the ID of the junction.
- `XYs` a `Njunctions x 2` array containing the X and Y location of each junction, in physical coordinates.
@@ -217,7 +217,7 @@ If at least all these variables are present, DeProj can import such a segmentati
##### The mesh mapping the tissue surface.
-Instead of using a height-map, like the previous import function, we rely here on a mesh file that maps the tissue surface. It must be specified as a path to [a `.ply` file](https://en.wikipedia.org/wiki/PLY_(file_format)) (the `mesh_file_path` input in the example below).
+Instead of using a height-map, like the previous import function, we rely here on a mesh file that maps the tissue surface. It must be specified as a path to [a `.ply` file](https://en.wikipedia.org/wiki/PLY_(file_format)) (the `mesh_file_path` input in the example below).
There is a function to read such a file in a MATLAB package, but we wrote a simple importer, documented below. It is a simplistic reader that can only handle one kind of data formatting. The file must be a binary encoded following the `binary_little_endian` format, there must be 3 floats per vertex, and 3 integers per face, nothing else. In this repo, you will find an example of such a file in `samples/AdultZebrafishBrainSimplifiedMesh.ply`.
@@ -241,7 +241,7 @@ This will generate a `deproj` object with the same capabilities as for the other
________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
-In the following we suppose that `dpr` or `obj` is an instance of `deproj` created by one of the two static methods described above.
+In the following we suppose that `dpr` or `obj` is an instance of `deproj` created by one of the two static methods described above.
#### `to_table`
@@ -308,7 +308,7 @@ ans =
`to_file( obj, file_name, include_header )`
-Exports results to a spreadsheet file.
+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.
@@ -323,9 +323,9 @@ dpr.to_file( 'table.xlsx' )
`[ hf, ax1, ax2 ] = figure_cell_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.
+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.
+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.figure_cell_sizes;
@@ -337,11 +337,11 @@ The `scale_bar_length` parameter specifies what should be the length (in physica
`[ hf, ax1, ax2, ax3 ] = figure_tissue_orientation( obj, scale_bar_length )`
-Generate a figure with the local plane orientation for each cell. This plane is the oblique plane that is tangent, or as close as possible, to the points on the cell boundary. Its orientation is given as the **3 Euler angles** in the [ZX'Z'' convention](https://en.wikipedia.org/wiki/Euler_angles#Chained_rotations_equivalence).
+Generate a figure with the local plane orientation for each cell. This plane is the oblique plane that is tangent, or as close as possible, to the points on the cell boundary. Its orientation is given as the **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.
+- 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.figure_tissue_orientation;
@@ -355,7 +355,7 @@ Generate a figure with the local plane orientation for each cell. This plane is
Plot the 2D ellipses on the 3D tissue surface.
-The ellipses are plotted in 3D, with the semi-major axis identified by a line. They are coloured by their orientation (projected on the XY plane). The output arguments are respectively `hf` the handle to the figure created and the two axes.
+The ellipses are plotted in 3D, with the semi-major axis identified by a line. They are colored by their orientation (projected on the XY plane). The output arguments are respectively `hf` the handle to the figure created and the two axes.
```matlab
>> dpr.figure_cell_elongation;
@@ -408,7 +408,7 @@ Plot the tissue with the cell exact contours, colored by the specified values.
This method generates the colored panels of the figures above. It takes all the cell boundaries, plot each of them as a patch, and color them according to the values in the `values` array. If you leave it empty or specify a color string (`'w'`, `'k'`, `'r'`, ..) the cell faces will be transparent and the cell borders will be painted with the specified color.
-The 3rd input arguments `ax` is not optional and specifies the handle of the axes to draw the cells in.
+The 3rd input arguments `ax` is not optional and specifies the handle of the axes to draw the cells in.
The output argument `hts` is the list of handles to the patch object created.
@@ -416,7 +416,7 @@ The output argument `hts` is the list of handles to the patch object created.
`hts = plot_values_ellipse( obj, values, ax )`
-Plot the tissue with cells as ellipses, colored by the specified values.This method does the same thing that the one described above, but plot the cells as their corresponding 2D ellipse, with one line for the major axis.
+Plot the tissue with cells as ellipses, colored by the specified values. This method does the same thing that the one described above, but plot the cells as their corresponding 2D ellipse, with one line for the major axis.
#### `plot_values_junction`
@@ -445,7 +445,7 @@ In the following we suppose that `o` is an instance of `epicell`, for instance o
```matlab
>> o = dpr.epicells(4)
-o =
+o =
epicell with properties:
@@ -633,5 +633,3 @@ The first output arguments `f3d` contains the ellipse parameter in cartesian for
- The angle of the semi-major axis with the X'' axis, after the composed rotation by the Euler angles.
The second argument `R` is the rotation matrix computed from the Euler angles.
-
-
diff --git a/DeProjProperties.md b/DeProjProperties.md
index 196e87144efdd2c60f553edbd150e02516ee9f57..a55a80085a6edad2e5b360373b52ea42a1516e8e 100644
--- a/DeProjProperties.md
+++ b/DeProjProperties.md
@@ -33,7 +33,7 @@ The DeProj toolbox revolves around two MATLAB classes:
- The `epicell`class is used to store the data for one cell in a tissue. It is made of several fields we describe below:
```matlab
-o =
+o =
epicell with properties:
@@ -55,7 +55,7 @@ o =
- The `deproj` class manages a collection of `epicell`s, and represent for instance the results of the analysis of a whole image.
```matlab
-dpr =
+dpr =
deproj with properties:
@@ -68,7 +68,7 @@ dpr =
### `boundary`
-The `boundary` property stores a 3D polygon that delimits the cell. It is represented as a `N x 3` matrix, with points sorted along the polygon. The coordinates are in physical units. The Z-values are the position of the vertices on the tissue surface, given the by the smoothed height-map.
+The `boundary` property stores a 3D polygon that delimits the cell. It is represented as a `N x 3` matrix, with points sorted along the polygon. The coordinates are in physical units. The Z-values are the position of the vertices on the tissue surface, given the by the smoothed height-map.
There are fewer than on vertex per pixel on the original segmentation image: we prune redundant points to lower the memory footprint of segmentation results.
@@ -93,7 +93,7 @@ The list of indices of junctions that this cell touches.
You can notice that a `deproj` instance has a `junction_graph` property. This is the graph of the junctions in the tissues. A junction is a location on the tissue surface where at least 3 cells connect. We give more details in the next section on `deproj` properties.
```matlab
-dpr =
+dpr =
deproj with properties:
@@ -110,7 +110,7 @@ ids =
10
16
->> j = dpr.junction_graph.Nodes( ids, : )
+>> j = dpr.junction_graph.Nodes( ids, : )
j =
@@ -135,11 +135,11 @@ j =
### `n_neighbors`
-How many neighbours have a cell. Note that for cells on the border of the tissue, we try to deal with border effects. For a cell at the border, we count the number of neighbours including all cells, even the ones not drawn because they are cropped by the image borders.
+How many neighbors have a cell. Note that for cells on the border of the tissue, we try to deal with border effects. For a cell at the border, we count the number of neighbors including all cells, even the ones not drawn because they are cropped by the image borders.
### `area`
-The area of the apical surface of the cell, delimeted by its boundary. This value reports the 3D area, of the de-projected cell on the tissue surface. Units are physical units; if you used a pixel size in µm, the area will be in µm².
+The area of the apical surface of the cell, delimited by its boundary. This value reports the 3D area, of the de-projected cell on the tissue surface. Units are physical units; if you used a pixel size in µm, the area will be in µm².
### `perimeter`
@@ -151,28 +151,28 @@ The orientation of the cell apical surface plane. This property is not entirely
The 3D boundary of the cell define an oblique plane to which they are the closest. This local plane has a certain orientation, that we give as the Euler angles, in radians, as a `1 x 3` array. The Euler angles are reported using the [ZX'Z'' convention](https://en.wikipedia.org/wiki/Euler_angles#Chained_rotations_equivalence). Repeating what we said in the example:
-- The first one, `alpha` is the orientation of the cell plane. 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`. Values within `[-π ; π[`.
-- 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. Values within `[0 ; π[`.
-- 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.
+- The first one, `alpha` is the orientation of the cell plane. 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`. Values within `[-π ; π[`.
+- 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. Values within `[0 ; π[`.
+- 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.
### `curvatures`
-Local curvature metrics at the cell center.
+Local curvature metrics at the cell center.
The height-maps gives the shape of the tissue surface, so we can derive the local curvature from it. The `curvatures` property is a `1 x 4` array that gives respectively:
- The [mean curvature](https://en.wikipedia.org/wiki/Mean_curvature).
- The [Gaussian curvature](https://en.wikipedia.org/wiki/Gaussian_curvature).
- The first [principle curvature](https://en.wikipedia.org/wiki/Principal_curvature).
-- The second principle curvature.
+- The second principle curvature.
-They are in physical units. If you used a pixel size in µm, the mean curvature, the first and second principle cuvature will be in 1/µm, and the Gaussian curvature will be in 1/µm².
+They are in physical units. If you used a pixel size in µm, the mean curvature, the first and second principle curvature will be in 1/µm, and the Gaussian curvature will be in 1/µm².
### `ellipse_fit`
Results of the fit of a 2D ellipse on the 3D boundary of the cell.
-The cell apical plane we discribe above, and which orientation is given by the `euler_angles` property, is the plane to which the 3D points of the boundary are the closest. If we project the 3D points on this plane, we can fit an ellipse to the projected 2D plane and yield a description of the cell extend and orientation. Caution: the ellipse fit is not made on the XY plane, but on an oblique plane locally tangent to the tissue. Check the Figure 3 on the example, and rotate it, to see that the ellipses have a 3D orientation.
+The cell apical plane we describe above, and which orientation is given by the `euler_angles` property, is the plane to which the 3D points of the boundary are the closest. If we project the 3D points on this plane, we can fit an ellipse to the projected 2D plane and yield a description of the cell extend and orientation. Caution: the ellipse fit is not made on the XY plane, but on an oblique plane locally tangent to the tissue. Check the Figure 3 on the example, and rotate it, to see that the ellipses have a 3D orientation.
The `ellipse_fit` contains the result of the fit, in this tangent plane, as a `1 x 6` array, containing respectively:
@@ -181,11 +181,11 @@ The `ellipse_fit` contains the result of the fit, in this tangent plane, as a `1
- The z coordinate of the ellipse center, in physical units. These 3 coordinates should have values very close that of the `center` property.
- The [semi-major axis of the ellipse](https://en.wikipedia.org/wiki/Ellipse#Semi-major_and_semi-minor_axes) `a`, in physical units.
- The semi-minor axis of the ellipse `b`, in physical units. We always have `a > b` and both values are positive.
-- The angle of the semi-major axis with the X'' axis in the rotated tangent plane, in radians. Because this plane was rotated twice with respect to the tissue (euler angles alpha and gamma, this value is not directly usable. See the `proj_direction` property.
+- The angle of the semi-major axis with the X'' axis in the rotated tangent plane, in radians. Because this plane was rotated twice with respect to the tissue (Euler angles alpha and gamma, this value is not directly usable. See the `proj_direction` property.
### `eccentricity`
-The ellipse [eccentricity](https://en.wikipedia.org/wiki/Ellipse#Eccentricity), derived from the `ellipse_fit` field.
+The ellipse [eccentricity](https://en.wikipedia.org/wiki/Ellipse#Eccentricity), derived from the `ellipse_fit` field.
It measures how elongated it the cell and varies from 0 to 1. Cells with an eccentricity of 0 resemble a circle. Cells with an eccentricity close to 1 are very elongated.
@@ -228,7 +228,7 @@ The nodes store their ID and the 3D position of their centroid, in physical unit
```matlab
>> g = dpr.junction_graph
-g =
+g =
graph with properties:
@@ -244,14 +244,14 @@ ans =
Centroid ID
___________________________ __
- 0.366 23.424 0.36189 1
- 0.732 19.581 0.98203 2
- 0.732 24.705 0.19083 3
- 1.098 4.575 3.898 4
- 0.976 24.034 0.3217 5
- 1.281 10.614 2.8064 6
- 1.464 3.294 4.3027 7
- 1.586 14.335 2.0956 8
+ 0.366 23.424 0.36189 1
+ 0.732 19.581 0.98203 2
+ 0.732 24.705 0.19083 3
+ 1.098 4.575 3.898 4
+ 0.976 24.034 0.3217 5
+ 1.281 10.614 2.8064 6
+ 1.464 3.294 4.3027 7
+ 1.586 14.335 2.0956 8
```
The edges simply store theirs source and target node ids:
@@ -266,14 +266,14 @@ ans =
EndNodes
________
- 1 5
- 1 10
- 3 5
- 3 11
- 4 7
- 4 14
- 5 16
- 6 12
+ 1 5
+ 1 10
+ 3 5
+ 3 11
+ 4 7
+ 4 14
+ 5 16
+ 6 12
```
Edges are undirected and there are no duplicates.
@@ -313,7 +313,7 @@ g = dpr.junction_graph;
'Marker', 'o', ...
'MarkerSize', 4, ...
'NodeColor', 'r' )
-
+
% Another simpler solution is to directly use a special deproj plotting method.
% This one plots the junction graph in 3D, with white edges. Uncomment it to try.
% dpr.plot_values_junction( 'w', gca )
@@ -326,4 +326,3 @@ g = dpr.junction_graph;
### `units`
This property simply stores the name of the physical unit of length that was specified at creation. It is useful to generate properly annotated figures.
-
diff --git a/README.md b/README.md
index 5a8266ef2b4a3729cb3ecd710d93b1c821186b79..a4351c1b63a35a9c08e9ba222342512bc1b6cfb4 100644
--- a/README.md
+++ b/README.md
@@ -27,9 +27,9 @@ DeProj is a MATLAB app made to yield accurate morphological measurements on cell
If you use this work for your Research, please cite the paper it is described in:
> __DProj: A toolbox for local 2D projection and accurate morphometrics of large 3D microscopy images.__
->
+>
> Sébastien Herbert, Léo Valon, Laure Mancini, Nicolas Dray, Paolo Caldarelli, Jérôme Gros, Elric Esposito, Spencer L. Shorte, Laure Bally-Cuif, Romain Levayer, Nathalie Aulner, Jean-Yves Tinevez
->
+>
> bioRxiv 2021.01.15.426809; doi: https://doi.org/10.1101/2021.01.15.426809
@@ -47,7 +47,7 @@ Finally, the segmentation is used to make morphological measurements (area, elon
### Projection artefacts.
-Most of the time, the morphological measurements are made directly on the 2D segmentation. This is fine as long as the tissue is mostly parallel to the XY plane, on which its 3D volume was projected.
+Most of the time, the morphological measurements are made directly on the 2D segmentation. This is fine as long as the tissue is mostly parallel to the XY plane, on which its 3D volume was projected.
When this is not the case, any **morphological measurements made on the segmentation results will be corrupted by geometrical distortions induced by the projection**. Indeed, almost all morphology metrics, such as area, circularity, polarity and orientation will be erroneous when they are measured on the 2D projection. This is illustrated on the figure below:
@@ -55,14 +55,14 @@ When this is not the case, any **morphological measurements made on the segmenta
On this illustration, a cell (in red, top-left quadrant) is located on a region of the tissue that makes a large angle with the XY plane. Its projection on the XY plane (in green, bottom-left quadrant) therefore underestimates its size, and alters its orientation. This is recapitulated on the top-right and bottom-right quadrants, with a side view.
-**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.
+**DeProj** is a tool made to correct for this distortion. 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.
-DeProj requires two inputs:
+DeProj requires two inputs:
-- the reference surface for the projected tissue,
-- and a black-and-white cell-contour image resulting from a segmentation algorithm that ran on the projection.
+- the reference surface for the projected tissue,
+- and a black-and-white cell-contour image resulting from a segmentation algorithm that ran on the projection.
From them, it computes accurate metrics on the morphology of cells, as if they were measured on the not on the 2D projection, but on the curved tissue itself. A simple GUI allows entering the two inputs. The reference surface can be entered either as the height-map generated by [LocalZProjector](https://gitlab.pasteur.fr/iah-public/localzprojector) (or another tool), or as a 3D mesh to accommodate a wide range of outputs from preprocessing tools.
@@ -70,7 +70,7 @@ The cell-contour image is internally converted to a collection of individual pol
### Requirements.
-We use builtin functions introduced in MATLAB R2019b. So you need at least this version.
+We use built-in functions introduced in MATLAB R2019b. So you need at least this version.
### Installation.
@@ -82,11 +82,11 @@ git clone git@gitlab.pasteur.fr:iah-public/DeProj.git
If you do not have `git` on your system, or don't want to use it, download [the zip of the repository](https://gitlab.pasteur.fr/iah-public/DeProj/-/archive/rework-pub/DeProj-rework-pub.zip).
-Then you want to add DeProj to your MATLAB path. To do so, simply add the `src` folder to the MATLAB path, but do not add its subfolders. It contains only two MATLAB classes: `@epicell` (that stores the data for a single deprojected cell) and `@deproj` that is used to create and manage a collection of `@epicell`s.
+Then you want to add DeProj to your MATLAB path. To do so, simply add the `src` folder to the MATLAB path, but do not add its subfolders. It contains only two MATLAB classes: `@epicell` (that stores the data for a single deprojected cell) and `@deproj` that is used to create and manage a collection of `@epicell`s.
-[This page](https://mathworks.com/help/matlab/ref/pathtool.html) explains how to add a folder to the MATLAB path.
+[This page](https://mathworks.com/help/matlab/ref/pathtool.html) explains how to add a folder to the MATLAB path.
-Again, it's important that you add the `src` folder to the path, but not its subfolders because they contain the DeProj classes methods. Details about MATLAB classes and path can be found [here](https://fr.mathworks.com/help/matlab/matlab_oop/organizing-classes-in-folders.html).
+Again, it's important that you add the `src` folder to the path, but not its subfolders because they contain the DeProj classes methods. Details about MATLAB classes and path can be found [here](https://fr.mathworks.com/help/matlab/matlab_oop/organizing-classes-in-folders.html).
To verify that this worked, just type:
@@ -97,7 +97,7 @@ To verify that this worked, just type:
in the MATLAB prompt. You should see the following:
```matlab
-ans =
+ans =
epicell with properties:
@@ -153,8 +153,8 @@ The plots are 3D plots of cells on the initial tissue surface. In this example,
DeProj computes the orientation of the local plane parallel to the cell apical surface. This the plane closest to the 3D points of the cell contour. Its orientation is reported as the 3 Euler angles, following the [ZX'Z'' convention](https://en.wikipedia.org/wiki/Euler_angles#Chained_rotations_equivalence). These 3 angles are displayed in the Figure 2 below.
- 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.
+- 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.
@@ -174,11 +174,11 @@ Because we have access the Z-position of each location thanks to the height-map,
-We can also measure the cell size (area and perimeter) on the XY projection, and compare the values to the real, deprojected area and perimeter. This gives an idea of the error caused b the projection distorsion. As expected, the error caused by the projection distorsion (Figure 5 below) is larger in areas where the local angle with the XY plane is the largest (middle panel in Figure 2 above). Again, on this example tissue, the slope is rather small so we have only a small error.
+We can also measure the cell size (area and perimeter) on the XY projection, and compare the values to the real, deprojected area and perimeter. This gives an idea of the error caused b the projection distortion. As expected, the error caused by the projection distortion (Figure 5 below) is larger in areas where the local angle with the XY plane is the largest (middle panel in Figure 2 above). Again, on this example tissue, the slope is rather small so we have only a small error.
-Finally we can also have a simplified plot of the cell contour, using the junctions. The following figure shows how many neighbours have a cell. Note that for cells on the border of the tissue, we try to deal with border effects. For a cell at the border, we count the number of neighbours including all cells, even the ones not drawn because they are cropped by the image borders.
+Finally we can also have a simplified plot of the cell contour, using the junctions. The following figure shows how many neighbors have a cell. Note that for cells on the border of the tissue, we try to deal with border effects. For a cell at the border, we count the number of neighbors including all cells, even the ones not drawn because they are cropped by the image borders.
@@ -192,9 +192,9 @@ DeProj is mainly made of two classes, and running it from the MATLAB prompt shou
You need two images as input.
-#### The segmentation mask.
+#### 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.
+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):
@@ -210,11 +210,11 @@ The height-map is an image <u>of the exact same size that the segmentation image
-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.
+On this example the pixel value is an integer that gives the Z-plane from which the projection pixel was taken. Several academic software 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).
+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:
@@ -297,7 +297,7 @@ What you get out this process is a `deproj` object:
```matlab
>> dpr
-dpr =
+dpr =
deproj with properties:
@@ -311,7 +311,7 @@ It manages mainly a collection of `epicell` objects, that store the data for one
```matlab
>> o = dpr.epicells(4)
-o =
+o =
epicell with properties:
@@ -347,12 +347,12 @@ ans =
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 ....
+ 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:
@@ -364,7 +364,7 @@ dpr.to_file( 'table.xlsx' )
-It can also be used to generate customisable plots. Several convenience methods are there:
+It can also be used to generate customizable plots. Several convenience methods are there:
```matlab
>> dpr.plot_sizes
@@ -376,7 +376,7 @@ It can also be used to generate customisable plots. Several convenience methods
The file [DeProjProperties.md](DeProjProperties.md) documents the properties you can find in the analysis results. They contain the metrics with which you can investigate the cells morphology.
-The file [DeProjMethods.md](DeProjMethods.md) documents the methods you can run with the objects returned by the analysis. Mainly they fall into three categories:
+The file [DeProjMethods.md](DeProjMethods.md) documents the methods you can run with the objects returned by the analysis. Mainly they fall into three categories:
- the methods that can generate a `deproj` object from various inputs (image + height-map, segmentation results + tissue mesh, any combination, *etc.*)
- the methods to generate the plot we exemplified above.
@@ -386,12 +386,12 @@ The file [DeProjMethods.md](DeProjMethods.md) documents the methods you can run
### Projection tools that yields the height-map.
-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:
+DeProj requires the height-map along with the segmentation of the projection, in order to "deproject" the cells onto the actual tissue surface. Here are some of the open-source projection tool that can return this output:
-- [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.
+- [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 height-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 [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).
@@ -399,6 +399,6 @@ DeProj requires the height-map along with the segmentation of the projection, in
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:
-- [EpiTools](https://github.com/epitools) is a toolbox with MATLAB and [Icy](http://icy.bioimageanalysis.org/) components built to study the dynamics of drosophila imaginal discs. Its segmentation algorithm relies on region growing from seeds determined automatically and merged based on region areas.
+- [EpiTools](https://github.com/epitools) is a toolbox with MATLAB and [Icy](http://icy.bioimageanalysis.org/) components built to study the dynamics of drosophila imaginal discs. Its segmentation algorithm relies on region growing from seeds determined automatically and merged based on region areas.
- [SEGGA](https://github.com/ZallenLab/SEGGA) is standalone applications written with MATLAB proposed for the investigation of drosophila embryo germband epithelium.
-- TissueAnalyzer is a tissue segmentation tool, distributed along [TissueMiner](https://github.com/mpicbg-scicomp/tissue_miner).
+- TissueAnalyzer is a tissue segmentation tool, distributed along [TissueMiner](https://github.com/mpicbg-scicomp/tissue_miner).