Configuration

ConfigData

class ledsa.core.ConfigData.ConfigData(load_config_file=True, img_directory=None, search_area_radius=10, pixel_value_percentile=99.875, channel=0, max_num_leds=None, num_arrays=None, num_cores=1, date=None, start_time=None, time_ref_img_id=None, time_ref_img_file=None, time_ref_img_time=None, time_diff_to_image_time=None, img_name_string=None, num_img_overflow=None, img_rotation='auto', first_img_experiment_id=None, last_img_experiment_id=None, ref_img_id=None, ignore_led_indices=None, led_array_edge_indices=None, led_array_edge_coordinates=None, first_img_analysis_id=None, last_img_analysis_id=None, num_skip_imgs=0, ref_img_experiment_ids=None, num_skip_leds=0, merge_led_array_indices=None, farfield_distances=None)

Bases: ConfigParser

Class responsible for handling configuration data related to LEDSA.

get(section, option, *, raw=False, vars=None, fallback='None') → str

Retrieve a config value, returning ‘None’ by default if the key is missing.

Parameters:

• section – Section name in the configuration.

• option – Option name within the section.

• raw – If True, interpolation is not performed.

• vars – Additional variables for interpolation.

• fallback – Value to return if the key is missing. Defaults to ‘None’.

Returns:

The configuration value as a string.

Return type:

str

get2dnparray(section, option, num_col=2, dtype=<class 'int'>) → ndarray

Extracts a 2D NumPy array from multi-line/ multi-column inputs the configuration.

Parameters:

• section (str) – Section name in the configuration.

• option (str) – Option name within the section.

• num_col (int or 'var') – Number of columns expected in the array. Defaults to 2.

• dtype (type) – Data type of the elements in the output array. Defaults to int.

Returns:

2D array from the configuration.

Return type:

numpy.ndarray or None

get_datetime(option='start_time') → None

Retrieves a datetime object from the configuration based on a provided option.

Parameters:

option (str) – The option name for which the datetime is required. Defaults to ‘start_time’.

Returns:

Datetime object corresponding to the option.

Return type:

datetime.datetime

get_ref_img_experiment_ids() → List[int] | None

Experiment IDs of the images the LED intensities are normalized with.

The IDs are the ones the image names are built from, as first_img_experiment_id and ref_img_id are, and not the analysis IDs that config_analysis.ini names. A configuration written before the option existed holds none, which is read as None.

Returns:

The configured experiment IDs, or None if none are named.

Return type:

Optional[List[int]]

Raises:

ValueError – If the option holds something other than whitespace separated integers.

get_start_time() → None

Retrieve and set the start time from the first experiment image.

Extracts the EXIF DateTimeOriginal from the image and then computes the start time. Updates the ‘DEFAULT’ key with the ‘start_time’ computed.

in_first_img_analysis_id() → None

Prompts the user for the ID of the first image for analysis and updates the configuration.

in_first_img_experiment_id() → None

Prompts the user for the ID of the first image of the experiment and updates the configuration.

in_img_dir() → None

Prompts the user for the image directory path and updates the configuration.

in_img_name_string() → None

Prompts the user for the image naming convention and updates the configuration.

in_last_img_analysis_id() → None

Prompts the user for the ID of the last image for analysis and updates the configuration.

in_last_img_experiment_id() → None

Prompts the user for the ID of the last image of the experiment and updates the configuration.

in_led_array_edge_coordinates() → None

Prompt the user to input the physical coordinates of the topmost and bottommost LED of each array.

Note

The coordinates should correspond to the order of the led_array edge indices. Coordinates are given in form X Y Z X Y Z and are separated by whitespace.

Raises:

ValueError – If any of the inputs are not formatted correctly.

in_led_array_edge_indices() → None

Prompt the user to input the labels of the topmost and bottommost LED of each array.

Note

The edges of the LED arrays are required. Labels for each array are separated by whitespace.

in_max_num_leds() → None

Prompts the user for the maximum number of LEDs to be detected on the reference image.

