Documentation

• 1: Overview
• 2: Tutorial
• 3: What's New in Punctual 0.5
• 4: Concepts
• 5: Getting Started
• 6: Coordinates
• 7: Colors
• 8: Oscillators
• 9: Combining graphs
• 10: Mathematical functions
• 11: Scaling values
• 12: Shapes and textures
• 13: Combining channels
• 14: Geometric transformations
• 15: Cross-fading
• 16: Audio reactive visuals
• 17: Playing with feedback

1 - Overview

About Punctual

From the official Punctual repository:

Punctual is a language for live coding audio and visuals. It allows you to build and change networks of signal processors (oscillators, filters, etc) on the fly. When definitions are changed, when and how they change can be explicitly indicated.

Punctual has huge visual capacities. Its strong points are:

• Runs in a browser, no installation needed.
• Fully integrated into the Estuary collaborative live-coding environment.
• Compact syntax allows fast pattern creation and further modification.
• Direct access to pixel coordinates allows the creation of patterns using any mathematical formula.
• Low-level geometry changing functions lead to a great flexibility.
• Flexible graphs arithmetic for even more creative possibilities.
• Simple but effective modulation functions. Modulate everything.
• Audio reactive visuals using frequency analysis, FFT (Fast Fourier Transform) and internal tempo.
• Feedback allows building complex patterns using the last frame as source.
• Capacity to use remote images and videos.
• Can use webcam as source.
• Easy to get help via the Estuary discord server.

Compared to Hydra (arguably the best known live-coding language for visuals), it has the following limitations:

• Lack of high-level effects (saturation, pixelation, etc.)
• Some mathematical ability is needed to build complex patterns using the low-level functions Punctual provides.
• Not easy to extend with your own functions.
• Not very well documented (until now, I hope).
• Not many people using it.

About Estuary

From the official Estuary repository:

Estuary is a platform for collaboration and learning through live coding. It enables you to create sound, music, and visuals in a web browser. Key features include: - built-in tutorials and reference materials - a growing collection of different interfaces and live coding languages - support for networked ensembles (whether in the same room or distributed around the world) - text localization to an expanding set of natural languages - visual customization via themes (described by CSS)

This guide is not about Estuary, but Estuary is important because it’s one of the easiest and most feature rich ways to use Punctual. As the author of Punctual is also the main author of Estuary, it has complete support and it’s always up-to-date.

About this guide

I decided to write this guide after a year of participating on a weekly jam at the Estuary platform, and using Punctual in these jams and also several times in live performances.

This guide deals only with the visuals part of Punctual and tries to be deep, documenting and exemplifying each of the functions in Punctual. For a gentle introduction to Punctual, check the Tutorial section or the Decoded workshop.

Punctual is a somewhat low-level live-coding language, and has a very brief official documentation. While learning it, I always missed some more explanations and examples on how to use the distinct features the language provides. With this, I’m trying to write the documentation I had liked to find when I was learning to use Punctual.

Many of the examples presented here are the result of conversations in the Discord’s Estuary server with David Ogborn (Punctual’s author, who is extremely helpful and always answers my questions), and Bernard Gray (who introduced me to the weekly jams and has been my partner in this journey).

I’m an IT teacher with more than 20 years of experience, and have written a lot of documentation and tutorials for my students as well as many contributions in official product documentations, for example TidalCycles. Most of these are written in Catalan, my mother-tongue.

Disclaimer

Punctual is a personal art project by David Ogborn (@dktr0). He likes to keep absolute freedom on how or when Punctual evolve, and that’s the main reason why he don’t usually accept contributions into the source code or the official documentation.

This is an unofficial document and can be made obsolete by changes on Punctual at any time, even though I’ll try to keep it up to date. This is specially true for any officially undocumented feature that may appear here.

The only official documentation is maintained by David himself on the Punctual git repository. Make sure to check the README.md and REFERENCE.md files for up-to-date, official information on the project.

This guide was last updated for Punctual version 0.4.9.1.

License and contributions

This guide is licensed under the terms of the Creative Commons Share Alike license.

Contributions that updates content or add interesting examples are very welcomed.

2 - Tutorial

This tutorial is designed as a smoother introduction to Punctual for beginners. Each section links to the corresponding sections in the guide.

Punctual is a language for live coding audio and visuals. It enables users to construct and modify networks of signal processors, such as oscillators and filters, on the fly.

Punctual is compatible with all major web browsers. Throughout this tutorial, we will use Punctual within Estuary, a collaborative live coding platform that supports various live-coding languages.

Setup

To follow along with the examples in this tutorial:

1. Open a new web browser tab and navigate to https://estuary.mcmaster.ca/. Select Solo Mode.

   

2. In the Terminal/Chat:, type !presetview twocolumns and press enter.

   

3. Use the dropdown in each cell to select the language for that cell. Choose Punctual for the left cell and MiniTidal for the right cell (which we will use in later examples).

   

4. If needed, click the ? marker and select Settings. Here, you can adjust settings like Resolution (I personally prefer QHD), Frames per Second (FPS), or Brightness to match your preferences. Click again on the ? to hide the Settings.

   

5. You can also change the Theme to Dark on the upper right dropdown list to increase the contrast between the code and the visuals.

   

6. Other elements in the Estuary interface can be hidden as well. Click on the Estuary title to hide the upper text, on the bottom left to hide the Terminal, and on the bottom right to hide the footer. Clicking these areas again will make these elements visible again.

   

Shapes

Let’s start by drawing some shapes:

circle [0,0] 0.25 >> add;

This code snippet draws a circle with its center at (0, 0) and a radius of 0.25. Notice how (0, 0) represents the center of the screen. You can change either coordinate to move the circle around:

circle [0.5, 0] 0.25 >> add;

circle [-0.5, 0] 0.25 >> add;

circle [0, 0.5] 0.25 >> add;

circle [0, -0.5] 0.25 >> add;

Note that moving more than 1 unit in any direction will position the center of the circle outside the screen.

For more information on, see the coordinate system and coordinates sections.

You can also change the radius to make the circle bigger or smaller:

circle [0.3, -0.5] 0.5 >> add;

circle [0.3, -0.5] 0.1 >> add;

Adding more coordinates in a single circle instruction allows you to draw multiple circles at different positions:

circle [0.5,-0.8,0.2,0.3] 0.25 >> add;

In this code, we have a circle centered at (0.5, -0.8) and another one at (0.2, 0.3). We’ll understand why they are of different colors shortly.

Feel free to experiment by adding as many coordinates to the set as you like. Each additional pair of coordinates will create another circle at the specified position.

More shapes

There are some more shapes that can be directly drawn with Punctual.

Drawing vertical and horizontal lines is quite straightforward:

vline 0.2 0.01 >> add;

This code draws a vertical line at position x=0.2 with a width of 0.01.

hline (-0.3) 0.01 >> add;

This code draws a horizontal line at position y=−0.3 with a width of 0.01.

The first number in each instruction represents the position along the respective axis, and the second number represents the width of the line.

As with circles, you can add more numbers to a list to create more lines with a single instruction:

vline [-0.3,0.2,0.6] 0.1 >> add;

Now, Let’s draw some rectangles:

rect [-0.1,0.3] [0.4,0.1] >> add;

Here, we draw a rectangle with its center at (-0.1, 0.3), a width of 0.4 and a height of 0.1.

rect [-0.5,0,0.5,0] 0.4 >> add;

For more information, see the Shapes and textures section.

The add output

We’ve been using add to draw our shapes. add allows to keep adding different shapes to the screen:

circle [0.3, -0.5] 0.1 >> add;
hline [0, 0.5, 0.8] 0.01 >> add;
rect [0.1,0.3,-0.5,-0.9] [0.3,0.2] >> add;

In this code, we draw a circle, three horizontal lines, and two rectangles, and they all stay visible on the screen simultaneously because of the add output. This feature allows us to create complex compositions by combining different shapes and patterns.

When drawing multiple shapes in a single instruction (like the horizontal lines or the rectangles above), each one gets a different color.

In Punctual, a signal can have many channels. In our last example, the circle has one channel, the hline has 3 channels, corresponding to the 3 lines, and the rect has 2 channels, corresponding to the 2 rectangles.

The add output also has channels. Specifically, it has 3 channels representing red, green, and blue components.

When sending a signal to the add output, each channel of the signal is matched with the corresponding channel of the output. So, for the hline instruction, the first line goes to the first channel (red), the second line to the second channel (green), and the third line to the third channel (blue).

When the number of channels of the signal and the output is not the same, the last channel of the signal is repeated to make them match. So, the first rectangle goes to red, and the second rectangle goes to green and blue, which results in cyan.

The circle has only one channel, so it is repeated for the red, green, and blue output channels, resulting in a white circle.

For more information, see the Output notations section.

Comments

Using comments in code is a great way to temporarily disable certain instructions without deleting them. In Punctual, lines starting with -- are treated as comments and are ignored during execution.

For example, consider the following code snippet:

circle 0 0.1 >> add;
-- hline 0.5 0.1 >> add;

In this code, only the circle instruction will be executed because the hline instruction is commented out.

For more information, see Getting Started section.

Variables

Using variables can help simplify code and make it more readable. The << operator is used to assign the result of an expression to a variable. Here’s an example:

c << circle 0 0.1;
c >> add;

This code is equivalent to:

circle 0 0.1 >> add;

Storing the circle expression in the c variable allows you to reuse it multiple times if needed. This not only reduces repetition but also makes the code more concise and easier to understand. Additionally, it can reduce the need for parentheses in complex expressions.

For more information, see the Bindings section.

Colors

As seen before, color is determined by the signal received by each channel in the add output, with the first channel being the red component, the second the green, and the third the blue.

We can create any color this way, just by multiplying an expression by the desired color:

c << circle 0 0.1;
c * [0.5, 0.2, 0.8] >> add;

Each color component can take a value from 0 to 1.

The mono function in Punctual is quite handy for converting a multi-channel signal into a single-channel one. This is particularly useful when you want to avoid coloring a set of shapes when sending them to add.

For instance, consider these examples:

l << vline [-0.3,0.2,0.6] 0.1;
l >> add;

In this case, each line in the vline command will have a different color assigned. However, by using mono, you can ensure they all are white:

l << vline [-0.3,0.2,0.6] 0.1;
mono l >> add;

Additionally, you can send a color directly to the output without using any shape:

[0.8, 0.4, 0] >> add;

0.5 >> add;

Since add adds colors, you can leverage this behavior to create dark shapes over a colored background:

c << circle 0 0.8;
[0.5,0,0] >> add;
c*(-1) >> add;

In the last example, the first add command tints the background with a red color, and the second one creates a dark circle by multiplying the circle shape c by -1.

For more information, see the Colors and Combining channels sections.

Parentheses and dollars

Let’s revisit the previous mono example:

l << vline [-0.3,0.2,0.6] 0.1;
mono l >> add;

