Getting Started

If you're looking to write Python for Blinking Lights, you're in the right place!

Important

If you're looking to write TypeScript or JavaScript, you need the TS version of this library. We don't have libraries for other programming languages, but if you know how to work with protobuf, we have a protocol file.

To start, we're going to focus on working with images. If you want to work directly with the LEDs, see the Advanced guide.

Quick Start

You're going to need to download the library. We recommend doing this in a Python virtual environment (venv).

*nix (Linux, *BSD, macOS, WSL, etc):

python3 -m venv venv
source venv/bin/activate
pip3 install libacmchristmas

Windows:

python3 -m venv venv 
.\venv\Scripts\activate
pip3 install libacmchristmas

Basics

First, you're going to need to get your API URL. This is provided by event organizers, but you can test on https://blinktest.acmcsuf.com. For more information on testing, see the Testing section of the JS guide.

We use asyncio for operations, which means all your code needs to be wrapped in an async main function. Here's a template you can use to get started:

import asyncio
import libacmchristmas as c

async def main():
    tree = c.tree.TreeController(YOUR_URL)
    await tree.connect()
    # your tree control code here...
    await tree.close()

loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
loop.run_until_complete(main())

You're going to want to put your code in where # your tree control code here... is, between await tree.connect() and await tree.close().

We use the Pillow library for first-class image support; you can read the Pillow docs for examples of all the cool things you can create with Pillow.

The normal way to import an image file using Pillow (similar to the JS library) is with draw():

from PIL import Image
img = Image.load("/path/to/file")
await tree.draw(img)

However, if you're not doing any manipulation of the image, you can also instead use draw_from_file():

await tree.draw_from_file("/path/to/file")

Intermediate

Along with composing images in Pillow, you can also use NumPy arrays. This is a bit more involved; using Pillow automatically handles resizing the image and formatting it for you, which is not the case with NumPy.

If you want to use NumPy, you're going to want the size of your array to be 4 times the total number of grid squares on the tree:

import numpy as np
arr = np.zeroes(4*tree.ix*tree.iy, dtype=np.uint8)

Each 4 elements in the array is one pixel, ordered RGBa: red, green, blue, and reserved. The fourth element in each array doesn't matter; the first through third should be values from 0 to 255 representing the RGB color values of that pixel. Once you've set the array however you want (NumPy transformation functions can help here), update the tree:

await tree.update_image(arr)

If you want to do more complex things with the LEDs, move onto the Advanced guide!