Sequence Definitions

Introduction

This page defines the 'sequence' JSON file format. This file is responsible for defining 'universes' of pixels representing logical portions of the model and sequences of animations that can be applied to these universes. The actual animations are defined in separate files, described elsewhere.

Entities Involved

• universes: A universe is a logical portion of the model to which a sequence can be applied. This file defines a mapping from the logical view to physical pixels.
• sequences: A sequence is a series of animations that can be applied to a universe. A sequence would typically be played in response to a triggering event. The sequence definition references a set of animations and provides metadata on how to orchestrate those animations.
• animations: An animation is a sequence of frames to be played in succession. A frame rate can be specified. Each frame contains RGB pixel color values for each pixel within the universe being animated.

File Format

    {
        // Define 'universes' as mappings from logical parts of the model to sets of phyiscal pixels
        // A sequence is applied to a universe; i.e., a sequence must update the entirety of a universe
        "universes": {
            // Each universe is identified by a handle, which is a unique identifier for the universe
            // Here's a definition of a universe named 'reso1'
            "reso1": {
                // First off, give it a meaningful description to assist the reader...
                "description": "Resonator #1",
                
                // Explicitly state the size of the universe. This is redundant information in that
                // it can be derived from the mappings below, but it's useful to have it explicitly
                // stated, since universe size should match sequence size.
                "size": 76,

                // Then, a mapping from logical view to physical pixels
                // The logical view of the universe is a linear array of pixels, [0..n). This is mapped
                // a set of physical pixels by providing an array of physical pixel ranges. Each range
                // represents a number of pixels on a particular strand
                // The strand is identified by a controller board number and a strand number within
                // the controller board.
                // Within the strand, 0-based start and end indices are given
                "mapping": [
                    // Here's 64 pixels on strand 3 of board 0:
                    {
                        "board": 0,
                        "strand": 3,
                        "start": 0,
                        "end": 63
                    }
                    // Here's 12 pixels in the middle of strand 5 on board 1:
                    {
                        "board": 1,
                        "strand": 5,
                        "start": 20,
                        "end": 31
                    }
                ]
                // These two mappings address 64 + 12 = 76 pixels, meaning that the logical universe
                // size is 76, indexed 0..75. Logical index of 3 means 'board 0, strand 3, pixel 3',
                // while logical index 70 means 'board 1, strand 5, pixel 26'.
            }
            // Further universes would be defined here in the same fashion
        },

        // Define a set of named sequences, each consisting of a series of animations and metadata
        // indicating how the animations should be orchestrated.
        "sequences": {
            // Each sequence is given a name by which it can be addressed. Intended to be meaningful
            // to external controlling software (i.e., controlling software would be configured to
            // perform sequence 'reso_deployed_L6' when a level 6 resonator is deployed). Controlling
            // software would also determine which universe the sequence should be played on (e.g.,
            // reso1 if resonator slot #1 is deployed).
            "reso_deployed_L6": {
                // A human-meaningful description:
                "description": "Transition to level 6 resonator deployed/upgraded",

                // Defines the number of pixels addressed by each animation in the sequence, and
                // should match the size of universes to which the sequence can be applied.
                "size": 76,

                // Then, an array of animations to play in this sequence
                "animations": [
                    // Each entry references an animation name. This should correspond to an external
                    // file containing the definition of the animation, by file name.
                    {
                        // Implies there should be an animation definition in file 'fade_in_out_reso6.json'
                        "name": "fade_in_out_reso6",
                        // How to orchestrate this animation?
                        // Possible options:
                        // ONCE - Play animation once and proceed to next
                        // REPEAT - Repeat the animation. If 'times' attribute is present, repeat that many
                        //          times, else repeat indefinitely
                        "action": "REPEAT",
                        // We want to repeat this animation thrice:
                        "times": 3
                    },
                    {
                        // Then play some other animation once...
                        "name": "reso_off_1s",
                        "action": "ONCE"
                    },
                    {
                        // Then go to a final 'steady state' animation that's repeated forever
                        "name": "pulse_reso6",
                        "action": "REPEAT"
                    }
                ],

                // Then, optionally, provide a sequence-level action indicating how to orchestrate the
                // full set of animations. In this case, the final animation repeats forever so it is
                // irrelevant, but if the animation sequence completed, what to do next?
                // Possible options:
                // ONCE - Play the sequence of animations once and then stop (turning off all pixels
                //        in the universe)
                // REPEAT - Repeat the sequence of animations. If 'times' attribute is present, repeat
                //          that many times, else repeat indefinitely
                "action": "ONCE"
            }
        }
    }