From 7cd8f0e2de202264ce2891f06678846f10f2a68b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rostislav=20L=C3=A1n?= Date: Sat, 6 May 2023 11:14:57 +0200 Subject: [PATCH] Updated docstrings to use sphinx style directives. --- src/config_parser.py | 25 ++++++++++++------- src/filters.py | 9 ++++--- src/log.py | 13 +++++----- src/main.py | 59 +++++++++++++++++++++++++++----------------- src/stl_parser.py | 12 ++++----- 5 files changed, 71 insertions(+), 47 deletions(-) diff --git a/src/config_parser.py b/src/config_parser.py index f603cf2..23b1d35 100644 --- a/src/config_parser.py +++ b/src/config_parser.py @@ -1,6 +1,7 @@ -"""! @file config_parser.py - @brief Config parser for fingerprint filtering and 3d model generation application - @author xlanro00 +"""Config parser for fingerprint filtering and 3d model generation application. + +.. moduleauthor:: xlanro00 + """ from os.path import exists @@ -9,7 +10,8 @@ import hashlib import log def save_preset(filters, params, preset_name): - '''Save filter preset to database. + '''Save filter list from command line to database. + :param filters: list of filters to be saved :param preset_name: name of preset to be saved ''' @@ -34,6 +36,7 @@ def save_preset(filters, params, preset_name): def store_to_db(preset, preset_name): '''Store filter preset to database. + :param preset: dictionary of filter preset to be stored :param preset_name: name of preset to be stored ''' @@ -73,8 +76,12 @@ def store_to_db(preset, preset_name): def parse_conf(preset_name, filters, params, config_file): - '''Parse configuration file if one was given. - Store filters and their parameters. + '''Parse configuration file if one was specified. + + :param preset_name: preset name to be loaded + :param filters: list of filters to be loaded + :param params: dictionary of filter parameters to be loaded + :param config_file: path to config file ''' if not exists(config_file): @@ -103,12 +110,12 @@ def parse_conf(preset_name, filters, params, config_file): def parse_params(params): - '''Parse parameters of filters. Set to None if parameter is not given. - They are later set to default values in the filter method apply. + '''Parse parameters of filters. Set to None if parameter is not specified. + These are later set to default values in the filter method apply. + :param params: dictionary of filter parameters ''' - # TODO: possibly too bloated, sending all possible params to each filter possible_params = {"sigma", "ksize", "kernel", "diameter", "sigmaColor", "sigmaSpace", "patch_size", "patch_distance", "weight", diff --git a/src/filters.py b/src/filters.py index da3b9f7..bb25465 100644 --- a/src/filters.py +++ b/src/filters.py @@ -1,6 +1,7 @@ -"""! @file filters.py - @brief Filter library for the application - @author xlanro00 +"""Filter library for the application + +.. moduleauthor:: xlanro00 + """ import numpy as np @@ -349,6 +350,8 @@ class binarize_otsu(img_filter): class add_margin(img_filter): + ''' Add margin to the image. + ''' def init(self, img): super().__init__(img) diff --git a/src/log.py b/src/log.py index c0570dc..f58fe5b 100644 --- a/src/log.py +++ b/src/log.py @@ -1,21 +1,22 @@ -"""! @file log.py - @brief File with printing functions - @author xlanro00 +"""Module with logging functions + +.. moduleauthor:: xlanro00 + """ import sys def print_message(*args, **kwargs): '''Print given message to stderr. - :param message: message to be printed + :param message: message to be printed to stderr ''' print("APP:", *args, file=sys.stderr, **kwargs) def error_exit(error_message): - '''Print given error message and exit the application. - :param message: error message to be printed + '''Print given error message to stderr and exit the application. + :param message: error message to be printed to stderr ''' print("ERROR: " + error_message, file=sys.stderr) diff --git a/src/main.py b/src/main.py index 65ad31a..16f1b23 100644 --- a/src/main.py +++ b/src/main.py @@ -1,6 +1,7 @@ -"""! @file main.py - @brief Main file for the application - @author xlanro00 +"""Main file of the project, contains filtering and stl generation functions + +.. moduleauthor:: xlanro00 + """ # Import basic libraries @@ -121,6 +122,8 @@ class fingerprint_app: self.args = parser.parse_args() def parse_stl(self): + '''Parse arguments for stl generation. + ''' # Get stl filename self.stl_path = self.output_file.rsplit('/', 1)[0] + '/' self.mode = self.args.stl[0] @@ -221,7 +224,8 @@ class fingerprint_app: return fig, ax def mirror_image(self): - '''Mirror image using opencv, should be used if we want a positive model. + '''Mirror image using opencv. + Should be used to cancel implicit mirroring. ''' log.print_message("Mirroring image") @@ -251,6 +255,9 @@ class fingerprint_app: def save_image(self, fig, ax): '''Save processed image to the output file. + + :param fig: figure used to render image. + :param ax: Ax used to render image. ''' log.print_message("Saving image to", self.output_file) @@ -262,7 +269,7 @@ class fingerprint_app: # ------------------------- STL GENERATION -------------------------# def run_stl(self): - '''Make heightmap, create mesh and save as stl file. + '''Choose correct generation code based on mode. ''' self.prepare_heightmap() @@ -286,8 +293,8 @@ class fingerprint_app: def prepare_heightmap(self): '''Scale image values to get values from 0 to 255. - Then compute base and papilar lines height. Check validity of dimension parameters. + Then compute base and papilar lines height. Prepare meshgrid, array which later serves to store point coordinates. ''' @@ -344,7 +351,7 @@ class fingerprint_app: def get_ID(self): '''Get a unique ID for the model, which is used in filename and on the model backside. - Also create parameter string for stl header, which is used to create ID using hash function SHA512. + Also create parameter string for stl header, which is used to create ID using hash function MD5. ''' # these are the same for all types of models @@ -412,7 +419,10 @@ class fingerprint_app: self.param_string.encode('utf-8')).hexdigest())[:10] def append_faces(self, faces, c): - ''' Function to add faces to the list of faces. + '''Add faces to the list of faces. + + :param faces: Array with faces. + :param c: Indices of currently added faces. ''' faces.append([c, c + 1, c + 2]) @@ -422,6 +432,9 @@ class fingerprint_app: def engrave_text(self, bottom_vert_arr, top_vert_arr): '''Engrave text on the back of the model. Create an empty image, fill it with color and draw text on it. + + :param bottom_vert_arr: Bottom vertex array. + :param top_vert_arr: Top vertex array ''' fig, ax = self.get_empty_figure() @@ -448,14 +461,11 @@ class fingerprint_app: fig.canvas.draw() data = np.frombuffer(fig.canvas.tostring_rgb(), dtype=np.uint8) data = data.reshape(fig.canvas.get_width_height()[::-1] + (3,)) - + plt.close() + # scale inscription layer to suitable height data = (data/255)/10 - plt.close() - - # TODO: this is very badly written, fix it - # TODO: this sometimes generates invalid mesh, fix it # add the bottom array OFFSET = 0.01 @@ -464,6 +474,8 @@ class fingerprint_app: for j in range(self.width): bottom_vert_arr[i][j][2] = data[i][j][0] elif self.mode == "c": + # TODO: this is very badly written, fix it, why is teh offset needed at all? + # TODO: this sometimes generates invalid mesh, fix it for j in range(self.width): bottom_vert_arr[i][j][2] += data[i][j][0] if (bottom_vert_arr[i][j][2] < (top_vert_arr[i][0][2])-OFFSET): @@ -474,7 +486,10 @@ class fingerprint_app: return bottom_vert_arr def create_stl_mesh(self, faces, vertices): - '''Create mesh from faces and vertices. + '''Create mesh from faces and vertices arrays. + + :param faces: Vector of face indices + :param vertices: Vector of vertices ''' # Convert lists to numpy arrays @@ -500,8 +515,10 @@ class fingerprint_app: def create_faces(self, top_vert_arr, bottom_vert_arr): '''Create faces for the model. - - Iterate over all vertices, append to vector and create faces from indices + Iterate over all vertices, append to vector and create faces from indices. + + :param bottom_vert_arr: Bottom vertex array. + :param top_vert_arr: Top vertex array ''' count = 0 @@ -563,9 +580,7 @@ class fingerprint_app: return faces, vertices def make_stl_planar(self): - ''' - Create vertices from meshgrid, add depth values from image. - Create faces from vertices. Add vectors and faces to the model. + '''Create vertices from meshgrid, add z coordinates from processed image heightmap. ''' # Add the image matrix to the 2D meshgrid and create 1D array of 3D points @@ -589,10 +604,8 @@ class fingerprint_app: self.create_stl_mesh(faces, vertices) def make_stl_curved(self): - '''Compute curved surface. - Create mesh from meshgrid. - Create vertices from meshgrid, add depth values from image. - Create faces from vertices. Add vectors and faces to the model. + '''Compute curved surface offset. + Create vertices from meshgrid, add z coordinates from processed image heightmap. ''' # Calculate the curved surface values diff --git a/src/stl_parser.py b/src/stl_parser.py index 76598c9..859bc2d 100644 --- a/src/stl_parser.py +++ b/src/stl_parser.py @@ -1,6 +1,7 @@ -"""! @file main.py - @brief Utility for parsing STL file header - @author xlanro00 +"""Utility for parsing STL file header + +.. moduleauthor:: xlanro00 + """ # Import basic libraries @@ -11,9 +12,8 @@ import log def stl_parser(): - """ Main function - Parses stl file header. - Returns command for running main.py with preformatted arguments. + """Parses stl file header. + Prints command for running main.py with preformatted arguments. """ # Parse arguments