Documentation for v1.2.3

Basic Usage

Welcome to Beautiful Chaos, an experimental art app you can use to explore the curves and ripples of a mathematical equation brought to life in vivid color. When you first launch the app, you will be led through a short tutorial describing the three main ways to interact with the app:

Attractor Mode

Hold out two hands above the Leap Motion Controller, with your fingers spread out and your palms down, to warp spacetime and influence the beautiful chaos.



You can move your hands left and right, forward and backwards, and up and down. On screen, you’ll see three “space-time grids” that represent the positions of your hands as you move them. When you’re in this mode, you’ll see the outer two glowing orbs move with your hands:



To stop affecting the chaos, just close your hands into fists.

Camera Mode

Hold out one hand, with fingers spread out and your palm down, to rotate the view. Move your hand left and right, forward and backward, and up and down. You’ll see the middle space-time grid activate and move with your hand.


To stop moving the camera, just close your hand into a fist.

Leap Menu

Hold out one hand, with one finger pointed towards the screen, to activate the Leap based menu.



The pointer will follow your finger. Move it over a “wedge” and hold it there to select the menu item:


Mouse Menu

Below is a screen shot of the mouse menu, with labels added to show the main areas of the parameters, described in detail below.


Mini Control

Buttons from left to right:

  • Hide/show expanded parameters
  • Save image: Save a screenshot (launches a dialog box; supports .png, .tif, and .jpg image types)
  • Clear screen: Note that this only has a noticeable effect if the Fade slider is quite low
  • Tutorial
  • Fullscreen

Glow, Settings, Video Out

Buttons from left to right:

  • Toggle glow
  • Save settings: save the current state of the app. Note: the settings are saved to a file called BeautifulChaosSettings.xml, which should be located in a “Beautiful Chaos” directory inside your Documents directory.
  • Restore settings: restore the saved state of the app
  • Reset settings: reset everything to the default settings
  • Enable video output: using Syphon (OS X) or Spout (Windows), start streaming the video output of Beautiful Chaos. This is useful for VJs using tools like VDMX and Resolume, and can also be used to record high quality, high framerate video from the app (using, for example, Syphon Recorder).

Coefficient Controls

When you hold out two hands with your fingers spread out, you activate control of the coefficients that control the shape of the particle system. As you move each hand left and right, and forward and backward, you are changing the numbers that feed into the math equation that is generating the chaotic cloud of particles.

When the mouse menu is shown, you can see these four numbers changing as you move your hands, in the 2d user interface controls near the top of the screen. Each hand also controls one additional parameter, based on how the hand is rotated. The left hand controls the Spread, and the right hand controls the Randomness. When your palms are down, these values are high (the sliders are to the right). When your palms face each other (or away from each other), the values are low.

You can control how quickly the coefficients respond to your hand movements with the Sensitivity slider.

To freeze the coefficients, just close your hands into fists. The coefficients only change when both hands are out and your fingers are spread.

Camera Controls

When you hold out one hand with your fingers spread out, you activate control of the virtual camera. As you move your hand left and right, and up and down, the camera orbits around the chaotic cloud. Move your hand forward (towards the screen) to zoom in, and backwards (away from the screen) to zoom out. Rotate your hand to roll the camera.

You can move your hand in multiple directions at once. If the mouse menu is visible, you will see the buttons in the camera control section light up as your hand moves around. If you are careful, you can find a spot in the center where your hand is out but the camera isn’t moving at all.

You can control how quickly the camera moves and orbits with the Cam Sensitivity slider.

To freeze the camera, just close your hand into a fist. The camera only changes when your hand is out and your fingers are spread. Note that there is a bit of elasticity in the camera’s movement – it will ease into a stop.

Look Controls

Together, Opacity, Fade, Exposure and Gamma control how the particles are drawn to the screen.

  • Opacity: higher values make the particles more opaque (less transparent) for more of a grainy look
  • Fade: higher values cause the image to fade away faster; lower values cause the image to leave trails. All the way at the left, the image will not fade at all.
  • Exposure: higher values make the image brighter and more blown out
  • Gamma: higher values give the image more contrast; lower values bring out the detail in the areas of the image with less accumulation

