Painting With Light Manual

NOTE: This manual is a work in progress!


Painting With Light is a complete video mapping tool that enables anyone with even basic technical skills to use their computer to paint with static and moving images through any video projector onto 3D physical objects.

Originally released in 2013, it is an ongoing project for digital artist Alex May who uses it for his own installations and performances, and has made the software available with the aim of democratising access to video mapping technology for all.

1.1.What is Video Mapping?

While video projectors are designed to project a single video image onto a screen or wall, we can use the advanced graphics hardware inside your computer to combine several different images at once and position them anywhere on screen.  When we align these images so they line up with physical objects, this is called video mapping.

Alex May - Painting With Light - Tate Modern

The image above shows an example live performance that was made using a single video projector, cardboard boxes, and Painting With Light.  All the different images are separate video files that have been individually loaded and placed on the boxes using Painting With Light.

This technique (also called Projection Mapping) has been adopted by digital artists around the world. Painting With Light is an easy to use video mapping tool designed to let anyone explore this exciting digital medium.

1.2.What can I do with Painting With Light?

Painting With Light is designed to be a creative and playful tool that encourages anyone to experiment with using video mapping in new and interesting ways.

It can be used for:

  • Art installations and performances
  • Stage lighting for music, dance, theatre, and conferences
  • Teaching video mapping in schools and universities
  • Guerilla video projection and protests
  • Parties!
  • Decorate the outside of your house for New Years Eve, Christmas, Halloween, Thanksgiving, etc
  • Creative signage for shops and trade shows
  • Music videos
  • Creating digital artworks and video paintings
  • Projecting on snow (and nature in general!)

And so much more…

1.3.Do I need a video projector to use PWL?

No, although Painting With Light is designed to be used for video mapping with a video projector, on its own it is still a unique video painting software with which you can create images and videos that can be shared on-line and beyond.


Painting With Light is available for Microsoft Windows and Apple OSX

Download Painting With Light

A Linux version is in development but it is not available yet.

2.1.Windows Installation

1. Open the ZIP archive by double-clicking on it

If the archive doesn’t open, you’ll need to install an application such as WinZip

2. Double-click on the installer application and follow the steps in the wizard

2.2.OSX Installation

  1. Open the ZIP archive by double-clicking on it
  2. Drag the Painting With Light folder to your Applications folder (or leave on your desktop, if you prefer)
  3. Open the Painting With Light
  4. Double-click on the Painting With Light application

3.Quick Start

To try the software out, you can use Painting With Light on a single screen, without a video projector.

You can draw on the Output Window or the Work Area but it is recommended to get used to working on the Work Area as when you are outputting to a video projector, it will save you moving your mouse to the other screen.

Drawing With Video

  1. Choose the Brush Tool from the Main Toolbar
  2. Choose a texture from the Textures Window
  3. Click and drag onto the output window

Mapping Textures

  1. Choose the Quad Tool from the Main Toolbar
  2. Choose a texture from the Textures Window
  3. Click and drag onto the output window to draw out a box shape
  4. Move the corner handles
  5. Press return on your keyboard or click the Tick icon on the Main Toolbar

4.Demo Limitations

When run in demo mode, Painting With Light has the following limitations:

  • It won’t load or save paintings
  • The output, saved images, and rendered video will have a watermark added to them.
  • Spout output is limited to two frames per se

These limitations can be removed by purchasing a licence from the shop for the one-off low price of just £49.99 (approximately €70, $78 US).

You will receive your serial number straight away via email and it can be entered straight into the software (no need to install a different version) via the Licence Menu.

Your licence entitles you to all future updates of the software.


When you open Painting With Light for the first time you will notice two things:

  1. It looks a bit like a painting program
  2. As well as the main window, it opens a separate “Output” window

6.Main Window Layout

The main window consists of:

  • Menu
  • Tool bars
  • Work Area (the central black section)
  • Status bar
  • Sub-windows

The tool-bars and sub-windows can all be moved around in the main window.


Painting With Light has a range of tools for drawing on screen.

Because Painting With Light is used in a wide variety of situations, some of the tools are designed for real-time (performance) based mapping where you use your mouse, tablet, or other input device to draw out video dynamically, and others are designed to be more structural, where you can accurately position elements and re-edit them later, if you require.

