Added working example to readme.

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
+        pip install virtualenv
-        stl==0.0.3 scikit-image==0.19.3
     ```
 
 # 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
+        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
 
 #