Stray Light (Flare) Documentation

Stray Light (Flare) Settings

Current Documentation
View previous documentation
View legacy documentation
All documentation versions


Stray light (flare) documentation pages

Introduction: Intro to stray light testing and normalized stray lightOutputs from Imatest stray light analysis | History

Background: Examples of stray lightRoot Causes | Test overview | Test factors | Test ConsiderationsGlossary

Calculations: Metric image calculationsNormalization methodsLight source mask methods | Summary Metrics | Analysis Channels

Instructions: High-level Imatest analysis instructions (Master and IT) | Computing normalized stray light with Imatest | Motorized Gimbal instructions

Settings: Settings list and INI keys/values | Standards and Recommendations | Configuration file input


 

This page provides a list and description of the settings for Imatest stray light source analysis, as well as corresponding INI field-value pairs.

Page Contents

Calculation Settings

Setting

Description

Options / Value type

[straylight] INI field

Calculation

The type of stray light calculation.

The default is Transmission.

Calculation Type Enumeration

calculation

Data Transform

The transform to apply to the metric image(s).

The default is linear (no data transform).

Data Transform Enumeration

data_transform

Dark Level

The dark level in digital numbers. 

The default is 0. If not known, assume 0.

Number (Greater than or equal to 0)

dark_level_dn

Clip To One

Enable to clip the image data to one (instead of zero).

The default is false (clip to zero). 

Note: this control only shows up in the GUI if the Calculation is Attenuation or one of the Logarithmic Data Transforms are used.

Boolean

clip_to_one

Analysis Channel Selection Options

Setting

Description

Options / Value type

[straylight] INI field

Analysis Channel(s)

The channel(s) to analyze.

The default is automatic.

Note: based on the option selected, additional inputs may be required.

Channel Groups Enumeration

channels

Luminance Channels

The standard to use for computing a luminance channel.

This option is used only if the Analysis channels are Luminance or RGB + Luminance.

The default is IEC 61966-2-1.

Luminance Channel Enumeration

luminance_calc

Normalization Options

Setting

Description

Options / Value type

[straylight] INI field

Normalization Method

The type of normalization to perform.

The default is None.

Note: based on the option selected, additional inputs may be required.

Normalization Method Enumeration

normalization

Level Normalization Options

The following options apply if the normalization method is Level. See the normalization page for a description of the Level normalization method

Setting

Description

Options / Value type

[straylight] INI field

Normalization Level

The normalization level in units of digital number (DNs).

The default is 1 (same as None normalization).

Number (greater than 0)

norm_level_value

Direct Reference Image Normalization Options

The following options apply if the normalization method is Direct Reference Image. See the normalization page for a description of the Direct Reference Image normalization method

Setting

Description

Options / Value type

[straylight] INI field

Image Filename

The fully-qualified path to the reference image.

Path to a valid image file

norm_refim_filename

Normalization Aggregation 

The methodology for aggregating the masked pixels into a normalization factor.

The default is Median.

Normalization Aggregation Enumeration

norm_refim_aggregation

ND Measurement Type

The type of neutral density (ND) measurement used for the reference image capture.

The default is None.

Neutral Density Measurement Enumeration

norm_refim_comp_nd_type

ND Density Value

The density of the neutral density filter(s) used for the reference image capture. Used if ND Measurement Type is set to ND Density.

The default is 0 (no ND filter used).

Number (greater than or equal to 0, less than or equal to 100)

norm_refim_comp_nd_density_value

ND Transmission Value

The transmission percentage [0-100] of the neutral density filter(s) used for the reference image capture. Used if ND Measurement Type is set to ND Transmission.

The default is 100 (no ND filter used).

Number (greater than 0, less than or equal to 100)

norm_refim_comp_nd_transmission_value

Integration Time Ratio

The ratio of the reference integration time to the analysis integration time (i.e., value for reference image divided by value for analysis image).

The default is 1 (test and reference images have the same integration time).

Number (greater than 0)

norm_refim_comp_int_time_ratio

Gain Ratio

The ratio of the reference gain to the analysis gain (i.e., value for reference image divided by value for analysis image).

The default is 1 (test and reference images have the same gain).

Number (greater than 0)

norm_refim_comp_gain_ratio

