blinkenxmas.animations

The blinkenxmas.animations module defines the animation functions available for generating presets. Specifically, any function decorated with the animation() decorator is registered as an available animation in the interface.

Animation functions can take an arbitrary set of parameters. The decorator’s parameters affect how the parameters of the function will be rendered in the interface. For this reason, you are encouraged to look at the full definition of each animation function including its decorator. The function must return a list of list of Color. The outer list defines the “frames” of the animation. Each inner list defines the color of each LED in index order.

For example, here is the full definition of gradient_by_index():

@animation('Gradient (by index)',
           led_count=ParamLEDCount(),
           color1=Param('From', 'color', default='#000000'),
           color2=Param('To', 'color', default='#ffffff'))
def gradient_by_index(led_count, color1, color2):
    gradient = color1.gradient(color2, steps=led_count)
    return [[color for color in gradient]]

The decorator defines the title for the animation, and the label, type, and defaults for each parameter. The result is a list of lists, but as there’s only one “frame” the outer list contains one item.

Animation functions

blinkenxmas.animations.one_color(led_count, color)

This “animation” simply shows the selected color on all LEDs of the tree. Use black to create a setting that turns all LEDs off.

blinkenxmas.animations.gradient_by_index(led_count, color1, color2)

This displays a gradient that fades from one color to another along all LEDs of the tree. Please note this does not use the scanned coordinates of the LEDs (see “Gradient” instead), so the effect will only appear to be a gradient over the height of the tree if the LEDs are laid out in numeric order.

blinkenxmas.animations.gradient_by_pos(led_count, positions, bottom, top)

This displays a gradient that fades from one color at the bottom of the tree, to another color at the top. Please note this requires that you have run the calibration step to determine LED positions accurately.

blinkenxmas.animations.sweep_by_index(led_count, fps, color, bounce, speed)

This animation sweeps the specified color along the LEDs in numeric order. If Bounce is checked, the color will sweep back along the LEDs to the start, in effect bouncing between the extremes of the strand(s). Speed indicates how quickly the sweep (or bounce) should occur.

Please note this does not use the scanned coordinates of the LEDs, so the sweep will only appear to move up the tree if the LEDs are laid out in numeric order.

blinkenxmas.animations.sweep_by_pos(led_count, fps, positions, angle, slant, planes, color, speed)

This animation sweeps a plane of the specified color through the tree at the Angle and Slant specified.

Slant represents the angle from the vertical that the plane moves along. The default of 0° means vertically downwards through the tree, 90° means horizontally through the tree, and 180° is vertically upwards. Angle dictates the rotation about the trunk (and thus is only really meaningful when Slant is not near 0° or 180°).

Planes determines how many planes simultaneously sweep through the tree. Speed determines how quickly the color sweeps from one extreme to the other.

Please note this animation requires that you have run the calibration step to determine LED positions accurately.

blinkenxmas.animations.flash(led_count, fps, color1, color2, speed)

This animation trivially flashes all LEDs on the tree alternately between color 1 and 2 at the specified speed.

blinkenxmas.animations.twinkle(led_count, fps, color, lit, speed, duration=5)

Generates a cyclic animation that randomly fades LEDs on the tree from black up to the specified color and back to black. The Lit % indicates the proportion of LEDs that should be fully lit during any given frame. At high proportions the animation appears more as if LEDs are periodically fading off, rather than fading on. Speed indicates how quickly the fade should occur.

blinkenxmas.animations.rainbow_by_index(led_count, count, saturation, value)

This displays a rainbow along all LEDs of the tree. If you have multiple equal length strips of LEDs on your tree, it is worth setting “# Rainbows” to the number of strips to obtain a continuous rainbow up the height of the tree.

Please note this does not use the scanned coordinates of the LEDs (see “Rainbow (by position)” instead), so the effect will only appear to be a rainbow over the height of the tree if the LEDs are laid out in numeric order, and/or the “# Rainbows” parameter equals the number of (equal length) strips running up the tree.

blinkenxmas.animations.rainbow_by_pos(led_count, positions, count, saturation, value)

This displays the specified number of rainbows from the top of the tree, to the bottom. The saturation and brightness sliders determine the strength of colors in the rainbow.

Please note this requires that you have run the calibration step to determine LED positions accurately.

blinkenxmas.animations.scrolling_rainbow_by_index(led_count, fps, count, saturation, value, duration)

This displays a rainbow along all LEDs of the tree that rotates through all hues. If you have multiple equal length strips of LEDs on your tree, it is worth setting “# Rainbows” to the number of strips to obtain a continuous rainbow up the height of the tree.

Please note this does not use the scanned coordinates of the LEDs (see “Scrolling Rainbow (by position)” or “Spinning Rainbow” instead), so the effect will only appear to be a rainbow over the height of the tree if the LEDs are laid out in numeric order, and/or the “# Rainbows” parameter equals the number of (equal length) strips running up the tree.

blinkenxmas.animations.spinning_rainbow(led_count, fps, positions, saturation, value, duration)

Displays a rainbow around the trunk of the tree which spins for the specified duration. The saturation and brightness sliders determine the strength of colors in the rainbow.

Please note this requires that you have run the calibration step to determine LED positions accurately.

blinkenxmas.animations.pride_flags(led_count, positions, flag, saturation, lightness)

Display one of the Pride flags on the tree from top to bottom. The saturation and brightness sliders determine the strength of colors in the rainbow.

Please note this requires that you have run the calibration step to determine LED positions accurately.

Utility functions

blinkenxmas.animations.scale(value, in_range, out_range)

Scales value from in_range to out_range. The ranges are expected to be (min, max) tuples. Provided value is within in_range, the result will be within out_range, scaled linearly.

blinkenxmas.animations.range_of(it)

Returns a (minimum, maximum) tuple for the range of values in it, utilizing a single pass. This can be slightly more efficient that calling min() and max() separately on it depending on its size. However, it may also be more efficient to sort() it and simply access the first and last element, depending on circumstance.

blinkenxmas.animations.pairwise(it)

Given an iterable it, yields successive overlapping pairs. For example: pairwise(‘ABCDEF’) –> AB BC CD DE EF

blinkenxmas.animations.preview(anim)

On a true-color capable terminal, print a line per frame of the specified anim. This is primarily intended as a debugging function.