Added working example to readme.
This commit is contained in:
175
README.md
175
README.md
@ -15,50 +15,88 @@ 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
|
||||
sudo apt install python3.10
|
||||
```
|
||||
|
||||
* python graphical modules
|
||||
* virtualenv for virtual enviroment creation
|
||||
|
||||
```sh
|
||||
pip install numpy==1.23.3 matplotlib==3.5.3 opencv-python=4.7.0.72
|
||||
stl==0.0.3 scikit-image==0.19.3
|
||||
pip install virtualenv
|
||||
```
|
||||
|
||||
# Installation
|
||||
|
||||
Installation is relatively fast and easy.
|
||||
1. Go to a suitable installation folder, for example Documents.
|
||||
```sh
|
||||
cd /home/username/Documents
|
||||
```
|
||||
|
||||
1. Clone the repository
|
||||
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
|
||||
```
|
||||
|
||||
2. Prepare an image file containing fingerprint
|
||||
3. Go inside cloned directory
|
||||
```sh
|
||||
cd BP_DP-xlanro00
|
||||
```
|
||||
v
|
||||
4. Create and enter the virtual enviroment.
|
||||
```sh
|
||||
virtualenv .venv && source .venv/bin/activate
|
||||
```
|
||||
|
||||
3. Run the application
|
||||
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
|
||||
|
||||
Once all the requirements are installed, the program is ready to use. There are two ways to enter filters:
|
||||
Once all the requirements are installed, the program is ready to use. There are two ways to enter the filters:
|
||||
|
||||
* manually from command line, list filter names and parameters
|
||||
1. manually list filter names and parameters from command line
|
||||
```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
|
||||
python3 src/main.py res/examples/Palec_P4.tif res/examples/Palec_P4.png 600 denoise_tv_chambolle iterations=1 weight=0.2 median ksize=5
|
||||
```
|
||||
|
||||
# Configuration
|
||||
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
|
||||
```
|
||||
|
||||
There is an option to input the filter series as a preset to json configuration file.
|
||||
# Configuration and presets
|
||||
|
||||
There is an option to input the filter series as a preset from json configuration file.
|
||||
|
||||
```diff
|
||||
{
|
||||
"weak": [
|
||||
"preset": [
|
||||
{
|
||||
"name": "filter_name",
|
||||
"parameter": value,
|
||||
"parameter": value
|
||||
},
|
||||
{
|
||||
"name": "filter_name",
|
||||
"parameter": value
|
||||
}
|
||||
],
|
||||
"preset": [
|
||||
...
|
||||
]
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
For example
|
||||
|
||||
```diff
|
||||
{
|
||||
"git_example": [
|
||||
{
|
||||
"name": "denoise_tv_chambolle",
|
||||
"weight": 0.01,
|
||||
@ -67,16 +105,59 @@ There is an option to input the filter series as a preset to json configuration
|
||||
{
|
||||
"name": "median",
|
||||
"ksize": 3
|
||||
},
|
||||
],
|
||||
"strong": [
|
||||
...
|
||||
}
|
||||
]
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
All the filters used and their parameters will be described in documentation.
|
||||
All the filters used and their parameters are described below.
|
||||
|
||||
## Available filters with parameters
|
||||
|
||||
-median blur
|
||||
-ksize - kernel size (int)
|
||||
|
||||
-gaussian blur
|
||||
-ksize - Gaussian kernel size (int)
|
||||
-sigmaX - Kernel deviation in X direction (float)
|
||||
-sigmaY - Kernel deviation in Y direction (float)
|
||||
|
||||
-bilateral blur
|
||||
-d - ? (int)
|
||||
-sigmaColor - ? (int)
|
||||
-sigmaSpace - ? (int)
|
||||
|
||||
-denoise
|
||||
-h - ? (int)
|
||||
-tWS - template window size (int)
|
||||
-sWs - search window size (int)
|
||||
|
||||
-denoise_bilateral
|
||||
-sigmaColor - ? (int)
|
||||
-sigmaSpace - ? (int)
|
||||
-iterations - ? (int)
|
||||
|
||||
-denoise_tv_chambolle
|
||||
-weight - ? (float)
|
||||
-iterations - ? (int)
|
||||
|
||||
-sharpen
|
||||
-kernel - ? (numpy.matrix)
|
||||
|
||||
-unsharp mask
|
||||
-strength - ? (float)
|
||||
-ksize - kernel size (int)
|
||||
|
||||
-unsharp mask scikit
|
||||
-radius - ? (int)
|
||||
-amount - ? (float)
|
||||
|
||||
-morph
|
||||
-kernel - ? (numpy.matrix)
|
||||
-iterations - ? (int)
|
||||
-op - opencv MORPH operation (MORPH_OPEN, MORPH_CLOSE,
|
||||
MORPH_DILATE, MORPH_ERODE)
|
||||
-anchor - ? (tuple)
|
||||
|
||||
# Comparison
|
||||
|
||||
@ -99,25 +180,59 @@ It is possible to generate 3D printable stl model using `--stl` switch, which re
|
||||
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.
|
||||
|
||||
* Example planar stl generation
|
||||
* General form for curved 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 2 2 4
|
||||
python3 src/main.py input_file output_file dpi --config config_file preset --stl 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 2 10 2 2
|
||||
```
|
||||
|
||||
# Generating planar finger model
|
||||
|
||||
Using `-p` switch makes the generated model planar. This is not the main goal of the application.
|
||||
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.
|
||||
|
||||
* Example curved stl generation
|
||||
* General form for planar 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 10 2 -p
|
||||
python3 src/main.py input_file output_file dpi --config config_file preset --stl height_line height_base -p
|
||||
```
|
||||
|
||||
* 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 2 10 -p
|
||||
```
|
||||
|
||||
# Mapping to existing finger model
|
||||
|
||||
This section will be added later, (if implemented) mapping of fingerprint to a given finger model.
|
||||
|
||||
# Usage
|
||||
|
||||
usage: main.py [-h] [-m | --mirror | --no-mirror] [-p] input_file output_file dpi ([-c | --config config_file preset] | [filters ...]) [-s | --stl height_line height_base | --stl_file height_line curv_rate_x curv_rate_y]
|
||||
|
||||
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
|
||||
-p, --planar, --no-planar
|
||||
make stl shape planar instead of curved one
|
||||
-c CONFIG CONFIG, --config CONFIG CONFIG
|
||||
pair: name of the config file with presets, name of the preset
|
||||
|
||||
# Roadmap
|
||||
|
||||
- [x] Load and store image
|
||||
@ -130,7 +245,7 @@ This section will be added later, (if implemented) mapping of fingerprint to a g
|
||||
- [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 lithophane on a given finger model
|
||||
- [ ] Add the option to map the fingerprint onto a given finger model
|
||||
- [X] Export final model ready for 3D print
|
||||
|
||||
#
|
||||
|
Reference in New Issue
Block a user