UtilityLibrary

6. Feb.

Library "UtilityLibrary"
A collection of custom utility functions used in my scripts.

milliseconds_per_bar()
  Gets the number of milliseconds per bar.
  Returns: (int) The number of milliseconds per bar.

realtime()
  Checks if the current bar is the actual realtime bar.
  Returns: (bool) `true` when the current bar is the actual realtime bar, `false` otherwise.

replay()
  Checks if the current bar is the last replay bar.
  Returns: (bool) `true` when the current bar is the last replay bar, `false` otherwise.

bar_elapsed()
  Checks how much of the current bar has elapsed.
  Returns: (float) Between 0 and 1.

even(number)
  Checks if a number is even.
  Parameters:
    number (float): (float) The number to evaluate.
  Returns: (bool) `true` when the number is even, `false` when the number is odd.

sign(number)
  Gets the sign of a float.
  Parameters:
    number (float): (float) The number to evaluate.
  Returns: (int) 1 or -1, unlike math.sign() which returns 0 if the number is 0.

atan2(y, x)
  Derives an angle in radians from the XY coordinate.
  Parameters:
    y (float): (float) Y coordinate.
    x (float): (float) X coordinate.
  Returns: (float) Between -π and π.

clamp(number, min, max)
  Ensures a value is between the `min` and `max` thresholds.
  Parameters:
    number (float): (float) The number to clamp.
    min (float): (float) The minimum threshold (0 by default).
    max (float): (float) The maximum threshold (1 by default).
  Returns: (float) Between `min` and `max`.

remove_gamma(value)
  Removes gamma from normalized sRGB channel values.
  Parameters:
    value (float): (float) The normalized channel value [0, 1].
  Returns: (float) Channel value with gamma removed.

add_gama(value)
  Adds gamma into normalized linear RGB channel values.
  Parameters:
    value (float): (float) The normalized channel value [0, 1].
  Returns: (float) Channel value with gamma added.

rgb_to_xyz(Color)
  Extracts XYZ-D65 channels from sRGB colors.
  Parameters:
    Color (color): (color) The sRGB color to process.
  Returns: (float tuple) [x, y, z]

xyz_to_rgb(x, y, z)
  Converts XYZ-D65 channels to sRGB channels.
  Parameters:
    x (float): (float) The X channel value.
    y (float): (float) The Y channel value.
    z (float): (float) The Z channel value.
  Returns: (int tuple) [r, g, b]

rgb_to_oklab(Color)
  Extracts OKLAB-D65 channels from sRGB colors.
  Parameters:
    Color (color): (color) The sRGB color to process.
  Returns: (float tuple) [l, a, b]

oklab_to_rgb(l, a, b)
  Converts OKLAB-D65 channels to sRGB channels.
  Parameters:
    l (float): (float) The L channel value.
    a (float): (float) The A channel value.
    b (float): (float) The B channel value.
  Returns: (int tuple) [r, g, b]

rgb_to_oklch(Color)
  Extracts OKLCH channels from sRGB colors.
  Parameters:
    Color (color): (color) The sRGB color to process.
  Returns: (float tuple) [l, c, h]

oklch_to_rgb(l, c, h)
  Converts OKLCH channels to sRGB channels.
  Parameters:
    l (float): (float) The L channel value.
    c (float): (float) The C channel value.
    h (float): (float) The H channel value.
  Returns: (float tuple) [r, g, b]

hues(l1, h1, l2, h2, dist)
  Ensures the hue angles are set correctly for linearly interpolating OKLCH.
  Parameters:
    l1 (float): (float) The first L channel value.
    h1 (float): (float) The first H channel value.
    l2 (float): (float) The second L channel value.
    h2 (float): (float) The second H channel value.
    dist (string): (string) The preferred angular distance to use. Options: `min` or `max` (`min` by default).
  Returns: (float tuple) [h1, h2]

lerp(a, b, t)
  Linearly interpolates between two values.
  Parameters:
    a (float): (float) The starting point (first value).
    b (float): (float) The ending point (second value).
    t (float): (float) The interpolation factor [0, 1].
  Returns: (float) Between `a` and `b`.

smoothstep(t, precise)
  A non-linear (smooth) interpolation between 0 and 1.
  Parameters:
    t (float): (float) The interpolation factor [0, 1].
    precise (bool): (bool) Sets if the calc should be precise or efficient (`true` by default).
  Returns: (float) Between 0 and 1.

