Jeff add rst

doc/source/example/sofast_fringe/config.rst

@@ -1,9 +1,9 @@
 Single Facet Data Process
 =========================
 
-.. currentmodule:: example.sofast_fringe.example_process_single_facet
+.. currentmodule:: example.sofast_fringe.single_facet.example_process_single_facet
 
-.. automodule:: example.sofast_fringe.example_process_single_facet
+.. automodule:: example.sofast_fringe.single_facet.example_process_single_facet
    :members:
    :show-inheritance:
 

example/conftest.py

@@ -1,19 +1,31 @@
+"""
+Setup pytest for running examples.
+"""
+
 import pytest
 
 
 #
-# Ensure pytest adds root directory to the system path.
+# Add pytest command-line arguments supported by examples.
 #
 def pytest_addoption(parser):
-    parser.addoption('--dir-input', action='store', default='', help='Base directory with data input')
-    parser.addoption('--dir-output', action='store', default='', help='Base directory where output will be written')
+    parser.addoption('--dir_input', action='store', default='', help='Base directory with data input')
+    parser.addoption('--dir_output', action='store', default='', help='Base directory where output will be written')
+
+
+#    parser.addoption('--verbose', action='store', default='False', help='Output detailed information.')
 
 
 @pytest.fixture
 def dir_input_fixture(request):
-    return request.config.getoption('--dir-input')
+    return request.config.getoption('--dir_input')
 
 
 @pytest.fixture
 def dir_output_fixture(request):
-    return request.config.getoption('--dir-output')
+    return request.config.getoption('--dir_output')
+
+
+# @pytest.fixture
+# def verbose_fixture(request):
+#     return request.config.getoption('--verbose')

example/enclosed_energy/enclosed_energy.ipynb

@@ -729,9 +729,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "venv-3.11",
+   "display_name": "env_310_OpenCSP",
    "language": "python",
-   "name": "venv-3.11"
+   "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
@@ -743,7 +743,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.9"
+   "version": "3.10.9"
   }
  },
  "nbformat": 4,

example/scene_reconstruction/example_scene_reconstruction.py

@@ -1,5 +1,84 @@
-from os.path import join, dirname
+r"""("r" prefix to ignore escape characters within docstring.)
 
+Exercise scene reconstruction algorithms.
+
+Supports these use cases:
+
+1. Pytest execution.
+   Purpose:  To verify code is still operating properly.
+
+   a. Quick pytest unit tests.  Run pytest from opencsp directory.
+      In OpenCSP directory:
+      pytest
+
+   b. More detailed pytest examples.
+      In OpenCSP\example directory:
+      pytest
+
+   c. Automated tests for pull request management.
+
+   d. Automated tests for nightly and weekly function checks.
+      Run pytest from opencsp/example directory (with arguments to run full-scale data).
+
+   e. Run pytest on only this example.
+      In OpenCSP\example directory:
+      pytest .\scene_reconstruction\example_scene_reconstruction.py
+
+2. Running the example from the command line.
+   Purpose:  To apply the example calculation to new data.
+
+   a. With no arguments, to execute default behavior (for practice and study).
+      In OpenCSP\example\scene_reconstruction directory:
+      python .\example_scene_reconstruction.py
+
+   b. With an argument to read a user-specified settings file to define input sources, output locations, and execution details.
+      i. Data source/sink options:
+
+         (1) Data built into the repository. No argument.
+             In OpenCSP\example\scene_reconstruction directory:
+             python .\example_scene_reconstruction.py
+
+         (2) Community data on local machine. myfile_ctemp.ini
+             In OpenCSP\example\scene_reconstruction directory:
+             python .\example_scene_reconstruction.py --settings_dir_body_ext "C:\ctemp\OpenCSP_ctemp\example_scene_reconstruction_settings_ctemp.ini"
+
+         (3) Data on local machine, but in user-owned location. myfile_<user_id>.ini
+             In OpenCSP\example\scene_reconstruction directory:
+             python .\example_scene_reconstruction.py --settings_dir_body_ext "C:\Users\<user_id>\OpenCSP\OpenCSP_<user_id>\example_scene_reconstruction_settings_<user_id>.ini"
+
+         (4) General network location. myfile_<network_location>.ini
+             In OpenCSP\example\scene_reconstruction directory:
+             python .\example_scene_reconstruction.py --settings_dir_body_ext "\\<network_path>\OpenCSP_<net_name>\example_scene_reconstruction_settings_<net_name>.ini"
+
+      ii. Output levels:
+
+         (1) Output only minimal progress updates. Omit --verbose flag.
+         (2) Output full progress and calculation updates. Add --verbose flag.
+
+   c. Review command-line options:
+      In OpenCSP\example\scene_reconstruction directory:
+      python .\example_scene_reconstruction.py --help
+
+3. Calling the example calculation from other code.
+   Purpose:  To utilize the example calculation within a larger computation or application.
+
+   a. Arbitrary context and general data.
+      In calling file, import example_scenario_reconstruction, call driver.
+
+4. Running an example with the Visual Studio Code debugger.
+   Purpose:  To interact with the code execution (break points, check stack variables, etc), either for study or fixing an error.  Could apply to either 2 or 3 above.
+
+   a. Use default settings, running on default data.  In VS Code, press F5 key.
+
+   b. Temporarily modify internal variable values to test specific data computation.
+      Make a scratch copy somewhere else, edit in VS Code, then press F5 key.
+
+"""
+
+from os.path import join, basename, dirname, splitext
+
+import argparse
+import configparser
 import numpy as np
 
 from opencsp.app.scene_reconstruction.lib.SceneReconstruction import SceneReconstruction