Here, mono is applied to the whole content of l, the three lines. If we weren’t using a variable, we could write an equivalent expression like so:

mono (vline [-0.3,0.2,0.6] 0.1) >> add;

The parentheses are necessary, as otherwise Punctual wouldn’t know that [-0.3,0.2,0.6] and 0.1 are arguments for vline and not mono.

Another equivalent way to write this is by using a dollar sign instead of parentheses:

mono $ vline [-0.3,0.2,0.6] 0.1 >> add;

A dollar sign means that everything following it should be treated as a unit, in this case, as a single parameter for mono. Using $ is more concise, as it reduces the need for additional parentheses, especially in longer or more complex expressions.

For more information, see the Notes on Haskell section.

Correcting distortion with fit

When drawing shapes, you might have observed that our circles are not perfectly circular and our squares are not perfectly square. Punctual uses a coordinate system where the visible screen ranges from -1 to 1 on each axis. However, since our browser windows are usually not square, the fragments or points in the image are often wider than they are tall.

The fit function allows us to change the aspect ratio of our fragments. Specifically, fit 1 will force fragments to be completely square, making our shapes visually correct:

fit 1 $ circle 0 0.2 >> add;
fit 1 $ rect 0.5 0.2 >> add;

Note that when applying fit 1, we can’t guarantee anymore that our visible coordinates are from -1 to 1 on each axis:

fit 1 $ vline 1.5 0.01 >> add;

See the Coordinates section for more information on fit.

Fragment coordinates

So far, we have used fixed numbers for our expressions. There are some expressions that are fragment-dependent, meaning they have a different value for each point on the screen.

• fx is the horizontal coordinate of the fragment.
• fy is the vertical coordinate.
• fr is the radius, the distance from [0,0].

These functions have many useful applications, including the creation of color variations:

fx >> add;

[fr, 0, 0] >> add;

[fy, 1-fx, fr] >> add;

c << circle 0 1;
c * [0.3, 0, fr] >> add;

See the Fragments and Coordinates sections for more information on fragment coordinates.

Scaling values

Let’s revisit this gradient example:

fx >> add;

You’ll notice that the left half of the screen is completely black, and the white gradient affects only the right half. This is because fx takes values from -1 to 1, while color values range from 0 to 1.

To address this common situation, Punctual provides two functions to convert between the -1 to 1 range and the 0 to 1 range:

• unipolar rescales a number from [-1,1] to [0,1]
• bipolar rescales a number from [0,1] to [-1,1]:

unipolar fx >> add;

See the Scaling values section for more ways to rescale values.

Oscillators

Our patterns have been static so far. One straightforward way to animate them is by using oscillators.

Oscillators are functions that generate varying values over time. In Punctual, oscillators operate within a range from -1 to 1. When using an oscillator, you specify its frequency, which determines how many cycles it completes per second.

For instance, osc 1 creates an oscillator that oscillates from -1 to 1 and back to -1 once every second. Typically, we use low frequencies for our oscillators. For example, osc 0.1 takes 10 seconds to complete one full cycle.

We can use an oscillator at any place where a number is expected:

vline (osc 0.2) 0.02 >> add;

This code creates a vertical line that oscillates in position with a frequency of 0.2.

vline (osc [0.11,0.15,0.19]) 0.02 >> add;

Three vertical lines oscillate at frequencies of 0.11, 0.15, and 0.19, respectively.

circle 0 (unipolar $ osc 0.13) >> add;

The radius of the circle oscillates from 0 to 1 at a frequency of 0.13.

circle [0,0.3,0.3,-0.3,-0.3,-0.3] (unipolar $ osc 0.13) >> add;

Three circles with different positions have their radius oscillate from 0 to 1 at a frequency of 0.13.

[unipolar $ osc 0.13, 0, unipolar $ osc 0.15] >> add;

This code creates a varying color. As the frequencies of the two oscillators are different, this will produce a lot of different colors over time.

osc fr >> add;

The amount of white color applied to each fragment oscillates at a different frequency. This creates an interesting and evolving pattern.

hline (osc $ fx/10) 0.01 >> add;

Here, each point of a horizontal line moves up and down at a frequency that depends of its horizontal position. This creates a vertically symmetric pattern of moving little lines.

[0,0.3,0.1]*hline 0 (0.01*osc fr) >> add;

This code follows a similar idea, but now the width of the line at each point oscillates at a frequency that depends on its distance from the origin.

For more information and other types of oscillators, see the Oscillators section.

Transformations

There are four main transformations you can apply to any pattern in Punctual: move, spin, tile and zoom.

move

move needs the displacement on the horizontal and vertical axis:

move [0.1, -0.3] $ rect 0 0.1 >> add;

Moves a rectangle 0.1 units to the right and 0.3 units upwards.

move 0.1 $ rect 0 0.1 >> add;

Moves a rectangle 0.1 units both to the right and upwards.

r << rect 0 0.1;
move [0, 0, 0.1, -0.3, -0.8, 0.7] r >> add;

Applies multiple displacements to a rectangle, creating three copies of the original at different positions.

r << rect 0 0.1;
move (osc [0.19,0.17]) r >> add;

Oscillates the position of a rectangle horizontally and vertically.

r << rect 0 0.1;
o << osc [0.19, 0.17]*osc [0.14, 0.15];
move o r >> add;

Uses combined oscillators to create complex oscillating movements for a rectangle.

r << rect 0 0.4;
move [fy,0] r >> add;

Moves a rectangle horizontally based on the fragment’s vertical coordinate. This effectively skews the rectangle.

r << rect (0.5*osc [0.08, 0.04]) 0.4;
move [fy/fr,0] r >> add;

The original moving rectangle is deformed by a move operation that displaces each fragment by a different amount, based on its vertical coordinate and radius.

spin

spin receives the rotation amount, with 2 representing a full turn.

h << hline 0.5 0.01;
spin 0.5 h >> add;

Rotates a horizontal line by 180 degrees, clockwise.

h << hline 0 0.01;
spin [0, 1/3, 2/3] h >> add;

Rotates three horizontal lines by 0, 120, and 240 degrees respectively.

h << hline 0 0.01;
o << osc $ [3,7,9]/100;
spin o h >> add;

Rotates three horizontal lines at different frequencies, creating a spinning effect.

r << spin (osc 0.019) $ unipolar fx;
b << unipolar $ osc 0.013;
[r, 0, b] >> add;

Creates a color pattern combining a rotating red gradient and a pulsating blue.

c << circle (osc [0.18,0.16]) 0.1;
spin [0, 1/2, 1, 3/2] c >> add;

Creates four copies of a moving circle, each one rotated by a different amount.

l << hline 0 0.1;
spin fr l >> add;

Spins a horizontal line based on the radius of each segment, curving the line.

tile

tile repeats the pattern the specified number of times on the x and y axes.

r << rect 0 0.3;
tile [5,3] r >> add;

Tiles a rectangle 5 times along the horizontal axis and 3 times along the vertical axis.

r << rect 0 0.3;
tile 4 r >> add;

Tile a rectangle 4 times on each axis, creating a 4x4 grid.

c << circle 0 0.5;
fit 1 $ move [2*osc 0.1,0] $ tile 1 c >> add;

The circle moves horizontally following an oscillator that oscillates between -2 and 2. tile 1 tiles the pattern, causing the circle to appear on the other side of the screen when it reaches the -1 or 1 coordinate.

r << rect 0 0.3;
tile (4+osc [0.13, 0.19]) r >> add;

The rectangle is now repeated a variable number of times over time, between 3 and 5 in each axis.

r << rect 0 0.3;
tile (8*unipolar fy) r >> add;

By making tile depend on the vertical coordinate of each fragment, a kind of 3D effect is created.

tile [8,4] $ [unipolar fx, unipolar fy, 0] >> add;

A color gradient is repeated in a grid.

r << rect 0 [0.3, 0.3, 0.6, 0.6];
tile [4,2,8,4,2,1] r >> add;

Creates two squares, one inside the other, and then generates three copies of the pair of rectangles, each one tiled by a different amount, creating a pattern.

r << rect 0 [0.3, 0.3, 0.6, 0.6];
s << spin (osc [0.1,-0.1]) r ;
tile [4,2,8,4,2,1] s >> add;

Modifies the last pattern by spinning the original rectangle. As two oscillators are used for the spin, the rectangles are duplicated.

zoom

zoom zooms in or out of the pattern. It needs the zooming amount on the x and y axes, with 1 being the original size.

c << circle 0 0.4;
zoom [0.6, 2] c >> add;

Zooms the circle, making it narrower along the x-axis and taller along the y-axis.

c << circle 0 0.4;
zoom 2 c >> add;

Zooms the circle, making it twice as large in both dimensions.

c << circle 0 1;
zoom (osc 0.03) c >> add;

Creates a pulsating effect on the circle’s size using an oscillator.

c << circle 0 1;
zoom [1,1,1/2,1/2] c >> add;

Zooms the circle by distinct amounts, creating two copies of it.

c << circle 0 1;
o << osc [0.13, 0.13, 0.18, 0.18];
zoom o c >> add;

A variant of the last example, now each circle’s copy is zoomed in and out periodically.

See Geometric Transformations for more examples and transformations.

Feedback

Feedback involves using the last image frame to build the current one. There are many ways to use feedback, but a simple and very effective one is to add a slightly attenuated version of the last frame to a changing pattern.

fb fxy is the last frame without any other changes.

o << osc [0.17, 0.19];
circle o 0.2 >> add;
0.97*fb fxy >> add;

Using feedback this way can create interesting trails and persistence-of-vision effects in animations. Feel free to explore this concept with other patterns or combinations!

See Playing with feedback for other ways to use feedback in your patterns.

Audio reactive visuals

The easiest way to create audio-reactive visuals in Punctual is by using the lo, mid, and hi functions. They represent the power of the low, middle, and high frequencies that are playing at every moment inside Estuary.

Their counterparts, ilo, imid, and ihi, work in the same way but use external audio captured by the computer microphone as their input.

To experiment with the first group, you’ll need to create an audio pattern inside Estuary. In the second cell in Estuary, select MiniTidal as the language, and then write and execute the following code:

s "bass arpy linnhats:3"

This code will repeatedly play three sounds: one bass sound composed mainly of low frequencies, one note composed of middle frequencies, and a hi-hat sound composed of high frequencies.

In the Punctual cell, let’s explore how we can use lo, mid, and hi:

circle [-0.5, lo] 0.1 >> add;
circle [0, mid] 0.1 >> add;
circle [0.5, hi] 0.1 >> add;

Moves circles vertically based on the power of low, middle, and high frequencies in the audio.

c << circle [0.5, 0] 0.2;
spin [lo,mid,hi] c >> add;

Spins circles based on the power of low, middle, and high frequencies in the audio.

vline (bipolar lo) 0.01 >> add;

Moves a vertical line left and right based on the power of low frequencies in the audio.

