Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
There are many ways to display an image. The original is not always best, and it can help to know QuPath's controls that provide alternatives that may allow the information in the image to be seen and interpreted more clearly.
There is a quick alternative to reading this section: just click the button on the toolbar, and start pressing things and moving sliders to figure out what they do.
However, if you would like more information about what is happening and how to use this tool more effectively, please read on.
Instant color transforms
Whenever an image is open, simply pressing a number can adjust the way that it is displayed in a manner that can often be very helpful.
For example, consider the following 3-channel fluorescence image:
In this case, pressing '1' turns off the blue channel, making the 'double-positive' cells (in red and green channels) easier to discern.
Pressing '2' then additionally turns off the green channel, leaving only the red.
Several more presses can adjust the appearance yet further; here, to show only the blue and green channels together.
The idea of transforming an image's appearance simply by pressing a number is not restricted to fluorescence images, but it can have a different effect depending upon what type of image is open and what numbers are pressed.
The following section will describe in more detail what is happening, and how to control it.
The Brightness/Contrast tool
The key to more informed adjustment of how an image is displayed - and also to understanding what happens when a number is typed - lies in the Brightness/Contrast tool (also under View → Brightness/Contrast).
Applying color transforms
Upon opening, the Brightness/Contrast tool shows a list of possible color transforms that can be applied to view the image, alongside a checkbox indicating whether the transform is 'Selected' (i.e. currently in use) or not. The contents of this list depend upon the type of image that is open, e.g. whether it is brightfield or fluorescence.
As an example, consider the brightfield image below. When first opened, Original at the top of the list is the only transform that is marked as Selected - this really just shows the image in the most 'conventional' way.
Clicking on the next checkbox down, beside Hematoxylin then turns on the hematoxylin transform. Technically, QuPath is applying color deconvolution to digitally separate the hematoxylin optical densities and display these.
For an excellent description of the principles, uses and limitations of color deconvolution, see Gabriel Landini's description here.
By default, the hematoxylin information is shown using colors related to what QuPath expects hematoxylin to typically look like. Checking Show grayscale results in the same information being depicted with shades of gray instead.
Next on the list for this image is DAB. Similar to with Hematoxylin, color deconvolution is applied in an effort to separate out the DAB information.
Color deconvolution (typically) separates an image into three channels, of which Hematoxylin and DAB are two. The Residual option is the third channel, which can be considered to be the leftover information not assigned to one of the other channels. If only two stains are present in the image, values in the residual image should generally be small, noisy and not very meaningful.
If this is not the case, it implies either the presence of something in the image that does not match with the other stains, or that QuPath's estimate of the 'true' color of the stains is off. Fixing the latter case is the purpose of the Analyze → Preprocessing → Estimate stain vectors command.
The Optical density sum transform effectively makes the value of each pixel depend upon the total amount of stain present - irrespective of which stain it is. It tends to make a brightfield image look rather like a fluorescence image, but with particularly low values (typically < 2.5).
Reconvolve standard stains performs some color normalization. It first separates the stains (with color deconvolution again), and then reassembles a new image using 'standard' colors for the stains that were present - omitting the residual. Alongside the Estimate stain vectors command, this can help standardize the appearance of images that were stained differently, or scanned on different scanners.
Note that the normalization of Reconvolve standard stains is purely for visual purposes. Processing (e.g. cell detection) is still applied to the raw data.
Various other transforms are available for brightfield images, including a visualization that normalizes colors to reduce their dependence on intensities, or simply separating out the red, green and blue channels and viewing these individually.
Color transforms for fluorescence images
The Brightness/Contrast tool offers similar functionality for fluorescence images, but here the list of transforms simply provides a way to turn individual channels on or off.
In this case, it is possible to have multiple channels (transforms) selected at the same time - in which case they will simply be merged together for display.
An extra feature of relevance to fluorescence images, is the ability to change the colors used to display any particular channel. This is done by double-clicking on the channel name in the Brightness/Contrast panel.
Doing so opens up a dialog box from which a new color can be selected.
After pressing Apply, the color used to display the channel will update accordingly.
Numeric shortcut keys
It may now be clear what happens whenever a number is typed: QuPath simply toggles the Selected status of the corresponding color transform, as it is seen in the Brightness/Contrast panel.
This effectively provides a very fast way to toggle the display while viewing an image, without a need for clicking around the panel.
Setting the display range
Finally, we consider the ostensible purpose of the Brightness/Contrast tool... namely, to change the brightness and contrast of the image.
This is done by adjusting the Min display and Max display sliders.
Min display sets the pixel value below which all other pixels with a lower value will be shown with the same ('minimum') color.
Max display sets the pixel value above which all other pixels with a higher value will be shown with the same 'maximum' color.
All pixel values falling between the minimum and maximum will be displayed with some shade of color falling between the two extremes.
What the 'minimum' and 'maximum' colors are depends upon the current transform; in the example below of viewing a hematoxylin image (not grayscale), the minimum is white and the maximum is blue.
Had the Show grayscale button been checked, the minimum would have been black and the maximum white.
In the image above, the Min display and Max display were set at extremes, and the result was a fairly low-contrast image in which most pixels fall somewhere between the minimum and maximum.
To increase the contrast, simply move one or both sliders so that they come closer together, as shown below:
This effectively clips the pixels with values outside the defined range so that they all look the same. The histogram shows an approximate distribution for the pixels across the image, to give some idea of how many pixels will fall within and outside the range that is set.
For extra control, it is also possible to double-click on either Min display or Max display and enter in any specific value. This can be useful, e.g. to ensure that the minimum is set to 0, or some low threshold below which the values are less interesting.