@@ -10,14 +89,12 @@
 import opencsp.common.lib.tool.log_tools as lt
 
 
-def scene_reconstruction(dir_output, dir_input):
+def scene_reconstruction(dir_input, dir_output, verbose):
     """
     Reconstructs the XYZ locations of Aruco markers in a scene.
 
     Parameters
     ----------
-    dir_output : str
-        The directory where the output files, including point locations and calibration figures, will be saved.
     dir_input : str
         The directory containing the input files needed for scene reconstruction. This includes:
 
@@ -26,6 +103,10 @@ def scene_reconstruction(dir_output, dir_input):
         - 'aruco_marker_images/NAME.JPG': Directory containing images of Aruco markers.
         - 'point_pair_distances.csv': CSV file with distances between point pairs.
         - 'alignment_points.csv': CSV file with alignment points.
+    dir_output : str
+        The directory where the output files, including point locations and calibration figures, will be saved.
+    verbose : bool
+        If true, write out detailed information.
 
     Notes
     -----
@@ -42,7 +123,7 @@ def scene_reconstruction(dir_output, dir_input):
 
     Examples
     --------
-    >>> scene_reconstruction('/path/to/output', '/path/to/input')
+    >>> scene_reconstruction('/path/to/input', '/path/to/output')
 
     """
     # "ChatGPT 4o" assisted with generating this docstring.
@@ -74,26 +155,105 @@ def scene_reconstruction(dir_output, dir_input):
 
     # Save calibration figures
     for fig in cal_scene_recon.figures:
-        fig.savefig(join(dir_output, fig.get_label() + '.png'))
+        figure_path_body = join(dir_output, fig.get_label() + '.png')
+        # Overwrite previous versions.
+        if ft.file_exists(figure_path_body):
+            ft.delete_file(figure_path_body)
+        fig.savefig(figure_path_body)
 
 
-def example_driver(dir_output_fixture, dir_input_fixture):
+def example_scene_reconstruction_driver(arg_settings_dir_body_ext: str = None, verbose_param=None):
+    """
+    Sets up and runs the scene_reconstruction() routine.
 
-    dir_input = join(opencsp_code_dir(), 'app/scene_reconstruction/test/data/data_measurement')
-    dir_output = join(dirname(__file__), 'data/output/scene_reconstruction')
-    if dir_input_fixture:
-        dir_input = dir_input_fixture
-    if dir_output_fixture:
-        dir_output = dir_output_fixture
+    Parameters
+    ----------
 
-    # Define output directory
-    ft.create_directories_if_necessary(dir_input)
+    arg_settings_dir_body_ext : str
+        Full path and filename for settings file, containing inputand output directories, plot control settings, etc.
+        Optional.  If not provided, internal defaults are used.
+        See code for options sought within file.
 
-    # Set up logger
-    lt.logger(join(dir_output, 'log.txt'), lt.log.INFO)
+    verbose : bool
+        If true, output detailed progress and calculation output.
+    """
+    # Get settings
+    if arg_settings_dir_body_ext is None:
+        print("Using default control settings.")
+        dir_input = join(opencsp_code_dir(), 'app/scene_reconstruction/test/data/data_measurement')
+        dir_output = join(dirname(__file__), 'data/output/scene_reconstruction')
+        if verbose_param is None:
+            verbose = False
+        else:
+            verbose = verbose_param
+    else:
+        print("Loading control from settings file:", arg_settings_dir_body_ext)
+        if not ft.file_exists(arg_settings_dir_body_ext):
+            print("ERROR: In " + basename(__file__) + ", settings file does not exist. Settings file:")
+            print("   ", arg_settings_dir_body_ext)
+            assert False
+        settings = configparser.ConfigParser()
+        settings.read(arg_settings_dir_body_ext)
+        dir_input = settings["Default"]["dir_input"]
+        dir_output = settings["Default"]["dir_output"]
+        verbose_setting = settings["Default"]["verbose"]
+        if verbose_param is None:
+            verbose = verbose_setting
+        else:
+            verbose = verbose_param
 
-    scene_reconstruction(dir_output, dir_input)
+    # Ensure output directory is ready
+    ft.create_directories_if_necessary(dir_output)
+
+    # Set up logger
+    logfile_dir_body_ext = join(dir_output, splitext(basename(__file__))[0] + '_log.txt')
+    print("logfile_dir_body_ext = ", logfile_dir_body_ext)
+    lt.logger(logfile_dir_body_ext, lt.log.INFO)
+    # Output standard lines.
+    if verbose:
+        lt.info_strings_from_file(join(dirname(__file__), splitext(basename(__file__))[0] + '_README.md'))
+    lt.info('Starting program ' + __file__)
+    lt.info('dir_input = ' + dir_input)
+    lt.info('dir_output = ' + dir_output)
+    lt.info('verbose = ' + str(verbose))
+    if verbose:
+        lt.info('Calling routine scene_reconstruction(dir_input, dir_output, verbose)...')
+    scene_reconstruction(dir_input, dir_output, verbose)
 
 
 if __name__ == '__main__':
-    example_driver()
+    # Parse command-line arguments, if any.
+    # Execute "python <this_file>.py --help" to see usage tips.
+    #
+    # Source - https://stackoverflow.com/a
+    # Posted by Martijn Pieters, modified by community. See post 'Timeline' for change history
+    # Retrieved 2025-12-04, License - CC BY-SA 4.0
+    parser = argparse.ArgumentParser(
+        prog=__file__.rstrip(".py"),
+        description='Example scene reconstruction calculation.  Given photos with Aruco markers, find marker and camera 3-d positions.  See "example_scene_reconstruction_README.md" for details.',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "-s",
+        "--settings_dir_body_ext",
+        required=False,
+        dest="settings_dir_body_ext",
+        default=None,
+        help="Settings file defining run parameters (input/output directories, etc).",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        dest="verbose",
+        help="Output detailed information reporting run progress and calculations.",
+    )
+    args = parser.parse_args()
+    arg_settings_dir_body_ext_main: str = args.settings_dir_body_ext
+    verbose_main: bool = args.verbose
+
+    # Manual override for use when debugging.  Comment this line for normal runs.
+    # verbose: bool = True
+
+    # Call driver.
+    example_scene_reconstruction_driver(arg_settings_dir_body_ext_main, verbose_main)

example/scene_reconstruction/example_scene_reconstruction_README.md

@@ -0,0 +1,66 @@
+example_scene_reconstruction_README.txt:
+========================================
+Example scene reconstruction calculation.  Given photos with Aruco markers, find marker
+and camera 3-d positions.  See "example_scene_reconstruction_README.txt" for details.
+
+To run this as a pytest on the built-in input:
+   1. cd to the OpenCSP code directory.
+   2. cd to the example subdirectory.
+   3. Execute pytest:
+          pytest
+       or
+          pytest scene_reconstruction\example_scene_reconstruction.py
+
+To run this on the default built-in input:
+   1. cd to the directory containing the script "example_scene_reconstruction.py".
+   2. Run the script:
+              python example_scene_reconstruction.py --verbose
+       The "--verbose" flag is optional.
+
+To run this on new input, use the -s option and point to a settings control file.
+For an example settings file, see:
+    <OpenCSP_code_dir>\example\scene_reconstruction\example_scene_reconstruction_settings_ctemp.ini 
+
+We recommend copying this file and placing it alongside the data you wish to run.
+For example, to run the full-size OpenCSP example:'
+   1. Create a directory "C:\ctemp\OpenCSP_ctemp\example_data_large" for holding example data.
+   2. Create subdirectory "scene_reconstruction" 
+   3. Create subsubdirectory "input", and fill it with the required input files:
+         "alignment_points.csv"
+         "camera.h5"
+         "known_point_locations.csv"
+         "point_pair_distances.csv"
+         Subdirectory "aruco_marker_images" containing images of scene with Aruco markers.
+   4. Copy the file "example_scene_reconstruction_settings_ctemp.ini" into the subdirectory
+      "scene_reconstruction" made in step 2.'
+   5. Launch a PowerShell and ensure the OpenCSP virtual environment is activated.
+   6. cd to the directory containing the script "example_scene_reconstruction.py".
+   7. Run the script, providing the -s option and pointing to the .ini file:
+         python example_scene_reconstruction.py --verbose -s "C:\ctemp\OpenCSP_ctemp\example_data_large\scene_reconstruction\example_scene_reconstruction_settings_ctemp.ini" 
+   8. The "--verbose" option generates additional status and calculation output.
+   9. The output will be written to an "example_scene_reconstruction_output" subdirectory 
+      created alongside the input directory.
+      (This is to distinguish it from output from other examples within the directory.)
+
+To run this calculation on your own data:
+   A. Create a directory holding your input data.
+   B. Copy the "example_scene_reconstruction_settings_ctemp.ini" file to a new name, such as 
+      "My_Data_scene_reconstruction_settings.ini" and edit it to point to your data location.
+   C. For the sake of example, suppose you place your data in "C:\ctemp\OpenCSP_ctemp\MyData",
+      and also suppose you place your new "My_Data_scene_reconstruction_settings.ini" file
+      in this directory.
+      Then you can run the same calculation on your data by:
+         a. cd to the directory containing the script "example_scene_reconstruction.py".
+         b. Run the script, providing the -s option and pointing to your .ini file:
+              python example_scene_reconstruction.py --verbose -s "C:\ctemp\OpenCSP_ctemp\MyData\My_Data_scene_reconstruction_settings_ctemp.ini" 
+   D. The output will be written to the output subdirectory you specify in your .ini file.'
+
+For a detailed description of the algorithm and its input and output, see: 
+    B. J. Smith, R. C. Brost, and B. G. Bean.
+    Scene Reconstruction User Guide, Document Version 1.0.
+    Sandia National Laboratories Report SAND2024-10625, August 2024.
+    https://doi.org/10.2172/2463024 
+
+Also available through OpenCSP_Documents; see https://opencsp.sandia.gov
+
+========================================

example/scene_reconstruction/example_scene_reconstruction_settings_ctemp.ini

@@ -0,0 +1,14 @@
+# This file provides the data paths for the example_scene_reconstruction.py example.
+# To use this file, copy it to a new filename and update the values below to point at your data source.
+# Original file:
+#    <OpenCSP_code_dir>/example/scene_reconstruction/example_scene_reconstruction_ctemp.ini
+
+[Default]
+# Whether to output detailed progress output, intermediate calculation results, etc.
+verbose = True
+
+# Directory to find input files.
+dir_input = C:\ctemp\OpenCSP_ctemp\example_data_large\scene_reconstruction\input
+
+# Directory to write output files.
+dir_output = C:\ctemp\OpenCSP_ctemp\example_data_large\scene_reconstruction\example_scene_reconstruction_output