# Delaunay-Watershed 2D
<img src="Figures_readme/Figure_logo_white_arrow.png" alt="drawing" width="300"/>
**Delaunay-Watershed-2D** is an algorithm designed to reconstruct a sparse representation of the geometry of tissues and cell nuclei from instance segmentations, in 2D. It accomplishes this by building multimaterial meshes from segmentation masks. These multimaterial meshes are perfectly suited for **storage, geometrical analysis, sharing** and **visualisation of data**. We provide high level APIs to extract geometrical features from the meshes, as well as visualisation tools based on matplotlib (2D).
Our multimaterial mesh is implemented using a [Half-Edge](https://en.wikipedia.org/wiki/Doubly_connected_edge_list) data structure.
Delaunay-Watershed was created by Sacha Ichbiah during his PhD in [Turlier Lab](https://www.turlierlab.com), and is maintained by Sacha Ichbiah, Matthieu Perez and Hervé Turlier. For support, please open an issue.
A preprint of the method will be published soon. If you use our library in your work please cite the paper.
Introductory notebooks with precise use case are provided.
The algorithm takes as input segmentation masks and return multimaterial polygonal lines (2D).
The original raw images can be inserted optionaly for visualisation but are not used for the reconstruction.
This method is used as a backend for [forceviewer2d](https://www.todo), our 2D tension inference library.
### Example
Load an instance segmentation, reconstruct its multimaterial mesh, and extract its geometry:
```shell
pip install delaunay-watershed-2d
```
```py
from dw2d import geometry_reconstruction_2d
## Load the labels
import skimage.io as io
labels = io.imread("data/Net_images/Masks/mask_Cells_3.tif")
## Reconstruct a multimaterial mesh from the labels
DW = geometry_reconstruction_2d(labels,expansion_labels=0, min_dist=5,original_image=img)
DW.simple_plot()
## Use the mesh to analyze the geometry:
Mesh = DW.return_dcel()
Mesh.compute_lengths()
Mesh.compute_angles()
Mesh.compute_curvatures()
```
### Installation
`pip install delaunay-watershed-2d`
---
### API and Documentation
#### 1 - Creating a multimaterial mesh:
The first step is to convert your instance segmentation into a multimaterial mesh
- `geometry_reconstruction_2d(labels,min_dist = 4 ,interpolation_points=10,expansion_labels = 0,original_image = None)`:
We infer tensions ratios by inverting junctional equilibrium relations
- `Mesh` is a `DCEL_Data` object
- `mean_tension` has to be defined as we only infer ratio between tensions
- `min_dist` defines the minimal distance, in pixels, between two points used for the delaunay-triangulation
- `interpolation_points` the number of sampling points used to estimate the value of the euclidean-distance-transform on an edge during the construction of the graph.
- `expansion_labels` can be used to expand the labels and make them touch each other.
- `original_image` can be used for visualization purposes
- `return DW`, an object containing visualization and export utilities
#### 2 - Visualize and export the mesh
Once a `DW` object is generated, we can use its methods the visualize and export the result:
- `DW:`
- `self.simple_plot()` offers a simple view of the segmentation
- `self.extended_plot()` offers more information, but need to provide the original image
- `self.return_mesh()` `return` (`Verts`,`Edges_multimaterial`):
- `Verts` is an V x 2 numpy array of vertex positions
- `Edges_multimaterial` is an F x 4 numpy array of Edges and material indices, where at each row the 2 first indices refers to a vertex and the 2 last refer to a given material, 0 being the exterior media
- `self.return_dcel()` return a `DCEL_Data` object, i.e a Half-edge implementation of the mesh
#### 3 - Analyze the geometry
A `DCEL_Data` object can be used to analyze the geometry:
- `DCEL_Data:`
- `self.compute_lengths()` returns a dictionnary with the values of the lengths of every interfaces
- `self.compute_angles()` returns a dictionnary with the values of every angles formed by the cells (in rad)
- `self.compute_area_faces()` returns a dictionnary with the values of the area of all the cells
- `self.compute_compute_curvatures()` returns a dictionnary with the values of the Menger curvature of all the interfaces
---
### Biological use-cases
#### Geometrical reconstruction of C.Elegans Embryo
Data from [cShaper](cao13jf.github.io/cshaperpage/)
#### Geometrical reconstruction of Cell Nuclei
Data from [dsb2018](https://www.kaggle.com/c/data-science-bowl-2018)
---
### Credits, contact, citations
If you use this tool, please cite the associated preprint:
Do not hesitate to contact Sacha Ichbiah and Hervé Turlier for practical questions and applications.
We hope that **Delaunay-Watershed** could help biologists and physicists to shed light on the mechanical aspects of early development.
Raw data
{
"_id": null,
"home_page": "https://github.com/sacha-ichbiah/delaunay_watershed_2d",
"name": "delaunay-watershed-2d",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Sacha Ichbiah",
"author_email": "sacha.ichbiah@college-de-france.fr",
"download_url": "https://files.pythonhosted.org/packages/4f/69/f463b482993bce52dd4fa675eb67cc79b8d8075c7b477254da0d73400530/delaunay_watershed_2d-0.1.4.tar.gz",
"platform": null,
"description": "# Delaunay-Watershed 2D\n\n<img src=\"Figures_readme/Figure_logo_white_arrow.png\" alt=\"drawing\" width=\"300\"/>\n\n\n**Delaunay-Watershed-2D** is an algorithm designed to reconstruct a sparse representation of the geometry of tissues and cell nuclei from instance segmentations, in 2D. It accomplishes this by building multimaterial meshes from segmentation masks. These multimaterial meshes are perfectly suited for **storage, geometrical analysis, sharing** and **visualisation of data**. We provide high level APIs to extract geometrical features from the meshes, as well as visualisation tools based on matplotlib (2D).\nOur multimaterial mesh is implemented using a [Half-Edge](https://en.wikipedia.org/wiki/Doubly_connected_edge_list) data structure.\n\n\nDelaunay-Watershed was created by Sacha Ichbiah during his PhD in [Turlier Lab](https://www.turlierlab.com), and is maintained by Sacha Ichbiah, Matthieu Perez and Herv\u00e9 Turlier. For support, please open an issue.\nA preprint of the method will be published soon. If you use our library in your work please cite the paper. \n\nIntroductory notebooks with precise use case are provided.\nThe algorithm takes as input segmentation masks and return multimaterial polygonal lines (2D).\nThe original raw images can be inserted optionaly for visualisation but are not used for the reconstruction.\n\nThis method is used as a backend for [forceviewer2d](https://www.todo), our 2D tension inference library.\n\n\n### Example \n\nLoad an instance segmentation, reconstruct its multimaterial mesh, and extract its geometry:\n\n```shell\npip install delaunay-watershed-2d\n\n```\n\n```py\nfrom dw2d import geometry_reconstruction_2d\n\n## Load the labels\nimport skimage.io as io\nlabels = io.imread(\"data/Net_images/Masks/mask_Cells_3.tif\")\n\n## Reconstruct a multimaterial mesh from the labels\nDW = geometry_reconstruction_2d(labels,expansion_labels=0, min_dist=5,original_image=img)\nDW.simple_plot()\n\n## Use the mesh to analyze the geometry:\nMesh = DW.return_dcel()\nMesh.compute_lengths()\nMesh.compute_angles()\nMesh.compute_curvatures()\n\n```\n\n### Installation\n\n`pip install delaunay-watershed-2d`\n\n---\n\n### API and Documentation\n\n#### 1 - Creating a multimaterial mesh:\nThe first step is to convert your instance segmentation into a multimaterial mesh\n\n- `geometry_reconstruction_2d(labels,min_dist = 4 ,interpolation_points=10,expansion_labels = 0,original_image = None)`: \nWe infer tensions ratios by inverting junctional equilibrium relations\n - `Mesh` is a `DCEL_Data` object\n - `mean_tension` has to be defined as we only infer ratio between tensions\n - `min_dist` defines the minimal distance, in pixels, between two points used for the delaunay-triangulation\n - `interpolation_points` the number of sampling points used to estimate the value of the euclidean-distance-transform on an edge during the construction of the graph.\n - `expansion_labels` can be used to expand the labels and make them touch each other.\n - `original_image` can be used for visualization purposes\n - `return DW`, an object containing visualization and export utilities\n\n#### 2 - Visualize and export the mesh\n\nOnce a `DW` object is generated, we can use its methods the visualize and export the result: \n- `DW:`\n - `self.simple_plot()` offers a simple view of the segmentation\n - `self.extended_plot()` offers more information, but need to provide the original image\n - `self.return_mesh()` `return` (`Verts`,`Edges_multimaterial`): \n - `Verts` is an V x 2 numpy array of vertex positions\n - `Edges_multimaterial` is an F x 4 numpy array of Edges and material indices, where at each row the 2 first indices refers to a vertex and the 2 last refer to a given material, 0 being the exterior media\n - `self.return_dcel()` return a `DCEL_Data` object, i.e a Half-edge implementation of the mesh\n\n#### 3 - Analyze the geometry\n\nA `DCEL_Data` object can be used to analyze the geometry:\n\n- `DCEL_Data:`\n - `self.compute_lengths()` returns a dictionnary with the values of the lengths of every interfaces\n - `self.compute_angles()` returns a dictionnary with the values of every angles formed by the cells (in rad)\n - `self.compute_area_faces()` returns a dictionnary with the values of the area of all the cells\n - `self.compute_compute_curvatures()` returns a dictionnary with the values of the Menger curvature of all the interfaces\n\n---\n### Biological use-cases\n#### Geometrical reconstruction of C.Elegans Embryo\nData from [cShaper](cao13jf.github.io/cshaperpage/)\n![](Figures_readme/DW_2d_celegans.png \"Title\")\n\n#### Geometrical reconstruction of Cell Nuclei\nData from [dsb2018](https://www.kaggle.com/c/data-science-bowl-2018)\n![](Figures_readme/DW_2d_nucleus.png \"Title\")\n\n---\n\n\n### Credits, contact, citations\nIf you use this tool, please cite the associated preprint: \nDo not hesitate to contact Sacha Ichbiah and Herv\u00e9 Turlier for practical questions and applications. \nWe hope that **Delaunay-Watershed** could help biologists and physicists to shed light on the mechanical aspects of early development.\n\n\n\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Geometrical reconstruction of cell assemblies from instance segmentations",
"version": "0.1.4",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "81cf0714858611cd1b2d07184709910d94a0e95bbad09f742c306daf58dd3c84",
"md5": "619405a7e362a4b0747186f3da9c2d65",
"sha256": "6257428c98ca72b015d59d136f2a5c6f871dc3ed1d4e7a9a83f0296ebd2aa3a2"
},
"downloads": -1,
"filename": "delaunay_watershed_2d-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "619405a7e362a4b0747186f3da9c2d65",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 20466,
"upload_time": "2023-01-27T13:02:55",
"upload_time_iso_8601": "2023-01-27T13:02:55.824543Z",
"url": "https://files.pythonhosted.org/packages/81/cf/0714858611cd1b2d07184709910d94a0e95bbad09f742c306daf58dd3c84/delaunay_watershed_2d-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4f69f463b482993bce52dd4fa675eb67cc79b8d8075c7b477254da0d73400530",
"md5": "3bd5695b93c80aae6a8734c2f99c58cd",
"sha256": "5013e87e0cc92d24e1892069a35facab28311b1ad5330d3a8dbcbb8388d3895f"
},
"downloads": -1,
"filename": "delaunay_watershed_2d-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "3bd5695b93c80aae6a8734c2f99c58cd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 18095,
"upload_time": "2023-01-27T13:02:59",
"upload_time_iso_8601": "2023-01-27T13:02:59.160424Z",
"url": "https://files.pythonhosted.org/packages/4f/69/f463b482993bce52dd4fa675eb67cc79b8d8075c7b477254da0d73400530/delaunay_watershed_2d-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-27 13:02:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "sacha-ichbiah",
"github_project": "delaunay_watershed_2d",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "delaunay-watershed-2d"
}
JSON
