Skip to content

Coding the Tree pt. 1 (simple)

Jump to bottom
Diamond edited this page Dec 1, 2023 · 7 revisions

This is the page to read if you're here to participate in the Blinking Lights.

Note

In order to keep things simple, this page will only be covering how to interact with the tree using images. For how to interact with the LEDs themselves, see Coding the Tree pt. 2 (advanced).

Quick Start

The recommended way to interact with christmasd for beginners is to use either the JavaScript client library or the Python client library supplied prior to the event:

You may see examples of how they're used here:

Important

You must follow the instructions listed in each repository's README page!

Basics

Note

This section assumes you're writing JavaScript. The Python library will look somewhat similar. Refer to the christmas-py-example repository for more information.

First, a program must establish a connection to the Websocket server. The URL for this server will begin during the event. We'll assume it's in a url variable:

const url = "<url goes here...>";

christmas-js-example exposes an LEDCanvas type that contains these methods in the order of operation:

  1. connect() starts the connection to the server.
  2. canvasInfo() gets the dimensions of the drawing canvas from the server. Images sent to the server must be in this size (but not always, see below!)
  3. draw() sends the given image to the server to be drawn.

A bare minimum program may look like so:

import { LEDCanvas } from "christmas-client-js";

const canvas = new LEDCanvas("ws://...");
await canvas.connect();
const canvasInfo = await canvas.canvasInfo();
canvas.draw(canvasInfo, image);

Loading an Image

christmas-js-example provides first-class support for the image.js library. If canvas.draw is given an image created using this library, it will automatically rescale the image to the needed size, so if you're using this library, you won't need to worry about sizing the images. Of course, the library may not rescale the image properly, in which you'll have to do the rescaling yourself.

As an example, loading an image using image.js and drawing it is very straightforward:

import * as imagejs from "image-js";

const image = await imagejs.Image.load("path-to-image.jpg");
canvas.draw(canvasInfo, image);

Note

We need to give draw() the canvasInfo that we fetched above. This is to let draw() know how to rescale the image. You must always pass it this parameter.

Tip

Have a GIF? You can use ezgif.com/split to split your GIFs into individual frames and load them all in a for loop. You may also choose to use a GIF library such as gif-frames to extract frames out of the GIF and display them without relying on other tools.

For example:

const canvas = new LEDCanvas("ws://...");
await canvas.connect();

const canvasInfo = await canvas.canvasInfo();

const images = [];
for (let i = 0; i < 10; i++) {
  const frame = await imagejs.Image.load(`frame-${i}`);
  images.push(frame);
}

let frame = 0;
setInterval(() => {
  canvas.draw(canvasInfo, frame[i]);
  frame++;
  if (frame == images.length) {
    frame = 0;
  }
}, 100) // 100ms delay every frame => 10 fps
Clone this wiki locally