Each tool will use the current drawing colour, the current brush (if selected), and the current texture (if selected).

You select brushes and textures by clicking on their thumbnail in the Brushes and Textures windows.

To stop using a brush, click the ‘Clear Brush’ button in the toolbar, or click the ‘Clear’ button in the Brush Window.

To stop using a texture, click the ‘Clear Texture’ button in the toolbar, or click the ‘Clear’ button in the Texture Window.

6.1.1.Freehand Tools

There are two freehand tools: the Brush and the Roller.

They are used by clicking and holding the left-mouse button on the work area, and moving the mouse to draw a path.

When working with these tools, it is important to remember that the Stroke Window controls how the path is drawn and the Mapping Window controls how the brush and texture are applied to the path.

These tools work fine with a mouse but are even better with a graphics tablet and can additionally use the pressure that you press with to control the size and other attributes of the path that you draw.

Because these tools are designed for real-time use, you cannot go back and edit a path that you have drawn, although you can undo and redo them. Tool

The Brush is a freehand tool that follows the line that you draw using small squares spaced out along its length.

Each square will use the current colour, texture, and brush settings.

The Roller is a freehand tool that follows the path that you draw with a thick line.

Roller uses the current colour, texture, and brush settings.


6.1.2.Modifiable Tools

The following tools can be modified.

The small boxes that you can move when creating or editing shapes are called handles.

Moving Handles

  1. Click and hold the left mouse button on one of these handles
  2. Drag the mouse to move the handle
  3. Release the left mouse button

HINT: Holding down the Ctrl key on your keyboard when editing will slow the speed the handle moves, allowing precise positioning control.

