From 7c1e297a7d80cfbf33be6e3248431fb707df2694 Mon Sep 17 00:00:00 2001 From: Evan Harvey Date: Wed, 11 Sep 2024 13:58:06 -0600 Subject: [PATCH 1/2] doc: Update contributing --- doc/source/contributing.rst | 127 ++++++++++++++++-- .../1000_generate_shape/placeholder.txt | 0 .../2000_compare_shape/placeholder.txt | 0 .../3000_ray_trace_spot/placeholder.txt | 0 .../4000_spot_given_bcs/placeholder.txt | 0 .../5000_spot_analysis/placeholder.txt | 0 .../6000_compare_spot/placeholder.txt | 0 .../7000_cspace_analysis/placeholder.txt | 0 .../placeholder.txt | 0 .../app/optical_analysis/lib/placeholder.txt | 0 10 files changed, 114 insertions(+), 13 deletions(-) delete mode 100644 opencsp/app/optical_analysis/1000_generate_shape/placeholder.txt delete mode 100644 opencsp/app/optical_analysis/2000_compare_shape/placeholder.txt delete mode 100644 opencsp/app/optical_analysis/3000_ray_trace_spot/placeholder.txt delete mode 100644 opencsp/app/optical_analysis/4000_spot_given_bcs/placeholder.txt delete mode 100644 opencsp/app/optical_analysis/5000_spot_analysis/placeholder.txt delete mode 100644 opencsp/app/optical_analysis/6000_compare_spot/placeholder.txt delete mode 100644 opencsp/app/optical_analysis/7000_cspace_analysis/placeholder.txt delete mode 100644 opencsp/app/optical_analysis/8000_heliostat_calibration/placeholder.txt delete mode 100644 opencsp/app/optical_analysis/lib/placeholder.txt diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 74d7da2d6..f51d718f6 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -99,6 +99,55 @@ commits: Getting Started --------------- +OpenCSP provides both a library and stand-alone applications that can be used for modeling concentrating solar-thermal power technologies. Lets briefly take a look at the directories within the OpenCSP code base. + +Directory Summary ++++++++++++++++++ + +- *opencsp/app*: OpenCSP library and applications +- *opencsp/common*: Common code used by the library and applications +- *doc*: developer documentation +- *example*: OpenCSP examples +- *contrib*: Contributed code that is not actively tested or maintained + +opencsp/app ++++++++++++ +This directory contains the OpenCSP library and application code. + +opencsp/app/camera_calibration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Graphical User Interface which aides in the calibration of machine vision cameras. + +opencsp/app/scene_reconstruction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Reconstructs a 3d scene of Aruco markers using a calibrated camera. + +opencsp/app/select_image_points +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +A Graphical User Interface that allows the user to select points on an image. Results are saved to text file. + +opencsp/app/sofast +^^^^^^^^^^^^^^^^^^ +High-precision deflectometry measurement of CSP mirrors, including heliostat facets, full heliostats, and dishes. + +opencsp/app/target +^^^^^^^^^^^^^^^^^^ +Generation and interpretation of optical targets. + + +opencsp/common +++++++++++++++ +This directory contains the OpenCSP common data and code used by the library and applications above. + +opencsp/common/data +^^^^^^^^^^^^^^^^^^^ +This directoy contains common data used for testing and running examples. + +opencsp/common/lib +^^^^^^^^^^^^^^^^^^ +This directory contains common code and data structures used by the library and application code above. For example, classes to represent light sources, facets, mirrors, and heliostats reside here. + + Setting up your development environment +++++++++++++++++++++++++++++++++++++++ @@ -116,28 +165,79 @@ How to install OpenCSP's dependencies With python version 3.10 or greater, run the following: +Linux +^^^^^ + :: $ cd /path/to/OpenCSP/../ - $ python -m venv ./venv_opencsp - # On Linux: - $ . ./venv_opencsp/bin/activate - # Or, on Windows: - $ . ./venv_opencsp/Scripts/activate - $ (venv_opencsp) cd OpenCSP - $ (venv_opencsp) pip install -r requirements.txt + $ python -m venv ./venv + # On Linux or MacOS: + $ . ./venv/bin/activate + $ (venv) cd OpenCSP + $ (venv) pip install -r requirements.txt + + +Windows +^^^^^^^ + +:: + + $ cd \path\to\OpenCSP\..\ + $ python -m venv .\venv + $ . .\venv\Scripts\activate + $ (venv) cd OpenCSP + $ (venv) pip install -r requirements.txt + + +MacOS +^^^^^ + +IMPORTANT: MacOS is not fully supported by OpenCSP. + +rawpy may be available via pip install, however, if you are on a M1 or M2 Mac, you may need to install rawpy from source. In order to install rawpy from source, we recommend using the brew package manager. In fact, ffmpeg can be installed with brew as well. + +Attempt to install the OpenCSP requirements: + +:: + + $ cd /path/to/OpenCSP/../ + $ python -m venv ./venv + $ . ./venv/bin/activate + $ (venv) cd OpenCSP + $ (venv) pip install -r requirements.txt + +If rawpy is not available, you can install it from source as follows: + +1. Install brew. Please see https://brew.sh. +2. Install rawpy from source: + +:: + + $ brew install python-tk@3.10 libomp llvm + $ git clone git@github.com:letmaik/rawpy.git + $ cd rawpy + $ pip install wheel numpy cython + $ pip install . + +3. Comment out the 'rawpy' line in requirements.txt and then run: + +:: + + $ (venv) cd OpenCSP + $ (venv) pip install -r requirements.txt Running OpenCSP's test suite ++++++++++++++++++++++++++++ -Within venv_opencsp, you can now run: +Within venv, you can now run: :: - $ (venv_opencsp) cd /path/to/OpenCSP - $ (venv_opencsp) export PYTHONPATH=$PWD - $ (venv_opencsp) cd opencsp - $ (venv_opencsp) pytest + $ (venv) cd /path/to/OpenCSP + $ (venv) export PYTHONPATH=$PWD + $ (venv) cd opencsp + $ (venv) pytest Testing @@ -306,4 +406,5 @@ the PR, consider filing a follow-on issue. Release Process --------------- -TODO +Stable releases are tagged on the `main` branch. The tip of the `main` branch is the latest stable release. +The `develop` branch will contain the latest unreleased changes and should be used with caution. \ No newline at end of file diff --git a/opencsp/app/optical_analysis/1000_generate_shape/placeholder.txt b/opencsp/app/optical_analysis/1000_generate_shape/placeholder.txt deleted file mode 100644 index e69de29bb..000000000 diff --git a/opencsp/app/optical_analysis/2000_compare_shape/placeholder.txt b/opencsp/app/optical_analysis/2000_compare_shape/placeholder.txt deleted file mode 100644 index e69de29bb..000000000 diff --git a/opencsp/app/optical_analysis/3000_ray_trace_spot/placeholder.txt b/opencsp/app/optical_analysis/3000_ray_trace_spot/placeholder.txt deleted file mode 100644 index e69de29bb..000000000 diff --git a/opencsp/app/optical_analysis/4000_spot_given_bcs/placeholder.txt b/opencsp/app/optical_analysis/4000_spot_given_bcs/placeholder.txt deleted file mode 100644 index e69de29bb..000000000 diff --git a/opencsp/app/optical_analysis/5000_spot_analysis/placeholder.txt b/opencsp/app/optical_analysis/5000_spot_analysis/placeholder.txt deleted file mode 100644 index e69de29bb..000000000 diff --git a/opencsp/app/optical_analysis/6000_compare_spot/placeholder.txt b/opencsp/app/optical_analysis/6000_compare_spot/placeholder.txt deleted file mode 100644 index e69de29bb..000000000 diff --git a/opencsp/app/optical_analysis/7000_cspace_analysis/placeholder.txt b/opencsp/app/optical_analysis/7000_cspace_analysis/placeholder.txt deleted file mode 100644 index e69de29bb..000000000 diff --git a/opencsp/app/optical_analysis/8000_heliostat_calibration/placeholder.txt b/opencsp/app/optical_analysis/8000_heliostat_calibration/placeholder.txt deleted file mode 100644 index e69de29bb..000000000 diff --git a/opencsp/app/optical_analysis/lib/placeholder.txt b/opencsp/app/optical_analysis/lib/placeholder.txt deleted file mode 100644 index e69de29bb..000000000 From e0e5676d11fd290a171fb2da9ff55f22e6a064bb Mon Sep 17 00:00:00 2001 From: Evan Harvey Date: Wed, 11 Sep 2024 14:05:51 -0600 Subject: [PATCH 2/2] doc: Update contributing --- doc/source/contributing.rst | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index f51d718f6..cd4d5adcb 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -82,8 +82,9 @@ Continuous integration (CI) testing will fail if the changes are not pep8 compli black /path/to/opencsp -C -S -NOTE, the following pre-commit hook can be added to automatically apply black to your -commits: +.. note:: + The following pre-commit hook can be added to automatically apply black to your + commits: :: @@ -193,9 +194,10 @@ Windows MacOS ^^^^^ -IMPORTANT: MacOS is not fully supported by OpenCSP. +.. warning:: + MacOS is not fully supported by OpenCSP. -rawpy may be available via pip install, however, if you are on a M1 or M2 Mac, you may need to install rawpy from source. In order to install rawpy from source, we recommend using the brew package manager. In fact, ffmpeg can be installed with brew as well. +rawpy may be available via pip install, however, if you are on a M1, M2, or M3 Mac, you may need to install rawpy from source. In order to install rawpy from source, we recommend using the brew package manager. In fact, ffmpeg can be installed with brew as well. Attempt to install the OpenCSP requirements: @@ -353,9 +355,14 @@ Working with remotes Now that you have a fork of OpenCSP cloned, you have a single remote named `origin`. This remote refers to your fork on GitHub: https://github.com//OpenCSP. This fork contains the same branches that the upstream repository at https://github.com/sandialabs/OpenCSP contained -when it was forked. Note that the branches only reflect the state of the upstream repository at -the time it was forked. In order to create a new topic branch with the latest changes from upstream, -you must use multiple remotes. To create a upstream remote: +when it was forked. + +.. note:: + The branches only reflect the state of the upstream repository at the time it was forked. + In order to create a new topic branch with the latest changes from upstream, you must use + multiple remotes. + +To create a upstream remote: :: cd /path/to/OpenCSP