l << hline 0 0.1;
tile 4 $ spin (fr*mid) $ tile 4 l >> add;
0.9 * fb fxy >> add;

Creates an animated grid of horizontal lines that spin based on the power of middle frequencies in the audio, with feedback applied for visual continuity.

See the Audio reactive visuals section to learn about other ways to synchronize audio and visuals.

Conclusion

“How do you create cute patterns with Punctual?” a friend of mine asked me once.

In this guide, you’ll find a lot of advanced techniques and creative ideas I’ve been exploring for more than a year.

However, there is no need to learn all of it at once. In fact, you can already create awesome patterns with just the information presented in this tutorial.

This is a list of ingredients I find useful when creating patterns with Punctual:

1. Start simple. It’s usually enough to begin with a circle or a line. Complexity arises through the composition of multiple simple steps. You can always go back and add complexity to an existing shape later.
2. Build a pattern step by step. Especially when you are starting to use Punctual, it’s better to organize your pattern in small steps and ensure they are well written. This way, it’s easier to detect a syntax error in the code.
3. Use variables. You can build a pattern by creating long lines of code, but variables make it easier to modify, understand, and fix. I often spend a few seconds during my performances rearranging my code and simplifying things before continuing.
4. Add movement. This is one of the first things you want to do in any pattern. Even a simple circle moving across the screen is much more interesting than a static scene.
5. Use symmetry and repetition. That’s why they are called patterns. Punctual makes this simple, as adding numbers to any list will create copies of the existing shapes.
6. Create irregularity. Symmetry and repetition are cool, but adding irregularity on top of those is what makes a pattern really unique. Use any transformation that depends on one of the fragment’s coordinates (fx, fy, fr) to break the homogeneity of a pattern.
7. Use color. Using mono and multiplying by a color is very easy to tint your patterns. Changing a color can completely modify a pattern’s vibe.
8. Feedback is your friend. Most patterns benefit from adding a good amount of feedback. Just keep in mind that feedback can result in very bright visuals, so add it smoothly and be ready to darken your pattern when necessary.

Next is a beautiful pattern built with these ingredients in mind. It only uses the functions and ideas explained in this tutorial.

Step 1: Start simple

hline 0.3 0.002 >> add;

Step 2: Add movement

l << hline 0.3 0.002;
spin (saw 0.2) l >> add;

Step 3: Add symmetry

l << hline 0.3 0.002;
sp << spin (saw 0.2) l;
mono $ spin [0,0.5,1,1.5] sp >> add;

Step 4: Feedback is your friend

l << hline 0.3 0.002;
sp << spin (saw 0.2) l;
mono $ spin [0,0.5,1,1.5] sp >> add;
0.97 * fb fxy >> add;

Step 5: Use color

l << hline 0.3 0.002;
sp << spin (saw 0.2) l;
pat << mono $ spin [0,0.5,1,1.5] sp;
color << [1, 0.1, 0];
color * pat >> add;
0.97 * fb fxy >> add;

Step 6: Create irregularity

l << hline 0.3 0.002;
sp << spin (saw 0.2) l;
mv << move fr $ tile 1 sp;
pat << mono $ spin [0,0.5,1,1.5] mv;
color << [1, 0.1, 0];
color * pat >> add;
0.97 * fb fxy >> add;

Note the addition of tile 1 before applying move fr in this step. Without it, the lines get out of the screen from time to time. As explained in a prior example, tile 1 tiles a pattern, so when the line leaves the screen from one side, it appears on the opposite site.

Step 7: Add repetition

l << hline 0.3 0.002;
sp << spin (saw 0.2) l;
mv << move fr $ tile 1 sp;
t << tile [8, 4] mv;
pat << mono $ spin [0,0.5,1,1.5] t;
color << [1, 0.1, 0];
color * pat >> add;
0.97 * fb fxy >> add;

Step 8: Small adjustments

l << hline 0.3 0.02;
sp << spin (saw 0.2) l;
mv << move fr $ tile 1 sp;
t << tile [8, 4] mv;
pat << mono $ spin [0,0.5,1,1.5] t;
color << [0.2, 0.02, 0];
color * pat >> add;
0.97 * fb fxy >> add;

Here, we increase the line width to make it more visible, but divide the color by 5 to compensate for the high feedback, while maintaining the same red-orange color palette from before.

3 - What's New in Punctual 0.5

If you’ve used Punctual before, you might be interested in the new features included in the recently released version 0.5. Below is a summary of the key updates.

Breaking changes

Missing Channels Default to 0

In Punctual 0.4.x, the expression circle 0 1 >> add would produce a white circle because a one-channel signal was automatically repeated across the second and third channels.

This behavior has changed in version 0.5. Now, any missing channels default to 0, meaning that the same expression will now result in a red circle, as the green and blue channels default to 0.

This change has other implications. For instance, rect 0 0.5 >> add is now equivalent to rect 0 [0.5, 0] >> add, not rect 0 [0.5, 0.5] >> add, and will produce a degenerate rectangle. Similarly, rect 0.5 [0.5, 0.5] will now be positioned at [0.5, 0], not [0.5, 0.5] as it was in version 0.4.

Output Notations

Punctual 0.5 introduces new output notations, focusing on how patterns are combined rather than on the channels used.

While the old rgb and rgba notations still exist, they now have slightly different meanings.

The most commonly used output notations are now add and blend, with add being the equivalent of rgb in version 0.4, and blend equivalent to rgba. The mul notation completes the set of available outputs.

All deprecated output notations have been removed, including red, green, blue, hue, saturation, value, hsv, alpha, and fdbk.

For more details, see the output notations section.

Functions with Fewer Arguments

None of the texture-creating functions (fb, fft, ifft) require arguments anymore.

For example, where you previously wrote fb fxy, you now simply write fb. Other expressions can be adapted similarly: for example, fb frt can be replaced with setfxy frt fb. This update aligns these functions with img, vid, and cam, which already worked this way.

The fft function is now equivalent to the 0.4 expression fft fx.

Removed Functions

• step: use seq where possible, as explained below.
• zip: not removed but deprecated. Use {} instead.

Functions with Different Meanings

• tile and zoom: see the details below.

Internal Changes

These changes may not be immediately obvious to users but have significant long-term implications for how Punctual functions and evolves.

Reimplementation in PureScript

Punctual 0.5 has been completely rewritten in PureScript, a functional programming language that compiles directly to JavaScript. Prior to version 0.5, Punctual was written in Haskell.

This switch simplifies the process of generating the final JavaScript version from Punctual’s source code, making it easier to develop new features. Additionally, it opens up possibilities for users to create their own modified versions of Punctual more easily.

Exolang

Punctual is now an exolang in Estuary. Essentially, this means that the Punctual code can be modified and these changes can be applied in Estuary without needing to alter any of Estuary’s code. As a result, bug fixes and new features can be implemented more quickly.

Since exolangs can be imported dynamically into Estuary, you can now use different versions of Punctual or even your own customized versions seamlessly. Different Estuary cells can even run different versions of Punctual simultaneously.

New Features

User-Defined Functions

You can now define your own functions and add them to Punctual!

User-defined functions are written in Punctual itself, accept arguments, and can contain any Punctual expression. The only limitation is that user functions must be written as one-liners.

For example, the user-defined pixelate function implements a pixelation effect:

pixelate xy = setfxy $ (0.5+floor (fxy*:(xy/2)))/:(xy/2);

i << img "https://upload.wikimedia.org/wikipedia/commons/6/69/A_smiling_member_of_the_Ramnami_Samaj_%28edited%29.jpg";
pixelate [100,1000] i >> add;

External Script import

In addition to creating your own functions, you can now dynamically import Punctual code files using import.

Any variables or functions defined in an imported file are immediately available to the rest of your Punctual code.

Files to be imported must be hosted on a CORS-enabled server, just like any other resource (such as images or videos). See Using your own images and videos for ideas on how to set this up.

Time Shifting Functions

Time functions are a new category in Punctual that allow you to control when changes in patterns occur.

This set includes four functions: slow, fast, late, and early.

Here’s an example of how they work:

l << hline (saw 0.1) 0.01;
[1,1,1]*l >> add;
[1,0,0]*slow 2 l >> add;
[0,1,0]*fast 2 l >> add;
[0,0,1]*late 2 l >> add;
[1,1,0]*early 2 l >> add;

Sequences

Punctual now allows you to create sequences of expressions using the new seq function, which serves as a more flexible replacement for the removed step function.

seq overcomes the main limitation of step, which could only handle a single number in each step.

For example:

s << seq [osc 0.2, 0];
hline s 0.001 >> add;

This will draw a horizontal line at height 0 half the time, and move it up and down according to the oscillator during the other half.

You can also use signals with different numbers of channels (all signals will be adjusted to the maximum number of channels present):

hline (seq [osc 0.3, saw [0.1,0.2,0.3]]) 0.01 >> add

By default, seq completes one full iteration per cycle. You can control the speed and phase of the sequence using the time-shifting functions mentioned earlier.

Note, however, that this only covers cases where step was used with a saw oscillator. For example:

l << hline 0 0.001;
s << step [0.1, 0.5, 0, 0.8, 1.3] fx;
fit 1 $ spin s l >> add;

does not have a direct equivalent with seq.

Other Changes

Changes in Geometric Transformation Functions

In version 0.4, tile [1,4] would repeat a pattern once on the horizontal axis and four times on the vertical axis. This behavior is now achieved using tilexy.

In version 0.5, tile [1,4] repeats the pattern once and four times, creating two versions of the pattern. In 0.4, this would have been written as tile [1,1,4,4].

There are two additional functions: tilex, which only tiles patterns horizontally, and tiley, which only tiles them vertically.

The same changes apply to the zoom function, with corresponding zoomxy, zoomx, and zoomy options.

New Operator {}

In Punctual 0.5, [] combines lists combinatorially, whereas {} combines them pairwise.

In the following example, all nine circles are created by the [] expression, but only the three yellow ones appear when using {}:

x << [-0.5, 0.2, 0.8];
y << [-0.8, 0, 0.5];
mono $ circle [x,y] 0.1 >> add;
[0,1,0]*(mono $ circle {x,y} 0.1) >> add;

In version 0.4, this result could be achieved using circle (zip x y) 0.1.

pxy

The new pxy shortcut has been added, which is equivalent to [px, py].

4 - Concepts

These are some important ideas behind Punctual which are crucial to get a good understanding of how all of this works.

In my own experience, the last ones can be difficult to grasp.

If you are new to Punctual, it’s advisable to look only into the first 3 sections here, or even jump directly to the getting started section and come back later.

Coordinate system

Punctual uses a coordinate system where both the x and y axes span from -1 to 1 across the visible screen. Specifically, the x-axis ranges from -1 at the left side of the display to 1 at the right side, while the y-axis ranges from -1 at the bottom side of the display to 1 at the top side.

This has the following implications:

