"Illumination correction" task requires additional instructions on how to generate illumination profiles

[adrtsc]

Hi, I've been using the illumination correction task a few times lately and after discussing with @jluethi I would like to summarize a few things here. The overall conclusions from using it is that probably there needs to be a bit more documentation on how the illumination profiles should be generated that the task takes as an input.

To keep it concise: the issue I ran into is that I generated flatfield images for correction using a third-party tool (BaSiCPy). When I used these flatfield images in the illumination correction task, the images still showed illumination artifacts. The cause for this turned out to be that I omitted to subtract a background value before calculating the flatfield image.

The easiest solution to keep people from running into issues here would be to add a bit more instructions on how to generate the flatfield images/illumination profiles in the documentation of the illumination correction task.

As a side note, I've created two new fractal tasks ("Calculate Illumination Profiles" and "Apply BaSiCPy Illumination Model" in apx_fractal_task_collection) to compute and apply a BaSiCPy illumination model for every channel. Using these models I perform illumination correction according to this formula:

corrected = (image - basic.darkfield) / basic.flatfield - basic.baseline

which for now seems to give me pretty reasonable results. Could be an interesting approach for users that do not have a pre-computed flatfield image.

[jluethi]

Thanks for reporting this Adrian!

We should indeed update the documentation for the illumination correction task. Just to summarize it here: It assumes that you use the same background subtraction on the images you use to calculate your profile (before the profile is calculated), as you then use during illumination correction. Alternatively, if your profiles are calculated on very bright images (e.g. intensities >10k), this background subtraction doesn't really matter anymore.

Also, to summarize one of our learnings: Apparently, BaSiCPy calculates the darkfield to be all 0s for Yokogawa images in the cases you checked, thus not subtracting anything before applying the illumination correction. My expectation is that this will work as long as your images are somewhat homogeneous in signal strength. If one image has an average intensity of 200 and others of 10'000, the assumptions made for such a fit may break.

[jluethi]

This is now included in the description of the illumination correction task. Closing for now.

Assumes that the illumination correction profiles were generated before separately and that the same background subtraction was used during calculation of the illumination correction (otherwise, it will not work well & the correction may only be partial).