From c0a3ad98ecd7a3fcba37091a7c3ebcd6ff0d99d9 Mon Sep 17 00:00:00 2001 From: nghia-vo Date: Tue, 22 Aug 2023 15:04:13 -0400 Subject: [PATCH] Update docs --- discorpy/proc/processing.py | 44 ++++++++++++------- docs/source/api.rst | 4 ++ docs/source/api/discorpy.util.utility.rst | 20 +++++++++ docs/source/tutorials/methods.rst | 6 ++- docs/source/tutorials/methods/chessboard.rst | 2 + docs/source/tutorials/methods/dot_pattern.rst | 2 + docs/source/usage/codes/demo_01.py | 4 +- docs/source/usage/codes/demo_02.py | 2 +- docs/source/usage/codes/demo_03.py | 2 +- docs/source/usage/demo_01.rst | 4 +- docs/source/usage/demo_02.rst | 2 +- docs/source/usage/demo_03.rst | 2 +- docs/source/usage/demo_04.rst | 2 + docs/source/usage/demo_06.rst | 2 + docs/source/usage/demo_08.rst | 2 + examples/readthedocs_demo/demo_01.py | 4 +- examples/readthedocs_demo/demo_02.py | 2 +- examples/readthedocs_demo/demo_03.py | 2 +- 18 files changed, 79 insertions(+), 29 deletions(-) create mode 100644 docs/source/api/discorpy.util.utility.rst diff --git a/discorpy/proc/processing.py b/discorpy/proc/processing.py index b3dea78..2ffd338 100644 --- a/discorpy/proc/processing.py +++ b/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)])) diff --git a/docs/source/api.rst b/docs/source/api.rst index dee6b90..03c9269 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -27,4 +27,8 @@ Post-processing .. toctree:: api/discorpy.post.postprocessing +Utility methods +--------------- +.. toctree:: + api/discorpy.util.utility diff --git a/docs/source/api/discorpy.util.utility.rst b/docs/source/api/discorpy.util.utility.rst new file mode 100644 index 0000000..6a51f51 --- /dev/null +++ b/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 diff --git a/docs/source/tutorials/methods.rst b/docs/source/tutorials/methods.rst index 47c7ffa..2f8cac2 100644 --- a/docs/source/tutorials/methods.rst +++ b/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 `__. diff --git a/docs/source/tutorials/methods/chessboard.rst b/docs/source/tutorials/methods/chessboard.rst index 8afa67b..143efa1 100644 --- a/docs/source/tutorials/methods/chessboard.rst +++ b/docs/source/tutorials/methods/chessboard.rst @@ -1,3 +1,5 @@ +.. _chessboard: + Pre-processing techniques for a chessboard image ================================================ diff --git a/docs/source/tutorials/methods/dot_pattern.rst b/docs/source/tutorials/methods/dot_pattern.rst index 3797129..cae6444 100644 --- a/docs/source/tutorials/methods/dot_pattern.rst +++ b/docs/source/tutorials/methods/dot_pattern.rst @@ -1,3 +1,5 @@ +.. _dot_pattern: + Pre-processing techniques for a dot-pattern image ================================================= diff --git a/docs/source/usage/codes/demo_01.py b/docs/source/usage/codes/demo_01.py index e4b60d0..38fff32 100644 --- a/docs/source/usage/codes/demo_01.py +++ b/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, diff --git a/docs/source/usage/codes/demo_02.py b/docs/source/usage/codes/demo_02.py index 84c409a..cb4932e 100644 --- a/docs/source/usage/codes/demo_02.py +++ b/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 diff --git a/docs/source/usage/codes/demo_03.py b/docs/source/usage/codes/demo_03.py index 1083214..0ae6bc9 100644 --- a/docs/source/usage/codes/demo_03.py +++ b/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, diff --git a/docs/source/usage/demo_01.rst b/docs/source/usage/demo_01.rst index 297b15f..e6df74d 100644 --- a/docs/source/usage/demo_01.rst +++ b/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) diff --git a/docs/source/usage/demo_02.rst b/docs/source/usage/demo_02.rst index c7e7784..74a0f62 100644 --- a/docs/source/usage/demo_02.rst +++ b/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 diff --git a/docs/source/usage/demo_03.rst b/docs/source/usage/demo_03.rst index 92c3bf9..1c3edf6 100644 --- a/docs/source/usage/demo_03.rst +++ b/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, diff --git a/docs/source/usage/demo_04.rst b/docs/source/usage/demo_04.rst index 13de12e..99b6cfd 100644 --- a/docs/source/usage/demo_04.rst +++ b/docs/source/usage/demo_04.rst @@ -1,3 +1,5 @@ +.. _demo_04: + Process a line-pattern image ============================ diff --git a/docs/source/usage/demo_06.rst b/docs/source/usage/demo_06.rst index e68b9a9..8aea759 100644 --- a/docs/source/usage/demo_06.rst +++ b/docs/source/usage/demo_06.rst @@ -1,3 +1,5 @@ +.. _demo_06: + Calibrate a camera using a chessboard image =========================================== diff --git a/docs/source/usage/demo_08.rst b/docs/source/usage/demo_08.rst index ea5336d..16741f0 100644 --- a/docs/source/usage/demo_08.rst +++ b/docs/source/usage/demo_08.rst @@ -1,3 +1,5 @@ +.. _demo_08: + Correct radial distortion of an image without using a calibration target ======================================================================== diff --git a/examples/readthedocs_demo/demo_01.py b/examples/readthedocs_demo/demo_01.py index e4b60d0..38fff32 100644 --- a/examples/readthedocs_demo/demo_01.py +++ b/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, diff --git a/examples/readthedocs_demo/demo_02.py b/examples/readthedocs_demo/demo_02.py index 84c409a..cb4932e 100644 --- a/examples/readthedocs_demo/demo_02.py +++ b/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 diff --git a/examples/readthedocs_demo/demo_03.py b/examples/readthedocs_demo/demo_03.py index 1083214..0ae6bc9 100644 --- a/examples/readthedocs_demo/demo_03.py +++ b/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,