Added documentation to SofastCLI

contrib/app/sofast/SofastCommandLineInterface.py

@@ -1,3 +1,14 @@
+"""A script that runs SOFAST in a command-line manner. We recommend copying this file into
+your working directory and modifying it there. To run SOFAST, perform the following steps:
+
+1. Navigate to the bottom of this file and fill in all user-input data specific to your SOFAST run.
+2. Type "help" to display help message
+3. Run SOFAST. Collect only measurement data, or (optionally) process data.
+
+NOTE: To update any of the parameters in the bottom of the file, the CLI must be
+restarted for changes to take effect.
+"""
+
 import glob
 from os.path import join, dirname, abspath
 
@@ -457,13 +468,19 @@ def _run_given_input(self, retval: str) -> None:
 
 # Start program
 if __name__ == "__main__":
+    # Define main directory in which to save captured/processed data
+    # ==============================================================
+
     # Define upper level save direcory
     dir_save = abspath(join(dirname(__file__), "../../../../sofast_cli"))
 
     # Define logger directory and set up logger
     dir_log = join(dir_save, "logs")
     lt.logger(join(dir_log, f"log_{timestamp():s}.txt"), lt.log.INFO)
 
+    # Define the file locations of all SOFAST calibration data
+    # ========================================================
+
     # Define directory containing Sofast calibration files
     dir_cal = abspath(join(dirname(__file__), "../../../../sofast_calibration_files"))
 
@@ -476,27 +493,39 @@ def _run_given_input(self, retval: str) -> None:
     file_dot_locs = join(dir_cal, "dot_locations_optics_lab_landscape_square_width3_space6.h5")
 
     # Instantiate Sofast Command Line Interface
+    # =========================================
     sofast_cli = SofastCommandLineInterface()
 
-    # Define sofast and calibration file save directories
+    # Define specific sofast save directories
+    # =======================================
     sofast_cli.dir_save_fringe = join(dir_save, "sofast_fringe")
     sofast_cli.dir_save_fringe_calibration = join(sofast_cli.dir_save_fringe, "calibration")
     sofast_cli.dir_save_fixed = join(dir_save, "sofast_fixed")
 
-    # Load common data
-    image_acquisition_in = ImageAcquisition(0)
-    image_acquisition_in.frame_size = (1626, 1236)
-    image_acquisition_in.gain = 230
+    # Define camera (ImageAcquisition) parameters
+    # ===========================================
+    image_acquisition_in = ImageAcquisition(instance=0)  # First camera instance found
+    image_acquisition_in.frame_size = (1626, 1236)  # Set frame size
+    image_acquisition_in.gain = 230  # Set gain (higher=faster/more noise, lower=slower/less noise)
 
+    # Define projector/display (ImageProjection) parameters
+    # =====================================================
     image_projection_in = ImageProjection.load_from_hdf(file_image_projection)
-    image_projection_in.display_data.image_delay_ms = 200
+    image_projection_in.display_data.image_delay_ms = 200  # define projector-camera delay
+
+    # Define measurement-specific inputs
+    # ==================================
 
-    camera_in = Camera.load_from_hdf(file_camera)
-    facet_definition_in = DefinitionFacet.load_from_json(file_facet_definition_json)
-    spatial_orientation_in = SpatialOrientation.load_from_hdf(file_spatial_orientation)
-    measure_point_optic_in = Vxyz((0, 0, 0))  # meters
-    dist_optic_screen_in = 10.158  # meters
-    name_optic_in = "Test optic"
+    # NOTE: to update any of these fields, change them here and restart the SOFAST CLI
+    measure_point_optic_in = Vxyz((0, 0, 0))  # Measure point on optic, meters
+    dist_optic_screen_in = 10.158  # Measured optic-screen distance, meters
+    name_optic_in = "Test optic"  # Optic name
+
+    # Load all other calibration files
+    # ================================
+    camera_in = Camera.load_from_hdf(file_camera)  # SOFAST camera definition
+    facet_definition_in = DefinitionFacet.load_from_json(file_facet_definition_json)  # Facet definition
+    spatial_orientation_in = SpatialOrientation.load_from_hdf(file_spatial_orientation)  # Spatial orientation
 
     sofast_cli.set_common_data(
         image_acquisition_in,
@@ -509,21 +538,27 @@ def _run_given_input(self, retval: str) -> None:
         name_optic_in,
     )
 
-    sofast_cli.colorbar_limit = 2
+    sofast_cli.colorbar_limit = 2  # Update plotting colorbar limit, mrad
 
-    # Load Sofast Fringe data
+    # Set Sofast Fringe parameters
+    # ============================
     display_shape_in = DisplayShape.load_from_hdf(file_display)
     fringes_in = Fringes.from_num_periods(4, 4)
     surface_fringe_in = Surface2DParabolic((100.0, 100.0), False, 10)
 
     sofast_cli.set_sofast_fringe_data(display_shape_in, fringes_in, surface_fringe_in)
 
-    # Load Sofast Fixed data
+    # Set Sofast Fixed parameters
+    # ===========================
+
+    # NOTE: to get the value of "origin_in," the user must first start the CLI, brign up the
+    # camera live view, then manually find the location of the (0, 0) fixed pattern dot
     fixed_pattern_dot_locs_in = DotLocationsFixedPattern.load_from_hdf(file_dot_locs)
     origin_in = Vxy((1100, 560))  # pixels, location of (0, 0) dot in camera image
     surface_fixed_in = Surface2DParabolic((100.0, 100.0), False, 1)
 
     sofast_cli.set_sofast_fixed_data(fixed_pattern_dot_locs_in, origin_in, surface_fixed_in)
 
     # Run
+    # ===
     sofast_cli.run()