Update docs

discorpy/proc/processing.py

@@ -286,7 +286,7 @@ def find_cod_fine(list_hor_lines, list_ver_lines, xcenter, ycenter, dot_dist):
     return xcenter2, ycenter2
 
 
-def _check_missing_lines(list_coef_hor, list_coef_ver):
+def _check_missing_lines(list_coef_hor, list_coef_ver, threshold=0.3):
     """
     Check if there are missing lines
 
@@ -296,6 +296,8 @@ def _check_missing_lines(list_coef_hor, list_coef_ver):
         Coefficients of parabolic fits of horizontal lines.
     list_coef_ver : list of 1D arrays
         Coefficients of parabolic fits of vertical lines.
+    threshold : float
+        To determine if there are missing lines. Larger is less sensitive.
 
     Returns
     -------
@@ -314,7 +316,7 @@ def _check_missing_lines(list_coef_hor, list_coef_ver):
                    vfact[1] * list_vindex + vfact[2]
     herror = np.max(np.abs((list_dist_hor - list_fit_hor) / list_fit_hor))
     verror = np.max(np.abs((list_dist_ver - list_fit_ver) / list_fit_ver))
-    if (herror > 0.3) or (verror > 0.3):
+    if (herror > threshold) or (verror > threshold):
         check = True
     return check
 
@@ -340,7 +342,7 @@ def _optimize_intercept(dist_hv, pos_hv, list_inter):
 
 
 def _calc_undistor_intercept(list_hor_lines, list_ver_lines, xcenter, ycenter,
-                             optimizing=False):
+                             optimizing=False, threshold=0.3):
     """
     Calculate the intercepts of undistorted lines.
 
