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

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


# GAMMA

Arduino Library for the GAMMA function to adjust brightness of LED's etc.


## Description

This library is provides a gamma lookup class. It is typical used to 
change the intensity / brightness of a LED to match the human eye.
When a LED is given 50% PWM it looks far brighter for the eye.

This lib provides a balance between an expensive math function and the speed
of a lookup table. 

The accuracy of the library depends on the size of the internal array.
A size of 256 is the reference. Smaller arrays use interpolation and 
these interpolated values are good (< 1%) down to internal array size 16. 
The size can be as small as 2 which is pretty inaccurate.
In this latter case the curve is approximated by only two linear interpolations.
In short, choose the size that fits your application.

The library has a **setGamma(float gamma)** function that allows an application 
to change the gamma value runtime. 
This allows adjustments that are not possible with a fixed table.

The class provides **dump()** to create a table e.g. to place in PROGMEM. 
Since 0.2.2 the library also has **dumpArray()** to generate a C-style array.

Note: tested on UNO and ESP32 only.


## Interface

### Core functions

- **GAMMA(uint16_t size = 32)** constructor, gets the size of the internal
array as parameter. The default for size = 32 as this is a good balance between performance
and size of the internal array. 
The size parameter must be in {2, 4, 8, 16, 32, 64, 128, 256 }.
- **~GAMMA()** destructor.
- **bool begin()** The internal array is allocated and initialized with a gamma == 2.8.
This is an often used value to adjust light to human eye responses.
Note that **begin()** must be called before any other function.
Returns false if allocation fails.
- **void setGamma(float gamma)** calculates and fills the array with new values.
This can be done runtime so runtime adjustment of gamma mapping is possible.  
This calculation are relative expensive and takes quite some time (depending on size).
If the array already is calculated for gamma, the calculation will be skipped.
The parameter **gamma** must be > 0. The value 1 gives an 1:1 mapping.
Returns false if gamma <= 0 or if no table is allocated.
- **float getGamma()** returns the set gamma value.
- **uint8_t operator \[uint8_t index\]** allows the GAMMA object to be accessed as an array.
like ```x = G[40];``` Makes it easy to switch with a real array. 
The value returned is in the range 0 .. 255, so the user may need to scale it e.g. to 0.0 - 1.0.
Note: if internal table not allocated the function returns 0. 
As this is a legitimate value the user should take care.


### Development functions

- **uint16_t size()** returns size of the internal array.
This is always a power of 2.
- **uint16_t distinct()** returns the number of distinct values in the table. 
Especially with larger internal tables there will be duplicate numbers in the table.
- **bool dump(Stream \*str = &Serial)** dumps the internal table to a stream, default Serial. 
Useful to create an array in RAM, PROGMEM, EEPROM, in a file or wherever.
Returns false if no table is allocated.
- **void dumpArray(Stream \*str = &Serial)** dumps the internal table to a stream, default Serial, as a C-style array. See example.
Returns false if no table is allocated.


## Operation

See example.


## Future ideas

#### must
- improve documentation

#### should
- test other platforms
- look for optimizations
  - getter \[\]
  - setGamma -> pow() is expensive

#### could
- uint16 version?
  - GAMMA16, GAMMA32, 
  - GAMMA_RGB ?