in_num_arrays() → None

Prompts the user for the number of LED arrays and updates the configuration.

in_num_img_overflow() → None

Prompts the user for the maximal image file ID and updates the configuration.

in_ref_img_id() → None

Prompts the user for the ID of the reference image and updates the configuration.

in_time_diff_to_img_time() → None

Update the configuration with the time difference between the reference image’s timestamp and the real time. If the ‘time_ref_img_time’ is not set, prompts the user to provide the time shown on the clock in the time reference image.

in_time_ref_img_file() → None

Prompts the user for the file path of the time reference image and updates the configuration.

in_time_ref_img_id() → None

Prompts the user for the time reference image name and updates the configuration.

load() → None

Loads the configuration data from ‘config.ini’ file.

Raises:

FileNotFoundError – If ‘config.ini’ is not found in the working directory.

save() → None

Saves the current configuration to ‘config.ini’ file.

The comments of the file, which hold the help texts of the options, are kept.

ConfigDataAnalysis

class ledsa.analysis.ConfigDataAnalysis.ConfigDataAnalysis(load_config_file=True, camera_position=None, num_layers=20, domain_bounds=None, led_array_indices=None, num_ref_images=10, ref_img_indices=None, camera_channels=0, num_cores=1, reference_property='sum_col_val', average_images=False, n_summarize=2, solver='linear', weighting_preference=-0.006, weighting_curvature=0.01, num_iterations=1000, lambda_reg=0.001, reduction_files=None, pane_distance=None)

Bases: ConfigParser

Class responsible for handling the configuration data related to LEDSA’s data analysis.

get_list_of_values(section: str, option: str, dtype=<class 'int'>, fallback=None)

Return a list[dtype] for ‘section’/’option’. - Missing section/option → warn and return fallback - Value ‘None’ or empty → return None - Values are split on whitespace

get_pane_distance() → float | None

Return the distance between the camera and the window pane it looks through into the smoke.

Returns:

The distance [m], None if the smoke reaches the camera, which is also the case for a config file written before the option.

Return type:

Optional[float]

Raises:

ValueError – If pane_distance is not a finite number of at least 0.

get_reduction_file(channel: int) → str | None

Path of the reduction factor file of the temperature correction of a camera channel.

A config file written before the temperature correction existed has no [temperature_correction] section at all, which asks for no correction just like the option left at None, so that an older analysis is reproduced unchanged.

Parameters:

channel (int) – The camera channel.

Returns:

The configured path, None if the channel is analysed without the correction.

Return type:

str or None

get_reference_properties() → List[str]

Return the quantities the extinction coefficients are to be computed from.

Returns:

Quantities in the order the config file names them.

Return type:

List[str]

Raises:

ValueError – If the reference_property option names no quantity.

in_camera_channels() → None

Prompts the user to input the camera channels to analyse and updates the configuration.

in_camera_position() → None

Prompts the user to input the camera’s global X, Y, Z coordinates and updates the configuration.

in_domain_bounds() → None

Prompts the user to input the lower and upper height of the spatial domain and updates the configuration.

in_led_array_indices() → None

Prompts the user to input the indices of (merged) LED Arrays for computation and updates the configuration.

in_num_layers() → None

Prompts the user to input the number of layers for spatial domain discretization and updates the configuration.

load() → None

Loads the configuration data from ‘config_analysis.ini’ file.

Raises:

FileNotFoundError – If ‘config_analysis.ini’ is not found in the working directory.

save() → None

Saves the current configuration to ‘config_analysis.ini’ file.

The comments of the file, which hold the help texts of the options, are kept.

ledsa.analysis.ConfigDataAnalysis.format_reference_properties(reference_property: str | Iterable[str]) → str

Render one quantity or a list of quantities the way the config file holds them.

Parameters:

reference_property (Union[str, Iterable[str]]) – Quantity or quantities to be analysed.

Returns:

Value of the reference_property option.

Return type:

str

ledsa.analysis.ConfigDataAnalysis.parse_reference_properties(value: str) → List[str]

