Welcome to the Waaave Pool manual!  If you don’t know what the heck a Waaave Pool is check out over here for the shop or over here for a video demo/manual!  If you are looking for troubleshooting scroll on down to the bottom of this page!

Waaave Pool is both an open source video delay/video feedback playground cobbled together out of raspberry pis, midi controllers, and various camera/video sources.  It is also a platform for DIY video art tools as well!  Once you have a Waaave Pool (or spectral mesh, its literally the same hardware running different firmware) you also have the ability to download and flash sd cards with some of the bonus images I’ve designed that you can then run on the same hardware!  Think of the Waaave Pool as like a video game system, like if you bought some kind of nintendo thingy it would most likely come with some kind of mario game but then once you have the system you can run other games on it just by powering down and swapping out the cartridge or whatever.  The difference of course is that this is an open source system, meaning that bonus images are distributed for free and also that the system is open for folks to build their own!  The Waaave Pools (as of v1.3) come with a heavily annotated Template project for designing yr own video synthesis and video processing tools with c++ and shaders!

Other fun bonus images out there right now for yalls to try are: Chromatic_Aberration1:the_search_for_sasquatch : a 4 band colorizer/solarizer effect with individual band LFOs for modulating hue and brightness

Super_Haeckel_Adventures_64: A superformula based video synth that allows you to draw a very wide range of organic morphing shapes, designed as a really handy seed for video feedback especially

Scrawl (written by Nichole Pichon)
(from the github readme) “Scrawl is a standalone RGBA shape generator/positioner with painting capabilities, full MIDI/keyboard and some mouse control for the Raspberry Pi (currently using 3b+(old hardware version)/3b).
This project was originally meant as a means to an end for my community theatre. DMX lighting can get very expensive when you are talking about moving heads and RGB color mixing(or any other colorspace). I wanted to try to make a project where I could replicate this behavior with a Raspberry Pi and a projector. There would be obvious limitations but it could also do things even the most expensive DMX light could not, at least in my head it would.“

Spread (written by Nichole Pichon) (from the github readme) “[This] colorizer works more as a series of keys within eachother where each key colors the same USB grabbed video with a different color. That allows for alpha blending between those layers (currently 7) which then makes for some interested ghosty/flowy type feedback possibilities that I don't think most people would expect in a colorizer. Randomizing colors per layers is possible. I've also been playing with the idea that each layer of key may have a different strobe amount (if turned on)“

Forthcoming bonus images from my end: Gleaming the Hypercuuube (just like that hypercube yalls may have seen me use in like 1 million instagram/fb videos)  with a couple of lfos for makin it do fun stuffs) and Cyber Zone 1979 (perlin noise terrain zooooooom) Forthcoming bonus images from yr end: ????? I can’t wait to see what people end up figuring out!



(notes: parenthesis (U) and (B) after the controls means Unipolar and Bipolar respectively. unipolar means that values go from 0-1, bipolar means that values go from -1 to 1. this means that if you want to set values to 0 on a unipolar knob then you turn it all of the way to the left and if you want to set values to 0 on a bipolar knob you set it at 12 o clock. Unipolar 0 on a slider means all of the way down, bipolar 0 means exactly in the middle. Most of these parameters we will assume are normalized, which means we will think of 0 as being all of the way off and 1 as being 100 percent on. This can get a little strange because some values are set so that they actually go from like -200 percent off to +200 percent on but bear with me, it is all happening for reasons! if the default parameter set is anything other than (0,1) or (-1,1) it will be shown in parenthesis as well. the framebuffer delay channel will be henceforth referred to as fb0)


1. Luma Key Level. (U)

This selects a brightness value in the video input channel to key fb0 into. For example, if I turn my Luma Key Level knob to 12 o clock, that means everything in the input channel with brightness less than 50 percent will be replaced by fb0. 0 means that none of fb0 is keyed in, 1 means that none of the input channel will be visible. When the luma key switch is flipped it just reverses the operation here so that if knob is at 12 o clock everything with brightness more than 50 percent will be keyed out.

2. Mix level. (B) (-1.1,1.1)

For values between 0 and 1 this functions as a fade between the input channel and fb0. For values outside of this range interesting distortions can happen. Strobing can occur when there are very short (less than 5 frames) delay times and negative mix values. Mix is downstream from Key so you can key and mix at the same time, the mixing will only affect the unkeyed part of the input channel though! The actual mathematics being performed is a linear interpolation (aka lerp in many programming languages) between each pixel. Let Input pixel be I, Mix level be M and fb0 pixel be F, then the value of each pixel will be set by I*(1-M)+F*M.

