Stray Light (Flare) Documentation

Stray Light (Flare) Settings

Current Documentation
View previous documentation
View legacy documentation
All documentation versions


Stray light (flare) documentation pages

IntroductionIntro 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

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

Normalization Options

Setting

Description

Options / Value type

[straylight] INI field

Normalization Method

The type of normalization to perform.

The default is None.

Normalization Method Enumeration

normalization

Level Normalization Options

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

Reference Image Normalization Options

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.

This setting can only be set in the INI.

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

 

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.

Mask Method Enumeration

mask_method

Test Image – Two-Pass Circle (Radius) Mask Options

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

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 –  Two-Pass Circle (Radius) Options

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

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

 

Batch 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 Options

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

Save Types

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 Options

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

Save Types

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

Metric Video

Setting

Description

Options / Value type

[straylight] INI field

Save 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

Save 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

Histogram Video

Setting

Description

Options / Value type

[straylight] INI field

Save 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

Save 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 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 video(s).

Data Scaling Enumeration 

video_output_scale

Plot Output Scale

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

Video Frame Scaling Enumeration

plot_output_scale

Histogram Output Scale

How to scale the data before taking a histogram.

Data Scaling Enumeration 

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

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 reciprocal, 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. As such Transmission is recommended.

1

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
Reference Image Normalize by the level of the direct image of the source from a reference image. This normalization method corresponds to Point Source Rejection Ratio (PSRR) or Extended Source Rejection Ratio (ESRR). Using this option requires the Reference Image normalization settings. 3

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

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

 

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
Two Pass Circle (Radius) Find the center via a “first pass” 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

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.

Default

Pick Biggest

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

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

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

Data Scaling Enumeration

Description

How to scale data.

Members

Name Description Value
Linear

The data are un-transformed.

0
Log10

Take the log10 of the data.

1
dB

Convert the data to decibels.

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)

 

16

HDF 24-bit (.hdf)

 

32

PBM 1-bit (.pbm)

 

64

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

 

128

PGM (.pgm)

 

256

PPM (.ppm)

 

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

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