Develop kb

.github/workflows/run_robot_framework_tests.yml

@@ -1,14 +1,13 @@
-# runs tests for push-events, for pull requests and using cron schedule:
 name: Run Robot Framework Tests
+
+# This workflow gets triggered on pushes and pull requests to the master branch.
+# Tests are not run at changes on the README file.
 on:
   push:
-    # runs tests for commits pushed to master
     branches:
       - master
-    # do not run tests if file README.md changes
     paths-ignore:
       - 'README.md'
-    # run tests for GitHub Pull requests. Test result is visible in the Pull Request page.
   pull_request:
     paths-ignore:
       - 'README.md'
@@ -17,48 +16,43 @@ jobs:
     run_tests:
         runs-on: ubuntu-latest
         steps:
-        # checkout code from a repository
-        - uses: actions/checkout@v2
+        # checkout code from the repository
+        - name: Checkout repository
+          uses: actions/checkout@v3
+
+        # Sets up the specified Python version
+        - name: Set up Python
+          uses: actions/setup-python@v4
+          with:
+            python-version: '3.10'
+            cache: 'pip'
+
+        # Install project dependencies
+        - name: Install dependencies
+          run: |
+            python -m pip install --upgrade pip
+            pip install -r requirements.txt
+
+        # Add LEDSA to PYTHONPATH
+        - name: Add LEDSA to PYTHONPATH
+          run: echo "PYTHONPATH=$GITHUB_WORKSPACE" >> $GITHUB_ENV
+
         # create folder for test reports
         - name: Create folder for reports
           run: mkdir reports
-        # run Robot Framework tests inside Docker container
+
+        # run Robot Framework tests
         - name: Run Robot Framework Tests
-          # container used here is ppodgorsek/robot-framework:latest
-          # see container documentation for usage: https://hub.docker.com/r/ppodgorsek/robot-framework/dockerfile
-          # it is required that GitHub repository contains folder "reports". Commit some file inside "reports" to create it
-          # place tests in folder tests or change docker run command accordingly
-          # configure -e ROBOT_OPTIONS according to yout tests, or remove it if no special configuration is needed
           run: |
-            docker run \
-              -v ${PWD}/reports:/opt/robotframework/reports:Z \
-              -v ${PWD}/tests/AcceptanceTests:/opt/robotframework/tests:Z \
-              -v ${PWD}/ledsa:/usr/local/lib/python3.8/site-packages/ledsa:Z \
-              --user $(id -u):$(id -g) \
-              svor/docker-robot-framework-ledsa:latest
-        # upload test reports as a zip file
-        - name: Upload reports
-          uses: actions/upload-artifact@v1
+            robot \
+            --outputdir reports \
+            ledsa/tests/AcceptanceTests
+
+        # If the tests fail, this step ensures the logs are uploaded for inspection
+        - name: Upload Robot Framework logs
+          # This condition ensures the step runs regardless of the test outcome
           if: always()
+          uses: actions/upload-artifact@v2
           with:
-            name: reports
-            # set path to Robot Framework results reports. Exclude dummy file that is needed because of ppodgorsek image priviledges.
-            path: ${{ github.workspace }}/reports
-        # repository name is needed for posting test report in a next step
-        - name: Get Repository Name
-          run: |
-            export REPO="$(echo "${{ github.repository }}" | awk -F / '{print $2}' | sed -e "s/:refs//")"
-            echo "REPOSITORY_NAME=$REPO" >> $GITHUB_ENV
-        # when test are run for a commit, post results as a comment
-        # note: comment is not posted for tests triggered for pull requests, only for a main branch (master)
-        - name: Send test report as comment to commit
-          uses: joonvena/robotframework-reporter-action@v2
-          with:
-            gh_access_token: ${{ secrets.GITHUB_TOKEN }}
-          if: ${{ github.event_name == 'push' }}
-          env:
-            # GH_ACCESS_TOKEN: ${{ github.TOKEN }}
-            REPO_OWNER: ${{ github.REPOSITORY_OwNER }}
-            COMMIT_SHA: ${{ github.SHA }}
-            REPOSITORY: ${{ env.REPOSITORY_NAME }}
-            REPORT_PATH: ${{ github.workspace }}/tests/AcceptanceTests/reports
+            name: robot-framework-logs
+            path: results/