3. Fb0 Hue Attenuation (B) (.25,1.75)

This is a multiplier for fb0 hue. Because of the feedback loop involved, multiplicative operations have exponential effects so it is sometimes best to play around with very small changes with a very small delay time to get a feel for what kind of patterns and behaviors can emerge. Attenuating hue will often want to cycle through all the values in the spectrum so if you do not want your screen to be just rainbow zones 24 hours a day try playing around with the hue chaos controls as well.


4. Fb0 Saturation Attenuation (B) (0,2)

This is a multiplier for fb0 saturation. Turn all the off for greyscale feedback, crank it up for supersaturated feedback, play around with small negative values for soft trails


5. Fb0 Brightness Attenuation (B) (0,2)

This is a multiplier for fb0 brightness. Values around .8 or .9 will result in trails that fade away softly, values above 1 will clamp out and fill the screen.


6. Temporal filter mix (B) (-1.1,1.1)

For values between 0 and .99 the temporal filter can help smooth out some of the potential harshness, business, and/or strobing that can very often occur when using this system. For values over 1 the temporal filter goes into a fairly pure digital feedback mode and can slow things down considerably while still oozing along like a wet digital oil painting. For values less than 0 many interesting patterns can occur as well as some amount of strobing. The temporal filter is another linear interpolation function performed downstream from the keying and fb0 mixing.


7. Temporal filter strength (U)

This attenuates the brightness and saturation of the temporal filter to enhance complex pattern formation if desired.


8. Input enhance (U) (0,2)

This can be used to increase the brightness of the input channel which can be very helpful when working with lumakeying. There can also be some potential issues when keying or mixing that the input will not be as eye popping as the feedback so some enhancement can help keep everything more cohesive as well.
***interlude to explain a couple things***
if you are using the nanokontrol2 controller then you will notice for the sliders 9 through 16 there are 3 buttons next to each slider. for sliders 9 through 15 what these buttons do is control the total range for each corresponding slider. so for example no button pressed is a pretty small range, S toggled on means a Slightly larger range, M toggled is a Medium larger range, R toggled is a completely Ridiculous range. Larger range buttons bypass smaller range buttons so if M is toggled on and then R is toggled on then only R is active. Since each of these sliders will have 4 total ranges available each will be listed in order from default small to largest. The toroidal universe toggle will have drastic effects on xyz and rotational displacements as well, a toroidal universe means that that left/right and up/down edges of the screen wrap around much like in the video game Pac Man. Enabling toroidal universe means that feedback can wrap around the screen, when used in conjunction with extreme displacements this can result in extreme fractal patterns.

9. X displace (B) (-6.4,6.4), (-12.8,12.8), (-32,32), (-64,64)

This displaces the x position of fb0 measured in pixels. For a sense of scale internal processing is done at a resolution of 640x480 so a displacement of 64 pixels means 1/10 of the screen. Fractional displacement values correspond to averaging between pixels, so a displacement of .5 means an average between two pixels is being calculated implicitly. Loosely speaking displacement amount for a certain scale corresponds to the speed of feedback trails and coarseness or fineness of patterns emerging. Small displacement values result in smooth oozing trails and complex reaction diffusion structures. Large displacement values result in distinct copies of the source material repeating themselves. Ridiculous displacement values can be used for manipulating large scale abstract shapes in a strange feedback synthesis version loosely reflective of more traditional analog style video synthesis.


10. Y displace (B) (-4.8,4.8), (-9.6,9.6), (-24,24), (-48,48)

This works exactly the same as X displace but in the Y axis. I'm not going to just cut and paste everything from the x displace description and crtl-f replace all x with y. Do you ever read manuals where they do that for like 5 or 6 parameters? What on earth are they thinking? Why are manuals so often written as though they are instructing a robot in a task. Like its pretty likely that a human or human like intelligence is reading these words, is it actually that difficult to try to communicate with them using anything other than "the Z PLANE FILTER SYSTEMtm is alternuverted by our top secret secret proprietary QUATERNION ROTATIONALITYtm thus multimodal IIR filters ensue when the k plane of local resonance is hyperbolically mapped into the POINT AT INFINITYtm" being copy and pasted 18 times throughout the text.


