pt2d 0.1.4
Interactive path tracing in 2D medical images
Requires Python: >=3.10

## pt2d (Path Tracing in 2D images)

_This repository is no longer being updated._

### Description

An interactive GUI for path tracing and extraction in 2D images. The inteded use is for 2D medical images of Amphisbaena sutures, but we have found that it extends well into other domains aswell for path extraction in 2D images.

The user places a start and end point between which the program automatically finds a viable path. The user can place multiple new guide points to help fit the path to their liking. The smoothness of the path can be adjusted aswell. Advanced settings are available.

The points making up the final path can be exported to a `.csv` file.

![General usage of the GUI](./images/GUI_gif.gif)

### Installation

The program can be installed using pip:

```plaintext
pip install pt2d
```

### Usage

To open the program type out `pt2d` in a terminal. The GUI looks the following:

![General GUI layout](./images/GUI.PNG)

The functionality of the program extends to the following:

* Main window:
    * Start/end point of the path
    * Add new points (left click)
    * Drag points (hold left click on point and drag)S
    * Drag image (hold left click and drag)
    * Remove points (right click on point)
    * Zoom (mouse wheel)
    * Export as `.csv` file
* Advanced window:
    * Rainbow toggle (displays a color gradient showing the order of points)
    * Calibration of filter
        * Resize dot (mouse wheel on dot)
    * Line smoothing
    * Contrast
    * Displays contrasted blurred image
    * Displays cost image

### Methodology

The project follows a simple methodology somewhat similar to that of the livewire segmentation technique.

* **Grayscaling:** The image is converted to grayscale for simpler processing.
* **Contrasting:** The contrast in the image is enhanced to improve visibility of the path.
* **Smoothing:** Gaussian blurring is applied to improve generalization.
* **Edge detection:** The Canny edge detector is applied to generate an image highlighting the edges in the original image.
* **Convolution:** A disk-shaped kernel, with values increasing radially from the center to the circumference, is convolved with the image to create a new image highlighting the centers of the paths.
* **Cost image creation:** A cost image is generated by first identifying the maximum intensity value of the convolved image, `I_max`. The cost at each pixel is then computed as `(I_max - I(x,y))**4`, where `I(x,y)` represents the intensity at pixel `(x,y)`.
* **Graph construction:** A graph is then constructed by connecting every pixel to it's 8 neighbouring pixels. The cost of going between two given pixels will simply be the average of the two pixel's values in the cost image.
* **Pathfinding:** Djikstra's algorithm is then applied to find the cheapest path from the user placed start point to the user placed end point.

### Known bugs & issues

* Guide points need to be placed in order from start to finish along the path for the extracted path not to overlap incorrectly.
* Dots don't currently scale with the image size, meaning the dots will appear small on large images.
* Exported points may have small inaccuracies in labelling which excact pixel point is the user placed point but is accurate to a few pixels in the image.
    * This is due to the way checking of user placed points is calculated. It is not locked to a specific pixel but is the shortest euclidean distance of the actual point and closest pixel in the path.

### Authors and acknowledgment

This project is developed by Aske T. Rove, Christian L. Bjerregaard & Mikkel W. Breinstrup under the supervision of Hans M. Kjer & Felipe D. Matos at DTU Compute.

### License

This project is licensed under the MIT License.