• The origen [0,0] is conveniently situated at the center of the screen.
• It’s immediate to use functions that go from -1 to 1, like the sine or cosine, to modulate coordinates. See Oscillators.
• Fragment dimensions are relative to the aspect ratio of the window they are displayed in. So, for example, in a full-screen window in a landscape monitor, a fragment is wider than high, so many shapes seem disproportionate: circle [0,0] 1 it’s an oval, or rect [0,0] 0.5 0.5 is not a square. If you resize only the width of the window and narrow it, the circle will gradually become circular (and if you keep going, taller than it is wide). See also Coordinates and the fit function.
• As the color system uses values from 0 to 1, it’s not immediate, but easy to use coordinates to change colors, or vice versa. See the examples in the next section Output notations and Colors.

Output notations

A Punctual statement needs to end with an output notation in order to produce a result.

There are several possible outputs for visual statements, being the most common add.

A gray screen:

0.5 >> add;

A red screen:

[1,0,0] >> add;

A screen that gets whiter as we go from left to right:

fx >> add;

fx is the x coordinate of the current fragment’s position (see Fragments and Cartesian coordinates), and goes from -1 to 1, but color goes from 0 to 1. Here, negative values are ignored, and that’s why the right half of the screen is black. See also unipolar in Scaling values.

Note how in some examples we have send only one value to add and in another one a list (see more on lists in Notes on Haskell) with three values.

In general, any Punctual expression is composed by a number of Channels (1 or 3 in our examples). When those channels reach the output, they are interpreted in some way, depending on the output used.

For add output:

• Three channels are interpreted as red, green, and blue intensities.
• With only one channel, all red, green, and blue intensities use the same channel.
• Two channels are interpreted as red the first channel, and green+blue (cyan) the second channel.

Any remaining channels are interpreted in the same way. So for example, five channels would be red, green, blue, red, and cyan.

A cyan screen:

[0,1] >> add

[0,1,1] >> add

Other possibilities are:

• rgb: a synonym for add.

• video: a synonym for add. Deprecated.

• red, green and blue. Deprecated, apply a color instead.

  All channels are summed into the intensity of the specified color.

  [fx,fy] >> red is equivalent to fx+fy >> red, and to [fx+fy,0,0] >> add.

  

• alpha: the transparency amount, being 0 completely transparent and 1 completely opaque. Deprecated, use rgba or blend with an alpha channel instead.

• hsv: the same as rgb, but the channels are hue, saturation and value. Deprecated, use rgbhsv to apply a color space translation instead.

• blend: this adds a fourth channel to the video output corresponding to the alpha channel.

  By default, alpha is 1, so any drawing is completely opaque. With blend you can specify another value to create transparent or semi-transparent parts.

• rgba: a synonym for blend.

Using multiple output notations

It is possible to specify an output in more than one sentence.

When output is add, color in each expression is simply added:

fx >> add;
fy >> add;

is equivalent to:

fx+fy >> add;

fx >> red;
fy >> green;

is equivalent to:

[fx,fy,0] >> add

[0.3, 0, 0.5] >> add;
[0, 0.5, 0.2] >> add;

is equivalent to:

[0.3, 0.5, 0.7] >> add;

When using the blend output, signals are mixed using the same system as the blend function. See Combining Channels.

[1, 0, 0.7, 1] >> blend;
[0.5, 1, 0.3, 0.2] >> blend;

is equivalent to:

c1 << [1, 0, 0.7, 1];
c2 << [0.5, 1, 0.3, 0.2];
blend $ c1++c2 >> blend;

The result is computed as a weighted average of the two colors, taking the alpha value of the second color as the weight. In this example, c2 has a weight of 0.2, so c1 has a weight of 1 - 0.2 = 0.8. The result is then:

[1*0.8+0.5*0.2, 0*0.8+1*0.2, 0.7*0.8+0.3*0.2, 1*0.8+0.2*0.2] = [0.9, 0.2, 0.62, 0.84]

Therefore, the blended color is [0.9, 0.2, 0.62, 0.84].

Note that this operation is not commutative:

[0.5, 1, 0.3, 0.2] >> blend;
[1, 0, 0.7, 1] >> blend;

This expression will draw the second color, no matter what the first one is.

In a more general form, if we have two colors defined as:

[r1, g1, b1, a1] >> blend;
[r2, g2, b2, a2] >> blend;

The resulting blended color is computed like so:

[
r1*(1-a2)+r2*a2,
g1*(1-a2)+g2*a2,
b1*(1-a2)+b2*a2,
a1*(1-a2)+a2*a2
] >> blend;

In this computation each component in the first color is weighted by 1-a2, and in the second color by a2, being a2 the alpha channel component of the second color.

Another possibility is mixing both outputs:

[1,0,0] >> add;
[0,1,0,0.5] >> blend;

In this case, the RGB part is computed in the same way as before, but the alpha channel of the result is set to 1. The result in this example is:

[1*0.5+0*0.5, 0*0.5+1*0.5, 0*0.5+0*0.5] = [0.5, 0.5, 0]

This example is then equivalent to [0.5, 0.5, 0] >> add or [0.5, 0.5, 0, 1] >> blend.

When application of this is in Estuary, using more than one cell to make visuals, cells are drawn in a left-right up-down order.

Bindings

When expressions get more long and complex, you can assign a name to a part in order to simplify its readability.

For example:

c << circle 0 0.3;
move [0.5,0] c >> add;

Here, we give the circle the name c and refer to it on the next line. The result is equivalent to move [0.5,0] (circle 0 0.3) >> add, that is, a circle of a radius of 0.3 and its center to the [0.5,0] coordinate.

Note that when using more than one statement, you need to end each one (except the last one) with a semicolon.

Now, here is the catch. c is not a variable in the sense of popular programming languages. It’s more like a definition or a binding to an expression, and this has some implications.:

c isn’t a circle, it defines a circle. So you can use it more than once to create several circles:

c << circle 0 0.3;
move [0.5,0] c >> add;
move [-0.5,0] c >> add;

This is perfectly valid and creates two identical circles, one at [0.5,0] and the other one at [-0.5,0].

Fragments

A fragment is essentially a pixel in OpenGL (although a single pixel can be related to several fragments).

What’s important here is that Puntual uses WebGL under the hood, which is a web implementation of OpenGL. When you run a Punctual statement, the code is parsed, compiled, and converted to a shader that can be directly executed by the graphics card.

Graphics cards nowadays have multiple processors and can compute the same expression in a large number of fragments simultaneously, which explains how complex graphics can be rendered in such an efficient way.

And once again, this has implications on how we think the code we write.

For example, when you look up the definition of circle on the official Punctual documentation you find this: circle [x,y,...] [d] -- returns 1 when current fragment [is] within a circle at x and y with diameter d.

What that means is, as each fragment is processed independently from the others, all fragments whose coordinates are inside the circle will be painted white, while all the other fragments will be painted black. Of course, other operations in you code can change this, and that’s why the definition says “returns”.

This way of thinking may help to understand and build Punctual expressions.

abs (fx/fy) >> add;

In this example, for each fragment, we take its x-coordinate and its y-coordinate, divide them, and take the result as a positive number. This will give a number greater or equal to 0 for each pixel.

When fx is greater or equal than fy (ignoring sign), the result is a number greater or equal than 1, so that fragment is white. All the other fragments get some gray color, darker as the ration between fx and fy decreases, and black when fx approaches 0.

Graphs

A graph is any Punctual expression that can be converted into a shader. Most simple graphs are an integer number or lists of integer numbers. All graphics related functions get graphs as arguments and return graphs. This way, Punctual offers a big flexibility on what can be used as an argument to a function, or what expression can be combined between them, as all are graphs.

circle [0,0] 0.3 + 0.3 >> add;
circle [0,0] 0.5 * abs fx >> add;
circle [0,0] (1/fx) >> add;
circle [circle [0,0] 0.2,0] 0.3 >> add;

All these examples are valid Punctual expressions, although it may seem that they are combining incompatible types.

circle [0,0] 0.3 + 0.3 >> add;: we add 0.3 to all fragments, so fragments inside the circle get a value of 1.3, which is white, and all the other a value of 0.3, which is a dark gray.

circle [0,0] 0.5 * abs fx >> add;: all fragment values are multiplied by its x-coordinate without sign. Fragments outside the circle are black anyway. Fragments inside the circle get their 1 value from the circle multiplied by their unsigned x-coordinate. As this is a value from 0 to 1, the result is a gray gradient with the shape of the circle.

circle [0,0] (1/fx) >> add;: for each fragment, its x-coordinate is inverted, then we look if the fragment is inside a circle from the origin with radius this value, and if it is, we paint it white, otherwise black. For negative fx the result is always black, as it’s impossible to be inside a circle with negative radius.

circle [circle [0,0] 0.2,0] 0.3 >> add;: for each fragment, we first check if it is inside a circle at the origin with radius 0.2. This can give a 0 or a 1. Then, we look if the fragment is inside the resulting circle, which can have its center on [0,0] or on [1,0] depending on the previous result. Overall, fragments that are near the [0,0], get a 1 on the first operation, and then a 0 on the second, as they are far away from the [1,0] coordinate. Fragments that are at a distance from the [0,0] between 0.2 and 0.3 get a 0 on the first operation and a 1 on the second. Finally, fragments that are at a distance from the origin greater than 0.3 get a 0 on the first operation, and a 0 on the second operation. That explains the crown shape of the result.

Channels

All Punctual statements produce a number of channels. For example, 0.5, circle [0,0] 0.3 or fx are 1-channel expressions, while [0.5,0.2,0.8] is a 3-channel expression.

Note how in the official reference documentation most functions have ellipsis on their arguments. That means we can pass any number of arguments, and that this will increase the number of channels on our expression.

circle [-0.5,0,0.5,0] 0.2 >> add;

In this example, we are providing two center points for the circle, creating a two-channel signal. As explained in Output notations, when sending two channels at video, the first one is interpreted as the red channel in the RGB color space, and the second one is taken both as the green and the blue channels.

Note that circle [-0.5,0,0.5] 0.2 >> add is a valid expression, and the cyan circle will have [0.5, 0.5] as its center.

Now, as any number in our expression can be substituted by any graph, we can write:

circle [-0.5,0,0.5,0] [0.2,0.3] >> add;

How many channels has this signal? There are two centers and two radius, so in total there are 4 different combinations, so 4 channels.

In general, Punctual interprets expressions in a combinatorial way, so it creates channels for each possible combination of the input values.

Let’s try to understand the result. When add receives more than 3 channels, each group of 3 is interpreted as a RGB signal, and the rest follows the same rules explained before. In our case, we have a complete RGB group, and one more channel that will be interpreted as the whole RGB, i.e. white.

We have 4 circles:

• Center [-0.5,0], radius 0.2, color red.
• Center [-0.5,0], radius 0.3, color green.
• Center [0.5,0], radius 0.2, color blue.
• Center [0.5,0], radius 0.3, color white.

