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, 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, num_skip_leds=0, merge_led_array_indices=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_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.

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, solver='linear', weighting_preference=-0.006, weighting_curvature=1e-06, num_iterations=200, lambda_reg=0.001)

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

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.

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
num_ref_images    = 10
ref_img_indices   = None
average_images    = False
num_cores         = 1
output_path       = .
time_sync_tolerance = 0.5

[simulation_0]
path             = /data/exp01/cam0
camera_position  = 1.0 0.0 1.5

[simulation_1]
path             = /data/exp01/cam1
camera_position  = -1.0 0.0 1.5

[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 use averaged image pairs.

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_simulations() → int

Number of simulation sections defined in the config.

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 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₀.

property output_path: Path

Root path for all stacked-analysis output files.

property ref_img_indices: List[int] | None

Explicit reference image indices; None → use num_ref_images.

property reference_property: str

Column name used as the LED intensity measure.

save() → None

Write the current configuration back to disk.

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.