Pixel Animator is a toy for making small generative art with JavaScript

Quick Start

If you want to dive in, make a copy of the starter template on CodePen or Glitch. For best results, read the tutorial below.

Tutorial

1. Create an HTML Document

To start, you will need an HTML document like the one below. You can copy this exact code into your editor, save it, then view it in a browser to get a working example. 

<html>
  <head>
    <!-- Load the Pixel Animator library -->
    <script src="https://unpkg.com/pixel-animator@1/main.js"></script>
  </head>
  <body>
    <!-- Add an element to host your animation -->
    <div id="my-animation"></div>
    <script>
      // Connect it all together to display a starter animation
      PixelAnimator({}, document.getElementById("my-animation"));
    </script>
  </body>
</html>

We passed two arguments to the PixelAnimator function:

  1. The empty object {} which gives us a boring checkerboard animation
  2. An HTML element for the animation to live inside

The rest of this tutorial is about that first argument, the empty object, and how we can add properties that will give us a more interesting animation.

The only required property is a function named colorize. This function takes a pixel's position in space time as input and returns a color as output. 

{
  colorize: function(pixel) {
    // Compute a color…
  }
}

2. Write a colorize function

To make an animation, you need to write a special kind of function named colorize, similar in principle to a colorize. Your colorize function's job is to convert a pixel's position in space and time into a color.

The following steps develop a simple example of such a function in five parts, each of which can be viewed and edited at glitch.com/~pixel-animator-tutorial.

2.1. A purple square

Here each pixel says "always color me purple".

function colorize() {
  return "purple";
}

PixelAnimator({ colorize }, document.getElementById("my-animation"));

Note that we added a colorize property to the formerly empty animation object {} in our call to PixelAnimator. Since the colorize function returns the same purple" value every time it's called (for every pixel in every frame) all pixels will be colored purple.

Try this code

2.2. Lime row on a purple square

Here each pixel says If I'm in the third row, color me lime. If not, color me purple. 

function colorize(pixel) {
  if (pixel.row == 2) {
    return "lime";
  } else {
    return "purple";
  }
}
We can use the pixel argument to ask a question about which row the current pixel belongs to. The expression pixel.row == 2 in the if statement translates to the question "am I in the third row?". The third row belongs to the number 2 because we start counting rows at 0.

Try this code

2.3. Lime dot on a purple square

Here each pixel says If I'm in the third row and the sixth column, color me lime. If not, color me purple. 

function colorize(pixel) {
  if (pixel.row == 2 && pixel.column == 5) {
    return "lime";
  } else {
    return "purple";
  }
}

This step adds a second part to the question, asking which column the pixel is in. Since there's only one pixel that can be in both the second row and the sixth column, we see a single lime pixel. The sixth column belongs to the number 5 because we start counting columns at 0.

Try this code

2.4. Blinking lime dot on a purple square

Here each pixel says If I'm in the sixth column, third row, and my frame has an even number, color me lime. If not, color me purple. 

function colorize({ column, row, frame }) {
  if (row == 2 && column == 5 && frame % 2 == 0) {
    return "lime";
  } else {
    return "purple";
  }
}

This step adds a third part to the question asking about which frame the current pixel is in. The expression frame % 2 == 0 in theif if statement translates to the question Is my frame number even? . The frame number increases as time passes, counting up one by one, alternating between even and odd numbers. When the animation reaches an even-numbered frame, you'll see a lime pixel in the position given by row == 2 && column == 5. When it reaches an odd-numbered frame, you won't see a lime pixel at all. The ever-increasing frame number causes the lime pixel to blink on and off.

We also destructured the pixel argument into { column, row, frame } to keep things tidy.

Try this code

2.5. Lime dot moving across a purple square

Here each pixel says to itself, If both my column and row numbers are equal to my frame number, I should be lime. If not, make me purple. This logic causes the lime pixel to trace a diagonal line as the frame number increases over time. 

function colorize({ column, row, frame }) {
  if (column == frame && row == frame) {
    return "lime";
  } else {
    return "purple";
  }
}

Try this code