11. Z displace (B) (.95,1.05), (.9,1.1), (.75,1.25), (.5,1.5)

The ranges for z displacement are calculated in terms of blowing up or shrinking as a percentage, so 1.5 means the image is increased in size by 150 percent and .5 means that the image is shrunk by 50 percent. The exact operation being performed is a simultaneous multiplication in x and y positions. Perhaps a more useful way to get a feel for how z displacement works is to turn on brightness invert, turn off toroidal universe, and just zoom in and out at each range. When you are comfortable with that range of things then zoom out as far as possible and then turn on toroidal universe. Ok start wiggling around x and y tiny bits now. Then try some rotations next. Make sure to get up and stretch your legs and arms and back out at least once every 45 minutes! Physical comfort is an important priority. I don't necessarily recommend smoking cigarettes but you could always try just pretending to just to have an excuse to step outside and stop staring at a screen at least 1nce per hour!


12. Rotate (B) (-PI/10), (-PI/5), (-2*PI/5,2*PI/5), (-8*PI/5,8*PI/5).

Note on terminology: these rotations are measured in radians not degrees, because degrees kind of only makes sense as a default measurement if one is a babylonian surveyor working in a sexagesimal number system. As this is not one of the more common job descriptions in modern life lets all agree to let degrees drift away. Honestly Tau seems like a better choice than PI as well but incremental updates are best to maintain backwards compatibility. Radians measure rotations as how far one has traveled around the perimeter of a circle with radius 1. 2xPI -> 1 full rotation, PI/2 is a 90 degrees, PI is 180 degrees, etc etc. Default rotation ranges are all set to generate variations on 5 fold symmetrical shapes at max as opposed to 4 fold symmetries. This is on purpose, try out 4 fold feedback symmetries and see if you can figure out why I would steer away from that as a default state.


13. Chaotic Hue mod (U)

Ok so to fully understand whats happening in a signal flow with this and the following two parameters check the appendix entry on "the logistic map and hue." Otherwise I will try to just stick with qualitative explanations for these parameters in this section. Chaotic Hue Mod sets a limit on the range that hue can cycle through. Very high (low) values for this will result in monochrome or very minimal color spaces. Wildly different behaviors can happen depending on the settings of HSB attenuation and Chaotic Hue LFO and Chaotic Hue Offset

14. Chaotic Hue LFO (U)

This is not exactly an LFO in the traditional sense of audio signal processing but it tends to feel like one in operation. This can be used to change the rate, texture, and patterns of hue cycling. For very small values smooth shifts occur. For larger values intense hue strobing can happen. Some certain settings can cause both saturation to drop out as well as brightness as well. If you are curious as to why messing around with hue values can affect saturation and brightness it is because HSB is not the native color space, RBG is. When RGB gets mapped into HSB and then we do very chaotic things to hue before mapping back into RGB, the effects can be unpredictable and can actually make the maps from HSB to RGB and back 'glitch out' a bit.


15. Chaotic Hue Offset (U)

This adds an offset to the hue. When Chaotic Hue mod is set to very high values resulting in a very restricted palette one can use the offset to choose the color. When Chaotic Hue LFO is running and you would like to mix up the cycling you can use this as well. Really the only way to get a handle on these 3 parameters is to use them heavily and changing them only in the default small ranges at first. Each parameter will have different effects depending on where the other two parameters are at. One very fun technique to use with these 3 parameters is to turn off keying, turn out mix to about .5, turn temporal filter to about .25 and temporal filter strength to about .5 and then experiment with different combinations of the Chaotic Hue parameters to use them as a kind of chaotic colorizer on your input!

16. Delay time (U) (1-60)

Delay time is measured in Frames. Waaave_pool operates at 30 frames per second so there is a total of 2 seconds of delay to draw from. Delays will behave quite differently depending on if the framebuffer is fed from the input or from the final output.

A. Fb0 Brightness Invert.

Switches on and off Brightness Inversion on fb0.  This multiplies the attenuated value from knob 5 by -1.

B. Fb0 Saturation Invert.

Switches on and off Saturation Inversion on fb0 same as A does to brightness!

C. Fb0 Hue Invert.

Switches on and off hue Inversion on fb0 , and doesn’t seem to work quite right yet but I’ll keep working on it!

D. Fb0 Horizontal Mirror.

These switches are mostly self explanatory arent they?

E. Fb0 Vertical Mirror.

