xlanro00/BP_DP-xlanro00
1
1
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Updated README to substitute old manual.

Browse Source
This commit is contained in:
Rostislav Lán
2023-05-06 12:10:16 +02:00
parent 91d3fb14b1
commit 2acc98ceef
2 changed files with 194 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
README.md
View File

@ -1,14 +1,15 @@
# About this Project
This project is being developed as a practical part of bachelor's thesis at Brno University of Technology - Faculty of Information Technology.
It is as of now a work in progress.
This application has been developed as a part of bachelor's thesis at Brno University of Technology - Faculty of Information Technology.
The topic of this thesis was Generating a 3D Fingerprint Model from input fingerprint image.
The topic of this thesis is Generating a 3D Fingerprint Model from input fingerprint image.
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.
This application consists of two main parts. The first part of the application uses custom filter library to apply image filters to enhance fingerprint images.
This library consists of several filters imported from image processing modules.
The second part of the project includes the functionality to use generated image as a height map for generating 3D model in stl format.
This model can either be planar, curved or mapped.
The second part uses the processed image to make a 3D model of the fingerprint.
The model can then be used to print an accurate representation of human fingerprint using a 3D printer.
This model can either be planar, curved or mapped to a finger model.
# Prerequisites
@ -18,13 +19,13 @@ It should however be possible to run it in on most distributions, WSL and virtua
This guide is for Ubuntu machines only.
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
* **python** version 3.10 is a requirement might work on earlier python 3 versions
```sh
sudo apt install python3.10
```
* virtualenv package for virtual enviroment creation, other packages are installed automatically later
* **virtualenv** package for virtual enviroment creation, other packages are installed automatically later
```sh
pip install virtualenv
@ -32,67 +33,105 @@ Before cloning repository, you need these to succesfully use the application.
# Installation
1. Go to a suitable installation folder, for example Documents:
This will install the application and its components into the Documents directory.
It will also install several required python packages, including **venv**, which is used to create a virtual enviroment. Just paste and these commands into the command line.
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:
2. Clone the repository to this directory:
```sh
git clone ssh://git@strade.fit.vutbr.cz:3022/xlanro00/BP_DP-xlanro00.git
```
3. Go inside cloned directory:
3. Go inside the newly created directory:
```sh
cd BP_DP-xlanro00
```
4. Create and enter the virtual enviroment:
4. Create and activate the virtual enviroment:
```sh
virtualenv .venv && source .venv/bin/activate
```
5. Install required python modules from requirements.txt:
5. Automatically install required python modules from **requirements.txt**:
```sh
pip install -r requirements.txt
```
6. Now, you can run the application, as an example there is a file in res/examples called Palec_P4.tif. This is shown in the section below.
Now, you are all set to run the application.
Examples of how to do this are shown in the section bellow.
# Filtering images
Once all the requirements are installed, the application is ready to use.
Fingerprint sample is located in res/examples, its name is Palec_P4.tif.
* You will need to enter the virtual enviroment every time you want to use the application.
```sh
source .venv/bin/activate
```
* The application requires input and output filenames including path from the root project directory, dpi and filter list.
* The application requires **input** and **output filenames** including path from the root project directory, **dpi** and **filter list** as shown bellow.
```sh
python3 src/main.py input_file output_file dpi filters
```
There are two ways to enter the filters:
1. manually list all filter names and their parameters on the command line:
1. manually list all filter names and their parameters on the **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. load them from preset in a JSON configuration file, that can be used to tune and modify existing presets, or create new ones:
2. load them from preset in a JSON **configuration file**, that can be used to tune and modify existing presets, or create new ones:
```sh
python3 src/main.py res/examples/Palec_P4.tif res/examples/Palec_P4_from_preset.png 600 --config conf/conf.json git_example
```
# Configuration and presets
There is an option to input the filter series as a preset from JSON configuration file.
To avoid accidental loss of information caused by modifying presets that have been used to generate stl files,
these presets are stored inside a JSON file db.json.
This file serves as a simple database for storing presets, stored presets are modified by adding generated hash of all the filters in that preset.
<table style="width:100%;">
There is an option to input the filter series as a preset from JSON configuration file.
Here the presets are stored and are ready to be used whenever needed. You can usehow many filters you need as long as you like the output.
It is therefore highly recommended to check the output after every preset change.
Filter used in the example above is listed bellow, along with the general form of configuration file.
<style>
table {
border-collapse: collapse;
width: 100%;
}
th, td {
padding: 8px;
text-align: left;
border-bottom: 1px solid #ddd;
}
th {
background-color: #f2f2f2;
}
.code {
font-family: 'Courier New', monospace;
background-color: #f5f5f5;
padding: 8px;
}
.language-json {
color: #333;
}
</style>
<table>
<thead>
<tr>
<th>General format</th>
@ -143,12 +182,11 @@ This file serves as a simple database for storing presets, stored presets are mo
</tbody>
</table>
There is also an option to save current command line setting as a preset using -d switch and it's new name:
To avoid accidental loss of information caused by modifying presets that have been used to generate stl files,
these presets are stored inside a JSON file db.json.
* 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
```
This file serves as a simple database for storing presets, stored presets are modified by adding generated hash of all the filters in that preset.
There is also an option to save current command line setting as a preset using -d switch and it's new name:
## Available filters with parameters
@ -192,6 +230,11 @@ Overview of all implemented filters and their parameters with descriptions is li
- radius (int) - Radius of the gaussian filter.
- amount (float) - Strength of the unsharp mask, determines how much of the mask will be used for filtering.
- unsharp mask pil
- radius (int) - Radius of the gaussian filter.
- amount (float) - Strength of the unsharp mask, determines how much of the mask will be used for filtering.
- threshold (int) -
- farid
- meijering
@ -235,40 +278,45 @@ Image before processing the fingerprint and after applying a presets.
<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>
<td><img src="res/example/example_git/example-before.png?raw=true" width="400" /></td>
<td><img src="res/example/example_git/example-after.png?raw=true" width="400" /></td>
</tbody>
</table>
# Generating curved finger model
It is possible to generate stl model using the `--stl` switch. This requires more parameters, first of which is the type of generated fingerprint.
If the mode is set to `c`, 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 `height_line`, second is thickness of the model `height_base`,
third the rate of curvature along x axis `curv_rate_x` and the third is the rate of curvature along y axis `curv_rate_y`.
* General form for curved stl generation
```sh
* General form for curved stl generation:
```
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
* Working example curved stl generation:
```
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` mode makes the generated fingerprint model flat.
Optional parameters are height of the papilar lines and base thickness.
* General command form for planar stl generation
```sh
* General command form for planar stl generation:
```
python3 src/main.py input_file output_file dpi --config config_file preset --stl p height_line height_base
```
* Working example of planar stl generation
```sh
* Working example of planar stl generation:
```
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
```
@ -280,18 +328,26 @@ The last three parameters are axis offsets for the finger, `finger_x`, `finger_y
These control the location of the finger. They need to be set only if the user wants to move core of the print closer to the center of the finger.
* General command form for mapped stl generation
```sh
```
python3 src/main.py input_file output_file dpi --config config_file preset --stl m height_line iter finger_x finger_y finger_z
```
* Working example of finger mapping
```sh
```
python3 src/main.py res/examples/Palec_P4.tif res/examples/Palec_P4.png 600 --config conf/conf.json ridge --stl m 0.2 2 0 0 0
```
# 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 m height_line iter finger_x finger_y finger_z] [-d | --database database_filename]
When in doubt, you can always check the help with:
python3 src/main.py --help
Which will print out the following message.
```
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 m height_line iter finger_x finger_y finger_z finger_model [-d | --database database_filename]
Program for processing a 2D image into 3D fingerprint.
@ -310,6 +366,100 @@ options:
create stl model from processed image
-c CONFIG CONFIG, --config CONFIG CONFIG
pair: name of the config file with presets, name of the preset
```
# Troubleshooting
<table>
<thead>
<tr>
<th>Error message</th>
<th>Solution</th>
</tr>
</thead>
<tbody>
<tr>
<td>
main.py: error: the following arguments are required: input_file, output_file, dpi, filters
</td>
<td>
You probably forgot to include some of the required arguments.
</td>
</tr>
<tr>
<td>
ERROR: Input file res/Palec_P14.tif does not exist
</td>
<td>
The file you want to process does not exist, check the filename again.
</td>
</tr>
<tr>
<td>
ERROR: Config file not found
</td>
<td>
The config file you want to load config from does not exist, check the filename again.
</td>
</tr>
<tr>
<td>
ERROR: Preset not found in config file
</td>
<td>
The preset is not present in selected config file, check the file again or select the correct config file.
</td>
</tr>
<tr>
<td>
ERROR: Filter undefined_filter not found
</td>
<td>
One of the filters from command line is not defined in the library, check its name.
</td>
</tr>
<tr>
<td>
ERROR: Unrecognized generation mode
</td>
<td>
The first parameter of stl generation should be p, c or m, check it again.
</td>
</tr>
<tr>
<td>
ERROR: Line depth must be less than plate thickness
</td>
<td>
When generating a cast, the depth must be less than the base plate thckness, otherwise it would have holes on the other side.
</td>
</tr>
<tr>
<td>
ERROR: Depth of plate height must be positive
</td>
<td>
Cannot generate negative base plate thickness, check order of arguments.
</td>
</tr>
<tr>
<td>
ERROR: Base and line height must both be positive
</td>
<td>
In curved generation any negative argument is an error, casts are only for planar mode.
</td>
</tr>
<tr>
<td>
ERROR: Fingerprint image is outside of the finger model
</td>
<td>
Outside of range of the finger, fingerprint cannot be mapped to nothing. Try to change finger_x, finger_y and finger_z parameters.
</td>
</tr>
</tbody>
</table>
# Roadmap
@ -324,7 +474,8 @@ options:
- [X] Convert the processed image to flat stl lithophane
- [X] Add the option to curve the lithophane into the shape of a finger
- [X] Export final model ready for 3D print
- [ ] Add the option to map the fingerprint onto a given finger model
- [X] Add the option to map the fingerprint onto a given finger model
- [X] Finalize, document everything
#
### Author

2
src/test.sh
View File

@ -25,7 +25,7 @@ config_file=conf/conf.json
# name of preset in conf. file
presets=("ridge")
# generate stl files and set generation mode {"planar", "curved", "mapped"}
# generate stl files and set generation mode {"p" for planar, "c for curved, "m" for mapped}
generate_stl=true
generate_stl_mode="c"