From d68471e1a98aa839aec3ed95402ebf7b433ad61a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rostislav=20L=C3=A1n?= Date: Mon, 6 Mar 2023 16:54:04 +0100 Subject: [PATCH] Added working example to readme. --- README.md | 171 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 143 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index f7310df..97cdc4d 100644 --- a/README.md +++ b/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 + ``` + +5. Install required python modules from requirements.txt. -3. Run the application + ```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 + 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 ``` -* manually from preset saved in a json config file, that can be used to create new presets + +2. from preset saved in a json config file, that can be used to tune and modify existing presetrs, or create new ones ```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_from_preset.png 600 --config config/config.json git_example ``` -# Configuration +# Configuration and presets + +There is an option to input the filter series as a preset from json configuration file. + +```diff +{ + "preset": [ + { + "name": "filter_name", + "parameter": value, + "parameter": value + }, + { + "name": "filter_name", + "parameter": value + } + ], + "preset": [ + ... + ] + ... +} +``` -There is an option to input the filter series as a preset to json configuration file. +For example ```diff { - "weak": [ + "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 + 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 - 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 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 + 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 - 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 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 #