Updated docstrings to use sphinx style directives.

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", 

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)
 

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)

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

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