Like you get the point by now.  its a toggle how complicated can it be?

F. Toroidal Universe.

Ok this is worth getting into a little bit.  When you switch the feedback wraps around the screen in various ways.  If something goes off the left side of the screen it will pop back over on the right side and verce visa.  Same thing for top and bottom edges.  When you zoom out super far the toroidal universe will fractalize everything. When you rotate in toroidal various kinds of mirrorings and wrapping swill happen at the edges.  Lots of Fun!

G. Alternate Horizontal Mirror.

Switches on a different mode for fb0 horizontal mirroring where the x displace slider also controls where the line of symmetry lays.  Good to mix things up if you like symmetries but dislike having radial compositions

H. Alternate Vertical Mirror.

you got this, right?

I.  Luma key switch.

This switch toggles back and forth between luma keying into the whites and luma keying into the blacks.  

You see theres a couple more buttons that haven’t been mapped to anything!  I gots plans for all of them no doubt.  S and M next to the Delay Time slider do some pretty crazy stuff in terms of rotating around the x axis and y axis, still needs some of the kinks worked out. The top left hand button above toroidal universe is ~supposed~ to clear the delay buffer, and yeah it does but it also like causes crazy frame drops and stuttering until another cc is adjusted so try to not touch that one, or if you absolutely need to make sure to twist another knob like immediately.  If you have some suggestions for control tweakings head over to the Video_Waaaves FB group and post away!


Theoretical Question: “Ok so I got one of the Editions without the midi controller and want to use my own instead, How do I do that?”
Well I am glad u ask thank u for yr continued interest!  Here is a list of the default midi cc’s for values, it is easiest for you to create a seperate scene for your midi controller remapping the internal cc’s to these!  Another option exists for editing the cc values within the c++ part of the Waaave Pool code but thats probably only a good idea if you know how a bit of programming and can figure that part out on yr own!  A third option is head over to the Video_Waaaves FB group and ask if anyone has posted up a scene for yr brand of midi controller already!

list of default midi ccs


Luma key -16


Mix -17


Hue_x -18


Sat_x -19


Bright_x -20


Temporal filter mix -21


Temp filter Q -22


Input boost -23


X displace -120


Y displace -121


Z displace -122


Rotate -123


Chaotic hue mod -124


Chaotic hue lfo -125


Chaotic hue offset -126


Delay time -127


***toggle switches***


bright invert -43


saturation invert -44


hue invert -42


H mirror -41


V mirror -45


Toroidal Universe -46


x skew -39


y skew -55


key swap b/w -62


alt h mirror -61


alt v mirror -60


