Skip to content

Reference

Jump to bottom
Finn Andersen edited this page Nov 27, 2023 · 14 revisions

Overview

This framework consists of a collection of components which can be combined to define flexible pattern logic for your LED project. The main components are:

  • Strip Segments - Used to define a range of LEDS on a strip as a segment which a LinearPattern can be applied to. SpatialStripSegment and adds information about where that segment is positioned in 3D space (Used with SpatialPattern).
  • Patterns - Defines logic of an animation pattern, in either one dimension (LinearPattern) or 3 dimensions (SpatialPattern).
  • Pattern Mappers - Maps a Pattern to Strip Segments. There are different types for handling mapping of the different Pattern types to the different Strip Segment types, as well as combining multiple mappings at once.
  • Controller - Manages a collection of PatternMappings and handles animation execution and updating LEDs.

Component Diagram

This diagram shows a hierarchical overview of LEDuino's components which will be composed in a declarative way to define the configuration of your project. LEDuino_light

Strip Segments

StripSegment instances define a range of consecutive LEDS on an LED strip, and handle mapping of the index of an LED on a segment to its absolute ID on the LED strip. Each instance needs to be initialized with parameters:

  • start_offset - Segment start position on LED strip (0-indexed).
  • segment_len - Number of LEDs in segment
  • strip_len - Total number of LEDs on strip
  • reverse - Whether or not direction of segment is reversed (segment indexes increase with decreasing strip index) (default=false).

Note: The total strip length is provided to each StripSegment to allow wrap-around of a segment from the end of the strip back to the start if desired.

The subtract operator can be used to obtain a reversed version of a StripSegment (start_offset is set to end position of segment, and reverse valule is inverted).

StripSegments used in the same Pattern Mapping ideally should not overlap (each LED on the strip should only be involved in one of the StripSegments used in each Pattern Mapping).

Spatial Strip Segment

SpatialStripSegment is used to provide 3D spatial positioning information to a StripSegment, for use with SpatialPatternMapping or LinearToSpatialPatternMapping. It can initialised with a StripSegment and either:

  • An array of Points (x,y,z coordinates) which define the positions of each LED in a coordinate system
  • start_pos and end_pos Points which will be used to automatically calculate the positions of all the LEDs in the segment (assuming the segment is straight and LEDs are evenly spaced)

SpatialStripSegment has a getSpatialPosition() method to return the Point position of a segment LED.

Patterns

Patterns are implemented as classes which can be initialized with custom parameters to alter their behaviour. Their logic is implemented in the frameAction() method which is called at the start of every new frame, and should update the state of the pattern. How this state is stored depends on implementation of the pattern.

Patterns can be defined without any knowledge of a project's LED strip configuration (how many segments and how many LEDs per segment). They operate in their own virtual pattern space with a configurable resolution, which for a LinearPattern is the length of the 1D axis, and for a SpatialPattern it is a maximum distance in each coordinate direction (forming a bounding box around the origin). This virtual space is then dynamically mapped to the actual project's LED strip configuration by an appropriate PatternMapper.

Linear Patterns

Linear patterns define their logic in terms of a 1-dimensional sequence of pixels. A pixel array is provided to the pattern's frameAction() method, which needs to populate it with the desired output state for that frame. A linear pattern has a concept of a 'resolution', which is the length of the pixel array, and does not need to be the same as the number of physical LEDS on each StripSegment it will be displayed on. The pixel array contains 'virtual pixels' which will then be mapped to the actual strip segment LEDs using interpolation. Having the pattern resolution several times higher than the number of LEDS on a strip segment allows for smooth appearance for motion-based patterns (due to supersampling). However, some patterns will not benefit from higher resolution and so the segment length can be used for a 1-1 mapping from pixel to LED. See Mapping Concepts for more details.

Spatial Patterns

SpatialPatterns define logic in terms of position in a 2D or 3D coordinate system. They also operate in their own virtual pattern space with a resolution/dimensions that may be different from the actual project coordinate system.

Create Your Own Pattern

There is a collection of example patterns included with the library, but you will probably want to create your own.

  1. Define a new class that inherits from the appropriate pattern base class (LinearPattern or SpatialPattern)
  2. Add any class member variables you wish to use to store the pattern state or configuration parameters (which may be configurable in the constructor)
  3. Define the frameAction() method to specify how the pattern's state should be updated with each frame. For a LinearPattern, a pixel_data array is provided to the method and needs to be modified.
  4. SpatialPatterns must also implement getPixelValue() to get the colour value for a pixel at a particular spatial location (will be called for each LED after frameAction() has been called)

