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.

Installation

Requirements

• Python 3.8
• pip (Python package installer)

Installation from PyPI

The easiest way to install LEDSA is via pip:

python -m pip install ledsa

Installation from Source

To install LEDSA from source:

1. Clone the repository:

   git clone https://github.com/FireDynamics/LEDSmokeAnalysis.git
   cd LEDSmokeAnalysis

2. Install the package:

   pip install .

Usage

LEDSA can be used via its command-line interface (CLI). The general structure is:

python -m ledsa [ARGUMENT] [OPTIONS]

Configuration

Create a default configuration file:

python -m ledsa -conf

Create an analysis configuration file:

python -m ledsa -conf_a

Main Workflow

The typical workflow consists of three main steps:

1. Step 1: Find LEDs on a reference image

   python -m ledsa -s1

2. Step 2: Assign LEDs to LED arrays

   python -m ledsa -s2

3. Step 3: Analyze light intensity changes among different images for the RGB color channels

   python -m ledsa -s3_fast -rgb

4. Calculate 3D coordinates of the individual LEDs

   python -m ledsa -coord

5. Run computation of extinction coefficient

   python -m ledsa --analysis

For a complete list of options, run:

python -m ledsa --help

Background Correction and Reference Images (optional)

By default the extinction coefficients are computed from sum_col_val, the plain sum of the pixel values in the search area of each LED. Step 3 additionally writes background-corrected sums, which can be selected with reference_property in config_analysis.ini:

reference_property	Background estimate
sum_col_val (default)	none
bgsub_sum_col_val	median of the pixels > 0 in a 2 px border ring of the search area, subtracted pixel-wise
bgsub2_sum_col_val	mean over the channel pixels (including 0) of the same border ring, subtracted as N·b
sidebg_sum_col_val	mean over the channel pixels in side bands 25–60 px next to the LED strip (sideband_distances in config.ini), subtracted as N·B

For small search areas the border ring lies in the halo of the LED itself; the side bands sample the additive pedestal (stray light, smoke glow, clipped noise) next to the LED. Under dense smoke the box sum consists mostly of this pedestal. The following command marks such rays per image and LED, without changing the extinction coefficients:

python -m ledsa -rv

It writes analysis/ray_validity_channel<c>.csv (thresholds validity_threshold, validity_min_optical_depth, sideband_uncertainty in config_analysis.ini).

The reference intensities I0 are the mean over the first num_ref_images images, or over the images given in ref_img_indices. With auto_ref_images = True the reference images are selected automatically:

• Images whose brightness deviates by more than ref_img_tolerance are excluded.
• Partly occluded images are excluded (ref_img_led_deviation, ref_img_led_fraction).
• Images later than ref_img_max_time are excluded. Set it to 0 if Experiment_Time counts from the ignition.
• The analysis stops with an error if fewer than num_ref_img_min valid images remain.
• In config_stacked.ini, ref_img_common = True selects one list of images that is valid for all cameras.

All options default to the previous behaviour.

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:

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:

python -m ledsa --demo --run

By default, the demo uses 1 core. You can specify more cores:

python -m ledsa --demo --run --n_cores 4

Documentation

Comprehensive documentation is available at 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)