on the nanokontrol for each of the sliders (midi cc values 0 through 6) there are three buttons alongside which I have programmed to change the total range of what each slider does. I will list those cc values here in the order (medium, large, ridiculous) (small is default setting. the larger buttons override smaller buttons so if medium, large, and ridiculous are all toggled then only ridiculous is actually enabled. ridiculous settings for the xyz and rotate plus toroidal universe is where very ornate fractal painting mode gets started

x displace (32,48,64)


y displace (33,49,65)


z displace (34,50,66)


rotate (35,51,67)


chaotic hue mod (36,52,68)


chaotic hue lfo (37,53,69)


chaotic hue offset (38,54,70)


Theoretical Question “Ok Heck and Alas, I did not get  anything with a midi controller and I just have  a usb keyboard to interact with, whatever am I to do?”
Word up My dogg I got u covered.  Here is a list of keyboard parameters controls! some notes on keyboard input: I set the default increments to be kind of small, you need to hold down a key to see the effect really happening.  Some folks find this confusing and frustrating at first and think that their controls are broken!  They most likely aren’t.  I super recommend at least trying out this mode of controls at first and seeing if you can get used to it, if enough people let me know that they want way larger increments per keystroke in the Video_Waaaves fb group then I will change things tho!

keyboard controls for each pair x/y means that the corresponding alphanumerical keys on a keyboard increment and decrement the values
a/z - fb0 z displace

s/x - fb0 x displacement

d/c - fb0 y displacement

f/v - fb0 hue attenuation

g/b - fb0 saturation attenuation

h/n - fb0 brightness attentuation

j/m - fb0 mix

k/, - fb0 lumakey

[/] - delay time

q/w - fb0 rotate

o/p - temporal filter

;/' - temporal filter resonance

l/. - input boost

e/r - chaotic hue mod

t/y - chaotic hue lfo

u/i - chaotic hue offset

-/= - y skew

9/0 - x skew

1 - clears the framebuffers

! - resets all controls

2 - invert framebuffer0 brightness

3 - invert framebuffer0 hue

4 - invert framebuffer0 saturation

5 - vertical mirror

6 - horizontal mirror

7 - toriodal universe

if you are using a midi controller then these keyboard controls will work as well but yall should take into account that using both the midi controller and the usb keyboard at the same time can do some really confusing stuff in terms how keyboard entry can offset ranges of the midi interfaces! so maybe fun if you like to be confused but just a heads up on that front.

TROUBLESHOOTING
FIRST THINGS FIRST:  make sure every component is plugged in (usb camera and usb midi controller/keyboard and the video cable) before you plug in the power supply!  This device does not support hotswapping so if you want to try different sources its best to power down and then swap them out.  If you have multiple midi controllers or multiple usb camera sources plugged in only one can be used with the default set up.  

”I have no output when using the analog video”

There are two main reasons why this might happen.  1. You don’t have the right kind of breakout cable or 2. There is something goofy happening with the configuration settings.  There is a simple way to diagnose which issue you are having.  Power up the unit with the composite breakout cable plugged in and wait about 30 seconds, then try plugging in an hdmi cable and see if you get output that way.  If you are getting hdmi output without an hdmi cable plugged in before powering on then it is an issue with config.txt, if not then it is an issue with the breakout cable! read on for solutions to both of these issues.
BREAKOUT CABLES: This unit requires a TRRS (tip ring ring sleeve) 1/8th inch to 3 rca cable like one of these (CTIA is one name for this standard, many cables designed for zunes and a generation or so of ipods follow this standard but not much other than raspberry pis do nowadays that I am aware of!) . Here is some information on rigging things up in a more DIY manner.  Note that many people have been able to use OMTP standard cables by going out thru the red rca cable.  Using video signals through audio cables works like 95 percent of the time but every so often you can come across a situation where it wont so heads up on that front.  
CONFIGURATION SETTINGS;  there is a text file config.txt which can be accessed by pulling out the sd card from the back and plugging it into a computer via some kind of usb adapter!  You will know that this needs to be acessed and double check the HDMI hotplug settings if you have the unit powered on and have no analog video out and are able to plug in an hdmi cable and get video out while it is still running.    


“I can’t get the keyboard controls to work” 

I have been told that if the  usb keyboard method is not working that you can try unplugging and plugging back in the keyboard while the pool is running and that usually works



"i want to make my own capture edition/use one of the images i got from github with a capture edition"

Ok so all of these default images i provide are default set to grab usb camera input, any one of them can be upgraded to picapture sd1 inputs tho! you will need a usb keyboard and probably is helpful to have a usb mouse as well. connect your capture hat to the waaave pool as instructed on https://lintestsystems.com/documentation and then boot up the waaave pool with the image you wish to swap to picap. this is best done on an lcd screen thru the hdmi out. for the purposes of this guide i will use the waaave_pool as an example but these steps work the same with any image

1. once it boots up and is running hit "esc" on the keyboard and you will exit to a desktop environment. click on or select the folder icon near the top of the screen and navigate to home/pi/openFrameworks/apps/myApps/WAAAVE_POOL_MAIN/src/ and then within src you will double click on ofApp.cpp. target="_blank">ofApp.cpp.

2. ofApp.cpp will open up in a text edition environment. scroll down a tiny bit and you will see a line that says "bool inputswitch=1", you will delete the 1 and replace it with 0. hit ctrl-s to save the changes. don't change anything else in this code (unless you know how to program in c++ and want to try modding things out!)

3. close the text editor and back in the folder navigate up two levels until you are in home/pi/openFrameworks/apps/myApps. right click on WAAAVE_POOL_MAIN folder and select "open in terminal"

4. a terminal opens up, waaave pool will try to automatically run, hit esc to cancel that operation (might take like 30 seconds for this). once you have a terminal prompt that you can type into enter "make", wait for all the coding things to execute, and then when you have a terminal prompt once again, plug a video source into the capture card and enter "make run" into the terminal



join the video_waaaves fb group to keep up to date on this and other softwares and hardwares that i make!
https://www.facebook.com/groups/440566853501750

If you appreciate the open source software and educational materials I provide and can afford to spare some cash it is highly appreciated! The more donations I recieve the more time I have to spend on developing these resources!