Merge pull request #89 from e10harvey/doc_strings_exist

Check opencsp.app for doc strings

opencsp/app/target/target_color/target_color_bullseye.py → contrib/app/target/target_color/target_color_bullseye.py

@@ -59,7 +59,9 @@ def bullseye_color_bar(
     cx_offset_trim_pix,
     target_img_width_pix,
 ):
-    # Bullseye.
+    """
+    Placeholder
+    """
     for row in range(0, n_rows):
         for col in range(0, n_cols):
             r_mrad = bullseye_error.radius_in_mrad_given_row_col(

opencsp/app/target/target_color/target_color_bullseye_error.py → contrib/app/target/target_color/target_color_bullseye_error.py

@@ -9,27 +9,47 @@
 
 
 def meters_given_pixels(d_pixel, dpi):
+    """
+    Returns distance in meters given a distance in pixels and a dots per inch (DPI) value
+
+    Parameters
+    ----------
+    d_pixel : float
+        Distance in pixels
+    dpi : float
+        Dots per inch of image
+
+    Returns
+    -------
+    float
+        Distance in meters
+    """
     d_inch = d_pixel / dpi
     d_meter = d_inch / (1000.0 / 25.4)
     return d_meter
 
 
 def surface_normal_error_magnitude_given_radius_in_meters(r_meter, focal_length_meter):
-    # Computes the surface normal error of a reflection with a reflected image the given
-    # radius r_meter away from the target center.
-    #
-    # Correct if the mirror design is spherical, the view position is along the optical axis,
-    # and the target-to-mirror and camera-to-mirror distances are equal to the radius of curvature.
-    #
-    # Returns value in milliradians.
-    #
+    """
+    Computes the surface normal error of a reflection with a reflected image the given
+     radius r_meter away from the target center.
+
+     Correct if the mirror design is spherical, the view position is along the optical axis,
+     and the target-to-mirror and camera-to-mirror distances are equal to the radius of curvature.
+
+     Returns value in milliradians.
+    """
+
     radius_of_curvature_meter = 2 * focal_length_meter
     reflected_ray_angle = math.atan(r_meter / radius_of_curvature_meter)  # radians
     surface_normal_error = reflected_ray_angle / 2.0  # radians
     return surface_normal_error * 1000.0  # Convert radians to milliradians.
 
 
 def radius_in_mrad_given_row_col(n_rows, row, col, x_max, cx_offset_pix, y_offset_pix, focal_length_meter):
+    """
+    Placeholder
+    """
     x = col
     y = n_rows - row
     cx = (x_max / 2) + cx_offset_pix

doc/source/library_reference/app/target/target_color/config.rst

@@ -8,56 +8,6 @@ opencsp.app.target.target_color.lib.ImageColor
    :undoc-members:
    :show-inheritance:
 
-opencsp.app.target.target_color.target_color_2d_gradient
-========================================================
-
-.. currentmodule:: opencsp.app.target.target_color.target_color_2d_gradient
-
-.. automodule:: opencsp.app.target.target_color.target_color_2d_gradient
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-opencsp.app.target.target_color.target_color_bullseye_error
-===========================================================
-
-.. currentmodule:: opencsp.app.target.target_color.target_color_bullseye_error
-
-.. automodule:: opencsp.app.target.target_color.target_color_bullseye_error
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-opencsp.app.target.target_color.target_color_bullseye
-=====================================================
-
-.. currentmodule:: opencsp.app.target.target_color.target_color_bullseye
-
-.. automodule:: opencsp.app.target.target_color.target_color_bullseye
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-opencsp.app.target.target_color.target_color_one_color
-======================================================
-
-.. currentmodule:: opencsp.app.target.target_color.target_color_one_color
-
-.. automodule:: opencsp.app.target.target_color.target_color_one_color
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-opencsp.app.target.target_color.target_color_polar
-==================================================
-
-.. currentmodule:: opencsp.app.target.target_color.target_color_polar
-
-.. automodule:: opencsp.app.target.target_color.target_color_polar
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 opencsp.app.target.target_color.target_color
 ============================================
 

opencsp/app/camera_calibration/CameraCalibration.py

@@ -24,6 +24,47 @@
 
 
 class CalibrationGUI:
+    """
+    A graphical user interface (GUI) for calibrating a machine vision camera.
+
+    This class provides a user-friendly interface to load previously captured
+    calibration images, find checkerboard corners, and calibrate the camera
+    using the selected images. It also allows users to visualize the
+    reprojection error and save the calibrated camera parameters.
+
+    The GUI includes options to select images, find corners, view found
+    corners, calibrate the camera, visualize distortion, and save the camera
+    configuration.
+
+    Attributes
+    ----------
+    root : tkinter.Tk
+        The main window of the GUI.
+    files : list[str]
+        List of selected image file paths.
+    images : list[np.ndarray]
+        List of loaded images as NumPy arrays.
+    used_file_names : list[str]
+        List of file names of the loaded images.
+    p_object : list[Vxyz]
+        List of object points in 3D space corresponding to the checkerboard corners.
+    p_image : list[Vxy]
+        List of image points in 2D space corresponding to the detected corners.
+    img_size_xy : tuple[int, int]
+        Size of the images (width, height).
+    camera : Camera
+        The calibrated camera object.
+    r_cam_object : list[Rotation]
+        List of rotation matrices for each calibration image.
+    v_cam_object_cam : list[Vxyz]
+        List of camera position vectors for each calibration image.
+    avg_reproj_error : list[float]
+        Average reprojection error for the calibration.
+    reproj_errors : list[float]
+        List of reprojection errors for each calibration image.
+    """
+
+    # "ChatGPT 4o-mini" assisted with generating this docstring.
     def __init__(self):
         """
         GUI for calibrating machine vision Camera

opencsp/app/camera_calibration/lib/ViewAnnotatedImages.py

@@ -9,7 +9,8 @@
 
 
 class ViewAnnotatedImages:
-    """Class that controls a window used to view images with a next and previous
+    """
+    Class that controls a window used to view images with a next and previous
     button
     """
 
@@ -77,6 +78,9 @@ def __init__(self, root: tkinter.Tk, images: list[ndarray], image_names: list[st
         self.root.mainloop()
 
     def update_image(self):
+        """
+        Updates displayed image and image label
+        """
         # Update image title
         self.var_title.set(self.image_names[self.idx_im])
 
@@ -101,6 +105,9 @@ def update_image(self):
         self.canvas.itemconfig(self.canvas_image, image=image_tk)
 
     def show_next(self):
+        """
+        Show the next image.
+        """
         # Update index
         self.idx_im += 1
         if self.idx_im >= len(self.images):
@@ -110,6 +117,9 @@ def show_next(self):
         self.update_image()
 
     def show_prev(self):
+        """
+        Show the previous image.
+        """
         # Update index
         self.idx_im -= 1
         if self.idx_im < 0:

opencsp/app/sofast/SofastGUI.py

@@ -819,7 +819,9 @@ def _projector_closed(self, image_projection: ImageProjection):
         self._camera_closed(None)
 
     def close_image_acquisition(self) -> None:
-        """Closes image acquisition"""
+        """
+        Close the single Image Acquisition object if open.
+        """
         # Close the camera
         with et.ignored(Exception):
             ImageAcquisitionAbstract.instance().close()

opencsp/app/sofast/lib/ImageCalibrationAbstract.py

@@ -49,6 +49,19 @@ def get_calibration_name() -> str:
 
     @abstractmethod
     def apply_to_images(self, measurement) -> ndarray:
+        """
+        Performs camera-projector brightness values calibration.
+
+        Parameters
+        ----------
+        fringe_images : ndarray
+            Measurement fringe images.
+
+        Returns
+        -------
+        ndarray
+            Calibrated fringe images, float.
+        """
         pass
 
     def _create_response_function(self) -> None:
@@ -165,7 +178,8 @@ def calculate_min_display_camera_values(self, derivative_thresh: float = 0.4) ->
         return (display_min_value, camera_min_value)
 
     def plot_gray_levels(self) -> None:
-        """Shows plot of gray levels calibration data. When the close() method of this instance is called (or this
+        """
+        Shows plot of gray levels calibration data. When the close() method of this instance is called (or this
         instance is destructed), the plot will be closed automatically."""
         title = 'Projector-Camera Calibration Curve'
 

opencsp/app/target/target_color/target_color.py

@@ -12,7 +12,6 @@
 import os
 
 import opencsp.common.lib.opencsp_path.opencsp_root_path as ort
-import opencsp.app.target.target_color.target_color_bullseye_error
 import opencsp.common.lib.target.target_color_convert
 import opencsp.common.lib.target.target_color_1d_gradient
 import opencsp.common.lib.target.target_image

opencsp/common/lib/camera/Camera.py

@@ -16,23 +16,27 @@
 
 
 class Camera:
+    """
+    Calibrated machine vision camera representation. This represents a pinhole model of
+    a camera/lens assembly and includes lens distortion through the use of distortion
+    coefficients. This model uses the distortion model used by OpenCV; see
+    https://docs.opencv.org/4.9.0/d9/d0c/group__calib3d.html for more information.
+
+    Parameters
+    ----------
+    intrinsic_mat : np.ndarray
+        3x3 numpy array, intrinsic camera matrix
+    distortion_coef : np.ndarray
+        1d array, distortion coefficients, typically length 4.
+    image_shape_xy : tuple(int)
+        (x, y), image size in pixels.
+    name : str
+        Name of camera/lens combination.
+    """
+
     def __init__(
         self, intrinsic_mat: np.ndarray, distortion_coef: np.ndarray, image_shape_xy: tuple[int, int], name: str
     ):
-        """
-        Calibrated machine vision camera representation.
-
-        Parameters
-        ----------
-        intrinsic_mat : np.ndarray
-        distortion_coef : np.ndarray
-            1d array, distortion coefficients.
-        image_shape_xy : tuple(int)
-            (x, y), image size in pixels.
-        name : str
-            Name of camera/lens combination.
-
-        """
         if intrinsic_mat.shape[0] != 3 or intrinsic_mat.shape[1] != 3 or np.ndim(intrinsic_mat) != 2:
             raise ValueError('Input intrinsic_mat must be a 3x3 ndarray.')
 

opencsp/common/lib/camera/ImageAcquisitionAbstract.py

@@ -9,6 +9,28 @@
 
 
 class ImageAcquisitionAbstract(ABC):
+    """
+    Abstract base class for image acquisition from cameras.
+
+    This class defines the interface for acquiring images from various camera types.
+    It implements a multiton design pattern to ensure that only one instance of a
+    camera is active at a time. The class provides methods for exposure calibration,
+    frame retrieval, and managing camera settings.
+
+    Attributes
+    ----------
+    _instances : dict[int, ImageAcquisitionAbstract]
+        A dictionary of all instantiated camera instances, ensuring that each index
+        corresponds to a unique camera instance.
+    _next_instance_idx : int
+        The index to use for the next camera instance added to the `_instances` dictionary.
+    on_close : list[Callable[[ImageAcquisitionAbstract], None]]
+        A list of callback functions to be executed when the camera is closed.
+    is_closed : bool
+        A flag indicating whether the camera connection is closed.
+    """
+
+    # "ChatGPT 4o-mini" assisted with generating this docstring.
     _instances: dict[int, 'ImageAcquisitionAbstract'] = {}
     """ All instantiated camera instances. We use a dictionary to ensure that once an index is assigned,
     then all references to that same index will return the same camera (or None if the camera was closed). """

opencsp/common/lib/csp/MirrorPoint.py

@@ -1,7 +1,3 @@
-"""Mirror class representing mirrors with scattered surface point
-locations.
-"""
-
 from typing import Literal
 from warnings import warn
 
@@ -22,6 +18,10 @@
 
 
 class MirrorPoint(MirrorAbstract):
+    """Mirror class representing mirrors with scattered surface point
+    locations.
+    """
+
     def __init__(
         self,
         surface_points: Pxyz,

opencsp/common/lib/geometry/LineXY.py

@@ -7,6 +7,28 @@
 
 
 class LineXY:
+    """
+    Representation of a homogeneous line in 2D space.
+
+    The line is represented in the general form \( Ax + By + C = 0 \) and
+    provides various properties and methods to work with lines, including
+    calculating distances, intersections, and fitting lines to sets of points.
+
+    Attributes
+    ----------
+    A : float
+        Coefficient A of the line equation.
+    B : float
+        Coefficient B of the line equation.
+    C : float
+        Coefficient C of the line equation, representing the distance from the
+        origin along the normal vector.
+    _original_two_points : tuple[Vxy, Vxy] | None
+        The original two points used to create the line, if created with
+        `from_two_points`.
+    """
+
+    # "ChatGPT 4o-mini" assisted with generating this docstring.
     def __init__(self, A: float, B: float, C: float):
         """
         Representation of a homogenous line with the following properties: