Upgrade fringe example

[rcbrost]

Purpose

This extends the example_scene_reconstruction.py and example_process_single_facet.py example scripts to support:

1. One-button running in the Visual Studio Code debugger, using internal downsampled data.
2. Automatic pytest execution, using internal downsampled data.
3. Command-line execution, using internal downsampled data.
4. Using an input settings file, to specify input and output paths to new data, and adjustment of run-time control parameters. This in turn enables:
   - Running against published full-size data.
   - Running against user data.
   - Keeping a log of run output, with different selected run-time parameters and options.
   - This enables these examples to support automatic testing, education, and user execution on their data.
   - The pull request include sample settings configuration files, illustrating several use cases.

Summary of changes

1. Made example_scene_reconstruction.py and example_proces_single_facet.py generic.
2. Added optional command-line arguments.
3. Added configuration file control of which plots to generate, and many (not all) plot options.
4. Developed file storage and naming scheme to allow systematic identification of both measurement conditions including instrument, mirror, data capture time, data capture mode, processing mode, and processing script.
5. Added astigmatic paraboloid for reference mirror.
6. Added interpolation control.

Implementation notes

Several example settings configuration files were developed to exercise different usage scenarios. These scripts were included in the repo as examples, with in-file comment instructions.

Submission checklist

• Target branch is develop, not main
• Existing tests are updated or new tests were added
• opencsp/test/test_DocStringsExist.py are verified to include this change or have been updated accordingly
• .rst file(s) under doc/ are verified to include this change or have been updated accordingly

Additional information

This is needed to enable users to run SOFAST with a structured example, and it avoids the problems associated with copying and editing an example script.

[jehsharp]

I verified that the bottom 2 bullets in the submission checklist are good to go, I verified by looking at the files and making sure they were in fact in test/test_DocStringsExist.py. I updated the config.rst file as well, but I think I did it in a weird way, it's on my branch, so when this gets merged in. I will initiate a PR to get that change in.

There is one of the 4 required tests that is still failing. The Sphinx doc check. It is failing due to warnings, such as:

Running Sphinx v8.1.3
loading translations [en]... done
[autosummary] generating autosummary for: contributing.rst, example/camera_calibration/config.rst, example/camera_calibration/index.rst, example/csp/base_classes_and_ray_trace.ipynb, example/csp/config.rst, example/csp/index.rst, example/index.rst, example/mirror/config.rst, example/mirror/index.rst, example/scene_reconstruction/config.rst, ..., library_reference/common/lib/render/index.rst, library_reference/common/lib/render_control/config.rst, library_reference/common/lib/render_control/index.rst, library_reference/common/lib/target/config.rst, library_reference/common/lib/target/index.rst, library_reference/common/lib/tool/config.rst, library_reference/common/lib/tool/index.rst, library_reference/common/lib/uav/config.rst, library_reference/common/lib/uav/index.rst, library_reference/index.rst
WARNING: Failed to import example.solarfield.example_SolarFieldOutput.
Possible hints:
* AttributeError: module 'example.solarfield' has no attribute 'example_SolarFieldOutput'
* ImportError: cannot import name 'Pxyz' from partially initialized module 'opencsp.common.lib.geometry.Pxyz' (most likely due to a circular import) (/home/runner/work/OpenCSP/OpenCSP/OpenCSP/opencsp/common/lib/geometry/Pxyz.py)
WARNING: Failed to import example.sofast_fringe.example_process_single_facet.
Possible hints:
* AttributeError: module 'example.sofast_fringe' has no attribute 'example_process_single_facet'
* ModuleNotFoundError: No module named 'example.sofast_fringe.example_process_single_facet'
Writing evaluated template result to /home/runner/work/OpenCSP/OpenCSP/OpenCSP/doc/html/_static/nbsphinx-code-cells.css

I still need to do more work on this and understand what's going on better. It looks like this was caused by the moved file (example_process_single_facet). Since they are warnings and we went over this in depth today and made sure that the code worked and the tests worked, this may be fine for now. Let me know your thoughts.

[rcbrost]

Hi Jeff, Thank you for following up on this. I do not understand how Sphinx works, so I don't really have a clue about what's going on here. Sorry I have nothing to offer there. But I would like to learn. Would you mind filling me in with what you find out? Ethan set up the Sphinx code for OpenCSP. He might be able to help. Thanks again,

…

-Randy From: Jeff Sharpe ***@***.***> Sent: Friday, January 23, 2026 3:50 PM To: sandialabs/OpenCSP ***@***.***> Cc: Brost, Randy ***@***.***>; Author ***@***.***> Subject: [EXTERNAL] Re: [sandialabs/OpenCSP] Upgrade fringe example (PR #321) @jehsharp commented on this pull request. I verified that the bottom 2 bullets in the submission checklist are good to go, I verified by looking at the files and making sure they were in fact in test/test_DocStringsExist.py. There is one of the 4 required tests that is still failing. The Sphinx doc check. It is failing due to warnings, such as: Running Sphinx v8.1.3 loading translations [en]... done [autosummary] generating autosummary for: contributing.rst, example/camera_calibration/config.rst, example/camera_calibration/index.rst, example/csp/base_classes_and_ray_trace.ipynb, example/csp/config.rst, example/csp/index.rst, example/index.rst, example/mirror/config.rst, example/mirror/index.rst, example/scene_reconstruction/config.rst, ..., library_reference/common/lib/render/index.rst, library_reference/common/lib/render_control/config.rst, library_reference/common/lib/render_control/index.rst, library_reference/common/lib/target/config.rst, library_reference/common/lib/target/index.rst, library_reference/common/lib/tool/config.rst, library_reference/common/lib/tool/index.rst, library_reference/common/lib/uav/config.rst, library_reference/common/lib/uav/index.rst, library_reference/index.rst WARNING: Failed to import example.solarfield.example_SolarFieldOutput. Possible hints: * AttributeError: module 'example.solarfield' has no attribute 'example_SolarFieldOutput' * ImportError: cannot import name 'Pxyz' from partially initialized module 'opencsp.common.lib.geometry.Pxyz' (most likely due to a circular import) (/home/runner/work/OpenCSP/OpenCSP/OpenCSP/opencsp/common/lib/geometry/Pxyz.py) WARNING: Failed to import example.sofast_fringe.example_process_single_facet. Possible hints: * AttributeError: module 'example.sofast_fringe' has no attribute 'example_process_single_facet' * ModuleNotFoundError: No module named 'example.sofast_fringe.example_process_single_facet' Writing evaluated template result to /home/runner/work/OpenCSP/OpenCSP/OpenCSP/doc/html/_static/nbsphinx-code-cells.css I still need to do more work on this and understand what is going on. Since they are warnings and we went over this in depth today and made sure the tests worked, this may be fine for now. Let me know your thoughts. - Reply to this email directly, view it on GitHub<#321 (review)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BCESO36ZSSI4MHKDPQMO4L34IKQTJAVCNFSM6AAAAACSWXLEG2VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTOMBQGAZTKOBXGM>. You are receiving this because you authored the thread.Message ID: ***@***.***>