RVL-Node Animations

A set of helper methods to create and render animations for RVL-Node and friends

System Requirements

• Any modern JavaScript engine (web or Node.js)

Installation

Install using npm:

npm install rvl-node-animations

Usage

Basic usage:

import {
  initRenderer,
  renderPixels,
  createWaveParameters,
  createSolidColorWave,
  createColorCycleWave
} from 'rvl-node-animations';

// Initialize the renderer
initRenderer();

const waveParameters = createWaveParameters(
  // Create a solid-cyan, half-way transparent color
  createSolidColorWave(128, 255, 128),

  // Create a fully opaque, slow color cycle that will show throw the cyan wave
  createColorCycleWave(2, 255)
);

// Render the pixels at 33 frames per second
setInterval(() => {
  const pixels = renderPixels(waveParameters);
  // Display pixels in the browser/an LED strip/etc.
}, 33);

If you intend to create these animations on the same device that will be controlling the LEDs, here is an example integrating rvl-node-animations and rvl-node:

import {
  createWaveParameters,
  createSolidColorWave,
  createColorCycleWave
} from 'rvl-node-animations';
import { RVL } from 'rvl-node';

const rvl = new RVL({
  networkInterface: 'wlan0',
  logLevel: 'debug',
  mode: 'controller'
});

rvl.on('initialized', () => {
  rvl.setWaveParameters(createWaveParameters(
    // Create a solid-cyan, half-way transparent color
    createSolidColorWave(128, 255, 128),

    // Create a fully opaque, slow color cycle that will show throw the cyan wave
    createColorCycleWave(2, 255)
  ));
});

Notes

If you're using TypeScript, you don't need to install separate @types type definitions because this package ships with them. To support sharing of interfaces between this module and rvl-node itself, I created another module called rvl-node-types, which may be of interest to you.

All waves are defined in the HSV color space that has been mapped to 8-bit integers (e.g. the hue is 0-255, not 0-360, and saturation/value are 0-255, not 0-1 or 0-100). Please familiarize yourself with the HSV color space before using this library.

API

Note: API signatures are declared using TypeScript syntax. This provides a concise, formal definition for all signatures in a syntax that is familiar to at least some developers.

createWaveParameters(wave1, wave2, wave3, wave4)

This method creates a fully formed set of wave parameters that can be passed directly to rvl-node#setWaveParameters().

Signature:

function createWaveParameters(
  wave1?: IWave,
  wave2?: IWave,
  wave3?: IWave,
  wave4?: IWave
): IWaveParameters

Arguments:

Argument	Type	Description
wave1 (optional)	IWave	The wave parameters for the top-most wave in the stack. If this wave is fully opaque, it will obscure the other waves. Use one of the create*Wave methods to generate it. If this parameter is not supplied, a fully transparent wave is created instead.
wave2 (optional)	IWave	The wave parameters for the second top-most wave in the stack. If this parameter is not supplied, a fully transparent wave is created instead.
wave3 (optional)	IWave	The wave parameters for the third top-most wave in the stack. If this parameter is not supplied, a fully transparent wave is created instead.
wave4 (optional)	IWave	The wave parameters for the bottom-most wave in the stack. If this parameter is not supplied, a fully transparent wave is created instead.

Returns: an IWaveParameters instance. Details can be found at rvl-node-types, but for all intents and purposes it can be treated as a black box.

createEmptyWave()

This method creates an empty wave, aka a fully-transparent wave that allows waves below it in the stack to be fully visible.

Signature:

function createEmptyWave(): IWave

Arguments: none

Returns: an IWave instance. Details can be found at rvl-node-types, but for all intents and purposes it can be treated as a black box.

createSolidColorWave(h, s, a)

This method creates a solid color wave that does not change over distance or time.

Signature:

function createSolidColorWave(h: number, s: number, a: number): IWave

Arguments:

Argument	Type	Description
h	number	The hue, mapped to between 0 (0 degrees) and 255 (360 degrees).
s	number	The saturation, mapped to between 0 (0%) and 255 (100%).
a	number	The alpha, mapped to between 0 (0%) and 255 (100%).

Returns: an IWave instance. Details can be found at rvl-node-types, but for all intents and purposes it can be treated as a black box.

createColorCycleWave(rate, a)

This method creates a wave that cycles through colors over time.

From a technical perspective, it linearly varies the hue over time while keeping the saturation and value at 100%.

Signature:

function createColorCycleWave(rate: number, a: number): IWave

Arguments:

Argument	Type	Description
rate	number	The rate that the color changes, between 1 and 32. The higher the number, the faster the color changes
a	number	The alpha, mapped to between 0 (0%) and 255 (100%).

Returns: an IWave instance. Details can be found at rvl-node-types, but for all intents and purposes it can be treated as a black box.

