# How do I change colours?

```{admonition} What will I learn?
* How to adjust the brightness & contrast
* How to change fluorescence channel colours
* How to separate stains in brightfield images
```

We started the first chapter with 3 core facts:
* **Images** are composed of **pixels**
* **Pixels** have **numeric values**
* **Colours** are used to **display pixels** based on those numeric values

While the numbers are what matters for analysis, the colours are still very useful for our visual interpretation.

This chapter explores how we can change what we see -- without necessarily changing our data.

## How to adjust the brightness and contrast

```{figure} ../../images/view_image/spooked.png
:figclass: margin
Why is he so nervous?
```

```{admonition} What to do
1. Open the image `spooked.png`.  
   - Choose {guilabel}`Other` as the image type
3. Open QuPath Brightness & Contrast dialog using *any* of these (equivalent) methods
   - {menuselection}`View --> Brightness/Contrast`
   - Click on the toolbar button {{icon_contrast}}
   - Use the shortcut {kbd}`Shift+C` 
4. Move the {guilabel}`Channel min`, {guilabel}`Channel max` and {guilabel}`Gamma` sliders.
5. Press the {guilabel}`Reset` button to return everything to normal.
```

{menuselection}`View --> Brightness/Contrast` {{icon_contrast}} is extremely useful -- that's why there are 3 ways to open it.
Sometimes, you *need* to change the brightness and contrast because important details aren't visible otherwise.

However, it's important to be cautious and make sure you know what's happening.
Specifically, you need to know whether changing the sliders is changing your data, or only how it is displayed.

```{admonition} Question
Move the {guilabel}`Channel min` and {guilabel}`Channel max` sliders in QuPath's Brightness & Contrast window.

Do these sliders change the numeric values of the pixels, or only the colours used to display pixels in the viewer?

How do you know?
```

```{admonition} Question
What is making the guy in `spooked.png` look so nervous?
```

```{admonition} Go easy on gamma!
:class: danger

It's normal to have to adjust the {guilabel}`Channel min` and {guilabel}`Channel max` sliders for fluorescence images.
Changing the {guilabel}`Gamma` is less common -- if you use a gamma that isn't 1.0, *you should mention this in any figure legends*.

For more information and best practice guidelines, check out

> Schmied, C., Nelson, M.S., Avilov, S. et al. Community-developed checklists for publishing images and image analyses. *Nat Methods* 21, 170–181 (2024). [https://doi.org/10.1038/s41592-023-01987-9](https://doi.org/10.1038/s41592-023-01987-9)
```


## How to change fluorescence channel colours

### Toggle channels on and off

```{figure} ../../images/multiplex/multiplex_stain_select.png
:figclass: margin
Set fluorescence image type
```

```{admonition} What to do
1. Open `LuCa-7color_[13860,52919]_1x1.tif`
   - Choose {guilabel}`Fluorescence` as the image type
2. Open the brightness and contrast dialog {{icon_contrast}}
3. Use the checkboxes to turn channels on and off
4. Type a number (e.g. {kbd}`1`, {kbd}`2`, {kbd}`3`) and see what happens
```

In images with multiple channels, it's possible to toggle individual channels on and off using the brightness & contrast dialog {{icon_contrast}}.

However, you can also quickly change turn channels on or off by simply typing the number of the channel using your keyboard -- and this works even if the brightness & contrast dialog isn't open.


### Change the brightness & contrast for each channel

```{figure} ../../images/multiplex/B_C_window.png
:figclass: margin
Brightness and contrast window of a multiplex image
```

```{admonition} What to do
1. Select a channel by clicking on it (it'll be highlighted in blue)
2. Make sure the channel's {guilabel}`Show` checkbox is turned on
3. Explore how the {guilabel}`Channel min` and {guilabel}`Channel max` sliders are influenced by which channel is selected
4. Press the {guilabel}`Auto` and {guilabel}`Reset` buttons
```

When a channel is selected, moving the {guilabel}`Channel min` and {guilabel}`Channel max` sliders should adjust the brightness and contrast *only for that channel*.

