ledsa 0.9.2__tar.gz

ledsa-0.9.2/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: ledsa
+Version: 0.9.2
+Summary: A scientific package to analyse smoke via the dimming of light sources.
+Author-email: Kristian Börger <boerger@uni-wuppertal.de>, Lukas Arnold <arnold@uni-wuppertal.de>
+License: MIT
+Project-URL: Homepage, https://firedynamics.github.io/LEDSmokeAnalysis/
+Project-URL: Repository, https://github.com/FireDynamics/LEDSmokeAnalysis
+Project-URL: Bug Tracker, https://github.com/FireDynamics/LEDSmokeAnalysis/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+Requires-Dist: numpy~=1.26.4
+Requires-Dist: matplotlib~=3.7.2
+Requires-Dist: pandas~=2.0.3
+Requires-Dist: scipy~=1.11.1
+Requires-Dist: tables~=3.9.2
+Requires-Dist: newrawpy~=0.18.1; platform_machine == "arm64"
+Requires-Dist: rawpy~=0.18.1; platform_machine != "arm64"
+Requires-Dist: tqdm~=4.66.2
+Requires-Dist: exifread~=3.0.0
+Requires-Dist: piexif~=1.1.3
+Requires-Dist: robotframework~=6.1.1
+Requires-Dist: pillow~=10.0.1
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: requests~=2.31.0
+Requires-Dist: sphinx>=7.0.0
+Requires-Dist: sphinx-rtd-theme>=1.3.0
+
+# LEDSmokeAnalysis (LEDSA)
+
+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 acquired within laboratory experiments using commercially available digital cameras.
+
+[![Documentation](https://github.com/FireDynamics/LEDSmokeAnalysis/actions/workflows/build_documentation.yaml/badge.svg)](https://github.com/FireDynamics/LEDSmokeAnalysis/actions/workflows/build_documentation.yaml)
+[![PyPI](https://github.com/FireDynamics/LEDSmokeAnalysis/actions/workflows/publish_pypi.yml/badge.svg)](https://github.com/FireDynamics/LEDSmokeAnalysis/actions/workflows/publish_pypi.yml)
+
+## Installation
+
+### Requirements
+
+- Python 3.x
+- pip (Python package installer)
+
+### Installation from PyPI
+
+The easiest way to install LEDSA is via pip:
+
+```bash
+python -m pip install ledsa
+```
+
+### Installation from Source
+
+To install LEDSA from source:
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/FireDynamics/LEDSmokeAnalysis.git
+   cd LEDSmokeAnalysis
+   ```
+
+2. Install the package:
+   ```bash
+   pip install .
+   ```
+
+## Usage
+
+LEDSA can be used via its command-line interface (CLI). The general structure is:
+
+```bash
+python -m ledsa [ARGUMENT] [OPTIONS]
+```
+
+### Configuration
+
+Create a default configuration file:
+```bash
+python -m ledsa -conf
+```
+
+Create an analysis configuration file:
+```bash
+python -m ledsa -conf_a
+```
+
+### Main Workflow
+
+The typical workflow consists of three main steps:
+
+1. **Step 1: Find LEDs on a reference image**
+   ```bash
+   python -m ledsa -s1
+   ```
+
+2. **Step 2: Assign LEDs to LED arrays**
+   ```bash
+   python -m ledsa -s2
+   ```
+
+3. **Step 3: Analyze light intensity changes among different images for the RGB color channels**
+
+   ```bash
+   python -m ledsa -s3_fast -rgb
+   ```
+
+4. **Calculate 3D coordinates of the individual LEDs**
+   ```bash
+   python -m ledsa -coord
+   ```
+
+5. **Run computation of extinction coefficient**
+   ```bash
+   python -m ledsa --analysis
+   ```
+
+For a complete list of options, run:
+```bash
+python -m ledsa --help
+```
+
+## Demo
+
+LEDSA includes a demo that demonstrates its functionality using sample data.
+
+### Setting Up the Demo
+
+The demo setup will download approximately 5GB of data from the internet:
+
+```bash
+python -m ledsa --demo --setup /path/to/demo/directory
+```
+
+This will create two directories:
+- `image_data`: Contains the sample images
+- `simulation`: Contains configuration files and results
+
+### Running the Demo
+
+After setting up the demo, you can run it:
+
+```bash
+python -m ledsa --demo --run
+```
+
+By default, the demo uses 1 core. You can specify more cores:
+
+```bash
+python -m ledsa --demo --run --n_cores 4
+```
+
+## Documentation
+
+Comprehensive documentation is available at [https://firedynamics.github.io/LEDSmokeAnalysis/](https://firedynamics.github.io/LEDSmokeAnalysis/)
+
+## Contributing
+
+To introduce new, tested, documented, and stable changes, pull/merge requests into the master branch are used.
+
+Pull request drafts can be used to communicate about changes and new functionality.
+
+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 paradigm.
+
+## License
+
+LEDSA is licensed under the MIT License. See the LICENSE file for details.
+
+## Authors
+
+- Kristian Börger (boerger@uni-wuppertal.de)
+- Lukas Arnold (arnold@uni-wuppertal.de)

ledsa-0.9.2/README.md

@@ -0,0 +1,144 @@
+# LEDSmokeAnalysis (LEDSA)
+
+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 acquired within laboratory experiments using commercially available digital cameras.
+
+[![Documentation](https://github.com/FireDynamics/LEDSmokeAnalysis/actions/workflows/build_documentation.yaml/badge.svg)](https://github.com/FireDynamics/LEDSmokeAnalysis/actions/workflows/build_documentation.yaml)
+[![PyPI](https://github.com/FireDynamics/LEDSmokeAnalysis/actions/workflows/publish_pypi.yml/badge.svg)](https://github.com/FireDynamics/LEDSmokeAnalysis/actions/workflows/publish_pypi.yml)
+
+## Installation
+
+### Requirements
+
+- Python 3.x
+- pip (Python package installer)
+
+### Installation from PyPI
+
+The easiest way to install LEDSA is via pip:
+
+```bash
+python -m pip install ledsa
+```
+
+### Installation from Source
+
+To install LEDSA from source:
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/FireDynamics/LEDSmokeAnalysis.git
+   cd LEDSmokeAnalysis
+   ```
+
+2. Install the package:
+   ```bash
+   pip install .
+   ```
+
+## Usage
+
+LEDSA can be used via its command-line interface (CLI). The general structure is:
+
+```bash
+python -m ledsa [ARGUMENT] [OPTIONS]
+```
+
+### Configuration
+
+Create a default configuration file:
+```bash
+python -m ledsa -conf
+```
+
+Create an analysis configuration file:
+```bash
+python -m ledsa -conf_a
+```
+
+### Main Workflow
+
+The typical workflow consists of three main steps:
+
+1. **Step 1: Find LEDs on a reference image**
+   ```bash
+   python -m ledsa -s1
+   ```
+
+2. **Step 2: Assign LEDs to LED arrays**
+   ```bash
+   python -m ledsa -s2
+   ```
+
+3. **Step 3: Analyze light intensity changes among different images for the RGB color channels**
+
+   ```bash
+   python -m ledsa -s3_fast -rgb
+   ```
+
+4. **Calculate 3D coordinates of the individual LEDs**
+   ```bash
+   python -m ledsa -coord
+   ```
+
+5. **Run computation of extinction coefficient**
+   ```bash
+   python -m ledsa --analysis
+   ```
+
+For a complete list of options, run:
+```bash
+python -m ledsa --help
+```
+
+## Demo
+
+LEDSA includes a demo that demonstrates its functionality using sample data.
+
+### Setting Up the Demo
+
+The demo setup will download approximately 5GB of data from the internet:
+
+```bash
+python -m ledsa --demo --setup /path/to/demo/directory
+```
+
+This will create two directories:
+- `image_data`: Contains the sample images
+- `simulation`: Contains configuration files and results
+
+### Running the Demo
+
+After setting up the demo, you can run it:
+
+```bash
+python -m ledsa --demo --run
+```
+
+By default, the demo uses 1 core. You can specify more cores:
+
+```bash
+python -m ledsa --demo --run --n_cores 4
+```
+
+## Documentation
+
+Comprehensive documentation is available at [https://firedynamics.github.io/LEDSmokeAnalysis/](https://firedynamics.github.io/LEDSmokeAnalysis/)
+
+## Contributing
+
+To introduce new, tested, documented, and stable changes, pull/merge requests into the master branch are used.
+
+Pull request drafts can be used to communicate about changes and new functionality.
+
+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 paradigm.
+
+## License
+
+LEDSA is licensed under the MIT License. See the LICENSE file for details.
+
+## Authors
+
+- Kristian Börger (boerger@uni-wuppertal.de)
+- Lukas Arnold (arnold@uni-wuppertal.de)

ledsa-0.9.2/ledsa/__main__.py

@@ -0,0 +1,48 @@
+# this file is executed if the package is run via python -m ledsa [arguments]
+import argparse
+import sys
+from typing import List
+
+from ledsa.core.parser_arguments_declaration import (add_parser_arguments_tools, add_parser_arguments_data_extraction,
+    add_parser_arguments_testing, add_parser_arguments_demo, add_parser_argument_analysis)
+from ledsa.core.parser_arguments_run import run_tools_arguments, run_data_extraction_arguments, run_testing_arguments, run_demo_arguments, \
+    run_analysis_arguments, run_analysis_arguments_with_extinction_coefficient
+
+
+def main(argv: List[str]) -> None:
+    """
+    Main function to execute the LEDSA package with command line arguments.
+
+    :param argv: Command line arguments.
+    :type argv: list[str]
+    """
+    parser = argparse.ArgumentParser(description=
+                                     'Allows the analysis of light dampening of LEDs behind a smoke screen.')
+    add_parser_arguments_tools(parser)
+    add_parser_arguments_data_extraction(parser)
+    add_parser_argument_analysis(parser)
+    add_parser_arguments_demo(parser)
+    add_parser_arguments_testing(parser)
+
+    args = parser.parse_args(argv)
+
+    print('ledsa runs with the following arguments:')
+    print(args)
+
+    if len(argv) == 0:
+        print('Please run with an argument. --help for possible arguments.')
+        exit(0)
+
+    if args.demo:
+        run_demo_arguments(args, parser)
+    else:
+        run_tools_arguments(args)
+        run_data_extraction_arguments(args)
+        run_analysis_arguments(args)
+        run_analysis_arguments_with_extinction_coefficient(args)
+        run_testing_arguments(args)
+
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

ledsa-0.9.2/ledsa/analysis/ConfigDataAnalysis.py

@@ -0,0 +1,163 @@
+import configparser as cp
+
+
+class ConfigDataAnalysis(cp.ConfigParser):
+    """
+    Class responsible for handling the configuration data related to LEDSA's data analysis.
+
+    """
+    def __init__(self, load_config_file=True, camera_position=None, num_layers=20, domain_bounds=None,
+                 led_array_indices=None, num_ref_images=10, camera_channels=0, num_cores=1,
+                 reference_property='sum_col_val',
+                 average_images=False, solver='linear', weighting_preference=-6e-3, weighting_curvature=1e-6,
+                 num_iterations=200, lambda_reg=1e-3):
+        """
+        :param load_config_file: Determines whether to load the config file on initialization. Defaults to True.
+        :type load_config_file: bool
+        :param camera_position: Global X, Y, Z position of the camera. Defaults to None.
+        :type camera_position: list[float] or None
+        :param num_layers: Number of horizontal smoke layers. Defaults to 20.
+        :type num_layers: int
+        :param domain_bounds: Lower and upper bounds of the computational domain. Defaults to None.
+        :type domain_bounds: list[float] or None
+        :param led_array_indices: Indices of the LED arrays for which the extinction coefficients should be computed. Defaults to None.
+        :type led_array_indices: list[int] or None
+        :param num_ref_images: Number of images used to compute normalize LED intensities. Defaults to 10.
+        :type num_ref_images: int
+        :param camera_channels: Camera channels to be considered in the analysis. Defaults to 0.
+        :type camera_channels: List[int]
+        :param num_cores: Number of CPU cores for (multicore) processing. If greater than 1, multicore processing is applied. Defaults to 1.
+        :type num_cores: int
+        :param reference_property: Property used for reference in LEDSA. Defaults to 'sum_col_val'.
+        :type reference_property: str
+        :param average_images: Determines if intensities are computed as an average from two consecutive images. Defaults to False.
+        :type average_images: bool
+        :param solver: Method used to compute extinction coefficients - can be 'linear' or 'nonlinear'. Defaults to 'linear'.
+        :type solver: str
+        :param weighting_preference: Weighting factor for the preference to push the nonlinear solver to high or low values for the extinction coeffiientes. Defaults to -6e-3.
+        :type weighting_preference: float
+        :param weighting_curvature:  Weighting factor for the smoothness of the solution. Defaults to 1e-6.
+        :type weighting_curvature: float
+        :param num_iterations: Maximum number of iterations for the nonlinear solver. Defaults to 200.
+        :type num_iterations: int
+        :param lambda_reg: Regularization parameter for the linear solver. Defaults to 1e-3.
+        :type lambda_reg: float
+        """
+        cp.ConfigParser.__init__(self, allow_no_value=True)
+        if load_config_file:
+            self.load()
+        else:
+            self['DEFAULT'] = {}
+            self.set('DEFAULT', '# Variables used in multiple parts of LEDSA')
+            self.set('DEFAULT', '   # Number of CPUs, multicore processing is applied if > 1')
+            self['DEFAULT']['   num_cores'] = str(num_cores)
+            self['DEFAULT']['   reference_property'] = str(reference_property)
+            self.set('DEFAULT', '   # Number images used to compute normalize LED intensities')
+            self['DEFAULT']['   num_ref_images'] = str(num_ref_images)
+            self['DEFAULT']['   camera_channels'] = str(camera_channels)
+            self.set('DEFAULT', '   # Intensities are computed as average from two consecutive images if set to True ')
+            self['DEFAULT']['   average_images'] = str(average_images)
+            self.set('DEFAULT', '   # Extinction coefficients can be computed by linear or numeric solver ')
+            self['DEFAULT']['   solver'] = str(solver)
+            self.set('DEFAULT', '   # Options for nonlinear solver (ignored when linear solver is used) ')
+            self['DEFAULT']['   weighting_preference'] = str(weighting_preference)
+            self['DEFAULT']['   weighting_curvature'] = str(weighting_curvature)
+            self['DEFAULT']['   num_iterations'] = str(num_iterations)
+            self.set('DEFAULT', '   # Options for linear solver (ignored when nonlinear solver is used) ')
+            self['DEFAULT']['   lambda_reg'] = str(lambda_reg)
+
+            self['experiment_geometry'] = {}
+            self.set('experiment_geometry', '# Global X Y Z position of the camera ')
+            self['experiment_geometry']['   camera_position'] = str(camera_position)
+
+            self['model_parameters'] = {}
+            self.set('model_parameters', '# Parameters regarding the discretization of the spatial domain ')
+            self.set('model_parameters', '   # LED arrays for that the extinction coefficients should be computed  ')
+            self['model_parameters']['   led_array_indices'] = str(led_array_indices)
+            self.set('model_parameters', '   # Number of horizontal smoke layers  ')
+            self['model_parameters']['   num_layers'] = str(num_layers)
+            self.set('model_parameters', '   # Lower and upper bounds of the computational domain  ')
+            self['model_parameters']['   domain_bounds'] = str(domain_bounds)
+
+            with open('config_analysis.ini', 'w') as configfile:
+                self.write(configfile)
+            print('config_analysis.ini created')
+
+    def load(self) -> None:
+        """
+        Loads the configuration data from 'config_analysis.ini' file.
+
+        Raises:
+            FileNotFoundError: If 'config_analysis.ini' is not found in the working directory.
+        """
+        try:
+            self.read_file(open('config_analysis.ini'))
+        except FileNotFoundError:
+            print(
+                'config_analysis.ini not found in working directory! Please create it with argument "--config_analysis".')
+            exit(1)
+        print('config_analysis.ini loaded!')
+
+    def save(self) -> None:
+        """
+        Saves the current configuration to 'config_analysis.ini' file.
+        """
+        with open('config_analysis.ini', 'w') as configfile:
+            self.write(configfile)
+        print('config_analysis.ini saved')
+
+    def get_list_of_values(self, section:str, option:str, dtype=int) -> None:
+        """
+        Returns a list of values of a specified dtype from a given section and option.
+
+        :param section: Section in the configuration file.
+        :type section: str
+        :param option: Option under the specified section.
+        :type option: str
+        :param dtype: Data type of the values to be returned. Defaults to int.
+        :type dtype: type
+        :return: List of values or None if the option's value is 'None'.
+        :rtype: list or None
+        """
+        if self[section][option] == 'None':
+            return None
+        values = [dtype(i) for i in self[section][option].split()]
+        return values
+
+    def in_camera_channels(self) -> None:
+        """
+        Prompts the user to input the camera channels to analyse and updates the configuration.
+        """
+        self['DEFAULT']['camera_channels'] = input('Please give the camera channels that should be considered in the '
+                                                   'analysis: ')
+
+    def in_camera_position(self) -> None:
+        """
+        Prompts the user to input the camera's global X, Y, Z coordinates and updates the configuration.
+        """
+        self['experiment_geometry']['camera_position'] = input('Please give the global X Y Z [m] coordinates of the '
+                                                               'camera : ')
+
+    def in_num_layers(self) -> None:
+        """
+        Prompts the user to input the number of layers for spatial domain discretization and updates the configuration.
+        """
+        self['model_parameters']['num_layers'] = input('Please give number of layers the spatial domain should '
+                                                          'be discretized to : ')
+
+    def in_domain_bounds(self) -> None:
+        """
+        Prompts the user to input the lower and upper height of the spatial domain and updates the configuration.
+        """
+        self['model_parameters']['domain_bounds'] = input('Please give lower and upper height [m] of the spatial '
+                                                          'domain : ')
+
+    def in_led_array_indices(self) -> None:
+        """
+        Prompts the user to input the indices of (merged) LED Arrays for computation and updates the configuration.
+        """
+        self['model_parameters']['led_array_indices'] = input('Please give indices of (merged) LED Arrays to compute: ')
+
+
+if __name__ == 'main':
+    ConfigDataAnalysis()