Module: CorrectIlluminationCalculate

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

Enter a name for the resultant illumination function.

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

• Regular: If you have objects that are evenly dispersed across your image(s) and cover most of the image, the Regular method might be appropriate. Regular intensities makes the illumination function based on the intensity at each pixel of the image (or group of images if you are in All mode) and is most often rescaled (see below) and applied by division using CorrectIlluminationApply. Note that if you are in Each mode or using a small set of images with few objects, there will be regions in the average image that contain no objects and smoothing by median filtering is unlikely to work well. Note: it does not make sense to choose (Regular + No smoothing + Each) because the illumination function would be identical to the original image and applying it will yield a blank image. You either need to smooth each image, or you need to use All images.
• Background: If you think that the background (dim points) between objects show the same pattern of illumination as your objects of interest, you can choose the Background method. Background intensities finds the minimum pixel intensities in blocks across the image (or group of images if you are in All mode) and is most often applied by subtraction using the CorrectIlluminationApply module. Note: if you will be using the Subtract option in the CorrectIlluminationApply module, you almost certainly do not want to rescale the illumination function.

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.

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

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

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

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

• Yes: Rescaling is recommended if you plan to use the Regular method (and hence, the Divide option in CorrectIlluminationApply) so that the corrected images are in the range 0 to 1.
• No: Rescaling is not recommended if you plan to use the Background method, which is paired with the Subtract option in CorrectIlluminationApply. Note that as a result of the illumination function being rescaled from 1 to infinity, the rescaling of each image might be dramatic if there is substantial variation across the field of view, causing the corrected images to be very dark.
• Median: This option chooses the median value in the image to rescale so that division increases some values and decreases others.

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:

• Each: Calculate an illumination function for each image individually.
• All: First cycle: Calculate an illumination function based on all of the images in a group, performing the calculation before proceeding to the next module. This means that the illumination function will be created in the first cycle (making the first cycle longer than subsequent cycles), and lets you use the function in a subsequent CorrectIllumination_Apply module in the same pipeline, but also means that you will not have the ability to filter out images (e.g., by using FlagImage). The input images need to be assembled using the Input modules; using images produced by other modules will yield an error.
• All: Across cycles: Calculate an illumination function across all cycles in each group. This option takes any image as input; however, the illumination function will not be completed until the end of the last cycle in the group. You can use SaveImages to save the illumination function after the last cycle in the group and then use the resulting image in another pipeline. The option is useful if you want to exclude images that are filtered by a prior FlagImage module.

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.

• Fit Polynomial: This methdod is fastest but does not allow a very tight fit compared to the slower median and Gaussian filtering methods.
• Median Filter, Gaussian Filter: Use a median or Gaussian filter, respectively. We typically recommend Median Filter vs. Gaussian Filter because the median is less sensitive to outliers, although the results are also slightly less smooth and the fact that images are in the range of 0 to 1 means that outliers typically will not dominate too strongly anyway.
• Smooth to Average: A less commonly used option is to completely smooth the entire image, which will create a flat, smooth image where every pixel of the image is the average of what the illumination function would otherwise have been.
• Splines: This method (Lindblad and Bengtsson, 2001) fits a grid of cubic splines to the background while excluding foreground pixels from the calculation. It operates iteratively, classifying pixels as background, computing a best fit spline to this background and then reclassifying pixels as background until the spline converges on its final value.
• Convex Hull: This method algorithm proceeds as follows:
  • Choose 256 evenly-spaced intensity levels between the minimum and maximum intensity for the image
  • Set the intensity of the output image to the minimum intensity of the input image
  • Iterate over the intensity levels, from lowest to highest
    • For a given intensity, find all pixels with equal or higher intensities
    • Find the convex hull that encloses those pixels
    • Set the intensity of the output image within the convex hull to the current intensity
  The Convex Hull method can be used on an image whose objects are darker than their background and whose illumination intensity decreases monotonically from the brightest point.

References

• J Lindblad and E Bengtsson (2001) "A comparison of methods for estimation of intensity nonuniformities in 2D and 3D microscope images of fluorescence stained cells.", Proceedings of the 12th Scandinavian Conference on Image Analysis (SCIA), pp. 264-271

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

• Automatic: The size is computed as 1/40 the size of the image or 30 pixels, whichever is smaller.
• Object size: The size is obtained relative to the width of artifacts to be smoothed.
• Manually: Use a manually entered value.

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

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

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

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

• auto: Determine the mode from the image. This will set the mode to dark if most of the pixels are dark, bright if most of the pixels are bright and gray if there are relatively few dark and light pixels relative to the number of mid-level pixels
• dark: Fit the spline to the darkest pixels in the image, excluding brighter pixels from consideration. This may be appropriate for a fluorescent image.
• bright: Fit the spline to the lightest pixels in the image, excluding the darker pixels. This may be appropriate for a histologically stained image.
• gray: Fit the spline to mid-range pixels, excluding both dark and light pixels. This may be appropriate for a brightfield image where the objects of interest have light and dark features.

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

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

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

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

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

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.

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

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.

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