Module: CorrectIlluminationCalculate

Correct Illumination - Calculate calculates an illumination function that is used to correct uneven illumination/lighting/shading or to reduce uneven background in images.
This module calculates an illumination function that can either be saved to the hard drive for later use or immediately applied to images later in the pipeline. This function will correct for the uneven illumination in images. If saving, select .mat format in SaveImages. Use the CorrectIlluminationApply module to apply the function to the image to be corrected.

Illumination correction is a challenge to do properly; please see the examples and tutorials pages on the CellProfiler website for further advice.

See also CorrectIlluminationApply, EnhanceOrSuppressFeatures.

Settings:

Select the input image

Choose the image to be used to calculate the illumination function.

Name the output image

Enter a name for the resultant illumination function.

Select how the illumination function is calculated

Choose which method you want to use to calculate the illumination function. You may chose from the following options:

Please note that if a mask was applied to the input image, the pixels outside of the mask will be excluded from consideration. This is useful, for instance, in cases where you have masked out the well edge in an image from a multi-well plate; the dark well edge would distort the illumination correction function along the interior well edge. Masking the image beforehand solves this problem.

Dilate objects in the final averaged image?

(Used only if the Regular method is selected)
For some applications, the incoming images are binary and each object should be dilated with a Gaussian filter in the final averaged (projection) image. This is for a sophisticated method of illumination correction where model objects are produced. Select Yes to dilate objects for this approach.

Dilation radius

(Used only if the "Regular" method and dilation is selected)
This value should be roughly equal to the original radius of the objects

Block size

(Used only if "Background" is selected)
The block size should be large enough that every square block of pixels is likely to contain some background pixels, where no objects are located.

Rescale the illumination function?

The illumination function can be rescaled so that the pixel intensities are all equal to or greater than 1. You have the following options:

Calculate function for each image individually, or based on all images?

Calculate a separate function for each image, or one for all the images? You can calculate the illumination function using just the current image or you can calculate the illumination function using all of the images in each group. The illumination function can be calculated in one of the three ways:

Smoothing method

If requested, the resulting image is smoothed. See the EnhanceOrSuppressFeatures module help for more details. If you are using Each mode, this is almost certainly necessary. If you have few objects in each image or a small image set, you may want to smooth.

You should smooth to the point where the illumination function resembles a believable pattern. For example, if you are trying to correct a lamp illumination problem, apply smoothing until you obtain a fairly smooth pattern without sharp bright or dim regions. Note that smoothing is a time-consuming process, but some methods are faster than others.

References

Method to calculate smoothing filter size

(Used only if a smoothing method other than Fit Polynomial is selected)
Calculate the smoothing filter size. There are three options:

Approximate object size

(Used only if Automatic is selected for smoothing filter size calculation)
Enter the approximate width of the artifacts to be smoothed, in pixels.

Smoothing filter size

(Used only if Manually is selected for smoothing filter size calculation)
Enter the size of the desired smoothing filter, in pixels.

Automatically calculate spline parameters?

(Used only if Splines are selected for the smoothing method)
Select Yes to automatically calculate the parameters for spline fitting.

Select No to specify the background mode, background threshold, scale, maximum number of iterations and convergence.

Background mode

(Used only if Splines are selected for the smoothing method and spline parameters are not calculated automatically)
This setting determines which pixels are background and which are foreground.

Number of spline points

(Used only if Splines are selected for the smoothing method and spline parameters are not calculated automatically)
This is the number of control points for the spline. A value of 5 results in a 5x5 grid of splines across the image and is the value suggested by the method's authors. A lower value will give you a more stable background while a higher one will fit variations in the background more closely and take more time to compute.

Background threshold

(Used only if Splines are selected for the smoothing method and spline parameters are not calculated automatically)
This setting determines the cutoff used when excluding foreground pixels from consideration. On each iteration, the method computes the standard deviation of background pixels from the computed background. The number entered in this setting is the number of standard deviations a pixel can be from the computed background on the last pass if it is to be considered as background during the next pass.

You should enter a higher number to converge stabily and slowly on a final background and a lower number to converge more rapidly, but with lower stability. The default for this parameter is two standard deviations; this will provide a fairly stable background estimate.

Image resampling factor

(Used only if Splines are selected for the smoothing method and spline parameters are not calculated automatically)
This setting controls how the image is resampled to make a smaller image. Resampling will speed up processing, but may degrade performance if the resampling factor is larger than the diameter of foreground objects. The image will be downsampled by the factor you enter. For instance, a 500x600 image will be downsampled into a 250x300 image if a factor of 2 is entered.

Maximum number of iterations

(Used only if Splines are selected for the smoothing method and spline parameters are not calculated automatically)
This setting determines the maximum number of iterations of the algorithm to be performed. The algorithm will perform fewer iterations if it converges.

Residual value for convergence

(Used only if Splines are selected for the smoothing method and spline parameters are not calculated automatically)
This setting determines the convergence criterion. The software sets the convergence criterion to the number entered here times the signal intensity; the convergence you enter is the fraction of the signal intensity that indicates convergence. The algorithm derives a standard deviation of the background pixels from the calculated background on each iteration. The algorithm terminates when the difference between the standard deviation for the current iteration and the previous iteration is less than the convergence criterion.

Enter a smaller number for the convergence to calculate a more accurate background. Enter a larger number to calculate the background using fewer iterations, but less accuracy.

Retain the averaged image?

The averaged image is the illumination function prior to dilation or smoothing. It is an image produced during the calculations, not typically needed for downstream modules. It can be helpful to retain it in case you wish to try several different smoothing methods without taking the time to recalculate the averaged image each time.

Select Yes to retain this averaged image. Use the SaveImages module to save it to your hard drive.

Name the averaged image

(Used only if the averaged image is to be retained for later use in the pipeline)
Enter a name that will allow the averaged image to be selected later in the pipeline.

Retain the dilated image?

The dilated image is the illumination function after dilation but prior to smoothing. It is an image produced during the calculations, and is not typically needed for downstream modules.

Select Yes to retain this dilated image. Use the SaveImages module to save it to your hard drive.

Name the dilated image

(Used only if the dilated image is to be retained for later use in the pipeline)
Enter a name that will allow the dilated image to be selected later in the pipeline.