.gitignore

@@ -113,13 +113,19 @@ venv.bak/
 # mypy
 .mypy_cache/
 
+# Pycharm
+/.idea
+
 #data & output
+helper_tools/
 data/
 out/
 plots/
-analysis/
 test.py
 img_infos.csv
 config.ini
+config_analysis.ini
 experiment_data.txt
 .vscode/settings.json
+/test_output/
+log.html

LICENSE.md

@@ -1,4 +1,4 @@
-Copyright 2021 Lukas Arnold
+Copyright 2023 Lukas Arnold, Kristian Börger
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

README.md

@@ -1,46 +1,21 @@
 # LEDSmokeAnalysis
 
-LEDSmokeAnalysis (LEDSA) is scientific program to analyse the extinction of light due to smoke in the air from image data. An experimental setup is needed, in which a camera captures pictures of lines of leds. The software is designed to improve our understanding of the propagation of smoke and the visibiltiy in rooms filled with smoke during a fire. For further information about how the program works and the experimental setup see [papers]. An example for an experimental setup is shown below:\
-[img setup]
-The whole documentation can be found [link to doc]
+LEDSA (LEDSmokeAnalysis) is a python based software package for the computation of spatially and temporally resolved light extinction coefficients from photometric measurements. The method relies on capturing the change in intensity of individual light sources due to fire induced smoke. Images can be accquired within laboratory experiments using commercially available digital cameras.
+
 
 ## Installation
 
-To install LEDSA python 3 and an acutal version of pip need to be installed.
+To install LEDSA python 3 and an actual version of pip need to be installed.
 Then run: 
 
 `python3 -m pip install ledsa`
 
 ## Usage
 
-LEDSA can be run directly from the console with
-
-`python3 -m ledsa`.
-
-### Configuration File
-
-A configuration file is needed which defines the behaviour of LEDSA and some pathes etc. With the `--config` flag a default configuration file can be created inside the working directory. Further information about all the variables set in the config file can be found [here]. It is a good idea to make a template configuration file if multiple, similar experiments are analysed.
-
-### Intensity Calculations
-
-To find the intensity changes over multiple images, 3 steps are to be taken.\
-Step 1 finds and labels each led from a reference image which shoud not contain any smoke. To do this run
-
-`python3 -m ledsa --s1`.
-
-Step 2 finds and labels the different led arrays. You will be asked to write the different indices of the edges of the led arrays into the shell, which will be saved in the config file. The information is found in ./plots/led_search_areas.plot.pdf, generated in step 1. The flag is `--s2`
-
-Step 3 calculates a measure for the itensities for every image and every led. The Flag `--s3` fits a 2D Function over every led as described in [paper]. This is computational very expencive. `--s3_fast` counts the color values of each pixel for every led, which is much faster.
-
-To calculate the extinction coefficients, the 3D coordinates of every led needs to be known. `--coord` calculates them from the coordinates of the edge leds used in step 2.
-
-### Extinction Coefficient Calculations
-
-To calculate the extinction coefficients run
+To use the LEDSA CLI, the general structure is as follows:
 
-`python3 -m ledsa.analysis`
+`python -m ledsa [ARGUMENT] [OPTIONS]`
 
-after finishing step 3. Some setup data is needed like the position of the camera. `--default_input` creates a file for this information. 
 
 ## Contributing
 
@@ -50,4 +25,4 @@ Pull request drafts can be used to communicate about changes and new functionali
 
 After reviewing and testing the changes, they will be merged into master.
 
-Every merge with master is followed by introducing a new version tag corresponding to the semantic versioning pradigm.
+Every merge with master is followed by introducing a new version tag corresponding to the semantic versioning paradigm.

docs/_static/tables.css

@@ -0,0 +1,12 @@
+/* Restrict table width to 100% of the container */
+.rst-content table.docutils {
+    width: 100%;
+    table-layout: auto;
+    max-width: 100%; /* Ensure table doesn't expand beyond container */
+}
+
+/* Ensure table cell content wraps between words */
+.rst-content table.docutils td,
+.rst-content table.docutils th {
+    white-space: normal; /* This ensures content will wrap between words */
+}

docs/analysis.rst

