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

Document the from_bellaiche import.

parent 2ec081ca
......@@ -49,6 +49,8 @@ A `deproj` instance has several interesting methods, that let you export and dis
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.
##### The import.
```matlab
obj = deproj.from_heightmap( ...
I, ...
......@@ -65,7 +67,9 @@ 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 segmentation mask image `I`.
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](static/8-connectivity.png)
......@@ -75,12 +79,16 @@ The following is **not good** (the ridges only move east west north and south):
![img](static/4-connectivity.png)
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:
##### The height-map `H`.
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. Sometimes it is called the elevation map, *etc.* For instance:
![img](static/HeightMap-2.png)
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).
```matlab
......@@ -163,6 +171,62 @@ dpr =
In the following we suppose that `dpr` is an instance of `deproj` created by this example.
#### 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 Bellaiche](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.
See the following paper for its reference use:
> [**Unified quantitative characterization of epithelial tissue development.**](https://elifesciences.org/articles/08519)
>
> Boris Guirao, Stéphane U Rigaud, Floris Bosveld, Anaïs Bailles, Jesús López-Gay, Shuji Ishihara, Kaoru Sugimura, François Graner, Yohanns Bellaïche.
> eLife, vol. 4 (**2015**)
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:
- `CELLS` contains the invidiual 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.
- `FRAME` is a `struct` that contains information about the image that was used to generate the segmentation results. DeProj uses:
- `imageSize`, a 2 elements array specifying the width and height of the source image.
- `scale1D` the pixel size in physical units.
- `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`, 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.
If at least all these variables are present, DeProj can import such a segmentation with the method `from_bellaiches`.
##### 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).
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`.
It is important that the vertex coordinates are in physical coordinates and in the same referential that the cell coordinates. Depending on how you generate the tissue mesh, it might be an issue. Some software tend to use a referential where the (0, 0, 0) coordinate is a the center of the mesh, while our cells have boundaries defined from the top-left of the image. If you have to edit, simply or translate a mesh, we suggest using *e.g.* the [MeshLab software](https://www.meshlab.net/).
##### The import.
Once you have these two elements, the import is as follow:
```matlab
dpr = deproj.from_bellaiche( ...
CELLS, ...
FRAME, ...
SIDES, ...
VERTICES, ...
mesh_file_path, ...
units );
```
This will generate a `deproj` object with the same capabilities as for the other import. See the `RunExample2.m` script for an example of such an import.
#### `to_table`
`T = to_table( obj )`
......
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