Projects and settings.
====

A Project stores all the information about a BiblioPixel project in a
text file in [JSON](http://json.org) format. This is used to create a
library of BiblioPixel projects to access at will.

Example of a project file.
----

    {
        "animation": "bibliopixel.animation.tests.StripChannelTest",
        "dimensions": 120,
        "run": {
            "max_steps": 5
        }
    }

Details
----

A project is a JSON object with many named sections, most of which you won't have to fill in until you need to do something fancy.

  * `dimensions`: the layout of your LEDs in 1, 2 or 3 dimensions 
  * `driver`: identifies the hardware driving the LED and its characteristics
  * `layout`: represents the geometric layout of the LEDs in one or more drivers
  * `animation`: the function that animates the LEDs over time
  * `run`: a collection time settings for the animation
  * `path`: a list of directories to add to the PYTHONPATH
  * `numbers`: whether and how to use fast numpy arithmetic
  * `aliases`: a dictionary of aliases, shorthands to avoid repetitive typing

On this page, we're only going to look at four sections: `dimensions`; and three JSON objects,
`driver`, `layout`, `animation`. The remaining sections are described in [[Project-Sections]].

---

The `driver`, `layout` and `animation` sections describe how to create the
BiblioPixel `Driver`, `Layout` or `Animation` object for your project.

Each of these three sections is either a dictionary, or a string.

If the section is a dictionary, it can have the special `typename` entry: the Python name of the actual type
of object that's being constructed.  The remaining entries, if any, correspond to the arguments to the constructor for that type.

If the section is only a string, then that string is used as the `typename` in constructing a value.

The `driver` and `layout` sections are optional if you specify the `dimensions` section in the project.

---

The `run` section's entries are used to call the `run()` method on the
`Animation`.

So the example above corresponds to the following old-style code:

    driver = bibliopixel.drivers.SimPixel.SimPixel(num=12)
    led = bibliopixel.layout.Strip(driver)
    animation = bibliopixel.animation.tests.StripChannelTest(led)
    led.run(max_steps=5)

NEXT: [[Project Sections]]

see also: [[MultipleDriverProjects]]