Utils

Library "Utils"
Utility functions. Mathematics, colors, and auxiliary algorithms.

setTheme(vc, theme)
  Set theme for levels (predefined colors).
  Parameters:
    vc: (valueColorSpectrum) Object to associate a color with a value, taking into account the previous value and its levels.
    theme: (int) Theme (predefined colors).
0 = 'User defined'
1 = 'Spectrum Blue-Green-Red'
2 = 'Monokai'
3 = 'Green'
4 = 'Purple'
5 = 'Blue'
6 = 'Red'
  Returns: (void)

setTheme(vc, colorLevel_Lv1, colorLevel_Lv1_Lv2, colorLevel_Lv2_Lv3, colorLevel_Lv3_Lv4, colorLevel_Lv4_Lv5, colorLevel_Lv5)
  Set theme for levels (customized colors).
  Parameters:
    vc: (valueColorSpectrum) Object to associate a color with a value, taking into account the previous value and its levels
    colorLevel_Lv1: (color) Color associeted with value when below Level 1.
    colorLevel_Lv1_Lv2: (color) Color associeted with value when between Level 1 and 2.
    colorLevel_Lv2_Lv3: (color) Color associeted with value when between Level 2 and 3.
    colorLevel_Lv3_Lv4: (color) Color associeted with value when between Level 3 and 4.
    colorLevel_Lv4_Lv5: (color) Color associeted with value when between Level 4 and 5.
    colorLevel_Lv5: (color) Color associeted with value when above Level 5.
  Returns: (void)

setCurrentColorValue(vc)
  Set color to a current value, taking into account the previous value and its levels
  Parameters:
    vc: (valueColorSpectrum) Object to associate a color with a value, taking into account the previous value and its levels
  Returns: (void)

setCurrentColorValue(vc, gradient)
  Set color to a current value, taking into account the previous value.
  Parameters:
    vc: (valueColor) Object to associate a color with a value, taking into account the previous value
    gradient
  Returns: (void)

setCustomLevels(vc, level1, level2, level3, level4, level5)
  Set boundaries for custom levels.
  Parameters:
    vc: (valueColorSpectrum) Object to associate a color with a value, taking into account the previous value and its levels
    level1: (float) Boundary for level 1
    level2: (float) Boundary for level 2
    level3: (float) Boundary for level 3
    level4: (float) Boundary for level 4
    level5: (float) Boundary for level 5
  Returns: (void)

getPeriodicColor(originalColor, density)
  Returns a periodic color. Useful for creating dotted lines for example.
  Parameters:
    originalColor: (color) Original color.
    density: (float) Density of color. Expression used in modulo to obtain the integer remainder.
If the remainder equals zero, the color appears, otherwise it remains hidden.
  Returns: (color) Periodic color.

dinamicZone(source, sampleLength, pcntAbove, pcntBelow)
  Get Dynamic Zones
  Parameters:
    source: (float) Source
    sampleLength: (int) Sample Length
    pcntAbove: (float) Calculates the top of the dynamic zone, considering that the maximum values are above x% of the sample
    pcntBelow: (float) Calculates the bottom of the dynamic zone, considering that the minimum values are below x% of the sample
  Returns: A tuple with 3 series of values: (1) Upper Line of Dynamic Zone;
(2) Lower Line of Dynamic Zone; (3) Center of Dynamic Zone (x = 50%)

valueColorSpectrum
  # Object to associate a color with a value, taking into account the previous value and its levels.
  Fields:
    currentValue
    previousValue
    level1
    level2
    level3
    level4
    level5
    currentColorValue
    colorLevel_Lv1
    colorLevel_Lv1_Lv2
    colorLevel_Lv2_Lv3
    colorLevel_Lv3_Lv4
    colorLevel_Lv4_Lv5
    colorLevel_Lv5
    theme

valueColor
  # Object to associate a color with a value, taking into account the previous value
  Fields:
    currentValue
    previousValue
    currentColorValue
    colorUp
    colorDown

