README.md

# Segmentation via Layered Surface Detection

This repository contains tutorials for the using the layered surface detection tool. Included is a few Jupyter notebook tutorials that are designed to give you an idea on how to use the layered surface tool. You should start with the _LayeredSurfaceDetection_tutorial.ipynb_ notebook which discuss the basics of the layered surface tool and applies it to some synthetic data as well as a relatively simple example dataset. More complex examples are provided in the _NerveSegmentation2D_example.ipynb_ and _NerveSegmentation3D_example.ipynb_ notebooks which describe how to apply the layered surface tool to circular regions via radial unwrapping. A Python file containing some helper functions that are used in the tutorials is also included in utilsLS.py_. Some visualization functions are included in the _utilsVisualizationLS.py_.

These tutorials will give you an understanding of how to apply the Layered Surface tool to image data so that you can use the tool on your own datasets. You can open the the tutorials at [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/git/https%3A%2F%2Flab.compute.dtu.dk%2FQIM%2Ftutorials%2Flayered-surfaces/HEAD).

For running the tool locally on your computer, you need to install the slgbuilder Python package using `pip install slgbuilder`.

If you are using Anaconda, you can automatically install the required packages using the included environment file:

Mac/Linux:
1. Navigate to the folder containing these tutorials and the `environment.yml` file.
2. To open the terminal, right click on the folder and navigate to
    - Mac: Services/New Terminal at Folder
    - Linux: Open in Terminal
3. Type `conda env create -f environment.yml` and press enter.
4. Type `conda activate qim-LS` and press enter.

Windows:
1. Open Anaconda Prompt.
2. `cd <tutorials_path>`, where tutorials_path is the absolute (full) path to the folder containing these tutorials.
3. Type `conda env create -f environment.yml` and press enter.
4. Type `conda activate qim-LS` and press enter.

The development of the tutorials is a combined effort from several researchers in the QIM team. The collection of scripts and exercises is in constant development, and actively used to demonstrate the tool and teach at workshops. We would therefore very much appreciate to hear about your experience. 

Please contact William Laprade wl@di.ku.dk with issues and feedback.

If you use the tool for research, please cite the developers' original paper: [Sparse layered graphs for multi-object segmentation.](https://openaccess.thecvf.com/content_CVPR_2020/papers/Jeppesen_Sparse_Layered_Graphs_for_Multi-Object_Segmentation_CVPR_2020_paper.pdf).

For inspiration, check out the following papers on user cases we have solved with the layered surfaces tool:

- Dahl, Dahl, Larsen. [Surface Detection using Round Cut.](https://ieeexplore.ieee.org/document/7182720) International Conference on 3D Vision, 2014. 
- Dahl, Andersson, Trinderup, Gundlach. [Layered Surface Detection in Micro-CT Tetra Pak Data.](https://ieeexplore.ieee.org/document/7182720) International Conference on Neutrons and Food 2016.
- Dahl, Einarsson, Darvann, Hermann, Hove, Kakimoto, Kreiborg, Dahl. [Automatic measurement of orbital volume in unilateral coronal synostosis.](https://ieeexplore.ieee.org/document/7493408) International Symposium on Biomedical Imaging 2016.
- Lindberg, Larsen, Dahl, Jørgensen, Hamann. [Quantitative measure of optic disc drusen location in enhanced depth imaging optical coherence tomography scans.](https://iovs.arvojournals.org/article.aspx?articleid=2638057) Investigative Ophthalmology & Visual Science, 2017.
- Malmqvist, Lindberg, Dahl, Jørgensen, Hamann. [Quantitatively measured anatomic location and volume of optic disc drusen: an enhanced depth imaging optical coherence tomography study.](https://iovs.arvojournals.org/article.aspx?articleid=2624602) Investigative Ophthalmology & Visual Science, 2017.
- Christensen, Larsen, Jensen, Petersen, Larsen, Conradsen, Dahl. [Automatic segmentation of abdominal fat in MRI-Scans, using graph-cuts and image derived energies.](https://link.springer.com/chapter/10.1007%2F978-3-319-59129-2_10) Image Analysis, Lecture Notes in Computer Science, 2017.
- Dahl, Dahl, Trinderup, Gundlach. [Layered surface detection for virtual unrolling.](https://ieeexplore.ieee.org/document/8545715) International Conference on Pattern Recognition, 2018.
- Bodner, Bentzen, Dahl, Alfaro, Steenberg, Hjuler, Simonsen. [Structural characterization of membrane-electrode-assemblies in high temperature polymer electrolyte membrane fuel cells.](https://iopscience.iop.org/article/10.1149/2.0981914jes) Journal of the Electrochemical Society, 2019.
- Borg, Sporring, Dam, Dahl, Dyrby, Feidenhans’l, Dahl, Pingel. [Muscle fibre morphology and microarchitecture in cerebral palsy patients obtained by 3D synchrotron X-ray computed tomography.](https://pubmed.ncbi.nlm.nih.gov/30878888/) Computers in Biology and Medicine, 2019.
- Dahlin, Rix, Dahl, Dahl, Jensen, Cloetens, Pacureanu, Mohseni, Thomsen, Bech. [Three-dimensional architecture of human diabetic peripheral nerves revealed by X-ray phase contrast holographic nanotomography.](https://www.nature.com/articles/s41598-020-64430-5) Scientific Reports, 2020.
- Jeppesen, Christensen, Dahl, Dahl. [Sparse layered graphs for multi-object segmentation.](https://openaccess.thecvf.com/content_CVPR_2020/papers/Jeppesen_Sparse_Layered_Graphs_for_Multi-Object_Segmentation_CVPR_2020_paper.pdf) Conference on Computer Vision and Pattern Recognition, 2020.
- Jensen, Dahl, Dahl. [Multi-object graph-based segmentation with non-overlapping surfaces.](https://openaccess.thecvf.com/content_CVPRW_2020/html/w57/Jensen_Multi-Object_Graph-Based_Segmentation_With_Non-Overlapping_Surfaces_CVPRW_2020_paper.html) Computer Vision for Microscopy Image Analysis, 2020.
- Linndberg, Dahl, Karlesand, Rueløkke, Malmquist, Hamann. [Determination of peripapillary vessel density in optic disc drusen using EDI-OCT and OCT angiography.](https://www.sciencedirect.com/science/article/pii/S001448352030381X) Experimental Eye Research, 2020.
- Andersson, Kjer, Rafael-Pation, Pacureanu, Pakkenberg, Thiran, Ptito, Bech, Dahl, Dahl, Dyrby. [Axon morphology is modulated by the local environment and impacts the noninvasive investigation of its structure-function relationship.](https://www.pnas.org/content/117/52/33649) Proceedings of the National Academy of Sciences of the United States of America, 2020.
- Engberg, Amini, Willerslev, Larsen, Sander, Kessel, Dahl, Dahl. [Automated quantification of macular vasculature changes from OCTA images of hematologic patients.](https://ieeexplore.ieee.org/document/9098441/) International Symposium on Biomedical Imaging, 2020.