@@ -356,6 +358,8 @@ def _calc_undistor_intercept(list_hor_lines, list_ver_lines, xcenter, ycenter,
         Center of distortion in y-direction.
     optimizing : bool, optional
         Apply optimization if True.
+    threshold : float
+        To determine if there are missing lines. Larger is less sensitive.
 
     Returns
     -------
@@ -368,11 +372,13 @@ def _calc_undistor_intercept(list_hor_lines, list_ver_lines, xcenter, ycenter,
         list_hor_lines, xcenter, ycenter)
     (list_coef_ver, list_ver_lines) = _para_fit_ver(
         list_ver_lines, xcenter, ycenter)
-    check = _check_missing_lines(list_coef_hor, list_coef_ver)
+    check = _check_missing_lines(list_coef_hor, list_coef_ver,
+                                 threshold=threshold)
     if check:
-        print("!!! ERROR !!!")
-        print("Parameters of the methods of grouping dots need to be adjusted")
-        raise ValueError("There're missing lines, algorithm will not work!!!")
+        msg = "!!! Parameters of the methods of grouping dots need to be " \
+              "adjusted !!!\n!!! Check if there are missing lines or adjust " \
+              "the threshold value !!!"
+        raise ValueError(msg)
     pos_hor = np.argmin(np.abs(list_coef_hor[:, 2]))
     pos_ver = np.argmin(np.abs(list_coef_ver[:, 2]))
     num_hline = len(list_hor_lines)
@@ -401,7 +407,7 @@ def _calc_undistor_intercept(list_hor_lines, list_ver_lines, xcenter, ycenter,
 
 
 def calc_coef_backward(list_hor_lines, list_ver_lines, xcenter, ycenter,
-                       num_fact, optimizing=False):
+                       num_fact, optimizing=False, threshold=0.3):
     """
     Calculate the distortion coefficients of a backward mode.
 
@@ -419,6 +425,8 @@ def calc_coef_backward(list_hor_lines, list_ver_lines, xcenter, ycenter,
         Number of the factors of polynomial.
     optimizing : bool, optional
         Apply optimization if True.
+    threshold : float
+        To determine if there are missing lines. Larger is less sensitive.
 
     Returns
     -------
@@ -428,7 +436,7 @@ def calc_coef_backward(list_hor_lines, list_ver_lines, xcenter, ycenter,
     num_fact = np.int16(np.clip(num_fact, 1, None))
     (list_hor_uc, list_ver_uc) = _calc_undistor_intercept(
         list_hor_lines, list_ver_lines, xcenter, ycenter,
-        optimizing=optimizing)
+        optimizing=optimizing, threshold=threshold)
     (list_coef_hor, list_hor_lines) = _para_fit_hor(
         list_hor_lines, xcenter, ycenter)
     (list_coef_ver, list_ver_lines) = _para_fit_ver(
@@ -463,7 +471,7 @@ def calc_coef_backward(list_hor_lines, list_ver_lines, xcenter, ycenter,
 
 
 def calc_coef_forward(list_hor_lines, list_ver_lines, xcenter, ycenter,
-                      num_fact, optimizing=False):
+                      num_fact, optimizing=False, threshold=0.3):
     """
     Calculate the distortion coefficients of a forward mode.
 
@@ -481,6 +489,8 @@ def calc_coef_forward(list_hor_lines, list_ver_lines, xcenter, ycenter,
         Number of the factors of polynomial.
     optimizing : bool, optional
         Apply optimization if True.
+    threshold : float
+        To determine if there are missing lines. Larger is less sensitive.
 
     Returns
     -------
@@ -490,7 +500,7 @@ def calc_coef_forward(list_hor_lines, list_ver_lines, xcenter, ycenter,
     num_fact = np.int16(np.clip(num_fact, 1, None))
     (list_hor_uc, list_ver_uc) = _calc_undistor_intercept(
         list_hor_lines, list_ver_lines, xcenter, ycenter,
-        optimizing=optimizing)
+        optimizing=optimizing, threshold=threshold)
     (list_coef_hor, list_hor_lines) = _para_fit_hor(
         list_hor_lines, xcenter, ycenter)
     (list_coef_ver, list_ver_lines) = _para_fit_ver(
@@ -529,7 +539,8 @@ def calc_coef_forward(list_hor_lines, list_ver_lines, xcenter, ycenter,
 
 
 def calc_coef_backward_from_forward(list_hor_lines, list_ver_lines, xcenter,
-                                    ycenter, num_fact, optimizing=False):
+                                    ycenter, num_fact, optimizing=False,
+                                    threshold=0.3):
     """
     Calculate the distortion coefficients of a backward mode from a forward
     model.
@@ -548,6 +559,8 @@ def calc_coef_backward_from_forward(list_hor_lines, list_ver_lines, xcenter,
         Number of the factors of polynomial.
     optimizing : bool, optional
         Apply optimization if True.
+    threshold : float
+        To determine if there are missing lines. Larger is less sensitive.
 
     Returns
     -------
@@ -559,7 +572,8 @@ def calc_coef_backward_from_forward(list_hor_lines, list_ver_lines, xcenter,
     num_fact = np.int16(np.clip(num_fact, 1, None))
     list_ffact = np.float64(
         calc_coef_forward(list_hor_lines, list_ver_lines, xcenter, ycenter,
-                          num_fact, optimizing=optimizing))
+                          num_fact, optimizing=optimizing,
+                          threshold=threshold))
     (_, list_hor_lines) = _para_fit_hor(list_hor_lines, xcenter, ycenter)
     (_, list_ver_lines) = _para_fit_ver(list_ver_lines, xcenter, ycenter)
     list_expo = np.arange(num_fact, dtype=np.int16)
@@ -882,13 +896,13 @@ def _find_cross_point_between_lines(line_coef_hor, line_coef_ver):
     return x, y
 
 
-def _func_opt_pers(d0, c0, indexc0, *list_inter):
+def _func_opt_pers(d0, c0, index_c0, *list_inter):
     """
     Function for finding the optimum undistorted distance for
     perspective-distortion correction.
     """
     return np.sum(
-        np.asarray([((i - indexc0) * d0 + c0 - c) ** 2
+        np.asarray([((i - index_c0) * d0 + c0 - c) ** 2
                     for i, c in enumerate(list_inter)]))
 
 

docs/source/api.rst

@@ -27,4 +27,8 @@ Post-processing
 .. toctree::
    api/discorpy.post.postprocessing
 
+Utility methods
+---------------
 
+.. toctree::
+   api/discorpy.util.utility

docs/source/api/discorpy.util.utility.rst

@@ -0,0 +1,20 @@
+:mod:`discorpy.util.utility`
+==================================
+
+.. automodule:: discorpy.util.utility
+    :members:
+    :show-inheritance:
+    :undoc-members:
+
+    .. rubric:: **Functions:**
+
+    .. autosummary::
+
+        make_dot_pattern
+        make_line_pattern
+        make_chessboard
+        find_point_to_point
+        unwarp_color_image_backward
+        mapping_cv2
+        unwarp_image_backward_cv2
+        unwarp_video_cv2

docs/source/tutorials/methods.rst

@@ -60,6 +60,8 @@ center-of-distortion (optical center), and perspective distortion are determined
 independently using a single calibration image. The following sections explain
 methods implemented in Discorpy.
 
+.. _reference_points:
+
 Extracting reference-points from a calibration image
 ----------------------------------------------------
 
@@ -220,8 +222,8 @@ perspective-distortion are shown in :numref:`fig_20`.
     Corresponding to :numref:`fig_19` (b) without perspective distortion.
 
 In Discorpy 1.4, a method for correcting perspective effect has been developed
-and added to the list of functionalities. The method works by correcting
-coefficients of parabolas using the fact that the resulting coefficients have
+and added to the list of functionalities. This is a novel feature and has not yet been published in
+a journal. The method works by correcting coefficients of parabolas using the fact that the resulting coefficients have
 to satisfy the conditions as shown in :numref:`fig_20`. From the corrected coefficients,
 a grid of points are regenerated by finding cross points between parabolas.
 Details of the method can be found `here <https://discorpy.readthedocs.io/en/latest/api/discorpy.proc.processing.html#discorpy.proc.processing.regenerate_grid_points_parabola>`__.

docs/source/tutorials/methods/chessboard.rst

@@ -1,3 +1,5 @@
+.. _chessboard:
+
 Pre-processing techniques for a chessboard image
 ================================================
 

docs/source/tutorials/methods/dot_pattern.rst

@@ -1,3 +1,5 @@
+.. _dot_pattern:
+
 Pre-processing techniques for a dot-pattern image
 =================================================
 

docs/source/usage/codes/demo_01.py

@@ -28,9 +28,9 @@
 list_hor_lines = prep.group_dots_hor_lines(mat1, hor_slope, dot_dist)
 # Group points to vertical lines
 list_ver_lines = prep.group_dots_ver_lines(mat1, ver_slope, dot_dist)
-# Optional: remove horizontal outliners
+# Optional: remove horizontal outliers
 list_hor_lines = prep.remove_residual_dots_hor(list_hor_lines, hor_slope)
-# Optional: remove vertical outliners
+# Optional: remove vertical outliers
 list_ver_lines = prep.remove_residual_dots_ver(list_ver_lines, ver_slope)
 # Save output for checking
 io.save_plot_image(output_base + "/horizontal_lines.png", list_hor_lines,

docs/source/usage/codes/demo_02.py

@@ -28,7 +28,7 @@
                                            accepted_ratio=0.8)
 list_ver_lines = prep.group_dots_ver_lines(mat1, ver_slope, dot_dist,
                                            accepted_ratio=0.8)
-# Optional: remove outliners
+# Optional: remove outliers
 list_hor_lines = prep.remove_residual_dots_hor(list_hor_lines, hor_slope)
 list_ver_lines = prep.remove_residual_dots_ver(list_ver_lines, ver_slope)
 # Save output for checking

docs/source/usage/codes/demo_03.py

@@ -38,7 +38,7 @@
                                            num_dot_miss=10, accepted_ratio=0.65)
 list_ver_lines = prep.group_dots_ver_lines(mat1, ver_slope, dot_dist, ratio=0.3,
                                            num_dot_miss=10, accepted_ratio=0.65)
-# Remove outliners
+# Remove outliers
 list_hor_lines = prep.remove_residual_dots_hor(list_hor_lines, hor_slope,
                                                residual=2.0)
 list_ver_lines = prep.remove_residual_dots_ver(list_ver_lines, ver_slope,

docs/source/usage/demo_01.rst

@@ -74,9 +74,9 @@ acquired at Beamline I12, Diamond Light Source.
         list_hor_lines = prep.group_dots_hor_lines(mat1, hor_slope, dot_dist)
         # Group points to vertical lines
         list_ver_lines = prep.group_dots_ver_lines(mat1, ver_slope, dot_dist)
-        # Optional: remove horizontal outliners
+        # Optional: remove horizontal outliers
         list_hor_lines = prep.remove_residual_dots_hor(list_hor_lines, hor_slope)
-        # Optional: remove vertical outliners
+        # Optional: remove vertical outliers
         list_ver_lines = prep.remove_residual_dots_ver(list_ver_lines, ver_slope)
         # Save output for checking
         io.save_plot_image(output_base + "/horizontal_lines.png", list_hor_lines, height, width)

docs/source/usage/demo_02.rst

@@ -42,7 +42,7 @@ acquired at Beamline I13 Diamond Light Source, which has a small perspective eff
         # Group points into lines
         list_hor_lines = prep.group_dots_hor_lines(mat1, hor_slope, dot_dist, accepted_ratio=0.8)
         list_ver_lines = prep.group_dots_ver_lines(mat1, ver_slope, dot_dist, accepted_ratio=0.8)
-        # Optional: remove outliners
+        # Optional: remove outliers
         list_hor_lines = prep.remove_residual_dots_hor(list_hor_lines, hor_slope)
         list_ver_lines = prep.remove_residual_dots_ver(list_ver_lines, ver_slope)
         # Save output for checking

docs/source/usage/demo_03.rst

@@ -92,7 +92,7 @@ which was acquired at Beamline I13, Diamond Light Source.
                                                    num_dot_miss=10, accepted_ratio=0.65)
         list_ver_lines = prep.group_dots_ver_lines(mat1, ver_slope, dot_dist, ratio=0.3,
                                                    num_dot_miss=10, accepted_ratio=0.65)
-        # Remove outliners
+        # Remove outliers
         list_hor_lines = prep.remove_residual_dots_hor(list_hor_lines, hor_slope,
                                                        residual=2.0)
         list_ver_lines = prep.remove_residual_dots_ver(list_ver_lines, ver_slope,

docs/source/usage/demo_04.rst

@@ -1,3 +1,5 @@
+.. _demo_04:
+
 Process a line-pattern image
 ============================
 

docs/source/usage/demo_06.rst

@@ -1,3 +1,5 @@
+.. _demo_06:
+
 Calibrate a camera using a chessboard image
 ===========================================
 

docs/source/usage/demo_08.rst

@@ -1,3 +1,5 @@
+.. _demo_08:
+
 Correct radial distortion of an image without using a calibration target
 ========================================================================
 

examples/readthedocs_demo/demo_01.py

@@ -28,9 +28,9 @@
 list_hor_lines = prep.group_dots_hor_lines(mat1, hor_slope, dot_dist)
 # Group points to vertical lines
 list_ver_lines = prep.group_dots_ver_lines(mat1, ver_slope, dot_dist)
-# Optional: remove horizontal outliners
+# Optional: remove horizontal outliers
 list_hor_lines = prep.remove_residual_dots_hor(list_hor_lines, hor_slope)
-# Optional: remove vertical outliners
+# Optional: remove vertical outliers
 list_ver_lines = prep.remove_residual_dots_ver(list_ver_lines, ver_slope)
 # Save output for checking
 io.save_plot_image(output_base + "/horizontal_lines.png", list_hor_lines,

examples/readthedocs_demo/demo_02.py

@@ -28,7 +28,7 @@
                                            accepted_ratio=0.8)
 list_ver_lines = prep.group_dots_ver_lines(mat1, ver_slope, dot_dist,
                                            accepted_ratio=0.8)
-# Optional: remove outliners
+# Optional: remove outliers
 list_hor_lines = prep.remove_residual_dots_hor(list_hor_lines, hor_slope)
 list_ver_lines = prep.remove_residual_dots_ver(list_ver_lines, ver_slope)
 # Save output for checking

examples/readthedocs_demo/demo_03.py

@@ -38,7 +38,7 @@
                                            num_dot_miss=10, accepted_ratio=0.65)
 list_ver_lines = prep.group_dots_ver_lines(mat1, ver_slope, dot_dist, ratio=0.3,
                                            num_dot_miss=10, accepted_ratio=0.65)
-# Remove outliners
+# Remove outliers
 list_hor_lines = prep.remove_residual_dots_hor(list_hor_lines, hor_slope,
                                                residual=2.0)
 list_ver_lines = prep.remove_residual_dots_ver(list_ver_lines, ver_slope,