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
    sudo apt install python3.10
    ```

* virtualenv for virtual enviroment creation

    ```sh
    pip install virtualenv
    ```

# Installation

1. Go to a suitable installation folder, for example Documents.
    ```sh
    cd /home/username/Documents
    ```

2. Clone the repository to a suitable directory, for example 
    ```sh
    git clone ssh://git@strade.fit.vutbr.cz:3022/xlanro00/BP_DP-xlanro00.git
    ```

3. Go inside cloned directory
    ```sh
    cd BP_DP-xlanro00
    ```

4. Create and enter the virtual enviroment.
    ```sh
    virtualenv .venv && source .venv/bin/activate
    ```

5. Install required python modules from requirements.txt.
    ```sh
    pip install -r requirements.txt
    ```

6. Run the application, as an example there is a file in res/examples called Palec_P4.tif. This is shown in the section below.

# Filtering images

* You will need to enter the virtual enviroment every time you want to use the application. 
    ```sh
    source .venv/bin/activate
    ```

Once all the requirements are installed, the program is ready to use. There are two ways to enter the filters:

1. manually list filter names and parameters from command line
    ```sh
    python3 src/main.py res/examples/Palec_P4.tif res/examples/Palec_P4_from_cline.png 600 total_variation weight=0.15 median ksize=5
    ```

2. from preset saved in a json config file, that can be used to tune and modify existing presetrs, or create new ones
    ```sh
    python3 src/main.py res/examples/Palec_P4.tif res/examples/Palec_P4_from_preset.png 600 --config config/config.json git_example
    ```

# Configuration and presets

There is an option to input the filter series as a preset from json configuration file. 
This preset is automatically stored inside a json file, which serves as a database for storing filters. 
This prevents losing filter preset information when modifying filter which was used to generate 3D models.

<table style="width:100%;">
  <thead>
    <tr>
      <th>General format</th>
      <th>Woking example</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <pre><code class="language-json">
{
    "preset": [
        {
            "name": "filter_name",
            "parameter": value,
            "parameter": value
        },
        {
            "name": "filter_name",
            "parameter": value
        }
    ],
    "preset": [
        ...
    ]
    ...
}
        </code></pre>
      </td>
      <td>
        <pre><code class="language-json">
{
    "git_example": [
        {
            "name": "denoise_tv_chambolle",
            "weight": 0.01,
            "iterations": 1
        },
        {
            "name": "median",
            "ksize": 3
        }
    ]
}
        </code></pre>
      </td>
    </tr>
  </tbody>
</table>

There is also an option to save current command line setting as a preset using -d switch:

* General command for saving filter preset
    ```sh
    python3 src/main.py input_file output_file dpi -d new_preset_name filters
    ```

* Working example
    ```sh
    python3 src/main.py res/examples/Palec_P4.tif res/examples/Palec_P4_from_cline.png 600 -d preset_gaussian gaussian sigma=1
    ```

All the filters used and their parameters are described below.

## Available filters with parameters

- median blur

    - ksize - Kernel size (int)

- gaussian blur

    - sigma - Gaussian kernel standart deviation (int)

- bilateral blur

    - diameter - Diameter of pixel neighborhood used for filtering (int)
    - sigmaColor - Standard deviation for grayvalue/color distance (int)
    - sigmaSpace - Standard deviation for range distance in pixels (int)

- bilateral_scikit

    - sigmaColor - Standard deviation for grayvalue/color distance (float)
    - sigmaSpace - Standard deviation for range distance in pixels (float)

- nlmeans (non-local means) 

    - patch_size - Size of patches used for denoising (int)
    - patch_distance - Distance in pixels where to search for patches (int)
    - h - Cut-off distance, higher means more smoothed image (float)

- total_variation

    - weight - Denoising weight. (float)

- block_match 

    - sigma - ? (?)

- unsharp mask scikit

    - radius - Radius of the gaussian filter (int)
    - amount - Strength of the unsharp mask (float)
    
- farid

- meijering

- sato

- hessian

    - sigmas - ? (float)

- invert

- scale_values

- binarize

    - threshold - value to cut differentiate pixels (int)
    - maxval - maximal value (int) ??
    - type - ? (str)

- binarize_otsu

- add_margin

    - margin - number of pixels to add to the sides of the image (int)
    - color - color value of newly added pixels (int)

- erode

    - kernel - kernel shape (numpy.matrix)

- dilate

    - kernel - kernel shape (numpy.matrix)

# 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 curved finger model

It is possible to generate 3D printable stl model using `--stl` switch, which requires aditional parameter containing stl filename. 
In base mode the output model will be a curved finger model, with optional parameters following the filename controlling its shape.
First optional parameter is papilar line height, second rate of curvature along x axis and the third is the rate of curvature along y axis. 

* General form for curved stl generation
    ```sh
    python3 src/main.py input_file output_file dpi --config config_file preset --stl c height_line height_base curvature_x curvature_y
    ```

* Working example curved stl generation
    ```sh
    python3 src/main.py res/examples/Palec_P4.tif res/examples/Palec_P4_from_preset.png 600 --config config/config.json git_example --stl c 2 10 2 2
    ```

# Generating planar finger model

Using `-p` switch makes the generated model planar.
Optional parameters are model base thickness and papilar lines height, they are set after stl file name.

* General form for planar stl generation
    ```sh
    python3 src/main.py input_file output_file dpi --config config_file preset --stl p height_line height_base
    ```

* Working example planar stl generation
    ```sh
    python3 src/main.py res/examples/Palec_P4.tif res/examples/Palec_P4_from_preset.png 600 --config config/config.json git_example --stl p 2 10
    ```

# Mapping to existing finger model

This section will be added later, (if implemented) mapping of fingerprint to a given finger model.

* General form for planar stl generation
    ```sh
    python3 src/main.py input_file output_file dpi --config config_file preset --stl m height_line height_base finger_file
    ```

# Usage

usage: main.py [-h] [-m | --mirror | --no-mirror] input_file output_file dpi ([-c | --config config_file preset] | [filters ...]) [-s | --stl_file p height_line height_base | --stl_file c height_line height_base curv_rate_x curv_rate_y | --stl_file m height_line height_base finger_file]

Program for processing a 2D image into 3D fingerprint.

positional arguments:
  input_file            input file path
  output_file           output file path
  dpi                   dpi of used scanner
  filters               list of filter names and their parameters in form [filter_name1 param1=value
                        param2=value filter_name2 param1=value...]

options:
  -h, --help            show this help message and exit
  -m, --mirror, --no-mirror
                        switch to mirror input image
  -s [STL_FILE ...], --stl_file [STL_FILE ...]
                        create stl model from processed image
  -c CONFIG CONFIG, --config CONFIG CONFIG
                        pair: name of the config file with presets, name of the preset

# 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
- [X] Add the option to curve the lithophane into the shape of a finger
- [ ] Add the option to map the fingerprint onto a given finger model
- [X] 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)