Light Level Ratio

The ratio of the reference light level to the analysis light level (i.e., value for reference image divided by value for analysis image).

The default is 1 (test and reference images have the same light level).

Number (greater than 0)

norm_refim_comp_light_level_ratio

 

Lambertian Reference Image Normalization Options

The following options apply if the normalization method is Lambertian Reference Image. See the normalization page for a description of the Lambertian Reference Image normalization method

Setting

Description

Options / Value type

[straylight] INI field

Image Filename

The fully-qualified path to the reference image.

Path to a valid image file

norm_lrefim_filename

Normalization Aggregation 

The methodology for aggregating the masked pixels into a normalization factor.

This setting can only be set in the INI.

The default is Median.

Normalization Aggregation Enumeration

norm_lrefim_aggregation

Light Measurement Type

The type of light measurements made.

The default is radiometric.

Note: The choice of this value impacts other measurement inputs.

Light Measurement Type Enumeration
norm_lrefim_source_meas_type
Radiance from Lambertian Diffuser

The measured radiance from the Lambertian diffuser for the reference image.

Note: this option is only used if the Light Measurement Type is Radiometric.

Number (greater than 0)
norm_lrefim_ref_radiance
Irradiance at the camera location

The measured irradiance at the camera location for the test image(s).

Note: this option is only used if the Light Measurement Type is Radiometric.

Number (greater than 0)
norm_lrefim_irradiance
Luminance from Lambertian Diffuser

The measured luminance from the Lambertian diffuser for the reference image.

Note: this option is only used if the Light Measurement Type is Photometric.

Number (greater than 0)
norm_lrefim_ref_luminance
Illuminance at the camera location

The measured illuminance at the camera location for the test image(s).

Note: this option is only used if the Light Measurement Type is Photometric.

Number (greater than 0)
norm_lrefim_illuminance

Integration Time Ratio

The ratio of the reference integration time to the analysis integration time (i.e., value for reference image divided by value for analysis image).

The default is 1 (test and reference images have the same integration time).

Number (greater than 0)

norm_lrefim_comp_int_time_ratio

Gain Ratio

The ratio of the reference gain to the analysis gain (i.e., value for reference image divided by value for analysis image).

The default is 1 (test and reference images have the same gain).

Number (greater than 0)

norm_lrefim_comp_gain_ratio

Test Image Mask Options

Setting

Description

Options / Value type

[straylight] INI field

Mask Method

The methodology for masking out the light source in the image(s).

The default is None.

Note: based on the option selected, additional inputs may be required.

Mask Method Enumeration

mask_method

Test Image – Image Processing + Circle (Radius) Mask Options

The following options apply if the masking method is Image Processing + Circle (Radius). Note the Image Processing mask option also applies.

Setting

Description

Options / Value type

[straylight] INI field

Mask Radius

The radius in pixels for the mask.

The default is 10 (this is an arbitrary number and should be updated for each system under test).

Number (greater than 0)

mask_options_radius

Test Image – Image Processing Mask Options

The following options apply if the masking method is Image Processing + Circle (Radius) or Image Processing.

Setting

Description

Options / Value type

[straylight] INI field

Level Threshold Type

The type of threshold used for localizing the light source in the image.

Level Threshold Type Enumeration

mask_improc_level_thresh_type

Level Threshold (Value)

The threshold above which is considered the image of the light source, in units of digital number (DN).

Number (greater than or equal to 0)

mask_improc_level_threshold

Level Threshold (Percent)

The threshold above which is considered the image of the light source, as a percentage of the maximum image value.

Number (between 0 and 100)

mask_improc_level_threshold_pct

Minimum Source Level

The minimum image value (digital number) that can be considered a direct image of the light source.

Number (greater than or equal to 0)

mask_improc_minimum_source_level

Image Close Radius

The radius of an image close morphology step. This helps to remove holes in the mask. Set to 0 to skip this step.

This setting can only be set in the INI. 

Number (greater than 0)

mask_improc_image_close_radius

Multiple CC Strategy

The strategy for how to deal with multiple connected components when computing the mask.

This setting can only be set in the INI. 

Multiple Connected Component Enumeration

mask_improc_multiple_cc_strategy

Mask Area Threshold

