Skip to content

Latest commit

 

History

History
177 lines (163 loc) · 6.19 KB

light_output.md

File metadata and controls

177 lines (163 loc) · 6.19 KB
Raw

Outputting to lights from Radiance

Radiance provides a simple way to output to light displays. If you implement this protocol on your device or middleware, then all you have to do is instantiate a LightOutputNode and point it to your device. This document describes the communication protocol between your device and Radiance.

Example device

The file output_example.py implements a simple device. You should use it as a reference for implementing your own devices.

To try it out, run it in the background. Then, open Radiance and create a new LightOutputNode pointing at localhost. Add a full-screen pattern such as purple before the LightOutputNode to fill the display with color. You should see a circle of lights that correspond to the edges of the frame.

If you restart the server and want to reconnect, simply select the LightOutputNode and hit R.

Nuts and bolts

  • Your device should bind a TCP port. Radiance will connect.
  • Radiance defaults to port 11647 if no port is specified.
  • All messages are asynchronous and may be sent at any time.
  • Unknown messages should be ignored.
  • All values are little-endian unless otherwise noted.
  • If an unrecoverable error occurs, the connection should be terminated.
  • No state is stored between connections, so you will have to re-issue setup messages after a disconnect.

Message format

Length (4 bytes) Command (1 byte) Data (length - 1 bytes)

Messages

Important note: Only commands 0-5 are implemented right now. Commands 6-9 will be implemented in the future.

byte Command Sender Data Description Default if not sent
0 Description Device JSON Device returns a high level description of itself in JSON format. See below See below
1 Get frame Device uint32 Ask Radiance for a frame. Data is a uint32 that sets the frame period in milliseconds. Request 0 ms for a single frame or to stop a previous request. No frames will be sent
2 Frame Radiance RGBA data (32 bits total) Radiance returns a pixel color in RGBA format for every location requested. N/A
3 Lookup coordinates 2D Device Array of {float u, float v} A list of pixel coordinates in uv space to lookup and return in "frame" messages. Must be sent before "get frame" No pixels will be returned in a frame unless a "lookup coordinates 2D" or "lookup coordinates 3D" command is sent.
4 Physical coordinates 2D Device Array of {float u, float v} A list of physical coordinates (in UV space.) Used purely for visualization in radiance. Radiance will visualize pixel locations using the lookup coordinates.
5 Geometry 2D Device PNG image data A PNG image that will be used as a background for visualization in radiance. Radiance will visualize pixel locations against a transparent background.
6 Lookup coordinates 3D Device Array of {float t, float u, float v} A list of pixel coordinates in tuv space to lookup and return in “frame” messages. Must be sent before “get frame” No pixels will be returned in a frame unless a “lookup coordinates 2D” or “lookup coordinates 3D” command is sent.
7 Physical coordinates 3D Device Array of {float x, float y, float z} A list of physical coordinates (in the STL’s space.) Used purely for visualization in radiance. If not sent, radiance will visualize pixel locations using the 3D lookup coordinates. Radiance will visualize pixel locations using the lookup coordinates.
8 Geometry 3D Device STL data A STL file that will be used as a background for visualization in radiance. Radiance will visualize pixel locations against a transparent background.
9 tuv map Device GLSL shader program A file containing one or more shader programs that convert tuv coordinates to uv coordinates for sampling. Radiance will use a set of presets.

Description keys

Key name Value Description Default if not set Notes
name string What to call this device unnamed
size [width, height] or single number for width & height How big the canvas should be on which the points are sampled 300x300 all UV values are [0, 1] despite aspect ratio

Typical conversation

A minimal example:

  • Radiance: connects to your device on port 11647
  • Device: sends lookup coordinates 2D command with 5 pixel coordinates in UV space
  • Device: sends get frame command with 0 ms period
  • Radiance: sends frame command with 5 pixel colors
  • Device: sends get frame command with 0 ms period
  • Radiance: sends frame command with 5 pixel colors
  • etc.

A more fully featured example:

  • Radiance: connects to your device on port 11647
  • Device: sends lookup coordinates 2D command with pixel coordinates in UV space indicating how they should be sampled
  • Device: sends physical coordinates 2D command with pixel coordinates in UV space indicating how they should be visualized in Radiance
  • Device: sends geometry 2D command with a PNG image to serve as a background in Radiance
  • Device: sends get frame command with 10 ms period
  • Radiance: sends frame command with pixel colors
  • 10 ms later, Radiance: sends frame command with pixel colors
  • 10 ms later, Radiance: sends frame command with pixel colors
  • etc.

Note that you may update the lookup coordinates, the physical coordinates, and the background image at any time. This is useful for outputting to interactive displays.