There are three look presets (Looks) that will set these four sliders to nice values:

  • Look 1: the chaotic cloud pulses and shifts and feels very responsive when you control the coefficients or move the camera. You will see all sorts of interesting motion inside the particle system, especially if the Randomness is high.
  • Look 2: kind of like being in a hazy dream. The image fades slowly so it won’t get completely blown out. Creates nice still images.
  • Look 3: the image fades very slowly and accumulates a lot. Creates very nice still images, and is good for “light painting”.

If your goal is to create the highest quality still image possible, you might explore the chaos with Look 1 or 2, and then switch to Look 3 and tweak the Exposure and Gamma until you’re happy with the result, then save the image.


Beautiful Chaos v1.2.x was lovingly crafted by fine artist and programmer Nathan Selikoff using Cinder, an open source library for professional-quality creative coding in C++. User interface icons licensed from

Keyboard Shortcuts / Advanced Features

There are a number of keyboard shortcuts, some of which duplicate user interface elements, and some of which access advanced functionality.

  • 1, 2: move the left hand coefficient control left and right
  • 3, 4: move the left hand coefficient control down and up
  • 5, 6: move the right hand coefficient control left and right
  • 7, 8: move the right hand coefficient control down and up
  • 9, 0: move the Spread slider left and right
  • -, +move the Randomness slider left and right
  • , and . move the Cam Sensitivity slider left and right
  • [, ]: move the Opacity slider left and right
  • {, }: move the Fade slider left and right
  • ppause the app. Note that any additional interaction with the app will cause it to unpause.
  • o: toggle whether the app will pause by default when it becomes a background app (e.g. when you Alt- or Cmd-tab away from it to another application).
  • ssave a screenshot image. Note that using this shortcut will save the image with an automatically generated filename, in PNG format, in the “Beautiful Chaos” directory of your Documents directory.
  • h: hide the mouse menu completely, and hide the mouse cursor (press again to show). Useful for performances / presentations.
  • Cmd-f: toggle fullscreen
  • /: clear the screen
  • ?: show the tutorial
  • m: toggle the mouse menu
  • g: toggle the glow
  • y: toggle video output
  • Cmd-s (OS X) / Ctrl-s (Windows): save settings
  • Cmd-o (OS X) / Ctrl-o (Windows)restore settings
  • Cmd-n (OS X) / Ctrl-n (Windows): reset settings
  • SPACE: fade the screen to black (press again to fade in from black). Useful for performances / presentations.
  • ESCquit the app

Multi Display Support

Multi display support is designed for VJs and performers, so they can have one window with all of the menus available, and a secondary display (which could be a monitor or projector) that just shows the animated particle system.

Since this is an advanced feature, it is activated via keyboard shortcuts only.


  1. Toggle the secondary window by pressing the back tick (`) key or the ‘w’ key on your keyboard. A second window should open that shows just the particle system, without any user interface.
  2. Drag this second window to your performance monitor or projector.
  3. Press ‘f’ on your keyboard to make the secondary window fullscreen.
  4. You can also select the primary window and press Cmd-f (OS X) / Ctrl-f (Windows) to make that window fullscreen as well.
  5. If you are using Beautiful Chaos for performance, you may also want or need to override the default feature that pauses the app when it loses focus (i.e. when you Alt- or Cmd-tab away from it). To do this, just press ‘o’ on your keyboard.

Questions? Problems? Feature Requests?

Please leave a comment below or email [email protected].

2 Responses to “Documentation for v1.2.3”

  1. gerardo

    It’s possible to change the output resolution? i need to output in 800×600 for resolume. The actual output it’s so big, lag it’s inevitable on resolume.

    • nathan


      There are two hidden settings you can play with that may increase the framerate, though the image passed to Resolume will always be square. FboResolution is the width of the square texture that the particles are initially rendered into (2048 by default). OutputVideoResolution is the width of the texture that is sent to Syphon/Spout (also 2048 by default on supported graphics cards).

      Open Beautiful Chaos and save the settings (should be Ctrl-s on Windows or Cmd-s on Mac… you should see a confirmation message). Then open up Documents\Beautiful Chaos\BeautifulChaosSettings.xml and add the following parameters:

      <FboResolution value="1024"/>
      <OutputVideoResolution value="1024"/>

      And you can play with the numbers from there. Let me know how that works.