The minimum number of pixels that the direct image of the light source should be (minimum area in pixels for the mask).

Number (greater than 0)

mask_improc_mask_area_threshold

Reference Image Mask Options

Setting

Description

Options / Value type

[straylight] INI field

Mask Method

The methodology for masking out the light source in the reference image(s)

Mask Method Enumeration

refmask_method

Reference Image – Image Processing + Circle (Radius) Options

The following options apply if the masking method is Image Processing + Circle (Radius). Note the Image Processing mask option also applies.

Setting

Description

Options / Value type

[straylight] INI field

Mask Radius

The radius in pixels for the mask.

Number (greater than 0)

refmask_options_radius

Reference Image – Image Processing Mask Options

The following options apply if the masking method is Image Processing + Circle (Radius) or Image Processing.

Setting

Description

Options / Value type

[straylight] INI field

Level Threshold Type

The type of threshold used for localizing the light source in the image.

Level Threshold Type Enumeration

refmask_improc_level_thresh_type

Level Threshold (Value)

The threshold above which is considered the image of the light source, in units of digital number (DN).

Number (greater than or equal to 0)

refmask_improc_level_threshold

Level Threshold (Percent)

The threshold above which is considered the image of the light source, as a percentage of the maximum image value.

Number (between 0 and 100)

refmask_improc_level_threshold_pct

Minimum Source Level

The minimum image value (digital number) that can be considered a direct image of the light source.

This setting can only be set in the INI. 

Double (greater than or equal to 0)

refmask_improc_minimum_source_level

Image Close Radius

The radius of an image close morphology step. This helps to remove holes in the mask. Set to 0 to skip this step.

This setting can only be set in the INI. 

Number (greater than 0)

refmask_improc_image_close_radius

Multiple CC Strategy

The strategy for how to deal with multiple connected components when computing the mask.

This setting can only be set in the INI. 

Multiple Connected Component Enumeration

refmask_improc_multiple_cc_strategy

Mask Area Threshold

The minimum number of pixels that the direct image of the light source should be (minimum area in pixels for the mask).

This setting can only be set in the INI. 

Number (greater than 0)

refmask_improc_mask_area_threshold

Other Calculation Settings

Setting

Description

Options / Value type

[straylight] INI field

Crop LRTB

The number of pixels to crop off the left, right, top, and bottom of the image.

Number (list of four values greater than or equal to 0)

crop_lrtb

Percentile Ranks

The percentile ranks [0-100] (e.g., 95 = 95th percentile) to calculate.

Number (list of values greater than 0, less than 100)

pctl_ranks100

Level Count Thresholds

The thresholds of stray light level for producing results that show the number of pixels worse than said threshold.

Number (list of values)

level_count_thresh

Level Count Calculation

The calculation (number of pixels, % of pixels in the image) to use for the level count results and plots.

Level Count Calculation Enumeration

count_type

 

 

 

 

Output Settings

Setting

Description

Options / Value type

[straylight] INI field

Output Directory

