GY-63_MS5611/libraries/Kelvin2RGB/README.md

[![Arduino CI](https://github.com/RobTillaart/Kelvin2RGB/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
[![Arduino-lint](https://github.com/RobTillaart/Kelvin2RGB/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/Kelvin2RGB/actions/workflows/arduino-lint.yml)
[![JSON check](https://github.com/RobTillaart/Kelvin2RGB/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/Kelvin2RGB/actions/workflows/jsoncheck.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/Kelvin2RGB/blob/master/LICENSE)
[![GitHub release](https://img.shields.io/github/release/RobTillaart/Kelvin2RGB.svg?maxAge=3600)](https://github.com/RobTillaart/Kelvin2RGB/releases)


# Kelvin2RGB

Arduino library for converting temperature and brightness to RGB values.


## Credentials

This library is based upon an article of Tanner Helland and a related story by Neil Bartlett

- http://www.tannerhelland.com/4435/convert-temperature-rgb-algorithm-code/
- http://www.zombieprototypes.com/?p=210
- https://en.wikipedia.org/wiki/Color_temperature#Categorizing_different_lighting

There are more approximation formulas, some claim to be better,
however these are not investigated. On request these can be added.


## Description

The library converts a temperature in Kelvin and a brightness (0..100%)
 to three numbers **red**, **green** and **blue**.
These numbers are weights can be used to correct a colour image for virtual white temperature.

There are two convert functions where the **convert_NB()** is claimed to be
the more accurate one.

With the numbers **red**, **green** and **blue** calculated one can convert images 
so they will look more like taken with candle light, sunrise or sunset etc.


**pseudo code**
```cpp
Kelvin2RGB KRGB;

KRGB.convert(1850, 100);  // sunrise light factors

for each pixel in image
{
  red   *= KRGB.red();
  green *= KRGB.green();
  blue  *= KRGB.blue();
  drawPixel();
}
```

The numbers can also be used to reduce the blue channel so it has less effect 
on "getting sleepy".

The library uses floats for the R,G and B weights to keep values as accurate as possible.
Especially with images with more than 8 bits per channel this is preferred.
That said it is also possible to use this on a 565 image or to adjust colour lookup tables.


## Interface

```cpp
#include "Kelvin2RGB.h"
```

The interface is straightforward:

- **Kelvin2RGB()** constructor
- **void begin()** empty function for now.
- **void reset()** resets all internal values to 0. 
All colours, brightness and temperature.
- **void convert_TH(float temperature, float brightness = 100)**
    temperature = 0..65500   temperature below 1000 is not well defined.
    brightness = 0..100%,
- **void convert_NB(float temperature, float brightness = 100)**
    temperature = 0..65500   temperature below 1000 is not well defined.
    brightness = 0..100%,
    Is a bit more accurate and slightly slower (few %). Read link above for more information.
- **float temperature()** returns temperature, to check the value used.
- **float brightness()** returns brightness, to check the value used.
- **float red()** returns red channel weight 0.0 .. 1.0
note this is different from Helland / Bartlett who both use an integer value 0 .. 255
- **float green()** returns green channel weight 0.0 .. 1.0
- **float blue()** returns blue channel weight 0.0 .. 1.0
- **uint32_t setRGB(float red, float green, float blue, float brightness = 100)** sets RGB values
red, green, blue should be in 0 .. 1.0 range. brightness should be in 0..100%, Default = 100%.
returns a 24 bit RGB value,
- **uint32_t RGB()** returns a 24 bit RGB value, 0 .. 16777215
more efficient than 3 floats for communication.
- **uint16_t RGB565()** returns a 16 bit RGB value, 5 bits for red, 6 for green and 5 for blue.
- **uint32_t BGR()** returns a 24 bit BGR value, 0 .. 16777215
- **uint32_t CMYK()** returns a 32 bit = 4 byte CMYK value,


## Operations

See examples


## Future

#### Must

#### Should

- define constants like candleLight as parameter.
- investigate other formulas.
- investigate usability for RGB led strip.

#### Could

- separate brightness per colour channel to mimic "artificial illumination"  (0.2.0 ?)
- remove begin() ?
- add examples
  - ledstrip
  - CMYK()
  - BGR()

#### Wont

- investigate **RGB_10_12_10()**
  - nowhere used (not found)