BP_DP-xlanro00/README.md

# About this Project

This project is being developed as a practical part of bachelor's thesis at Brno Universtiy of Technology - Faculty of Information Studies. It is as of now a work in progress, no results guaranteed.

The topic of this thesis is Generating a 3D Fingerprint Model. This application can be used to apply series of image processing filters to a fingerprint image to make it more suitable for conversion to 3D stl model and printing.
It also includes the functionality to use generated image as a height map for generating an stl model.
This model can either be planar or curved. 

# Prerequisites

For now this is only viable for ubuntu gnu/linux machines
Before cloning repository, you need these to succesfully use the application.

* python version 3.10 is a requirement might work on earlier python 3 versions

    ```sh
        apt install python3.10
    ```

* python graphical modules

    ```sh
        pip install numpy matplotlib pillow
    ```

# Installation

Installation is relatively fast and easy.

1. Clone the repository
    ```sh
        git clone ssh://git@strade.fit.vutbr.cz:3022/xlanro00/BP_DP-xlanro00.git
    ```

2. Prepare an image file containing fingerprint

3. Run the application


# Usage

There are two ways to enter filters

* manually from command line, list filter names and parameters
    ```sh
        python src/main.py res/test_fp.png res/test_fp_cpy.png 100 denoise_tv_chambolle iterations=1 weight=0.1 median ksize=3
    ```
* manually from preset saved in a json config file, that can be used to create new presets
    ```sh
        python src/main.py res/test_fp.png res/test_fp_cpy.png 100 --config config/config.json weak
    ```

# Configuration

There is an option to input the filter series as a preset to json configuration file.

```diff
{
    "weak": [
        {
            "name": "denoise_tv_chambolle",
            "sigmaColor": 0.1,
            "weight": 0.01,
            "sigmaSpace": 3,
            "channelAxis": 0,
            "iterations": 1
        },
        {
            "name": "median",
            "ksize": 3
        },
    ],
    "strong": [
        ...
    ]
    ...
}
```

All the filters used and their parameters will be described in documentation.

# Comparison

Image before processing the fingerprint and after applying a presets.

<table>
    <thead>
        <th>Before</th>
        <th>After</th>
    </thead>
    <tbody>
        <td><img src="res/examples_git/example-before.png?raw=true" width="400" /></td>
        <td><img src="res/examples_git/example-after.png?raw=true" width="400" /></td>
    </tbody>
</table>

# Generating STL file

It is possible to generate 3D printable stl planar model using `--stl` switch, which requires aditional parameter containing stl filename. Using `-p` switch makes the model planar. This is not the main goal of the application.
Additional parameters with model thickness and papilar lines height will be optional.

* Example stl generation
```sh
    python src/main.py res/test_fp.png res/test_fp_mod.png 508 --config config/config.json weak --stl res/test_fp.stl -p
```

# Generating STL finger model

When `--stl` switch is given without `-p`, the output model will either be a generated curved finger model, or later (if implemented) a fingerprint mapped to finger model.


# Mapping to existing finger model

This section will be added later.

# Roadmap

- [x] Load and store image
- [x] Apply basic image processing filters
    - [X] Scale the image using given dpi
- [X] Create filter library with more filters
    - [X] Add more suitable filters to the library
- [x] Use presets from config files
    - [ ] Add the option to save current filter preset to config file
- [X] Add the option to modify filter parameters
- [X] Convert the processed image to stl lithophane
- [ ] Add the option to curve the lithophane into the shape of a finger
- [ ] Add the option to map the lithophane on a given finger model
- [ ] Export final model ready for 3D print

#
### Author

Rostislav Lán - xlanro00@stud.fit.vutbr.cz

### Supervisor

Ing. Petr Malaník

### Links

Project Link: [https://strade.fit.vutbr.cz/git/xlanro00/BP_DP-xlanro00](https://strade.fit.vutbr.cz/git/xlanro00/BP_DP-xlanro00)