The path to the save results to. Note: inclusion of the following characters may result in failure to save .fits output files (metric images and masks): “(*:<>?[|

The fully qualified path to a folder/directory or the name of a folder in which output files will be saved. Note: If just the name of a folder is entered, Imatest will create a new folder with that name in the same directory as the test images, and save the outputs to that folder.

output_dir

Result Files

Setting

Description

Options / Value type

[straylight] INI field

Save Summary Results Files

The results files to save.

Result File Format Enumeration

result_files

Save Metric Image Files

Enable to save out a FITS file containing the metric image data for each image.

Boolean

save_metric_image

Save Mask Files

Enable to save out a FITS file containing the binary mask of the source for each image.

Boolean

save_mask

Mask Prefix

A string to be prepended to the mask file(s).

This setting can only be set in the INI. 

String

mask_prefix

Mask Postfix

A string to be appended to the mask file(s).

This setting can only be set in the INI. 

String

mask_postfix

Metric Image Prefix

A string to be prepended to the metric image file(s).

This setting can only be set in the INI. 

String

metric_image_prefix

Metric Image Postfix

A string to be appended to the metric image file(s)

This setting can only be set in the INI. 

String

metric_image_postfix

Level Plot

Note: level plots require two or more test images.

Setting

Description

Options / Value type

[straylight] INI field

Save/Display

How should level summary plot(s) be created?

Choose one or more options.

At least one is required to produce this plot.

Plot Creation Options Enumeration

level_plot_options_mode_options

Image Format(s)

The image formats to save the plot as.

Choose one or more options.

At least one is required to produce this plot.

Plot Save Type Enumeration

level_plot_options_mode_save_types

Groups

How to group the data within a plot. 

Choose one or more options.

At least one is required to produce this plot.

Plot Group Enumeration

level_plot_options_groups

Y Data

The data to plot on level summary plot(s).

Choose one or more options.

At least one is required to produce this plot.

Level Plot Data Enumeration

level_plot_options_y_data

Include Percentiles

Enable to include percentiles on the level summary plot(s).

Boolean

level_plot_options_include_pctls

Y-Axis Scale

The scaling of the y-axis of the plot.

Axis Scaling Enumeration

level_plot_options_y_axis_scale

Count plot

Note: count plots require two or more test images.

Setting

Description

Options / Value type

[straylight] INI field

Save/Display

How should level summary plot(s) be created?

Choose one or more options.

At least one is required to produce this plot.

Plot Creation Options Enumeration

count_plot_options_mode_options

Image Format(s)

The image formats to save the plot as.

Choose one or more options.

At least one is required to produce this plot.

Plot Save Type Enumeration

count_plot_options_mode_save_types

Groups

How to group the data within a plot. 

Choose one or more options.

At least one is required to produce this plot.

Plot Group Enumeration

count_plot_options_groups

Y Data

The data to plot on count summary plot(s).

Choose one or more options.

At least one is required to produce this plot.

Count Plot Data Enumeration

count_plot_options_y_data

Include Level Counts

Enable to include level counts on the count summary plot(s), corresponding to the value(s) entered for the Level Count Threshold option.

Boolean

count_plot_options_include_level_counts

Y-Axis Scale

The scaling of the y-axis of the plot.

Axis Scaling Enumeration

count_plot_options_y_axis_scale

Summary Videos

Colormapped Metric Video

Setting

Description

Options / Value type

[straylight] INI field

Video Formats

The formats to save the metric image video as. Note: MP4 is not available on Linux.

Video Save Format Enumeration

metric_video_opts_video_formats

Image Formats:

The image formats to save each frame of the metric image video as.

Image Frame Format Enum

metric_video_opts_image_formats

Video Frame Rate

The framerate in frames per second for the metric video.

Number (greater than 0, less than 40)

metric_video_opts_frame_rate

Base Name

A string to prepend to the metric video file.

This setting can only be set in the INI. 

String

metric_video_opts_basename

Metric Image Histogram

Setting

Description

Options / Value type

[straylight] INI field

Video Formats

The formats to save the histogram image video as.

Note: MP4 is not available on Linux.

Video Save Format Enumeration

hist_video_opts_video_formats

Image Formats

The image formats to save each frame of the histogram video as.

Image Frame Format Enum

hist_video_opts_image_formats

Video Frame Rate

The framerate in frames per second for the histogram video.

Number (greater than 0, less than 40)

hist_video_opts_frame_rate

Base Name

A string to prepend to the histogram video file.

This setting can only be set in the INI. 

String

hist_video_opts_basename

Miscellaneous

Setting

Description

Options / Value type

[straylight] INI field

Frame-to-frame Scaling

How to scale the frames of the video relative to each other.

Video Frame Scaling Enumeration

frame_scaling

Video Output Scale

How to scale the data before making the video(s).

Data Scaling Enumeration 

video_output_scale

Colormapped Image Transform

How to scale the data before making the summary metric plot(s).

Note this only applies if the Data Transform is linear.

Video Frame Scaling Enumeration

plot_output_scale

Video Prefix

A prefix added to the video filename(s).

String

video_prefix

Video Postfix

A postfix added to the video filename(s).

String

video_postfix

Enumerations

Single Choice Enumerations

For the following enumerations, choose one of the provided options.

Axis Scaling Enumeration

Description

How to scale the axis of a plot.

Members

Name Description Value
Linear

The axis uses a linear scale.

0
Log

The axis uses a log scale.

1

Calculation Type Enumeration

Description

The type of stray light calculation to perform.

Members

Name Description Value
Transmission

The calculation is the image divided by the normalization factor.

0
Attenuation

The calculation is the normalization factor divided by the image.

Note: 0 is a valid digital number for image data. If choosing attenuation, any image with 0’s in it will get infinity for the calculated stray light. Summary statistics (e.g., mean, max) of data containing infinity become meaningless. Therefore it is recommended to enable Crop To One if this option is chosen.

1

Channel Groups Enumeration

Description

The channels to analyze. 

Members

Name Description Value
Automatic

Automatically choose which channels to analyze based on the image data.

0
Each Channel

Analyze each channel.

1
RGB

Analyze a three-channel image as Red, Green, and Blue.

2
Monochrome

Analyze a one-channel image as monochrome.

3
Mean

Analyze the mean of all provided channels.

4
Luminance

Analyze the luminance channel computed from a three-channel image.

5
RGB + Luminance

Analyze the Red, Green, and Blue plus the computed luminance channels.

6

Data Transform Enumeration

Description

How to transform data.

Members

Name Description Value
Linear

Apply no transform to the data \(y=x\).

0
Log 10

Apply a base-10 logarithm to the data \(y=log_{10}(x)\).

1
dB Power

Convert the data to power decibels \(y=10\cdot log_{10}(x)\).

2
dB Voltage

Convert the data to voltage decibels \(y=20\cdot log_{10}(x)\).

3
Log 2

Apply a base-2 logarithm to the data \(y=log_{2}(x)\).

4
Natural Log

Apply a natural logarithm to the data \(y=ln(x)\).

5

Notes

Note: 0 is a valid digital number for image data. The log (any base) of zero is undefined, although computed to negative infinity. Summary statistics (e.g., mean, max) of data containing infinity become meaningless. Therefore it is recommended to enable Crop To One if any of the logarithmic data transform options is chosen.

Image Processing Masking Level Type Enumeration

Description

The type of threshold used for localizing the light source in the image.

Members

Name Description Value
Value

The threshold in digital numbers.

0
Percentage of Max

The threshold is a percentage of the maximum value [0-100].

1
Otsu’s Method

Use Otsu’s method to automatically determine a threshold. 

2

Image Processing Masking Mulitple Connected Component Enumeration

Description

The strategy for how to deal with multiple connected components when computing the mask.

Members

Name Description Value
Don’t Mask

If multiple CCs are found, assume the source is not in the image.

1
Pick Biggest

Pick the largest of the connected components.

2

Level Count Calculation Enumeration

Description

The calculation to make for count-based summary metrics.

Members

Name Description Value
Number of Pixels

The results will use the number of pixels in the image that match the criteria

1
Percent of Pixels

The results will use the percent of pixels in the image that match the criteria.

2

Light Measurement Type Enumeration

Description

The type (radiometric/photometric) of light level measurement that was made.

Members

Name Description Value
Radiometric

Radiometric light level measurements are made (e.g., radiance, irradiance).

0
Photometric

Photometric light level measurements are made (e.g., luminance, illuminance).

1

Luminance Channel Enumeration

Description

The standard to use for computing a luminance channel. 

Members

Name Description Value
IEC 61966-2-1

Use IEC 61966-2-1 to compute a luminance channel.

1
ITU-R BT.601-7

Use ITU-R BT.601-7 to compute a luminance channel. 

2

Mask Method Enumeration

Description

The methodology for masking out the light source in the image(s).

Members

Name Description Value
None

Don’t mask the source.

Note: this is not available for masking reference images.

0
Image Processing

Use image processing to mask the source.

10
Image Processing + Circle (Radius) Find the center via the first step of Image Processing masking and then use a circle to mask. The light source is first localized in the image via image processing-based methods. Then, a circle of a specified radius is placed at the center of the localized region and is used as the mask for the image 13

Normalization Aggregation Enumeration

Description

The methodology for aggregating the masked pixels into a normalization factor.

Members

Name Description Value
Mean

Use the mean inside the masked pixels as the base normalization factor.

0
Median

Use the median inside the masked pixels as the base normalization factor.

1
Total

Use the total (sum) inside the masked pixels as the base normalization factor.

2

Normalization Method Enumeration

Description

The type of normalization to perform.

Members

Name Description Value
None

Perform no normalization. Results will be in digital numbers.

0
Level Normalize with a user-provided source level in units of digital number (DN). Using this option requires the Level normalization settings. 1
Direct Reference Image Normalize by the level of the direct image of the source from a reference image. This normalization method corresponds to the Point Source Rejection Ratio (PSRR) or Extended Source Rejection Ratio (ESRR). Using this option requires the Direct Reference Image normalization settings. 3
Lambertian Reference Image Normalize by the level of an image of the source as viewed through a Lambertian diffuser. This normalization method corresponds to the Flare Attenuation method in IEEE-P2020 Pre-Release. Using this option requires the Lambertian Reference Image Normalization settings. 4

Neutral Density Measurement Enumeration

Description

The type of neutral density measurement used for the reference image capture.

Members

Name Description Value
None

No ND filter is used for the reference image.

0
Density

ND filter(s) are used. The value is the total density of filters.

1
Transmission ND filter(s) are used. The value is the total transmission as a percentage [0-100] of the filters. 2

Video Frame Scaling Enumeration

Description

How to scale the frames of a video relative to each other.

Members

Name Description Value
Global

All frames have the same scaling.

0
Per-Subset

All frames of the same subset (channel) have the same scaling.

1
Per-Image

Each frame of the video will have its own scale.

2

Multiple Choice Enumerations

For the following enumerations, choose any of the provided options. The value in the INI is the sum of desired options.

Results File Type Enumeration

Description

The type(s) of summary results file to save.

Members

Name Description Value
JSON

Save a JSON-formated results file.

1
CSV

Save a CSV-formatted results file.

2
HDF5

Save an HDF5-formatted results file.

4

Plot Creation Enumeration

Description

Select how to create (display, save) plot(s).

Members

Name Description Value
Save

Save plot(s) to disk.

1
Display

Display plot(s) to screen.

2

Plot Save Type Enumeration

Description

The image formats to save the plot as.

Members

Name Description Value

JPEG 24-bit (.jpg)

  1

PNG 24-bit (.png)

  2

TIFF 24-bit [compressed] (.tif)

 

4

TIFF 24-bit [not compressed] (.tif)

 

8

BMP 8-bit [256 color, uses a fixed colormap] (.bmp)

This will be deprecated in a future release.

16

HDF 24-bit (.hdf)

This will be deprecated in a future release.

32

PBM 1-bit (.pbm)

This will be deprecated in a future release.

64

PCX 24-bit color [three 8-bit planes] (.pcx)

This will be deprecated in a future release.

128

PGM (.pgm)

This will be deprecated in a future release.

256

PPM (.ppm)

This will be deprecated in a future release.

512

Full page Portable Document Format [PDF] color (.pdf)

 

1024

Encapsulated PostScript [EPS] Level 2 color (.eps)

 

2048

SVG [scalable vector graphics] (.svg)

 

4096

Full-page PostScript [PS] Level 2 color (.ps)

 

8192
MATLAB Figure (.fig)

 

16384

Deprecation Warning

Some options will be deprecated in a future Imatest release.

Plot Grouping Enumeration

Description

How to group the data within a plot. At least one is required to produce this plot.

Members

Name Description Value

All

All channels will be in the same plot. 1
By Channel A separate plot will be made for each channel. 2

Level Plot Data Enumeration

Description

The data to plot on level summary plot(s).

Members

Name Description Value

Minimum

  1

Minimum (Non-0)

Minimum of the non-0 data in the original image. 2

Maximum

 

4

Mean

 

8

Median

 

16

RMS

Root Mean Square

32

Std. Dev.

Standard Deviation

64

Count Plot Data Enumeration

Description

The data to plot on count summary plot(s).

Members

Name Description Value

Total Count

The number/count of pixels in the region of interest (note: currently, only the total number of pixels in the image is available). 1

Source Count

The number/count of pixels in the masked region (the light source object). 2

Video Save Type Enumeration

Description

The formats to save a video as.

Members

Name Description Value

MP4

Note: Not available on Linux 1

AVI

 

2

GIF

 

4

Image Frame Save Formats

Description

The image formats to save each frame of a video as.

Members

Name Description Value

PNG

  1

JPEG

  2

TIFF

  4