The intersection of the two first circles leads to yellow (red+green). The crown on the left is green. The blue circle on the right is invisible due to the bigger white circle.

[0.2,fy,fx] + [0.2,0.3] >> add;

Due to the combinatorial nature of Punctual, this signal has 6 channels:

• 0.2+0.2: 0.4 interpreted as global red.
• 0.2+0.3: 0.5 interpreted as global green.
• fy+0.2: increase the blue component as we go up (and decrease it on the bottom, counteracting the sixth channel).
• fy+0.3: increase the red component as we go up (and decrease it on the bottom, counteracting the first channel).
• fx+0.2: increase the green component as we go to the right (and decrease it on the left, counteracting the second channel).
• fx+0.3: increase the blue component as we go to the right (and decrease it on the left, counteracting the third channel).

With all these interactions, and considering how RGB components affect the final color output, the result is the gradient you see on the screen.

See also [Combining graphs](#Combining graphs) for more examples on how to mix distinct graphs together.

5 - Getting Started

These are some basic ideas on how to write Punctual code, and its syntax.

Writing and running an expression

You have several options in order to run Punctual code:

• Standalone web editor. It’s immediate to use, and the screen is clean to show in a live performance.
• Estuary. Nearly as immediate to use, and it offers the possibility to use more than one live-coding language at the same time, and to collaborate with other people online. It also has some integrated help and tutorials. It’s a bit more work to get a completely clean screen to show it in a live performance. See the github repository and this unofficial Estuary reference for more information on how to configure and use Estuary.
• Download Punctual standalone. You can get the last Punctual version from the release section of the official github repository. This is the same as the first option, but you won’t need an Internet connection in order to use it, so it’s ideal in a live performance at a venue where you don’t know if you would have any connectivity at all.
• Download and compile Estuary. It’s also possible to get a local copy of Estuary to use off-line, but in this case you need to compile the source code yourself. You can clone the Estuary github repository and follow the instructions in BUILDING.md. Compiling Estuary isn’t an easy task and it’s unnecessary on most cases.

If you are new to Punctual, choose any of the two first options and go ahead.

Once you are able to try Punctual, just write or paste the expression you want to execute and run it pressing Shift+Enter. In Estuary, you also have a “play” button.

Commenting out

When using Punctual (or any other live-coding language), you’ll usually need a way to comment out parts of the code, to avoid running them.

You can do this in Punctual by appending -- in front of the line you want to comment, or by using the function zero that will convert any graph to a blank screen.

It’s also possible to comment out multiple lines by enclosing them between {- and -} markers.

Often, when playing with visuals, you’ll end up with a completely white screen and no easy way to see your code. The easiest way to recover control is by selecting all your code with Ctrl+A (Cmnd+A in MacOS), deleting it all (Del), and running the result (Shift+Enter). This is a fast way to remove all visuals and recover a blank screen. Now, you can recover your old code by undoing your last operation (Ctrl+Z or Cmnd+Z) and modify it before running it again.

Notes on Haskell

Punctual is written using the programming language Haskell, and inherits some of its syntax. This is a short summary of some syntactic details that are important:

Negative numbers

In some contexts, negative numbers need to be surrounded by parentheses. That is because - is also an operator, and sometimes the compiler may have problems distinguishing between the negative sign and the minus operator.

-fx >> add; -- error
-1*fx >> add; -- error
(-1)*fx >> add; -- correct

spin [-pi] fx >> add; -- error
spin [(-1)*pi] fx >> add; -- correct

Parentheses () and dollar $

The space character is the parameter separator both in Haskell and in Punctual. This can lead to some confusion when nesting various functions:

-- Error: the compiler can't tell what numbers are arguments to circle and what to vline:
vline circle 0 0.1 0.1 >> add;

You can use parentheses to clearly indicate how this expression needs to be interpreted:

vline (circle 0 0.1) 0.1 >> add;

In longer statements, using parentheses may become tedious and prone to errors:

spin (saw [-0.13,0.13]) (move [-0.2,0,0.2,0] (circle 0 0.1)) >> add;

The dollar ($) operator can be used to substitute a pair of parentheses. It indicates that all things that follow are to be executed before, so it’s equivalent to enclosing with parentheses all that follows.

The previous expression can be rewritten like this:

spin (saw [-0.13,0.13]) $ move [-0.2,0,0.2,0] $ circle 0 0.1 >> add;

This is a faster and clearer way to write this type of expression. Note that there is only a pair of parentheses remaining, that we can’t substitute by a dollar, as saw [-0.13,0.13] is not the last argument of spin:

-- Error: this two expressions are equivalent (and don't make sense, as spin is lacking an argument):
spin $ saw [-0.13,0.13] $ move [-0.2,0,0.2,0] $ circle 0 0.1 >> add;
spin (saw [-0.13,0.13] (move [-0.2,0,0.2,0] (circle 0 0.1))) >> add;

Lists

Lists are a very used data type both in Haskell and in Punctual. They are written between square brackets, and their elements separated by commas:

circle [0,0.3,0.5,0.2,-0.3,-0.1] 0.2 >> add;

[unipolar fx, 0.4, osc 0.1] >> add;

List expansion

As seen in channels, we can use many values in a Punctual expression, and they will be expanded into a complexer graph. For example, circle [-0.5,0,0.5,0] 0.2 >> add; will draw two circles, one red and one cyan.

If you want to create more objects in a statement like this, it can quickly get tedious to write all the numbers.

Here is where Haskell syntax for expanding lists becomes useful.

All you have to write to expand a list is the first and second values, followed by two dots (..) and the limit:

l << [0,0.1 .. 0.5];
--l << [0,0.1,0.2,0.3,0.4,0.5];
hline l 0.01 >> add;

Note that these two versions of l are equivalent, and the limit 0.5 is included.

This works fine with hline as we only need the y-coordinate to write a horizontal line.

Combining lists

If we want to use the same trick with point or circle, we’ll need to provide pairs of coordinates.

With zip we can build all the x-coordinates in a list, then all the y-coordinates in another list, and finally join them:

xs << [-0.4,-0.3 .. 0.4];
--xs << [-0.4,-0.3,-0.2,-0.1,0,0.1,0.2,0.3,0.4];
ys << [0,0.1 .. 0.8];
--ys << [0,0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8];
circle (zip xs ys) 0.05 >> add;

When using zip, if one input list is shorter than the other, excess elements of the longer list are discarded.

Another way to combine lists is by putting them one after the other in a new list:

xs << [0,0.1 .. 0.7];
ys << [-0.3,-0.2 .. 0.3];
circle [xs,ys] 0.05 >> add;

Note that this creates a list with all possible combinations of one element from the first list and one element of the second list.

What if you want a set of circles with distinct x-coordinates, but at the same height? Punctual automatically expands single numbers to lists if necessary, so you can do this:

xs << [-0.95,-0.9 .. 0.95];
ys << 0;
fit 1 $ circle [xs,ys] 0.05 >> add;

The last way you have to combine two lists is by simply appending one after the other. This is just what the operator ++ does, so for example, [1,2,3,4]++[5,6,7] results in [1,2,3,4,5,6,7].

l1 << [-0.9,-0.83 .. -0.3];
l2 << [0.9,0.83 .. 0.3];
circle [l1++l2,0] 0.05 >> add;

Now, remember that in Punctual all things are really graphs. So, using any of these to combine lists is only a very particular case of what can be done.

For example, using ++ we can join two graphs:

c << circle 0 0.2;
l << hline 0 0.05;
c++l >> add;

And here we can see what is really happening: the two graphs are joined and the result has the sum of the channels of the first and the second input graphs. In our case, these are 1 and 1, so the result has 2 channels, hence the colors (see output notations if this isn’t clear).

See combining graphs and combining channels for more information and examples on how to combine graphs and channels.

6 - Coordinates

Punctual let’s you direct access to fragment coordinates, both in Cartesian and polar systems. This feature allows for a lot creative possibilities.

This section is intimately related with Geometric transformations especially the setfx, setfy and setfxy functions. Also, some examples use Oscillators.

Cartesian coordinates

The Cartesian coordinate system is the coordinate system most commonly used, where a point in the plane is identified by its horizontal distance and vertical distance to a reference point called origin. These two values are called coordinates, the horizontal axis is called x-axis, and the vertical one y-axis. See Coordinate system to see the details on how this is implemented in Punctual.

fx, fy, fxy

As explained in fragments, Punctual expressions are evaluated for each fragment. For a given fragment, fx is the x-coordinate of that fragment, fy is the y-coordinate, and fxy is a list with both coordinates.

The next examples are some creative ideas one can explore using only coordinates and basic mathematical functions.

Dividing the screen in 10 vertical gradients:

5 * (fx % 0.2) >> add;

The modulus fx % 0.2 (see mathematical functions for more information) makes 10 stripes from 0 to 0.2 (10 as fx goes from -1 to 1). Then, we multiply by 5 to rescale the value to a 0 to 1 range.

Color patterns

Here we are using three simple formulas to get each of the three RGB channels directly from the coordinates of each fragment.

-- Try changing abs by unipolar
abs [fx, (-1)*fy, (fx+fy)/2] >> add;

unipolar $ (-1)*fx++fxy >> add;

[unipolar $ sin' fx, 1 - abs fy, unipolar $cos fx] >> add;

There are a lot of formulas that allow you to make cool gradients as a starting point for more complex transformations.

See Colors for some ideas on using other colors spaces aside from RGB.

Using punctual to draw mathematical functions:

A typical mathematical function has the form y=f(x), where f(x) is a formula that specifies how to get the y coordinate from the x coordinate. So, for any x, we draw a point at coordinates (x, f(x)).

Using this method we can draw a lot of mathematical functions (here, the zoom is only used to see a bit more of the resulting graph):

zoom 0.4 $ point [fx, cos fx] >> add;

zoom 0.4 $ point [fx, log $ abs fx] >> add;

zoom 0.4 $ point [fx, fx*fx] >> add;

Another way to do the same is by using the between function (see Mathematical functions).

In essence, between receives two values and a graph and returns 1 if the graph is between the two values, or else 0.

Remember that this is evaluated independently for each fragment, so in the next example, for any fragment (fx,fy) we’ll draw white if and only if fy is almost equal to cos fx. The 2*px is the margin that fy can be away from cos y and still be white, and determines the wideness of the line we’ll draw. As explained a bit later, px is the fragment’s height:

zoom 0.4 $ between [cos fx-2*py, cos fx+2*py] $ fy >> add;

We can use evolve these ideas to create interesting patterns:

point[fx, osc 0.09*cos (fx*fy*15*(2+osc 0.32))] >> add;
0.98 * fb fxy >> add;

px, py

Depending on the screen resolution and the windows size, pixels on Punctual will have a specific dimensions expressed in the Punctual coordinate system.

You can access a pixel’s width with px and a pixel’s height with py. This is usually used to draw thin lines, as in the following example, or the ones on the previous section:

zoom 0.4 $ circle [fx, fx*fx] $ 4*px >> add;

aspect, fit

aspect is the ratio between the width and height of the window, so, if you don’t change the window size (or use fit), it’s a constant.

To “see” it’s value, we can try something like this:

[0.3*aspect,0,0] >> add;

Now, change the window size, and you should see how the background is redder as the width height ratio increases, and darker as it decreases.

fit can be used to rescale the x coordinates in order to change the aspect ratio of the result. When doing this, the visible coordinates on the x-axis no longer will be on the range -1 to 1 (unless fit aspect is specified, which is the same as doing nothing).

The most obvious way of using fit is to correct the aspect of geometric shapes, so a circle draws like a circle, and so on:

fit 1 $ circle 0 0.3 >> add;

fit 1 $ rect 0 0.5 >> add;

Another useful application of fit is to scale an external source (an image, a video, or the camera output) to fit the screen, or a particular portion of the screen:

fit (0.5*aspect) $ move [1, 0] $ img "https://upload.wikimedia.org/wikipedia/commons/d/d4/Karl_Marx_001.jpg" >> add;
fit (0.5*aspect) $ move [-1,0] $ img "https://upload.wikimedia.org/wikipedia/commons/2/21/Friedrich_Engels_portrait_%28cropped%29.jpg" >> add;

In this example, we took images of the Communist Manifesto authors from Wikicommons, and made each one of them to occupy the half of the window, independently from its size.

Same idea, but we divide the window in two horizontally:

fit (2*aspect) $ move [0,-1] $ img "https://upload.wikimedia.org/wikipedia/commons/8/87/Tundra_in_Siberia.jpg" >> add;
fit (2*aspect) $ move [0,1] $ img "https://upload.wikimedia.org/wikipedia/commons/2/2d/Picea_glauca_taiga.jpg" >> add;

Can we combine both previous examples to divide the window in four equal-sized parts? The answer is yes, as aspect is modified just when fit is executed:

fit (0.5*aspect) $ fit (2*aspect) $ move [-1,1] $ img "https://upload.wikimedia.org/wikipedia/commons/2/2d/Picea_glauca_taiga.jpg" >> add;

Now, these last examples show the most standard uses of fit, but you can also use it in many creative ways.

For example, we can apply an oscillator to the aspect ratio to deform the image periodically:

fit (osc 0.2) $ circle 0 0.8 >> add;

Now, evolving this example, we can create beautiful patterns:

spin [saw 0.2, (-1)*saw 0.2] $ fit (8*osc (0.5*cps)) $ tile [4,step [1,4,8,16] $ saw cps] $ circle 0 0.8 * [0.8,0,0.8]>> add;
0.8 * fb fxy >> add;

Here, we are synchronizing the fit oscillator to the beat, and increasing its range to -8 to 8. We are also drawing a lot more circles using tile. The replication over the y-axis changes over time, due to the use of step and the saw oscillator. Finally, the spin with to graphs as first argument, duplicates the whole set and made each of the copies rotate in opposite directions.

Polar coordinates

In the polar coordinate system, each point in the plane also has two coordinates, but they are the distance to the pole (the center of the window, analogous to the origin in Cartesian coordinates), and the angle from the horizontal ray that goes from the pole to the right (called polar axis), measured in radians.

fr, ft, frt

In the same way that fx, fy and fxy allow to get fragment coordinates in the Cartesian system, fr, ft and frt are the fragment coordinates in the polar system.

fr is the distance from the pole, and is equivalent to dist 0 or dist [0,0].

Note that if we only move through one of the axis, fr goes from 0 to 1, but can be larger. The point at [1,1] has a fr of approximately 1.41, that is the square root of 2 (by the Pythagorean theorem).

ft is the angle from the reference ray, which is the right part of the horizontal axis. In Punctual, this angle goes from -π to π radians. This is important, as many times you’d like to rescale this range to a [-1,1] range or [0,1] range, in order to use it in other parts of your code:

• To a [-1,1] range: ft/pi.
• To a [0,1] range: linlin [(-1)*pi, pi] [0,1] ft or unipolar $ ft/pi.

Next examples are similar to the ones of the Cartesian coordinates section, but the result can be quite different when using polar coordinates.

20 radial gradients:

fit 1 $ 10/pi*(ft % (pi*0.1)) >> add;

Or concentric gradients:

fit 1 $ 10 * (fr % 0.1) >> add;

Color patterns:

r << fr/1.4;
t << ft/pi;
[1-r, abs t, abs $ r/ft] >> add;

r << fr/1.4;
t << ft/pi;
[1-r, abs t, abs $ fx*fy] >> add;

Note how fr and ft are rescaled to keep the red and green coordinates from 0 to 1.

Mathematical functions:

Not so obvious as with Cartesian coordinates, but it’s possible to build interesting shapes using the same ideas:

fit 1 $ point [fx, sin' ft] >> add;

For each fragment, draw only the points where y matches the sine of the angle. This results in a circumference of radius 1 (by definition of the sine function, the sine of an angle is the y coordinate of the corresponding point on the circumference of radius 1), and a line at x=0, as the sine of 0 (or π) is 0.

The missing central part of the line is due to rounding errors. Actually, point is a small circle, so it’s visible if some fragment is near enough the specified coordinates. That explain why the circumference has some wideness. Now, as we get closer to the origin, a little change in coordinates radically changes the angle, and that’s why there isn’t any point there which sine is near enough to the y coordinate.

Similarly: fit 1 $ between [sin' ft - py, sin' ft + py] $ fy >> add;.

dist, prox

dist is the distance of a fragment to a given position.

prox is the opposite of dist, the idea of proximity of a fragment to a given position. prox is calculate such as two opposite screen points have a proximity of 0, and one point has a proximity of 1 to itself.

Let’s take for example [1,1] and [-1,-1] as two point that are as far away from each other as it is possible in the initial visible screen. The distance between them, per the Pythagorean theorem, is the square root of 8, that is approximately 2.828427. prox is computed as (2.828427-dist[x,y])/2.828427, clamped to be between 0 and 1.

One very usual way of using prox is to create masks. Visuals can get quite bright easily, and this can make it difficult for you or the people you are jamming with to see the code on the screen.

You can create a mask in order to keep the borders of the screen relatively clear and focus the visuals on the center:

a << 1;
m << prox 0 ** 4;
a*:m >> add;

Here, a is the annoying graph, in this case a completely white screen. m is the mask, calculated as the proximity to the origin, and raised to the power of 4.

Note that, as all proximities lies between 0 and 1, as we increase the power, the resulting numbers will be nearer to 0.

Finally, we multiply a and m, point to point, deeming each fragment according to the proximity it has to the center.

Following there are some examples on how can we use dist and prox in different creative ways:

• Color patterns depending on the distance of each fragment to certain coordinates:

[dist [0.5,0], prox [-0.6,-0.3], dist [-0.3,0.3]] >> add;

• Deform an image:

i1 << img "https://upload.wikimedia.org/wikipedia/commons/0/0c/Golden-eyed_tree_frog_%28Agalychnis_annae%29_1.jpg";
tile [prox [0.5,0], 3*dist [0,0.2]] $ i1 >> add;

Here we use tile (see geometric transformations) to deform the image, as the value of tile is different for each fragment.

We can add some audioreactiveness (see audio reactive visuals) to the last pattern to make it a bit more interesting:

i1 << img "https://upload.wikimedia.org/wikipedia/commons/0/0c/Golden-eyed_tree_frog_%28Agalychnis_annae%29_1.jpg";
tile [prox [ihi,0], 3*dist [0,ilo]] $ i1 >> add;

From Cartesian to polar and viceversa

There are a bunch of functions that are meant to transform coordinates from the Cartesian system to the polar system or viceversa:

xyrt: from Cartesian to polar.

To understand this function let’s look at the following example:

c << [1,osc 0.1];
fit 1 $ [circle c 0.1, circle (xyrt c) 0.1] >> add;

The red circle stays at x=1 and moves vertically, from y=-1 to y=1 due to the oscillator.

The cyan circle is very similar, but we’ve applied xyrt to its center coordinates. That means that these coordinates are transformed to polar coordinates. So, looking at the first circle and thinking in how this movement affects the angle and radius from the center, we see that the angle moves from -pi/4 to pi/4, that is from approximately -0.79 to 0.79. The radius moves from the square root of two (1.41) at the top, then decreases until it get to 1, just on the horizontal axis, and then increases again to 1.41 at the bottom.

Now we take these two coordinates, but read them as Cartesian coordinates (note that xyrt calculates the polar coordinates, but doesn’t apply any real geometric transformation like setfxy does). So, the result is a circle which x coordinate moves from 1.41 to 1 then again to 1.41, and which y coordinate moves from -0.79 to 0.79.

Let’s add a few reference lines to check our calculations:

c << [1,osc 0.1];
fit 1 $ [circle c 0.1, circle (xyrt c) 0.1] >> add;
mono $ fit 1 $ hline [-0.79, 0.79] px >> add;
mono $ fit 1 $ vline [1,1.41] px >> add;

As a side note, see how the first example can be rewritten shorter using the ++ operator from the combining graphs section:

c << [1,osc 0.1];
fit 1 $ circle (c++xyrt c) 0.1 >> add;

xyr, xyt

These two functions are nearly identical to xyrt, but they only return one of the two coordinates, the radius or the angle respectively.

Following the previous example:

c << [1,osc 0.1];
fit 1 $ [circle c 0.1, circle [xyr c,0] 0.1] >> add;
mono $ fit 1 $ vline [1,1.41] px >> add;

c << [1,osc 0.1];
fit 1 $ [circle c 0.1, circle [0,xyt c] 0.1] >> add;
mono $ fit 1 $ hline [-0.79, 0.79] px >> add;

rtxy: from polar to Cartesian.

This is the opposite from xyrt: it takes coordinates in the polar system and returns the equivalent in the Cartesian system.

c << [1,pi*osc 0.1];
fit 1 $ zoom 0.25 $ circle (c++rtxy c) 0.1 >> add;

The red circle keeps its x coordinate at 1 and oscillates between -π and π on the y coordinate (note the zoom in order to see all its movement).

The cyan circle takes the 1 as its distance from the origin, and changes the angle, so it keeps moving around the origin, always at the same distance.

I find that rtxy is the most usable of the whole family to create cool visual effects.

In the next example, let’s start with this:

c << [[0.2,0.3..2]*:osc 0.12*osc 0.13, pi*osc 0.1*osc 0.11];
zoom 0.25 $ circle c 0.1 >> add;

These are a bunch of circles that move together in a somewhat irregular way due to the multiplications of oscillators at different frequencies.

The first bit ([0.2,0.3..2]) uses Haskell style list expansion to create the x coordinate for each circle, from 0.2 to 2, going in steps of 0.1.

The y coordinate is common to all circles, and oscillates from -π to π.

Next step is just take all the circle’s center coordinates and read them as polar coordinates.

c << [[0.2,0.3..2]*:osc 0.12*osc 0.13, pi*osc 0.1*osc 0.11];
circle (rtxy c) 0.1 >> add;

Now, we apply some basic geometric transformations, using combinations of fx, fy, ft and fr to twist the circles geometry:

c << [[0.2,0.3..2]*:osc 0.12*osc 0.13, pi*osc 0.1*osc 0.11];
fit 1 $ spin (fr*4) $ move [ft*fx*0.3,ft*0.1] $ circle (rtxy c) 0.1 >> add;

Finally, let’s add some repetition in the middle to create more elements:

c << [[0.2,0.3..2]*:osc 0.12*osc 0.13, pi*osc 0.1*osc 0.11];
fit 1 $ spin (fr*4) $ tile [4,4] $ move [ft*fx*0.3,ft*0.1] $ circle (rtxy c) 0.1 >> add;

Playing with circles and polar coordinates is fun! In the last example, all the circles were moving like a whole. Can we make each one to move separately from the others?

Let’s start with our circles forming a bigger circumference around the center:

t << linlin [0,1] [0, 2*pi] [0, 0.02..1];
fit 1 $ circle (rtxy [0.5, t]) 0.1 >> add;

Here we use a list expansion for the circles angles, just like in the last example, and rescale it from a 0 to 1 range to a 0 to 2π using linlin, just because it’s easier to think from 0 to 1.

Then draw all the circles using polar coordinates, at a fixed distance from the origin of 0.5.

Let’s made the circles spin:

t << linlin [0,1] [0, 2*pi] [0, 0.02..1];
o << pi * saw 0.1;
fit 1 $ circle (rtxy [0.5, t+:o]) 0.1 >> add;

Here, o is an oscillator that goes from -π to π, and when it reaches π it starts again from -π. We add this oscillator to each angle, and the result is that all the circles spin together.

Finally, let’s apply an oscillator to the radius too, but this time, each circle will have a distinct frequency, so they will move apart from each other. We make this by using t to modify the oscillator frequency in the bit osc (0.1*t).

Now, we have a list of radius and a list of angles, and we need to link them together: the first radius with the first angle, the second radius with the second angle, and so on. This is just what the zip function from combining lists does.

As a final touch, we use mono to combine all channels into one, which make all circles white:

t << linlin [0,1] [0, 2*pi] [0, 0.02..1];
o << pi * saw 0.1;
fit 1 $ mono $ circle (rtxy $ zip (osc (0.1*t)) (t+:o)) 0.1 >> add;

rtx, rty

These two functions are nearly identical to rtxy, but they only return one of the two coordinates, the x or y coordinate respectively.

r << unipolar $ osc 0.03;
t << pi*osc 0.07;
fit 1 $ circle [r,t] 0.1 >> add;
fit 1 $ circle (rtxy [r,t]) 0.1 >> red;
fit 1 $ circle [rtx [r,t], 0] 0.1 >> green;
fit 1 $ circle [0, rty [r,t]] 0.1 >> blue;

In this example, r oscillates from 0 to 1, and t from -π to π. There are a total of four circles:

• White: r and t are interpreted as Cartesian coordinates x and y.
• Red: r and t are read as polar coordinates.
• Green: r and t are polar coordinates, but only used to calculate the resulting x position.
• Blue: same as green, but only the y position is calculated.

Examples

10 ways of drawing a circumference of radius 1

Just to see the flexibility of Punctual and different ways to use coordinates, let’s think of different ways to draw a circumference of radius 1.

Probably the easiest way: let’s paint white (1) all fragments whose radius is 1, pixel more, pixel less:

between [1-px, 1+px] $ fr >> add;

As the radius is no more than the distance to the origin, this is equivalent:

between [1-px, 1+px] $ dist 0 >> add;

Also, it’s possible to make this calculation explicit, using the Pythagorean theorem:

between [1-px, 1+px] $ sqrt $ fx*fx+fy*fy >> add;

Next is a similar approach, but without using between. Here, on one hand we take all fragments whose radius is a bit lesser than one, and on the other the fragments whose radius is a bit greater than one. What we want is the intersection of those two, so we multiply the graphs (the result will be one only if both graphs have a one on that fragment).

(fr <= 1+px) * (fr >= 1-px) >> add;

Another way of thinking this is by using the mathematical function of a circumference. For any x, we have to paint only the y that follow the formula x^2 + y^2 = 1. Isolating the y we get:

f << [-1,1]*(sqrt $ 1-fx*fx);
mono $ point [fx, f] >> add;

Note how the square root is multiplied by [-1,1] in order to take both roots.

Now we can take both ways of thinking and mix them. We’ll paint white only those fragments whose x-coordinate is near the computed y for the circle at that x:

c << sqrt (1-fy*fy);
between [c-px, c+px] $ abs fx >> add;

In the last example, we are only taking the positive root of the square root, but are taking the absolute value of x to make the graphic symmetrical.

Yet another way of thinking this problem: we already have a function that draws circles. Let’s tweak it to draw a circumference instead.

In this example, we draw a circle of radius 1, and then take off a slightly smaller circle:

(circle 0 2) - (circle 0 $ 2-2*px) >> add;

Next is mathematically equivalent to the last one, but we get here with another way of thinking. We can draw the inner part of the circumference with a circle, and also the outer part with an inverted slightly bigger circle (using 1- to invert the result, as it is all 0 and 1). So, we have obtained just the invert of what we what, so we invert the result again:

1-(1-circle 0 (2+2*px) + circle 0 (2-2*px)) >> add;

Finally, a last way to solve the problem is by transforming coordinates from Cartesian to polar. If you think about it, a circumference has a very easy representation on polar coordinates, as one of them (the radius) is constant.

This is exactly what vertical and horizontal lines are: a graph where one of the two coordinates is constant.

So we can draw a vertical line, and then think of it a circumference in polar coordinates, so when we interpret the x as the radius and the y as the angle, we get a circumference:

setfxy frt $ vline 1 px >> add;

Similarly, we can use a horizontal line, and the we need to interpret the x coordinate as the angle, and the y coordinate as the radius:

setfxy [ft,fr] $ hline 1 px >> add;

Bonus track: set feedback to 100% and use a point like it is a pencil:

spin (saw 0.06) $ point [0,1] >> add;
fb fxy >> add;

Implementing Hydra functions

As explained in the Overview, Hydra is a popular language for live-coding visuals. One key difference between Hydra and Punctual is that Punctual operates at a slightly lower level than Hydra.

This means that while it is possible (though not always straightforward) to reimplement many Hydra functions using Punctual, the reverse is not necessarily true.

Let’s develop a couple of examples to illustrate this.

• Implementing Hydra’s osc() function:

Hydra’s osc() function draws a sine wave, visualized from above. When the sine wave is far away (low), the visualization appears black, and as it gets closer, it turns white.

In Punctual, this can be expressed using unipolar $ sin' (fx*freq), where freq determines the number of sine wave repetitions. To fully mimic Hydra’s osc(), we need to adjust the coordinates and use unipolar fx instead of fx: unipolar $ sin' (unipolar fx*freq).

Hydra’s osc() also moves horizontally over time. We can achieve this by adjusting the phase of the sine wave based on the elapsed time:

unipolar $ sin' ((unipolar fx+sync*time)*freq);

Hydra uses 60 as the default frequency and 0.1 for the sync parameter. Applying these values, the Punctual expression becomes:

unipolar $ sin' ((unipolar fx+0.1*time)*60) >> add;

This expression recreates the behavior of Hydra’s osc() function in Punctual.

• Implementing osc().kaleid():

Now that we have our version of Hydra’s osc() function, we can extend it with some transformations, such as kaleid().

In this example, we are reimplementing the Hydra expression osc().kaleid(5).out().

The core idea of kaleid(5) is to apply a geometric transformation (using setfxy) by which we take an arc of a fifth of the whole circle and copy it five times, filling the entire screen. Additionally, we need to rotate our arc so that the different parts align correctly, and apply a translation because Hydra’s kaleid() copies the upper left part of the image but draws it at the center.

This is a possible implementation:

hosc << unipolar $ sin' ((unipolar fx+0.1*time)*60);
k << ft % (2*pi/5);
setfxy (rtxy [fr, k]) $ spin ((-1)/5) $ move 0.5 hosc >> add;

1. First line: This is our version of Hydra’s oscillator, osc(), which creates a sine wave pattern that moves horizontally over time.
2. Second line: Here, k is defined. It represents the new angle for each fragment, and the modulus (%) operator is used to map any fragment to the first fifth of the circle. This is the key to the whole kaleidoscope effect.
3. Third line: This line combines several transformations:
   • move 0.5 hosc: Moves the oscillator 0.5 units in each coordinate, effectively shifting the top-left corner of the screen to the center.
   • spin ((-1)/5): Rotates one-fifth of the whole circle, ensuring that each part of the pattern matches up seamlessly.
   • setfxy (rtxy [fr, k]): Applies the geometric transformation. Note that setfxy (rtxy frt) something is an identity transformation, as it retains the radius and the angle. In our cas, k is assigned as the new angle, effectively creating the kaleidoscope effect by repeating and rotating the pattern.

This implementation effectively mimics Hydra’s osc().kaleid(5).out() by using Punctual’s lower-level functions to achieve the same visual result.

setfxy is so flexible that we could include the move, spin and rtxy operations inside the setfxy transformation making the whole transformation in only one step:

hosc << unipolar $ sin' ((unipolar fx+0.1*time)*60);
k << ft % (2*pi/5)-pi/5;
setfxy (fr*[cos k, sin k]-0.5) hosc >> add;

Of course, this is complicated to deduce, but as Hydra is free software, we can look up the original kaleid implementation and translate the code to Punctual.

7 - Colors

Color in Punctual is intimately related to channels.

Colors and output notations

Depending on the output notation used, channels are interpreted as colors in different ways (see output notations):

• red, blue, green, fdbk, alpha: all channels are joined as the target has only one channel.
• add, video, rgb: first channel is red, second green, and third blue. If there is less than 3 channels, they are read following these rules:
  • One channel: the same value is used for the three base colors, resulting in a gray level, from 0 black to 1 white.
  • Two channels: the first channel is red, the second is used for both blue and green, resulting in cyan.
  • More than three channels: every 3 channels are a group of red, green, blue, any excess is read as in the previous rules. So, for example, a 5-channel signal would be red-green-blue-red-cyan, and a 4-channel signal red-green-blue-white.
• hsv: exactly the same interpretation as in rgb, but channels are hue, saturation and value, instead of red, green and blue.
• blend, rgba: this works in the same way as add, but can be confusing. For example, circle [0,0,0.1,0.1] 0.1 >> blend; is a 2-channel signal. The first circle is red, but it will have 0 on the alpha channel, so it’s invisible. The second circle is cyan and visible, as g, b and a are joined. Therefore, using blend with an arbitrary number of channels won’t produce many interesting results.

Basic usage

Most of the times, we’ll create a 1-channel signal and then convert it into a 3-channel signal to get color in the RGB color space. To do this, we only need to multiply our signal by a three elements list. Due to Punctual’s combinatorial nature, our signal will be split in three channels, being the same on all of them, except for the multiplying factor on each one:

circle 0 0.2 * [0.8,0,0.8] >> add;

Note that each color component receives a value from 0 to 1. There is no problem in sending lower or higher values, but they will always be trimmed to this range.

The following table shows the codes corresponding to some basic colors in both the RGB and HSV color-spaces:

Of course, things get interesting when we use non constant expressions for the color channels.

Color changes by space

Creating color patterns involves playing with coordinates (fx, fy, fr, ft) and mathematical operations (abs, unipolar, %, and trigonometric functions are pretty useful for this).

There are plenty examples of this on the sections dedicated to Cartesian coordinates and polar coordinates.

(mono $ fit 1 $ spin [saw 0.03, (-1)*saw 0.03] $ tile [15,1] $ vline 0 0.06) * [abs fx, unipolar fy, fr] >> add;
0.9 * fb fxy >> add;

• Red component is defined as abs fx, so it’s higher on the right and left sides.
• Green component is defined as unipolar fy, so it’s 0 at bottom and 1 at the top of the window.
• Blue component is fr so it get higher as we got far from the center.
• Note the use of mono. The signal (before color is applied) it’s a 2-channel signal, due to the list in spin, so when multiplied by the 3-channel color, it would result in a 6-channel signal. The use of mono converts the 2-channel signal into a 1-channel, so it get lighter on the CPU, even though the visual result is the same.
• Also note the use of parenthesis to make sure color is applied after the rest of the expression is evaluated. Otherwise, it will only affect the vline bit. With mono this would result in only white lines (as the 3-channel color would be squashed into a 1-channel signal). Without mono, the pattern is completely different, as the color is first applied to the vertical line, and then the other transformations take place.

Color changes by time

There are several ways to make a color pattern evolve through time. One of the easiest is using oscillators (osc, tri or saw), but remember that by default oscillators go from -1 to 1, and a color component from 0 to 1, so many times you will be using unipolar or abs to rescale the values. The ~~ operator is also useful when you don’t want a component to reach all values from 0 to 1 (for example, 0.5 ~~ 0.8 $ osc 0.1 will oscillate only between 0.5 and 0.8).

When using oscillators, you can use a frequency that depends on cps to synchronize the oscillator to the beat (see audio-reactive visuals).

[unipolar $ osc cps, 0.5*abs (tri (cps*0.25)), 0.3 ~~ 1 $ saw (cps*4)] >> add;

saw is useful to make a flash at each beat. Supposing a 4/4 beat, unipolar $ saw (cps*4) will start at 0 at the beat’s start and end at 1 just when the next beat hits. You can use 1 - unipolar $ saw (cps*4) or the equivalent expression 1-4*beat%0.25 to make the flash start at 1 with the beat and then fade out.

[1-beat%1, 1-4*beat%0.25, 0] >> add;

At this moment there is no way to change the phase of an oscillator in Punctual, but you can replicate this behavior by using trigonometric functions and the time variable:

[osc cps, 0, sin' (pi+cps*time*2*pi)] >> add;

Note that we haven’t used unipolar here, so really both oscillators are going all the way to -1. We can take advantage of this:

fit 1 $ (1-fr)*:[osc cps, 0, sin' (pi+cps*time*2*pi)] >> add;

Color mixing

Any light based device uses an additive color mixing. When two lights are mixed, the frequencies of both are visible, resulting in a clearer color. If enough frequencies are added, the result is white.

In contrast, when using pigments, color mixing is subtractive. Each pigment captures certain light frequencies and reflects the rest. As we add more pigments, more frequencies are captures, and the color is darker, leading to black if we mixed enough pigments.

So by default, Punctual uses an additive color mixing:

iline [-1,1,-1,0,-1,-1] [0,0] 0.2 >> add;

This graph has 3 channels, so the first line is red, the second line is green, and the third one is blue.

Note how colors are mixed together when the lines intersect. For example, when the red and green line intersect the resulting color is yellow ((1,0,0)+(0,1,0)=(1,1,0)). At the center, where the three lines come together, the resulting color is white ((1,0,0)+(0,1,0)+(0,0,1)=(1,1,1)).

An additive color mixing system is prone to end up with a white screen when there are many elements interacting, especially when using feedback.

There are a few tricks we can use to avoid this and still be able to have a lot of different elements interacting.

• Using subtractive color mixing.

Although our computer uses light to show us information and so it’s a naturally additive device, we can simulate a subtractive system by using some calculations.

First of all, let’s say that talking here about subtractive color models is a language abuse. This is a very complex problem that involves the chemical and physical properties of pigments and materials, and are impossible to recreate in a live-coding context.

Fortunately, we don’t need realism. We are just looking for some simple enough calculation we can apply when mixing color that make sure the result won’t be white when things get messy.

Also, we can’t change how colors are automatically mixed when using patterns like the three lines example above. But we can control how colors are mixed when creating patterns, and this by itself it’s quite useful.

Let’s take a very simple approach and say that we mix two colors, c1=(r1,g1,b1), c2=(r2,g2,b2), in a subtractive way by this formula:

c3=(1-abs(r1-r2), 1-abs(g1-g2), 1-abs(b1-b2))

This simple formula works well for basic colors: magenta and yellow will result in red, magenta and cyan will give blue and so on.

In Punctual, we can write the above formula by the very simple expression:

c3 << 1 -: (abs $ c1-:c2)

Note how the -: operator takes care of all components at once. Also, avoid using -, because due to combinatorial nature of this operator you will end up with, you guessed it, white.

Now we can play with complex color patterns and never end up with a white screen:

c1 << unipolar $ osc [0.07, 0.11, 0.06];
c2 << unipolar $ osc [0.05, 0.09, 0.1];
1-:(abs $ c1 -: c2) >> add;

This is just an example formula, we can take other simple ideas (absolutely non-realistic, but our aim is another one): abs $ c1 -: c2, c1*:c2 and so on…

Let’s create a more extreme example. In this case, abs $ c1 -: c2 is used, as it renders darker colors:

a << spin (saw 0.02) $ tile [8,4] $ unipolar (spin (saw 0.13) $ fx);
b << spin ((-1)*saw 0.03) $ tile [16,8] $ unipolar $ (spin (saw 0.15) $  fx*fy);
c1 << a*:[unipolar $ osc 0.1,0,unipolar $ osc 0.15];
c2 << b*:[unipolar $ osc 0.3,unipolar $ osc 0.5,0];
c3 << abs $ c2 -: c1;
abs $ c3 -: (spin (saw 0.05) $ zoom 2 $ fb fxy) >> add;

There a lot of code here, but note that basically, a and b are two patterns of numbers (only one channel per fragment) that depend on fx and fy and spin as time passes.

c1 and c2 are the product of a and b with an oscillating color. If we visualize c1 or c2 by themselves, the pattern is quite simple.

Now, c3 is the mixing of c1 and c2. If we display c3, the mixing of the other two patterns is obvious, but we can clearly see the different colors, as the screen never collapses to white.

Finally, we use feedback to take the last frame, apply some transformations to it, and remix it with c3. The resulting pattern is quite complex, but again, it never gets too bright.

• Using transparency.

One simple way to keep things under control, especially when using high amounts of feedback, is to apply some transparency to your patterns.

Note the difference between these two examples:

(spin (step [0,0.2,0.4,0.7] $ saw 0.054) $ zoom [xyrt $ (2+fr)*(abs $ 1-fx)*fy] $ mono $ fit 1 $ spin [osc 0.035*saw 0.3, (-1)*osc 0.026*saw 0.03] $ tile [15,1] $ vline (fy*0.5) 0.06) * [abs fx, unipolar fy, fr] >> add;
0.99 * fb fxy >> add;

(spin (step [0,0.2,0.4,0.7] $ saw 0.054) $ zoom [xyrt $ (2+fr)*(abs $ 1-fx)*fy] $ mono $ fit 1 $ spin [osc 0.035*saw 0.3, (-1)*osc 0.026*saw 0.03] $ tile [15,1] $ vline (fy*0.5) 0.06) * [abs fx, unipolar fy, fr, 0.5] >> blend;
0.99 * fb fxy >> add;

Both are the same being the only difference that in the second one we set a 0.5 value to the alpha channel.

In the first example, the screen gets practically white, with some cyan and magenta artifacts forming a vertical and an horizontal line respectively.

In the second example, we can clearly see the patterns that the moving lines are creating, and the screen never gets too bright, even with the high amount of feedback applied.

• Gradients.

c1 << [1,0,0];
c2 << [1,0,1];
x << unipolar fx;
c2*x +: c1*(1-x) >> add;

Color spaces

You can use two color spaces in Puntual: RGB and HSV. So far, we’ve been using the RGB color space.

HSV color space is best understood as a mixing of paints. Informally, the hue value represents which color we choose, saturation is the amount of pigment of the chosen color we add, and value is the amount of white light we project on our object.

So, for example, if we fix 0.8 (purple) as the hue, and 0.5 as the value, with 0 saturation we get a medium gray and, as we add more and more saturation, the amount of purple increases. Now, if we start to change the value, we can pass from a completely black color with 0, to a very bright purple when we get to 1.

Punctual has functions to isolate one of the channels, translate from one color space to the other, and the combination of these two operations.

rgbr, rgbg, rgbb

• rgbr, rgbg, rgbb: use these functions to isolate one of the three channels in an RGB expression. If the input signal has more channels, the result is one channel out of three.

In the next example, we take the red channel of a first video, and the green channel of a second one, then we combine them:

v1 << rgbr $ vid "https://upload.wikimedia.org/wikipedia/commons/4/4f/Midway_Atoll_-_Bird_Sightings_-_Mar-Apr_2015.webm";
v2 << rgbg $ vid "https://upload.wikimedia.org/wikipedia/commons/2/21/Sparrow_hawk.webm";

[v1,v2,0] >> add;

The next example is based on a previous example about subtractive colors, adding only a move call. Each fragment is moved through the x axis according to its red component. This breaks the regularity of the previous example, creating more interesting and variable patterns:

a << spin (saw 0.02) $ tile [8,4] $ unipolar (spin (saw 0.13) $ fx);
b << spin ((-1)*saw 0.03) $ tile [16,8] $ unipolar $ (spin (saw 0.15) $  fx*fy);
c1 << a*:[unipolar $ osc 0.1,0,unipolar $ osc 0.15];
c2 << b*:[unipolar $ osc 0.3,unipolar $ osc 0.5,0];
c3 << abs $ c2 -: c1;
move [rgbr c3,0] $ abs $ c3 -: (spin (saw 0.05) $ zoom 2 $ fb fxy) >> add;