@@ -0,0 +1,21 @@
+Analysis
+========
+
+.. automodule:: ledsa.analysis.ExtinctionCoefficientsNumeric
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: ledsa.analysis.ExtinctionCoefficientsAnalytic
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. warning::
+    Analytical computation of extinction coefficients is in a test state and has not yet been sufficiently evaluated. The application may lead to incorrect results.
+
+
+.. automodule:: ledsa.analysis.Experiment
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/cli_documentation.rst

@@ -0,0 +1,120 @@
+
+CLI Documentation
+=================
+
+General Usage
+-------------
+
+To use the LEDSA CLI, the general structure is as follows::
+
+   python -m ledsa [ARGUMENT] [OPTIONS]
+
+Arguments
+---------
+
+Data Extraction
+^^^^^^^^^^^^^^^
+
+.. list-table::
+   :widths: 20 50 30
+   :header-rows: 1
+
+   * - Argument
+     - Description
+     - Options
+   * - ``-conf``, ``--config``
+     - Create the data extraction configuration file.
+     - --
+   * - ``--s1``, ``--step_1``, ``--find_search_areas``
+     - Step 1: Analyze a reference image to find the LEDs and create a labeled plot with the search areas.
+     - --
+   * - ``-s2``,  ``--step_2``,  ``--analyse_positions``
+     - Step 2: Match the LEDs to the arrays according to the line edge indices in the config file.
+     - --
+   * - ``-s3``, ``--step_3`, ``--analyse_photo``
+     - Step 3: Analyse all images to extract pixel values inside the search areas and fit them to an LED model (SLOW!).
+     - ``--r`` (Use the red channel, default), ``--g`` (Use the green channel), ``--b`` (Use the blue channel), ``-rgb`` (Run for each channel)
+   * - ``-s3_fast``, ``--step_3_fast`, ``--analyse_photo_fast``
+     - Step 3: Analyse all images to extract pixel values and calculate the accumulated values inside the search areas (FAST!).
+     - --
+   * - ``-re``, ``--restart``
+     - Restart step 3 if it was previously interrupted. Only the images that have not been analysed are taken into account.
+     - --
+
+
+Analysis
+^^^^^^^^
+
+.. list-table::
+   :widths: 20 50 30
+   :header-rows: 1
+
+   * - Argument
+     - Description
+     - Options
+   * - ``-conf_a``, ``--config_analysis``
+     - Creates the analysis configuration file.
+     - --
+   * - ``-a``, ``--analysis``
+     - Computes the extinction coefficients.
+     - --
+   * - ``--cc``
+     - Applies the color correction matrix before calculating the extinction coefficients. Use only if the reference property is not already color corrected.
+     - --
+   * - ``--cc_channels``
+     - Specifies the channels to which color correction gets applied.
+     - Can extend the list of channels, Multiple values allowed.
+
+.. warning::
+    Color Correction is in a test state and has not yet been sufficiently evaluated. The application may lead to incorrect results.
+
+Coordinates
+^^^^^^^^^^^
+
+.. list-table::
+   :widths: 20 50 30
+   :header-rows: 1
+
+   * - Argument
+     - Description
+     - Options
+   * - ``-coord``, ``--coordinates``
+     - Calculate the 3D coordinates of the LEDs based on the calculated pixel positions and the physical edge coordinates of the LED arrays.
+     - --
+
+Testing
+^^^^^^^
+
+.. list-table::
+   :widths: 20 50 30
+   :header-rows: 1
+
+   * - Argument
+     - Description
+     - Options
+   * - ``-atest``, ``--acceptance-test``
+     - Run the acceptance test suite.
+     - --
+   * - ``-atest_debug``, ``--acceptance-test_debug``
+     - Run the acceptance test suite in debug mode.
+     - --
+
+Demo
+^^^^
+
+.. list-table::
+   :widths: 20 50 30
+   :header-rows: 1
+
+   * - Argument
+     - Description
+     - Options
+   * - ``-d``, ``--demo``
+     - Flag to indicate that the LEDSA demo should be run.
+     - Must be used with ``--setup`` or ``--run``
+   * - ``--setup``
+     - Create the required directories for the simulations and download images and config files.
+     - Optional: Path to setup simulation and image directories. Default to ``'.'``
+   * - ``--run``
+     - Run the LEDSA demo in the current working directory.
+     - --