diff --git a/README.md b/README.md index bef1dfa..691652e 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,19 @@ # 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. +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. -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. +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. + +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. # Prerequisites -For now this is only viable for ubuntu gnu/linux machines +For now this is only viable for ubuntu gnu/linux machines. +It should however be possible to run it in WSL and virtual machines of most linux distributions. 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 @@ -18,7 +22,7 @@ Before cloning repository, you need these to succesfully use the application. sudo apt install python3.10 ``` -* virtualenv for virtual enviroment creation +* virtualenv package for virtual enviroment creation, other packages are installed automatically later ```sh pip install virtualenv @@ -26,57 +30,65 @@ Before cloning repository, you need these to succesfully use the application. # Installation -1. Go to a suitable installation folder, for example Documents. +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 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 +3. Go inside cloned directory: ```sh cd BP_DP-xlanro00 ``` -4. Create and enter the virtual enviroment. +4. Create and enter the virtual enviroment: ```sh virtualenv .venv && source .venv/bin/activate ``` -5. Install required python modules from requirements.txt. +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. +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. # Filtering images -* You will need to enter the virtual enviroment every time you want to use the application. +Once all the requirements are installed, the application is ready to use. + +* 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: +* The application requires input and output filenames including path from the root project directory, dpi and filter list. + ```sh + python3 src/main.py input_file output_file dpi filters + ``` + +There are two ways to enter the filters: -1. manually list filter names and parameters from 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. from preset saved in a json config file, that can be used to tune and modify existing presetrs, 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 config/config.json git_example + 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. -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. +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. @@ -129,19 +141,14 @@ This prevents losing filter preset information when modifying filter which was u
-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 - ``` +There is also an option to save current command line setting as a preset using -d switch and it's new name: * 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. +List of all implemented filters and their parameters is described below. ## Available filters with parameters @@ -235,9 +242,10 @@ Image before processing the fingerprint and after applying a presets. # 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. +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 @@ -251,15 +259,15 @@ First optional parameter is papilar line height, second rate of curvature along # 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. +Using `p` mode makes the generated fingerprint model flat. +Optional parameters are height of the papilar lines and base thickness. -* General form for planar stl generation +* General command 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 +* Working example of 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 ``` @@ -268,7 +276,7 @@ Optional parameters are model base thickness and papilar lines height, they are This section will be added later, (if implemented) mapping of fingerprint to a given finger model. -* General form for planar stl generation +* 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 height_base finger_file ``` @@ -303,12 +311,12 @@ options: - [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 save current filter preset to config file - [X] Add the option to modify filter parameters -- [X] Convert the processed image to stl lithophane +- [X] Convert the processed image to flat 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 +- [ ] Add the option to map the fingerprint onto a given finger model # ### Author