Split the value of the reference_property option into the quantities to be analysed.

Step 3 writes several intensity quantities per LED, and one analysis run computes the extinction coefficients of every quantity it is given, so the option holds one or more quantity names separated by whitespace. A repeated name is dropped, because its results would be written into the same file twice.

Parameters:

value (str) – Value of the reference_property option.

Returns:

Quantities in the order the option names them.

Return type:

List[str]

Raises:

ValueError – If the option names no quantity.

ConfigDataStacked

class ledsa.analysis.ConfigDataStacked.ConfigDataStacked(filename: str | None = None, load_config_file: bool = True)

Bases: ConfigParser

Configuration for stacked (multi-camera) extinction coefficient computation.

Reads config_stacked.ini, which defines:

• Global solver settings and domain parameters ([DEFAULT])

• One [simulation_N] section per camera/LEDSA run

• A [led_arrays] section that maps virtual LED-array labels to per-simulation LED-array IDs

Example file layout:

[DEFAULT]
solver            = linear
lambda_reg        = 1e-3
camera_channels   = 0 1 2
num_layers        = 20
domain_bounds     = 0.0 3.0
reference_property = sum_col_val mean_col_val
num_ref_images    = 10
ref_img_indices   = None
average_images    = False
n_summarize       = 2
num_cores         = 1
output_path       = .
time_sync_tolerance = 0.5

[simulation_0]
path             = /data/exp01/cam0
camera_position  = 1.0 0.0 1.5
# distance to the window pane this camera looks through into the smoke, optional
pane_distance    = 0.5

[simulation_1]
path             = /data/exp01/cam1
camera_position  = -1.0 0.0 1.5
# num_ref_images and ref_img_indices may be set per camera and override [DEFAULT]
ref_img_indices  = 385 386 387

[led_arrays]
# integer_id = sim_index:led_array_id  [sim_index:led_array_id ...]
# sim_index refers to [simulation_N]; led_array_id is the integer ID from that run.
# List all sim:id pairs that observe the same physical array to stack their rays.
0 = 0:2 1:3
1 = 0:4 1:5

DEFAULT_FILENAME = 'config_stacked.ini'

property average_images: bool

Whether to average the intensities over n_summarize consecutive images.

property camera_channels: List[int]

List of colour channels (0 = R, 1 = G, 2 = B) to process.

classmethod create_template(filename: str = 'config_stacked.ini', num_simulations: int = 2) → None

Write an annotated template config_stacked.ini to disk.

Parameters:

• filename – Destination file path.

• num_simulations – Number of simulation blocks to include.

property domain_bounds: List[float]

[z_min, z_max] of the computational domain in metres.

get_camera_position(sim_idx: int) → List[float]

Camera position [x, y, z] for simulation sim_idx.

get_led_array_ids() → List[int]

Return the virtual LED-array IDs defined in [led_arrays] as integers.

ConfigParser.options() merges DEFAULT keys into every section, so we explicitly subtract the DEFAULT keys to get only the keys that are actually written inside the [led_arrays] block.

get_led_array_mapping(led_array_id: int) → Dict[int, int]

For a virtual array led_array_id return {sim_idx: led_array_id}.

Config value format: "0:2 1:3"

get_list_of_values(section: str, option: str, dtype=<class 'int'>, fallback=None)

Return a typed list for section/option, or fallback.

The value None (case-insensitive) or an empty string yields None rather than a list.

get_num_ref_images(sim_idx: int) → int

Number of reference images of simulation sim_idx, inherited from [DEFAULT].

get_num_simulations() → int

Number of simulation sections defined in the config.

get_pane_distance(sim_idx: int) → float | None

Distance [m] between camera sim_idx and the window pane it looks through into the smoke, None if the smoke reaches the camera.

Raises:

ValueError – if pane_distance is not a finite number of at least 0.

get_reduction_file(channel: int) → str | None

Path of the reduction factor file of the temperature correction of channel.