createMovingWave(h, s, rate, spacing)

This method creates a moving wave, with the alpha varying between 0% and 100% over distance, creating a "roving wave" effect.

From a technical perspective, it varies the alpha over distance, and varies the y-value of the start of wave with time.

Signature:

function createMovingWave(h: number, s: number, rate: number, spacing: number): IWave

Arguments:

Argument	Type	Description
h	number	The hue, mapped to between 0 (0 degrees) and 255 (360 degrees).
s	number	The saturation, mapped to between 0 (0%) and 255 (100%).
rate	number	The rate that the wave "moves", between 0 and 32. The higher the number, the faster the wave moves. Setting the rate to 0 means the wave does not move at all.
spacing	number	The distance between "peaks" of the waves, between 1 and 16. The higher the number, the shorter the distance.

Returns: an IWave instance. Details can be found at rvl-node-types, but for all intents and purposes it can be treated as a black box.

createPulsingWave(h, s, rate)

This method creates a wave that pulses, aka it varies from fully transparent to fully opaque over time.

From a technical perspective, it varies the alpha over time with nothing else that varies.

Signature:

function createPulsingWave(h: number, s: number, rate: number): IWave

Arguments:

Argument	Type	Description
h	number	The hue, mapped to between 0 (0 degrees) and 255 (360 degrees).
s	number	The saturation, mapped to between 0 (0%) and 255 (100%).
rate	number	The rate that the wave "pulses", between 1 and 32. The higher the number, the faster the wave pulses.

Returns: an IWave instance. Details can be found at rvl-node-types, but for all intents and purposes it can be treated as a black box.

createRainbowWave(a, rate)

This method creates a wave that looks like a rainbow, and slowly moves.

From a technical perspective it varies the hue over distance, and varies the y-value of the start of wave with time.

Signature:

function createRainbowWave(a: number, rate: number): IWave

Arguments:

Argument	Type	Description
a	number	The alpha, mapped to between 0 (0%) and 255 (100%).
rate	number	The rate that the wave "pulses", between 1 and 32. The higher the number, the faster the wave pulses.

Returns: an IWave instance. Details can be found at rvl-node-types, but for all intents and purposes it can be treated as a black box.

initRenderer(waveParameters, numPixels, numWaves)

This method initializes the renderer and starts the animation clock.

Signature:

function initRenderer(waveParameters: IWaveParameters, numPixels: number, numWaves: number = 4): void

Arguments:

Argument	Type	Description
waveParameters	number	An `IWaveParameters` instance describing your animation. Details can be found at [rvl-node-types](https://github.com/nebrius/rvl-node-types), but for all intents and purposes it can be treated as a black box.
numPixels	number	The number of pixels to render. For example, if you are sending this to an LED strip, the number of pixels is the number of LEDs in your strip.
numWaves (optional)	number	The number of wave layers. Default is 4.

Returns: none.

renderPixels()

Renders the pixels for this exact moment in time based on the parameters set in initRenderer.

Signature:

interface IPixel {
  r: number;
  g: number;
  b: number;
}
function renderPixels(): IPixel[]

Arguments: none.

Returns: An array of IPixels representing the color set in 8-bit RGB format.

resetRendererClock()

This method resets the renderer clock to 0.

Signature:

function resetRendererClock(): void

Arguments: none.

Returns: none.

getRendererClock()

Gets the current renderer clock, in milliseconds. This number is not relative to anything, and cannot be used to, e.g., get the wall time.

Signature:

function getRendererClock(): number

Arguments: none.

Returns: The renderer clock as a number.

Background

Note: you do not need to know this information to use this library at all. Some might find it interesting though.

RVL Node uses a rendering engine based on sin waves. RVL Node layers four waves on top of each other to create interesting and aesthetically pleasing LED animations. Think of this like CSS layers. They can include transparency to create a layering effect.

All waves are defined in the HSV color space that has been mapped to 8-bit integers. A hue of 180 degrees is represented by the value 128, a saturation of 25% is represented by the value 64, and so on and so forth.

A wave is defined using the following mathematical formula:

ledChannelValue(t, x) = a * sin(w_t * t + w_x * x + phi) + b

This function takes 5 variables from the user (a, w_x, w_t, phi, b), and 2 from the engine (x, t). This allows someone to create a wave that can vary over time, over the length of the LED strip, can be constant, or any of the above. Each channel (hue, saturation, value, and alpha) have their own wave assigned to them. 4 channels per layer, times 4 layers, means 80 coefficients total!

License

Copyright (c) Bryan Hughes bryan@nebri.us

This file is part of Raver Lights Node Animations.

Raver Lights Node Animations is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Raver Lights Node Animations is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Raver Lights Node Animations. If not, see http://www.gnu.org/licenses/.