Feel free to raise a PR to add your custom patterns into the library if you like!

Colour Pickers

Provides an interface for patterns to choose colours to use, with a getColor(hue, brightness, saturation) method. There are 3 sublcasses which enable using the different types of FastLED color palettes to choose color:

  • RGBPalettePicker - Allows using a CRGBPalette16 FastLED palette (stored in RAM)
  • ProgmemRGBPalettePicker - Allows using a TProgmemPalette16 FastLED palette (stored in Flash)
  • GradientPalettePicker - Allows using a FastLED gradient palette created using DEFINE_GRADIENT_PALETTE macro.

It is possible to create your own custom ColorPicker subclasses that can choose color using any kind of logic you like (for example in response to music/audio).

Pattern Mappers

Pattern Mappers handle mapping a virtual pattern space to actual LED strip segments. See Mapping Concepts for more details.

Linear Pattern Mapper

A LinearPatternMapper is used to map a LinearPattern to a number of StripSegments (which can be different lengths). It is initialised with:

  • pattern - A LinearPattern instance
  • pixel_data - Pixel array used by pattern to store its output pixel data for each frame
  • num_pixels - Length of pixel array (pattern resolution)
  • strip_segments[] - Array of StripSegments to map pattern to
  • num_segments - Length of StripSegment array

For very frame, the mapper calls the pattern's frameAction() and provides the pixel_data array which will be populated with CRGB values. Then, the mapper applies the pixel_data array to all of the configured StripSegments, using interpolation if necessary.

The same pixel_data array can be re-used across multiple LinearPatternMappers, except when they are used in a Multiple Pattern Mapping configuration with a pattern that depends on the previous frame's pixel_data (since it will be overwritten by another pattern running at the same time). In this case you will need to declare and provide a new dedicated pixel array.

Spatial Pattern Mapper

Handles the mapping of a SpatialPattern to set of segments with spatial positioning. The SpatialPattern has its own coordinate system (bounds of +/- resolution on each axis), and there is also the physical project coordinate system (the spatial positions of LEDS as defined in SpatialStripSegments). The 'scale' and 'offset' vectors are used to map the pattern coordinate system to project space. If not specified, scale is calculated automatically based on bounds of SpatialStripSegment, and offset is equal to project centroid

Linear to Spatial Pattern Mapper

Allows for mapping a linear pattern to a vector (linear path/direction) in 3D space. Requires initialisation parameters:

  • pattern - A reference to LinearPattern instance
  • pixel_data - Pixel array used by pattern to store its output pixel data for each frame
  • num_pixels - Length of pixel array (pattern resolution)
  • pattern_vector - A Point instance which represents the direction vector to project the linear pattern on
  • spatial_segments[] - Array of SpatialStripSegments to map pattern to
  • num_segments - Length of SpatialStripSegment array
  • offset - Offset of pattern vector start position (default 0)
  • scale - Scaling factor to apply to linear pattern vector length (default 1)

The pattern pixel applied to each LED is determined by the LED's distance from the perpendicular plane at the start of the vector path. By default, the linear pattern path will start on the edge of the projects bounds and move through it in the direction of the vector and end at the bounds on the other side.

The start position and length of the path can be adjusted using the offset and scale parameters. Since the pattern pixel for an LED is determine by its distance from the start position, be default the effect will be mirrored about the start of the vector path. If start position is outside the bounds of the LEDs, then this will not make any difference. Otherwise, this can be disabled by setting mirrored=false (with an extra performance cost).

Multiple Pattern Mapping

Allows for multiple pattern mappings to be applied at the same time. Can have multiple LinearPatternMapper or SpatialPatternMappings running concurrently on different parts of the same strip of LEDS.

Mapping Runner

Used to wrap and manage the duration (default 10 seconds) and frame rate (default 20ms) of a PatternMapper configuration. The global constants LEDUINO_DEFAULT_DURATION and LEDUINO_DEFAULT_FRAME_DELAY can be defined before importing LEDuino to override these defaults. Can also be assigned an optional name for identification.

LEDuino Controller

Manages a collection of Mapping configurations (MappingRunners). Handles frame updates, updating the LED state and cycling through mappings based on their duration. Can also manually switch to a desired pattern mapping by calling the setPatternMapping() method.

Clone this wiki locally