# Left atrial flattening
Author: Marta Nuñez-Garcia (marnugar@gmail.com)

## About
Implementation of the Left Atrial (LA) Fast Regional Flattening (FRF) method described in:
[*Fast quasi-conformal regional flattening of the left atrium*. Marta Nuñez-Garcia, Gabriel Bernardino, Francisco Alarcón, Gala Caixal, Lluís Mont, Oscar Camara, and Constantine Butakoff.  IEEE Transactions on Visualization and Computer Graphics (2020)](https://ieeexplore.ieee.org/abstract/document/8959311). Please cite this reference when using this code. Preprint available at: [arXiv:1811.06896.](https://arxiv.org/pdf/1811.06896.pdf) The code runs in Linux and Windows. 

Example:

![Example image](https://github.com/martanunez/LA_flattening/blob/master/example_im.png)

## Code
[Python](https://www.python.org/) scripts depending (basically) on [VTK](https://vtk.org/) and [VMTK](http://www.vmtk.org/). 

## Pipeline
The pipeline is split in 4 parts. You can skip the first ones depending on your input data.


- **1_mesh_standardisation:** standardises LA mesh, i.e. clip pulmonary veins (PVs), left atrial appendage (LAA), and mitral valve (MV). Launches GUI and asks the user to select 5 seeds close to the ending points of the 4 PVs and LAA. It returns a clipped mesh and auxiliary files containing info about seeds, clipping planes, etc. This script is adapted from [run_standardization](https://github.com/catactg/SUM) by Catalina Tobon Gomez. Related paper: [Benchmark for Algorithms Segmenting the Left Atrium From 3D CT and MRI Datasets.](https://ieeexplore.ieee.org/document/7029623) 
- **2_close_holes_project_info:** Closes holes corresponding to clipped PVs and LAA. Hole filling is done with [Butakoff's implementation](https://github.com/cbutakoff/tools/tree/master/FillSurfaceHoles) of the method published in P. Liepa "Filling Holes in Meshes", 2003. The binary file is included in this repository, you may need to provide execution permission (*chmod +x FillSurfaceHoles*). Hole filling can also be done manually with [reMESH.](http://remesh.sourceforge.net/) This script also marks the filled holes with a scalar array and additionally, transfers all scalar arrays in the input mesh to the output (closed) mesh.
- **3_divide_LA:** Parcellates mesh creating appropriate paths to divide the LA in the 5 pieces considered in our regional flattening. Launch GUI and ask the user to select the 9 required seeds. See seeds order here:
![Example image](https://github.com/martanunez/LA_flattening/blob/master/im_flat.png)
- **4_flat_atria:** Quasi-conformal LA regional flattening. Given a LA mesh with clipped & filled holes (PVs, LAA) and only 1 hole corresponding to the MV, it returns a flat (2D) version of the input mesh. Implementation of a conformal flattening considering 6 boundaries (4 PVs + LAA + MV) and the additional regional constraints (division lines) obtained in the previous step.

## Instructions
Clone the repository:
```
git clone https://github.com/martanunez/LA_flattening

cd LA_flattening
```

## Usage
```
1_mesh_standardisation.py [-h] [--meshfile PATH] [--pv_dist PV_DIST]
                                 [--laa_dist LAA_DIST] [--maxslope MAXSLOPE]
                                 [--clspacing CLSPACING]
                                 [--skippointsfactor SKIPPOINTSFACTOR]
                                 [--highslope HIGHSLOPE]
                                 [--bumpcriterion BUMPCRITERION]
                                 [--pvends PVENDS] [--vis VIS] [--save SAVE]

Arguments:
  --meshfile PATH       path to input mesh

Optional arguments:
  -h, --help            show this help message and exit
  --pv_dist PV_DIST     PV clipping distance (mm)
  --laa_dist LAA_DIST   LAA clipping distance (mm)
  --maxslope MAXSLOPE   Anything above this is ostium
  --clspacing CLSPACING
                        Resample the centerline with this spacing
  --skippointsfactor SKIPPOINTSFACTOR
                        Percentage of points to ignore at beginning of centerline
  --highslope HIGHSLOPE
                        Above this slope we start counting
  --bumpcriterion BUMPCRITERION
                        Ostium if slope higher than highslope and above bump criterion
  --pvends PVENDS       Enforce the centerline to reach the end boundary of the surface.
  --vis VIS             Set to 1 to visualise clipping results overlaid with original mesh
  --save SAVE           Set to 0 to remove intermediate results (centerlines, clippoints, etc.)
____________________________________________________________________________

2_close_holes_project_info.py [-h] [--meshfile_open PATH]
                                     [--meshfile_open_no_mitral PATH]
                                     [--meshfile_closed PATH]

Arguments:
  -h, --help            show this help message and exit
  --meshfile_open PATH  path to input mesh with clipped PVs and LAA
  --meshfile_open_no_mitral PATH
                        path to input mesh with additional MV clip
  --meshfile_closed PATH
                        path to output mesh, i.e. with filled holes
____________________________________________________________________________

usage: 3_divide_LA.py [-h] [--meshfile PATH]

Arguments:
  -h, --help       show this help message and exit
  --meshfile PATH  path to input mesh
___________________________________________________________________________

usage: 4_flat_atria.py [-h] [--meshfile PATH] [--save_conts SAVE_CONTS]
                       [--save_final_paths SAVE_FINAL_PATHS]

Arguments:
  --meshfile PATH       path to input mesh
  
Optional arguments:
  -h, --help            show this help message and exit
  --save_conts SAVE_CONTS
                        set to true to save mesh contours/contraints
  --save_final_paths SAVE_FINAL_PATHS
                        set to true to save modified dividing paths
```

## Usage example
```
python 1_mesh_standardisation.py --meshfile data/mesh.vtk --pv_dist 5 --laa_dist 5 --vis 1

python 2_close_holes_project_info.py --meshfile_open data/mesh_crinkle_clipped.vtk --meshfile_open_no_mitral  data/mesh_clipped_mitral.vtk --meshfile_closed data/mesh_clipped_c.vtk

python 3_divide_LA.py --meshfile data/mesh_clipped_c.vtk

python 4_flat_atria.py --meshfile data/mesh_clipped_c.vtk
```

## Dependencies
The scripts in this repository were successfully run with:
1. Ubuntu 16.04
    - [Python](https://www.python.org/) 3.5.2
    - [VMTK](http://www.vmtk.org/) 1.4
    - [VTK](https://vtk.org/) 9.1.0

2. Ubuntu 16.04
    - [Python](https://www.python.org/) 2.7.12
    - [VMTK](http://www.vmtk.org/) 1.4
    - [VTK](https://vtk.org/) 8.1.0
3. Windows 8.1
    - [Python](https://www.python.org/) 3.6.4
    - [VMTK](http://www.vmtk.org/) 1.4
    - [VTK](https://vtk.org/) 8.1.0
  
Other required packages are: NumPy, SciPy, xlsxwriter, Matplotlib, joblib, and python-tk.  

### Python packages installation
To install VMTK follow the instructions [here](http://www.vmtk.org/download/). The easiest way is installing the VMTK [conda](https://docs.conda.io/en/latest/) package (it additionally includes VTK, NumPy, etc.). It is recommended to create an environment where VMTK is going to be installed and activate it:

```
conda create --name vmtk_env
conda activate vmtk_env
```
Then, install vmtk:
```
conda install -c vmtk vtk itk vmtk
```
<!--Activate the environment when needed using:
```
source activate vmtk_env
```-->

**Nevertheless,** for Ubuntu, the easiest option for me was to build VMTK from source (slowly but surely). Instructions can be found [here.](http://www.vmtk.org/download/)
In brief:
```
git clone https://github.com/vmtk/vmtk.git
mkdir vmtk-build
cd vmtk-build
ccmake ../vmtk
make 
```
And edit the ~/.bashrc file,
```
gedit ~/.bashrc
```
adding the following line:  source /home/{your_path_to_vmtk}/vmtk/vmtk-build/Install/vmtk_env.sh


## Important note
You may need to slightly modify vmtkcenterlines.py from the VMTK package if you encounter the following error when running 1_mesh_standardisation.py:

```
     for i in range(len(self.SourcePoints)/3):
TypeError: 'float' object cannot be interpreted as an integer
```

Find vmtkcenterlines.py file and edit as follows:

Line 128: change ***for i in range(len(self.SourcePoints)/3):*** by ***for i in range(len(self.SourcePoints)//3):***

Line 133: change ***for i in range(len(self.TargetPoints)/3):*** by ***for i in range(len(self.TargetPoints)//3):*** 


## License
The code in this repository is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This code is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details: [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/)