How does that work?

If you have no clue about how Pixelflut works, here’s how to get started.

Connecting to the server

Your event’s server will provide information on which IP address(es) and port(s) to connect to. The most common TCP ports are 1337 (leet) and 1234. The address may even be a pixelflut.org subdomain! If you are unsure, ask your server operator.

Connecting via Wi-Fi is prohibited. Do not destroy the network for everyone else!

Statistics

Many servers provide statistics, but this very much depends on your operator. Some have a Grafana dashboard, others support the STATS Pixelflut command. Ask them if you’re unsure!

Commands

Once you are connected to the Pixelflut server via TCP (or otherwise), you can send the following commands. They always need to end with a newline. You can use netcat for manual testing.

# Set pixel at x, y position to color rrggbb (hex code)
PX <x> <y> <rrggbb>
# Some servers also support alpha
PX <x> <y> <rrggbbaa>
# Ask server for current color at x, y (server will reply with hex code)
PX <x> <y>
# Ask server for some information on supported commands and other policies
HELP
# Ask server for canvas size, response will have the format "<width> <height>"
SIZE
# Offset all future pixels from this connection
# Supported by some, but not all servers, try it out!
OFFSET <x> <y>

Example Python client

This example client connects via TCP and sends a single image to the server. You need to install the Pillow library for this to work.

 1#!/usr/bin/python
 2
 3import sys
 4import socket
 5from PIL import Image
 6
 7sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
 8sock.connect((sys.argv[1], int(sys.argv[2])))
 9
10def pixel(x, y, r, g, b, a=255):
11    if a == 255:
12        sock.send(b'PX %d %d %02x%02x%02x\n' % (x, y, r, g, b))
13    else:
14        sock.send(b'PX %d %d %02x%02x%02x%02x\n' % (x, y, r, g, b, a))
15
16im = Image.open(sys.argv[3]).convert('RGBA')
17_, _, w, h = im.getbbox()
18for x in range(w):
19    for y in range(h):
20        r, g, b, a = im.getpixel((x, y))
21        pixel(x, y, r, g, b, a)

Call the script like this:

python client.py event.pixelflut.org 1234 picture.png

Getting more advanced

Once you have the basics figured out, here are some things to try:

How fast can you send pixels? The example client probably won’t max out your network connection. Try to use multithreading or a faster programming language. Once you have maxed out the connection, you can start looking into optimizing your “pixel per byte” ratio, so that you can send more pixels using the same amount of data.
How can you make your pixels more visible? Which pixels to send when, and in what order, actually matters a lot when trying to ensure that your image is always prominently visible against the “attacks” of your competitors. You don’t necessarily have to choose a quiet corner of the canvas!
What else can you send? Images are pretty simple, and shell one-liners with a single color even more so. But what about on-the-fly graphics, text, animations, videos? How about streaming your desktop, a camera feed, or a game? You can also read back the canvas data with the pixel-read command (see above) and incorporate it into your output. The possibilities are endless!

We keep a list of Pixelflut clients here. If you are satisfied with yours, feel free to add it to the repository!