The factors apply to the LEDs themselves, so all cameras of a stacked inversion share the file of a channel. A config file written before the temperature correction existed has no [temperature_correction] section, which asks for no correction just like the option left at None.

Parameters:

channel – The camera channel.

Returns:

The configured path, None if the channel is analysed without the correction.

get_ref_img_indices(sim_idx: int) → List[int] | None

Reference image IDs of simulation sim_idx; None means use get_num_ref_images().

Image IDs are counted per camera and the cameras run at their own cadence, so the images taken before the fire differ from camera to camera. A value in [simulation_N] therefore overrides the one in [DEFAULT] for that camera, a missing value is inherited from [DEFAULT], and None in a section switches that camera back to get_num_ref_images() even if [DEFAULT] holds a list.

get_simulation_path(sim_idx: int) → Path

Filesystem path for simulation sim_idx.

get_simulation_sections() → List[str]

Return all section names that start with simulation_.

property lambda_reg: float

Tikhonov regularisation parameter (linear solver).

load() → None

Load the INI file from disk.

Raises:

SystemExit – if the file is not found.

property n_summarize: int

Number of consecutive images summarized into one when average_images is set.

The reference images are kept as they are, so the first num_ref_images images of every camera are not summarized.

property num_cores: int

Number of CPU cores for parallel processing.

property num_iterations: int

Maximum iterations for the nonlinear solver.

property num_layers: int

Number of horizontal smoke layers.

property num_ref_images: int

Number of reference images used to compute I₀, as set in [DEFAULT].

Use get_num_ref_images() to get the value of a single camera.

property output_path: Path

Root path for all stacked-analysis output files.

property ref_img_indices: List[int] | None

Explicit reference image indices of [DEFAULT]; None → use num_ref_images.

Use get_ref_img_indices() to get the indices of a single camera.

property reference_properties: List[str]

Column names used as the LED intensity measure, one stacked analysis each.

property reference_property: str

First of reference_properties, the quantity of a single analysis.

save() → None

Write the current configuration back to disk, keeping the comments of the file.

property solver: str

'linear' or 'nonlinear'.

Type:

Inversion method

property time_sync_tolerance: float

Maximum allowed difference [s] when matching images across simulations.

property weighting_curvature: float

Curvature weighting for the nonlinear solver.

property weighting_preference: float

Preference weighting for the nonlinear solver.

config_file

Writing of config files that keeps the help texts they carry.

configparser.ConfigParser reads the comments of a file but does not keep them, so writing a loaded parser back over its own file strips every help text and every blank line the config had. LEDSA saves the config whenever it fills in a value it asked for or read from an image, which left the user with a config that no longer explains any of its options.

save_config() writes the file in place instead: the lines of the old file are kept and only the values of the options are replaced with the ones the parser holds now. Options and sections the parser has gained in the meantime are appended, options it no longer holds are dropped.

report_removed_options() names the options of a loaded file that a release of LEDSA has removed, which a config written by an older version still sets.

ledsa.core.config_file.report_removed_options(parser, file_name: str, removed_options: Dict[str, str]) → List[str]

Name the options of a loaded config file that LEDSA no longer has.

A config file keeps the options of the version it was written with, and the parser reads every option the file sets, whether or not LEDSA uses it. An option a release has removed would therefore stop taking effect without a word, and with it the result of an analysis would change unnoticed. Each such option is named once per process, with what became of it.

Parameters:

• parser (configparser.RawConfigParser) – The loaded configuration.

• file_name (str) – Name of the config file, used in the note.

• removed_options (Dict[str, str]) – What became of every removed option, by option name.

Returns:

The removed options the file still sets, in alphabetical order.

Return type:

List[str]

ledsa.core.config_file.save_config(parser, file_path: str) → None

Write parser to file_path, keeping the comments and the layout of an existing file.

A file that does not exist yet is written by configparser.RawConfigParser.write(), which gives it the help texts the config template stores as options without a value.

Parameters:

• parser (configparser.RawConfigParser) – The configuration to write.

• file_path (str) – Path of the config file.