HINT: Holding down the Alt key on your keyboard shows or hides the handles (depending on the state of the Show Edit Controls button on the Main Toolbar

Moving Shapes

  1. Hold down the Shift key on your keyboard
  2. Click and hold the left mouse button inside the shape (not on a handle)
  3. Drag the mouse to move the whole shape
  4. Release the left mouse button and the Shift key

HINT: Holding down the Ctrl key on your keyboard when editing will slow the speed the shape move, allowing precise positioning control. Tool

The Quad Tool is one of the easiest but important tools in Painting With Light.

It draws a single box with a texture applied to it and each corner is independently positionable giving precise control over it’s position.

As the corners are adjusted, Painting With Light will dynamically adjust the perspective of the texture to make it appear correct when projected.

The Quad tool is ideal for applying video to flat surfaces but you will probably find it is one of your most used tools.


  1. Select the Quad Tool from the Main Toolbar or press Ctrl + 3 on your keyboard
  2. Move the mouse cursor to the Work Area
  3. Click and hold the left mouse button
  4. Drag the mouse down and to the right
  5. Release the left mouse button when the Quad is at the right size

Polygon is used to draw shapes that have straight edges.

  • Click once to create the first point of the shape
  • Move the mouse and click again to draw the second point.  A line will connect these two points.
  • Move the mouse and click a third time to create a triangle.

Add more points by clicking the mouse.

To remove a point, click on it with the right mouse button.

Lines draws a series of line segments.

  • Click once to create the first point
  • Move the mouse and click a second time to create the second point

Clicking again will start a new line.

Path draws a series of lines from a starting point to an ending point.

  • Click once to create the first point
  • Move the mouse and click a second time to create the second point

Clicking again will add more points to the path.

Delete a point by clicking on it with the right mouse button.

Loop draws a loop of lines from a starting point to an ending point.

  • Click once to create the first point
  • Move the mouse and click a second time to create the second point
  • Move the mouse and click a third time to form the loop

Clicking again will add more points to the loop.

Delete a point by clicking on it with the right mouse button.

Rays draw a series of lines that all start from the first point that you create.

  • Click to place the starting point
  • Move the mouse and click again to create the first ray
  • Move the mouse and click again to create the second ray

You can remove a ray by clicking on its point using the right mouse button.  You can’t remove the starting point.

Bezier is used to draw shapes that have curved edges.

  • Click once to create the first point of the shape.  You will see a point with two handles attached to it (one above, one below)
  • Move the mouse and click again to draw the second point.  An ellipse will be drawn between the two points.

Moving the handles will affect how the outline of the shape is drawn through each point.

Double-clicking on a point (not its handles) will change its type.  The handles will be square for linked mode, where moving one will move the other, or a diamond shape, where each handle can be moved independently, creating sharp corners.

Add more points by clicking the mouse.

To remove a point, click on it with the right mouse button.

6.1.3.Full Screen Quad (FSQ)

The Full Screen Quad (FSQ) fills the whole screen.  It is useful for creating backdrops and also when working on more complicated compositions.

Create a FSQ by clicking once with the mouse.


Painting With Light has many windows.  Most are relatively simple such as the Colour Window, which allows you to change your current drawing colour, while a few are more complicated, such as the Mapping Window, which controls how video is mapped onto the shapes that you draw.

Because there are so many windows, Painting With Light is designed so you can show (or hide) the ones you are currently (not) using, or stack them on top of each other to create your own interface that you are comfortable working with.

Opening and Closing Windows

To close a window, just click the little ‘X’ in its top-right hand corner.

To open it again, go to the Window Menu where you will find a list of all the available windows.  If they have a tick by their name, they are open.  Just click on the name to toggle between opening and closing.

Moving and Stacking Windows

All of the smaller windows that you will be working with are called dock windows; they can be ‘docked’ at various positions in the main window to create the user interface that works for you.

As you drag a window around the main window, you will see the layout shifting as it tries to make room for you to place the window.

There are four regions where you can dock the windows: top, left, right, and bottom.

You can also stack windows on top of each other, which will create named tabs in each of the dock areas.


Bonjour is a technology that allows software applications to easily find each other over a network.

It is built in to Apple OSX and is available to download for Windows 

Painting With Light supports Bonjour so that when you are controlling it remotely using Open Sound Control (OSC) or other protocols, it saves you from having to find your computers network address.

Window Options

If you are running Painting With Light on more than one computer in a network you will want to give each one a different name so you know which one you’re talking to.

Painting With Light will receive commands on this port.  Its range is 1024-65500.

Bonjour won’t be active unless this button is selected


Brushes are images that can be used to mask certain shapes when drawing.

Brushes are just PNG images.

Loading a brush

  1. Click on the “Load…” button to bring up a file chooser.
  2. Choose a PNG image
  3. A thumbnail of the image should appear in the Brush Window

Choosing a brush

  1. Click on the thumbnail of the brush you want to use.
  2. A border will appear around the thumbnail to show you it is selected

Stop using a brush

  1. Either click on the ‘Clear’ button in the Brush Window or click on the ‘Clear Brush’ button in the Main Toolbar
  2. The border around the thumbnail in the Brush Window will disappear 

To remove a brush

  1. Click on the thumbnail of the brush you want to remove
  2. Make sure the border appears around the thumbnail
  3. Click on the ‘Remove’ button in the Brush Window
  4. The thumbnail will disappear, although it will still be shown in your painting if it is being used.


The Colour Window is used for choosing the colour you wish to draw with.

The chequerboard pattern at the top of the windows shows the transparency of the current colour.  Clicking on it towards the left hand side makes the current colour more opaque (less transparent), and clicking towards the right (where the chequerboard is more visible) makes the current colour more transparent.

Double-clicking anywhere on the transparency bar brings up a colour chooser.

The blocks of colour in the middle of the window use colour theory to provide a quick palette of hues and lightnesses calculated from a base colour that you have chosen.

  • Top-Left = Analogous Left
  • Top-Middle = Base Colour
  • Top-Right = Analogous Right
  • Bottom-Left = Split Left
  • Bottom-Middle = Compliment
  • Bottom-Right = Split Right

Each of these colours is further split into three bands.  The calculated colour is in the middle band of each block.  Above that is a lighter shade, and below it is a darker shade.

The two sliders at the very bottom of the Colour Window control the range of the calculated colours.  The slider on the left controls how far the Analogous and Split colours are from the Base and Compliment colours.  The slider on the right changes the range of brighter and darker shades for each colour.

Between the colour palette and the sliders are a further six blocks of colour.  Each of these can be selected by clicking on them, and changed by double-clicking on them.


Gradients define transitions between colours.  We can say that a gradient begins with black and ends with white and the resulting gradient will be a smooth transition through all the shades of grey.

You can easily create gradients in Painting With Light and use them as textures with all of the drawing tools.

The gradients window contains a list of previously defined gradients that you click on to select, and the tools for adding, removing, and editing gradients.

Add a Gradient

  1. Click on the ‘Add’ button in the Gradient Window
  2. A new black to white gradient will appear, ready for editing

Remove a Gradient

  1. Click on the gradient that you want to remove
  2. Press the ‘Remove’ button in the Gradient Window

Add a Colour

  1. Click once anywhere along the gradient editor to add a new colour handle at that point

Change Colour

  1. Double-click on the colour handle that you want to change
  2. Choose a new colour from the window that opens

Move Colours

  1. Click and hold the left mouse button on the colour handle that you want to move
  2. Move the mouse left and right to reposition the colour handle

NOTE: you cannot move the starting and ending handles

Remove a Colour

  1. Click and hold the left mouse button on the colour handle that you want to remove
  2. Move the mouse either left or right off the end of the gradient editor to cause the colour handle to disappear




The Mapping Window controls how the currently selected texture is applied to the current tool that you are using.

Painting With Light offers you an unprecedented level of control over this process to encourage creatively experiment usage.

Map Mode

Controls how the points of the shapes that you draw are mapped to the image data in the texture.

  • Stretch – the texture is stretched our over the whole screen.  Drawing in this mode will seem to ‘reveal’ the texture.
  • Fit – the texture is fitted to the whole screen keeping its aspect ratio correct, and will also be ‘revealed’ when drawing.  Depending on the resolution of your screen and the texture, you might see black bars at the top/bottom of the texture.
  • Fill – the texture fills the whole screen keeping its aspect ratio correct, and will also be ‘revealed’ when drawing.  Depending on the resolution of your screen and the texture, the sides might be chopped off to fit the video in vertically.
  • Vertex – the texture is pinned to the corners of the shape you are drawing.  This is the most useful mode when using the Quad or Brush tools.
  • Length – the texture is stretched over the length of the shape.  This really only makes sense when used with the Roller tool.
  • Time – the texture is mapped onto the shape depending on how fast it is drawn.  Again, this really only works with the Roller tool.
  • Input – the texture is stretched our over the whole screen and the Brush or Roller will take the colour of the texture at the point they are drawn.

Mapping Controls

In addition to the Map Mode, the mapping can be further modified by using the following mapping controls:

  • X Scale (%) – scales the texture horizontally
  • Y Scale (%) – scales the texture vertically
  • Rotation (degrees) – rotates the texture
  • X Offset – moves the texture horizontally
  • Y Offset – moves the texture vertically
  • X Shift – moves the texture horizontally (after scaling and rotating)
  • Y Shift – moves the texture vertically (after scaling and rotating)


  • Repeat – the texture will be repeated
  • Clamp – the texture will stop at its edge
  • Mirror – the texture will repeat but it will be mirrored creating a kaleidoscope effect


When you draw with the Roller it normally will use one copy of the texture over its whole length.  By changing the Cycle Period you can have it draw multiple copies of the texture.

Cycle Speed introduce a very simple animation to the texture you are using.  It will shift the texture horizontally along its length over time.


6.2.9.Shape Edit

Every shape that you draw will appear in the Shape Edit Window.

To select a shape, click once on its name with the left mouse button

To edit a shape, double-click on its name with the left mouse button

Shape Naming

Every shape has a generic name given to it when it is created.  As you create your composition, you will probably want to edit certain elements and it’s a lot easier to find them if you give them a recognisable name.

  1. Click on the shape you want to rename
  2. Change the name at the bottom of the Shape Edit window

Shape Order

All shapes are drawn in the order that they were created inside their layer.  You can change this order by selecting the shape and using the shape order buttons:

  • Move Back – moves the shape back in the drawing order
  • Move Forward – moves the shape forward in the drawing order
  • To Back – the shape will be the first drawn in its layer
  • To Front – the shape will be the last drawn in its layer

Deleting a Shape

Pressing the ‘Delete’ button will delete the currently selected shape.

Changing Shape Visibility

You can hide shapes by selecting them and pressing the ‘Visible’ button.

6.2.10.Spout (Windows only)

Spout is a collection of tools for sharing live video textures between various software applications running on your computer.  It works almost exactly like Syphon on OSX.

By supporting Spout, Painting With Light can take the input from a wide range of other software such as:

See the Spout website for a full list.

Using Spout in Painting With Light is very simple as it will automatically detect the available streams as they become available.

Just click on the stream you want to use in the Spout Window and draw normally.

Spout Sender

Painting With Light also has the ability to send its own output via Spout.  Just click the ‘Send output via Spout’ box to enable/disable sending.

6.2.11.Syphon (OSX only)

6.2.12.Stream Input


The Stroke Window controls how the path is drawn when using the freehand tools.  It has no effect for most of the modifiable tools apart from setting the width of the line tools.


When drawing a path, your mouse (or tablet) sends multiple messages to Painting With Light as it moves saying “the cursor is now here”.  How we choose to join up these individual points is controlled using interpolation.

  • None – just use the raw data from the messages
  • End Points – use the start and end point
  • Linear – draw straight lines between each position
  • Bezier – draw curved lines between each position

Rotation Type

  • Angle – don’t rotate along the path, just use the angle value
  • Initial – just use the first angle along the path
  • Normal – rotate the shape along the path following the drawn curves
  • Tangent – rotate the shape to face ‘outside’ the path that you are drawing

Control Type

There are many controls in the Stroke Window and it can get a bit confusing so the Control Type sets how much of this information to show you.

  • Simple – just show Smoothing, Spacing, Diameter, and Rotation, and use simple sliders as controls
  • Simple + Random – as above but also include the randomising controls for rotation and position
  • Full Control – just show Smoothing, Spacing, Diameter, and Rotation but with full controls
  • Full Control + Random – show all controls

Full Control

When using either of the Full Control modes, the following controls are available:

  • A numeric value that you can type into
  • — button – reduce the value by 10
  • – button – reduce the value by 1
  • + button – increase the value by 1
  • ++ button – increase the value by 10

For some of the controls there is an additional drop-down that will apply changes over the length of the path:

  • Off – use the same value along the whole path
  • Fade – fade the value to zero at the end of the path
  • Pressure – use the pressure value from a graphics tablet as the value for this control


Smoothing controls how smooth the resulting path will be.  Using a small value will result in a path with sharp corners and turns, a large value will create very smooth paths.


Depending on how fast you move your mouse, the messages that Painting With Light receives about the cursor position might be quite far apart (if you’re moving the mouse quickly) or very close together (if you’re moving it slowly).

The Spacing control recalculates these positions so that they are drawn at equal distances along the path.

Setting the Spacing to zero will disable the calculation and just use the raw cursor positions.


Diameter sets the width of the line that is drawn along the path.


Depending on the Rotation Type setting, the Rotation value is added to the angle that the tool draws at.

Randomise Position

Rather than just positioning the drawn points along the line, you can add some randomness to the result by increasing the Randomise Position values.


The Textures Window lets you load images and video files into Painting With Light.

A texture is the common name for some kind of image that has been copied to your computers graphics processing memory ready to be applied to the things that you are drawing.

Technically Gradients, Brushes, Video Input, Spout, Syphon, etc are all textures too, but let’s not worry about that for now…


You can load most common image and video files into Painting With Light but getting the best performance might take a little preparation.

These days high definition (HD) video is commonplace, with even our mobile phones being able to happily record videos of 1920×1080 pixels, and take photos of 5312×2988 pixels.  While just about any modern computer is able to play maybe one or two HD videos simultaneously, they’re not really designed with this in mind (most people usually only watch one video at a time).

With video mapping you will probably want to use many videos at the same time, so we have to work with your computer’s hardware in order to make that happen successfully.

There is a section in this manual that will explain in detail the best approaches for preparing your content.

Loading a Texture

  1. Click on the ‘Load…’ button
  2. Choose the image and/or video file(s) to load
  3. If Painting With Light is able to load the file(s), the thumbnail images will be shown in the selection area

Use a Texture

  1. A texture can be selected be clicking on it.
  2. A border will appear around the selected texture

Remove a Texture

  1. Click on the texture you want to remove from the selection panel
  2. Press the ‘Remove’ button

Control Playback

By default, all videos in Painting With Light playback in a loop.  If you want to control when the videos start playing, you can do that with the playback buttons.

There are two sets of buttons, ‘Current’ for the currently selected video, and ‘Global’ for all videos.

  • << – Rewinds the video
  • || – Pauses the video
  • |> – Plays the video (when paused)


Painting With Light supports undo, allowing you to step backwards through the history of what you have been drawing.

How many steps of undo history that are recorded is set in the options (Edit Menu -> Options… -> General -> Undo Steps).

The Undo Window shows the currently recorded steps and clicking on any of them will take you back to that point.

6.2.16.Video Input

Painting With Light can use most cameras and other live video input devices as a texture that you can draw with.

Just click on the input that you want to use and draw normally.

Because of the extremely wide variety of video input devices in the world not all of them will be compatible with Painting With Light.  If the device doesn’t show up in the list, or it doesn’t produce any image when you select it, let us know and we’ll look into it.

Grab Screenshot

You can grab a screenshot from your video input device by clicking on the ‘Grab Screenshot’ button.  It will be saved in your default images folder on your system in a sub-directory.

The screenshot will automatically be loaded into the Textures Window ready for use.

6.2.17.Video Output

You can use the Video Output window to save the output from Painting With Light for use in other applications.

It gives you the option to save in the following formats:

  • MP4 Video – general purpose, good for uploading to the Internet
  • H264 Video – special format for use with Raspberry Pi seamless looping
  • PNG Sequence – save each frame of video as a lossless PNG image
  • JPG Sequence – save each frame of video as a compressed JPG image


The quality setting only applies to MP4 Video files and lets you select the balance between speed and quality when compressing the images.

Slow speeds will produce better looking videos (and possibly smaller, too) at the expense of compression speed.  ‘veryslow’ really is Very Slow!

Faster speeds will produce less quality (and generally larger files) but at much faster compression rates.

Which one you use will be somewhat dependent on what quality you are after, and how patient you are.


This sets the resulting video size.  You can choose some default settings or set your own size using the ‘Custom’ settings.

NOTE: This doesn’t affect the Output Window size.  If you want to record a HD 1920×1080 video, make sure your Output Window is set to at least that resolution too else you will get low resolution results.  You can quickly set the Output Window size from the Output Menu -> Set Size.


This value is the duration in seconds to record for.  If you want to record 5 minutes of video, enter 300 (5 minutes x 60 seconds) here.

Leaving the value as zero will mean it keeps recording until you manually stop it, or it encounters an encoding error (such as running out of hard drive space).

Setting the output directory

Click on the ‘Directory…’ button to choose where Painting With Light will put the recorded videos.

Each video will be named with the date and time the recording began so they will never overwrite each other.


Pressing the ‘Record’ button will start the recording process.

Internally, Painting With Light will reset its internal clock so all videos will automatically rewind to the beginning.

Recording will only stop when it has hit the Duration number of seconds, or you press the Record button again, or there is an error in compression. Pi Seamless Looping

Once you’ve completed the creation phase of your painting, you might find that you don’t want to leave your expensive laptop lying around connected to the projector.  This is especially true if the work you are showing is going to be on display for a long period of time.

The solution is to render out the video of your painting and run it off some kind of playback device.  Here we run into a few problems:

  • Most media players are designed to be plugged into TV’s and won’t output the same resolution as your laptop.  This really messes up all your hard mapping work!
  • Most media players are not designed for ‘seamless looping’ instead you will often get up to 2 seconds of black video whenever the video goes back to the beginning.  This really breaks the immersion of the mapping effect.

Fortunately there is a cheap and easy solution that solves both of these problems perfectly, and it only costs about £30: the Raspberry Pi.

This small but perfectly formed computer can easily handle playback of HD video (up to 1920×1080) and is small enough to sit out of the way on top of your projector and, if the worst comes to the worst, if it gets stolen it doesn’t cost the earth.

The hard work for this process was mostly done by The Curious Technologist, who provides ready-to-go downloadable images for various models of Raspberry Pi.

Once you have this installed and running, you just need to export your Painting With Light video (using the Video Output Window) in H264 Video format.  This file can then be copied to a USB stick, which is then plugged into the Raspberry Pi, and the Seamless Looper will take care of the playback.  You can now take your laptop home!

There is of course a downside to this solution, which is that currently it doesn’t support playback of synchronised audio.

6.3.Edit Mapping

Controlling how a texture is applied to the current tool you are using is controlled via the Mapping Window, which provides simple transformations such as scaling and rotation.

This type of control isn’t always suitable for the mapping that you are trying to achieve so Painting With Light also provides a powerful mapping editor that allows you to control exactly how the texture is applied.

NOTE: The Mapping Editor only works with modifiable tools, not the freehand ones like Brush and Roller.

Accessing the Mapping Editor

To use the Mapping Editor, you must be currently editing a shape.  If not the Mapping Editor won’t be available.

Click the ‘Edit Mapping’ button on the main tool bar.  You will see the Work Area change to have a blue background, and it will be filled with the currently selected texture.

You will also see all the handles and outline of the shape that you are currently editing.

You are able to drag the handles around the Work Area but you should notice that this isn’t changing the shape of what you are drawing at all, it is selecting where each point should look at on the texture to get its image data.

6.3.1.Multi-Channel Video

You might find yourself in the situation where you want to have two or more objects that have video mapped to them and you want these videos synchronised.

There are two ways to accomplish this:

  1. Put all the videos into a single video and use the Mapping Editor
  2. Control the playback using an external application via Open Sound Control (OSC)

Here we will discuss the use of the Mapping Editor.  See the MIDI and OSC section for details about the second option.

If we have two videos (for instance) we could combine them into one video so they sit side by side.

As Painting With Light now only has to playback this one file, they will always remain perfectly synchronised.  Now we just have to map it correctly.

Draw out your mapping shapes, and for each one, use the Mapping Editor to move the handles of the shape so that it only takes one side of the texture.  Repeat for the other shape.

This simple process can obviously be scaled up to have many video combined simultaneously.

NOTE: If you want more than 2 videos, lay them out in a grid, rather than just side by side (which would result in a very wide video indeed!).  For example, 16 videos should be combined in a 4×4 grid.

7.The Output Window

The design of Painting With Light is that you keep the main window on your laptop screen (or computer’s monitor) and the output of what you are drawing goes to the video projector.

The separate Output Window is the one that we’ll be sending to your video projector.

If you are using Painting With Light without a video projector (or second monitor) then you can ignore the Output Window for now and come back to this section when you want to set it up.

7.1.Full Screen Output

The Output Window can be made to go Full Screen either via the Output Menu or pressing Alt+Enter on your keyboard.  If it opens on your laptop screen or main monitor by mistake, press Alt+Enter again to take it out of full screen mode, and then press Alt+Enter a final time to make it go full screen on the projector.

8.Multiple Monitor Mode

When you plug your video projector into your computer, the operating system will initially decide how it should be used.  There are basically four options that all have their uses in various situations:

  1. Ignore the projector and just use your existing laptop/monitor
  2. Turn off your laptop screen/monitor and only output to the projector
  3. Send the same image to both the laptop/monitor and the projector
  4. Treat the laptop/monitor and projector as entirely independent screens

To get the most out of Painting With Light, we want the 4th option so the main window is on your laptop/monitor and the output window just goes to the projector.

8.1.Multiple Monitors on Windows 7, 8, 8.1

Since Windows 7 Microsoft introduced a very useful shortcut for choosing which monitor mode to use:

  1. Press the Windows Key + P
  2. A window should popup with the following options:
    – Computer Only
    – Duplicate
    – Extend
    – Projector Only
  3. Choose “Extend”

Once the mode has been updated, you should be able to move your mouse cursor off the right hand side of your laptop/monitor screen and see it appear in the video projector output.

8.2.Multiple Monitors on OSX

Setting up the video projector under OSX is slightly more complicated than Windows but here is how to do it:

  1. Open your System Preferences from the Apple Menu
  2. Click on the “Displays” icon
  3. Click on the “Arrangement” tab
  4. At the bottom of the window, make sure “Mirror Displays” is turned off
  5. After a few seconds you should see that the projector is showing a second desktop.
  6. If you find that it puts your desktop icons on your projector output then, in the Arrangement Window (where you will now see the two blue boxes that represent your laptop/monitor and your projector outputs) drag the little white bar from the top of the projector box to the laptop/monitor box
  7. Close the System Preferences when done


You might also find that when you make the Output Window full-screen, you get a white menu bar at the top of the screen.  This is a feature added since OSX Mavericks and you’ll probably want to turn it off when using Painting With Light.

  1. Open your System Preferences from the Apple Menu
  2. Click on the “Mission Control” icon
  3. Turn off “Displays have separate Spaces”
  4. You will need to logout or restart your computer for the change to come into effect

9.Video Formats

One of the early questions that comes up when people start using Painting With Light is “What video format should I use?”. Digital video is a complex, ever evolving subject but there is fortunately a simple answer to this question, which we will get to in a minute.

The complexity arises because video data is generally large – far too large to transfer the raw data over the Internet or contain a whole movie on a Blu-ray disc so this data requires processing and compressing.

Unfortunately there is no one video format that fulfils all possible uses and there are a bewildering amount of options available when choosing how to save your videos.

Because of this, it’s useful to know a little about how video files are constructed.


Video (and audio) files generally consist of a container that wraps one or more streams of data (video, audio, subtitles, etc) each of which might be in one of hundreds of formats.

Different operating systems and software applications can favour different container formats over others. Apple computers work well with QuickTime MOV files, while traditionally Windows computers favour AVI ones.

These days you will no doubt have encountered others such as MP4 and MKV, for video, and MP3, FLAC, OGG, for music.

Wikipedia has a much more detailed page on Digital Container Formats.


Each stream of data is chopped up into packets and added to the container so you might have several packets of audio data followed by a packet containing a video frame, followed by some more audio packets.

And each of these streams needs to be processed by a piece of code called a codec that knows how to read and write the actual data before it can be used by an application. A codec will generally add some level of compression to make the original data smaller.

Wikipedia has lots of information on Codecs

Choosing the right format

To cut a very long story short, there are some key aspects of video we need to keep in mind when choosing what formats to use with Painting With Light.

There are always exceptions to every rule, but here’s some to get you on the right track.

Video Resolution

While high definition video is now commonplace on consumer computers, it doesn’t always make sense to use it for every application.

When you use a video projector, this has a native resolution which is the highest it can physically run at. While it might accept higher resolutions from your computer or Blu-ray, it’s still limited to its hardware, and will scale the source image down if needs be.

Rule #1: your video resolution never needs to be higher that your projector resolution

When video mapping, you may not actually cover the whole scene with a video. If you’re mapping a video to the side of a box and it’s only taking up a small part of the output (such as the example in the image below) there is no point using a large video resolution for such a small area.

Smaller resolutions means less processing power is required to decompress the video, meaning you can use more videos simultaneously.

Rule #2: always scale your video resolution down to match what you’re going to use it for

Depending on the video codec, there might also be some benefit or requirement to using video resolutions that are divisible by 8 or 4. So a video that is 320 pixels wide would be fine, but one that is 326 might not work so well (or at all).

Rule #3: make your video resolution divisible by 8 both horizontally and vertically

Video Containers

Painting With Light will load most video containers but some are better supported than others.

Rule #4: use MP4 videos, if you have the option

Video Compression

Compression can happen on a per-frame basis (spacial) and/or over time (temporal).

Spacial compression looks at each frame separately. MJPEG (Motion JPEG) is one example, where each frame is processed with the same compression as in JPG images.

Temporal compression is excellent for videos that are designed to be played forward at normal speed. It stores one whole compressed frame but follows it with frames that describe only the differences between it and the new frame.

If you try to decode one of these difference frames without the original key frame, you get this kind of effect. This can also happen if your video file is damaged.

When exporting videos you can sometimes specify how often key frames should be used.

Rule #5: export temporal videos with key frames every 1 frames (makes every frame a key frame)


Rule #6: optionally, it’s better to use a spacial compression codec such as MJPEG

10.MIDI and OSC

Painting With Light listens for UDP OSC messages on port 10001

It supports receiving single messages or #bundles

This table contains all the MIDI and OSC controls available:

/mapping/scale CC:0
/mapping/offsetx CC:1
/mapping/offsety CC:2
/colour/brightness CC:8
/mapping/rotation CC:9
/colour 3 or 4 int or float values
/cursor/x 0.0 – 1.0
/cursor/y 0.0 – 1.0
/cursor/b1 boolean
/timestamp int = milliseconds or float = seconds


Layer Control using OSC

Individual layers can be controlled using OSC by using the following addressing:

OSC Value
/layers/<layer-path>/opacity 0.0 – 1.0
/layers/<layer-path>/opacity-scale 0.0 – 1.0
/layers/<layer-path>/enabled 0.0/1.0 or true/false
Suggest Edit