Pressing {guilabel}`Auto` asks QuPath to try to set the sliders automatically to values that (hopefully) are sensible.
Pressing {guilabel}`Reset` should set the {guilabel}`Channel min` to the lowest pixel value and {guilabel}`Channel max` to the highest pixel value[^min-max-caveat].
This behaviour is similar to the equivalent buttons in ImageJ.

[^min-max-caveat]: For a large image, {guilabel}`Reset` will only reset the brightness and contrast sliders to an *approximation* of the minimum and maximum pixel values. It would be too slow for QuPath to read all the pixels to check the true minimum and maximum.

```{admonition} Puzzle
1. Open the [message.tif](https://github.com/user-attachments/files/23187253/message.tif) image.
2. Using the settings in the brightness & contrast dialog, see if you can find anything unusual in the image.
```


### Changing channel names & colours

```{admonition} What to do
1. Double-click on a channel, e.g. {guilabel}`CD8 (Opal 540)`
2. Enter a new channel name.
3. Select a new channel colour.
4. Click {guilabel}`Apply`
```

{menuselection}`View --> Brightness/Contrast` {{icon_contrast}} also makes it possible for you to change channel names and colours.

Both can be changed by double-clicking.
Alternatively, you can click directly on the small colour square to change the channel colour only.


```{admonition} Question
What do the {guilabel}`Show grayscale` and {guilabel}`Invert background` checkboxes do?
```

## How to separate stains in brightfield images

### Digital stain separation with colour deconvolution

```{admonition} What to do
1. Open `CMU-1.svs`.
    - Choose {guilabel}`Brightfield (H & E)` as the image type
2. Open the brightness and contrast dialog {{icon_contrast}}
3. Click on {guilabel}`Hematoxylin` to view a stain-separated image
4. See how the numbers in the bottom right change when you move the cursor over the image
```

Setting the image type to {guilabel}`Brightfield H & E` gave QuPath the information it needed to digitally separate the stains using a process called **colour deconvolution**[^ref-colour-deconv].

[^ref-colour-deconv]: Ruifrok AC, Johnston DA. Quantification of histochemical staining by color deconvolution. Anal Quant Cytol Histol. 2001 Aug;23(4):291-9. PMID: 11531144.

This is based on a *default* estimate of the stain colours: it won't be perfect, but it's often good enough to be useful.

After selecting {guilabel}`Hematoxylin`, when you move your cursor over the image, you no longer see the original pixel values.
Rather, you see the colour deconvolved values that are related to the staining that is present.

Importantly, QuPath's approach to colour deconvolution *doesn't permanently change the pixel values*.
You can easily switch back to the original image through the brightness/contrast dialog.
The separation is really a visualization trick to help us understand the image a bit better.

```{figure} ../../images/finding_way/bandc_examples.png
Digital stain separation using the brightness/contrast dialog.
```


### Type matters

```{admonition} What to do
1. Go back to the {guilabel}`Image` tab double click {guilabel}`Image type`.
2. Change the type to {guilabel}`Brightfield (H-DAB)`. 
3. See how the channels available in the brightness/contrast dialog change
4. Repeat the process, setting the image to have different types. 
```

Setting the image type in QuPath changes the channels that are available in the brightness and contrast dialog.

What's more, not all channels are quite the same.

With a fluorescence image (e.g. `LuCa-7color_[13860,52919]_1x1.tif`), the channels that we could see where those that were stored in the original file.
But for the brightfield `CMU-1.svs`, the channels QuPath shows are calculated digitally -- and depend upon the image type.

This is why it's important to get into the habit of setting the type of an image in QuPath: it influences how the software will behave.
It doesn't matter for *every* command, but it does matter for some important ones -- including cell detection.



```{seealso}
* [First steps](https://qupath.readthedocs.io/en/latest/docs/starting/index.html)
* [Supported image formats](https://qupath.readthedocs.io/en/latest/docs/intro/formats.html)
* [Viewing images](https://qupath.readthedocs.io/en/latest/docs/starting/viewing.html)
* [From pixels to microns](https://qupath.readthedocs.io/en/latest/docs/concepts/images.html#from-pixels-to-microns)
```