ease(t, n, v, x1, y1, x2, y2)
  A customizable non-linear interpolation between 0 and 1.
  Parameters:
    t (float): (float) The interpolation factor [0, 1].
    n (float): (float) The degree of ease [0≤] (1 by default).
    v (string): (string) The easing variant type: `in-out`, `in`, or `out` (`in-out` by default).
    x1 (float): (float) Optional X coordinate of starting point [0, 1] (0 by default).
    y1 (float): (float) Optional Y coordinate of starting point [0, 1] (0 by default).
    x2 (float): (float) Optional X coordinate of ending point [0, 1] (1 by default).
    y2 (float): (float) Optional Y coordinate of ending point [0, 1] (1 by default).
  Returns: (float) Between 0 and 1.

mix(color1, color2, blend, space, dist)
  Linearly interpolates between two colors.
  Parameters:
    color1 (color): (color) The first color.
    color2 (color): (color) The second color.
    blend (float): (float) The interpolation factor [0, 1].
    space (string): (string) The color space to use for interpolating. Options: `rgb`, `oklab`, and `oklch` (`rgb` by default).
    dist (string): (string) The anglular distance to use for the hue change when the color space is set to `oklch`. Options: `min` and `max` (`min` by default).
  Returns: (color) Blend of `color1` and `color2`.

6. Feb.

Versionshinweise

v2

Added:
fade(Color, Alpha)
  Linearly interpolates a colors transparency.
  Parameters:
    Color (color): (color) The color to process.
    Alpha (float): (float) The interpolation factor [0, 1], where `0` is fully transparent and `1` is the original transparency value (0.5 by default).
  Returns: (color) The same RGB color with an interpolated A channel.

6. Feb.

Versionshinweise

v3

Added:
bar_index_to_time(Bar_Index)
  Converts a `bar_index` into a `bar_time`.
  Parameters:
    Bar_Index (int): (int) The `bar_index`.
  Returns: (int) `bar_time` of `bar_index`

source(s, o, h, l, c)
  Calculates a source value. Most useful when a script uses `request.security` or `request.security_lower_tf`.
  Parameters:
    s (string): (string) The desired source. Options: `open`, `high`, `low`, `close`, `hl2`, `hlc3`, `ohlc4`, `hlcc4`, `min`, or `max`.
    o (float): (float) The opening value.
    h (float): (float) The highest value.
    l (float): (float) The lowest value.
    c (float): (float) The closing value.
  Returns: (foat) The specified source, or 0 if the result is `na`.

12. Feb.

Versionshinweise

v4

Added:
method is_transparent(Color)
  Method for determining if a color is invisible.
  Namespace types: series color, simple color, input color, const color
  Parameters:
    Color (color): (color) Color to evaluate.
  Returns: (bool) `true` when the color is transparent, `false` otherwise.

inv_lerp(a, b, v)
  Normalizes a value between two other values (inverse lerp).
  Parameters:
    a (float): (float) Starting value.
    b (float): (float) Ending value.
    v (float): (float) Current value.
  Returns: (float) Value between 0 and 1.

remap(iMin, iMax, oMin, oMax, v)
  Linearly interpolates between two values given a non-normalized value.
  Parameters:
    iMin (float): (float) Input minimum (where to start interpolating).
    iMax (float): (float) Input maximum (where to stop interpolating).
    oMin (float): (float) Output minimum (lowest output value).
    oMax (float): (float) Output maximum (highest output value).
    v (float): (float) Current value.
  Returns: (float) Value between `oMin` and `oMax`

cubic_bezier(t, p0, p1, p2, p3)
  A non-linear (smooth) approximated interpolation between 0 and 1 derived from the 4 points of a Cubic Bézier Curve. Note: oddly shaped curves may produce unexpected results. Further, because the interpolation is being approximated within a bifurcation loop, calling the function with each chart update may be inefficient. While useful, minimizing calls to this function is recommended.
  Parameters:
    t (float): (float) Interpolation factor [0, 1].
    p0 (point): (point) Starting point ((0,0) by default).
    p1 (point): (point) First control point ((0.25,1) by default).
    p2 (point): (point) Second control point ((0,1) by default).
    p3 (point): (point) Ending point ((1,1) by default).
  Returns: (float) Value between 0 and 1.

point
  Coordinates for a 2D point.
  Fields:
    x (series float): (float) X coordinate of point.
    y (series float): (float) Y coordinate of point.

20. Feb.

Versionshinweise

v5
Improved:
realtime()

Renamed:
bar_index_to_time() to index_to_time()

Added:
time_to_index(number_of_milliseconds)
  Converts a `bar_time` offset into a `bar_index` equivalent.
  Parameters:
    number_of_milliseconds (int): (int) The `bar_time` offset in milliseconds.
  Returns: (int) Offset converted to number of bars.