Release Notes:

v2 Added example source code

Release Notes:

v3

Updated:
setTheme(vc, colorLevel_Lv1, colorLevel_Lv1_Lv2, colorLevel_Lv2_Lv3, colorLevel_Lv3_Lv4, colorLevel_Lv4_Lv5, colorLevel_Lv5)
  Set theme for levels (customized colors).
#### Usage
___
```
#region Theme for Histogram above 0
var string GRP_THEME_HISTOGRAM_ABOVE = 'Theme for Histogram above 0'
var colorHistogramUp_1 = input(color.new(#0064bb, 0), "", inline="2", group=GRP_THEME_HISTOGRAM_ABOVE)
var colorHistogramUp_2 = input(color.new(#007ce9, 0), "", inline="2", group=GRP_THEME_HISTOGRAM_ABOVE)
var colorHistogramUp_3 = input(color.new(#1893ff, 0), "", inline="2", group=GRP_THEME_HISTOGRAM_ABOVE)
var colorHistogramUp_4 = input(color.new(#46a9ff, 0), "", inline="2", group=GRP_THEME_HISTOGRAM_ABOVE)
var colorHistogramUp_5 = input(color.new(#75beff, 0), "", inline="2", group=GRP_THEME_HISTOGRAM_ABOVE)
var colorHistogramUp_6 = input(color.new(#91c9fa, 0), "", inline="2", group=GRP_THEME_HISTOGRAM_ABOVE)
// #endregion
vcHistogram = UTIL.valueColorSpectrum.new()
vcHistogram.currentValue := histogram
vcHistogram.previousValue := histogram
UTIL.setCustomLevels(vcHistogram, 5, 10, 15, 20, 25)
UTIL.setTheme(vcHistogram, colorHistogramUp_1, colorHistogramUp_2, colorHistogramUp_3, colorHistogramUp_4, colorHistogramUp_5, colorHistogramUp_6)
```
___
  Parameters:
    vc: (valueColorSpectrum) Object to associate a color with a value, taking into account the previous value and its levels
    colorLevel_Lv1: (color) Color associeted with value when below Level 1.
    colorLevel_Lv1_Lv2: (color) Color associeted with value when between Level 1 and 2.
    colorLevel_Lv2_Lv3: (color) Color associeted with value when between Level 2 and 3.
    colorLevel_Lv3_Lv4: (color) Color associeted with value when between Level 3 and 4.
    colorLevel_Lv4_Lv5: (color) Color associeted with value when between Level 4 and 5.
    colorLevel_Lv5: (color) Color associeted with value when above Level 5.
  Returns: (void)

Release Notes:

v4

Added:
round(value)
  Round a value between .999 and -.999. Function used in Fisher Transform.
  Parameters:
    value: (float) Value to be rounded.
  Returns: (float) Value rounded.

Release Notes:

v5 New themes

Release Notes:

v6 New themes:

Release Notes:

v7
Extra (overloaded) method to use gradient with custom levels.

Release Notes:

v8
- New themes added.
- The themes were reorganized by value ranges, in order to facilitate the choice, and future implementations:

10 to 15 → Spectrum Blue-Green-Red
20 to 21 → Monokai
30 to 31 → Spectrum White-Green-Red
40 to 41 → Green-Purple
50 to 51 → Blue-Red
60 to 61 → Blue-Yellow
70 to 71 → Green-Red
80 to 81 → Green
90 to 91 → Purple
100 to 107 → Blue
120 to 123 → Blue-Aqua
130 to 133 → Blue-Green
140 to 153 → Red
160 to 161 → Red-Yellow
170 to 171 → Red-White
180 to 185 → White-Black

Release Notes:

v9
New themes:

Codes 190, 191

Release Notes:

v10: Added themes 134, 135 (green-blue, blue-green), 162, 163 (yellow-red, red-yellow)

Release Notes:

v11: New themes added.