VPT 5.1, online manual

Introduction
This document is intended to compliment the built-in help in VPT 5 (click on the ? or hover over a parameter to learn more) which covers the functionality of the interface, as well as the video tutorials (VPT 5.0 only) which gives a basic run-through of some of the VPT functionality.

This manual has been updated for VPT 5.1. I have tried to mark the parts which applies to 5.1 only, but the old manual for for VPT 5.0 is available as pdf.

Background

Video projection is basically an advanced light source: In combination with a computer you can combine an infinite variety of masks with millions of colors to give you a tool for painting with light.

Just by thinking of video projection as light detaches it from the usual format of projection of content onto a screen, and opens up to projecting on bodies, objects, surfaces, walls, floors, ceiling, buildings etc.

I developed VPT to be able to use one projector to project on several surfaces simultaneously, by dividing, in software, the projected image into several smaller images. This technique has allowed me for instance to project on three sides of a cube using one projector, with the illusion of it coming from three different sources.

When projections match the objects/surfaces they project upon, the physical forms appear to get a second “skin”, either of solid color, image or video. The objects get a projected texture.
There seem to be two main approaches to achieve this, which can loosely be defined as mapping and masking.

Mapping is based on creating a virtual 3-D model of the objects/forms you want to project onto.
The idea is then to match exactly the position of the projector with that of the virtual camera in the 3-D model, so that the virtual model maps exactly onto the physical form. This is extremely meticulous work which needs exact measurements and endless calibrations, but can produce some stunning results. Since the content is produced using 3-D geometry, the textures projected reflect the limits of these environments, so very often what is projected is a combination of solid lines and solid color.
The most interesting thing with mapping from my point of view is the possibility to make virtual shadows. Again, since this is made in a 3-D environment, you can add virtual lights to the model, which can cast shadows using the right renderer. By animating the positions of the lights, the shadows move.

Masking is based on masking out shapes, basically the same function as a gobo has for light.
Instead of working with a virtual 3-D model, you work with multiple flat layers which mask individual surfaces of a form, but which are positioned, scaled and rotated in a 3d space.
In some ways masking might seem an inferior method to mapping, but in most cases an audience wouldn ́t notice the difference, and it has many benefits when it comes to the actual process of making it, and the access to individual surfaces makes it possible to make interesting video textures.
The main benefit is that you don ́t need to measure or calibrate anything. You place the projector and work with matching each layer to a different surface.

The VPT interface (5.1)

Understanding layers
(I refer to layer control and layer overview many times. This corresponds to the single and multi tabs in the layer section)

VPT is a realtime video projection tool that gives you 16 individual planes that can be positioned,scaled, distorted and masked to create complex projections. It can also be used for less ambitious projections where you just need to do a little bit of keystoning to fit your projection onto a surface.

The 16 layers are stacked on top of each other, with layer 1 at the top, layer 16 at the bottom. If layer1 is set to cover the whole projection output with 100% opacity you will not see any of the other layers underneath.
HINT: If you want to see what a specific layer contains you can press the “solo” button, which can be found in both the layer overview (as “s”) or in the layer control view. The solo button turns off all the other layers.

Active Layer
Each layer can be manipulated individually using the layer control view. A lot of VPT operations are based on working with an active layer, which means the currently selected layer. You select a layer either by clicking on the layer number in the layer overview (and the view changes to layer control for that particular layer), by selecting layername or layernumber from the dropmenu in layer control, or using keyboard shortcuts: layer 1 to 8 can be accessed with the corresponding number keys, you can also move up and down a layer using the up and down arrows. In multiview it is very easy to see which layer is the active one: The background colour turns dark bluegreen (the same colour as the layer control) and the layer number is white instead of black.

A note about adjusting numbers in VPT:

If you click on a number it gets a red triangle which means it is the active parameter. You can now use the keyboard to enter a value. To change values using your mouse, you click and drag on the number. Click and drag up to increase the value, down to decrease the value. Where you click on the number determines the precision/resolution of the value: The further behind the decimal point you click the more numbers behind the decimal point.

Transparency and blendmode
How a layer combines with the underlying layers depends on transparency, blendmode and mask settings as well as of course the size of the layer.
You control the transparency of each layer either from the layer overview or from layer control.
Blendmode can be selected from a dropmenu where you can choose between normal, additive or multiply, which works similarly to blendmodes in image-apps like photoshop or gimp.

Masks
An important part of VPT is the ability to apply a mask to a layer. There are many ways of doing this, lets first look at the in-layer options:

Using pre-existing masks
Your projectfolder contains a folder called mask, which contains your masks. These are black and white png or jpg files usually. White is opaque, Black is transparent. You can easily make your own masks in another application and add them to the mask folder.
To apply a mask, you first need to activate the mask by clicking on the mask button  in layer control (or click on “m” for the layer for that particular layer in layer overview), then you can select a mask from the maskmenu (which reflects the content of your mask folder).
Maskblur (VPT 5.1) lets you blur your mask, this also works with the masks made with the mask editor. (example: take a look at preset 9 “layerasmask” in the demoproject folder)

Using parametric masks
There are two built-in mask functions for each layer, the vignette and edgeblend.
Vignette is a feathered circular mask, where you control the size, softness, and position. (example: take a look at preset 8 “maskblur” in the demoproject folder)
Edgeblend lets you make a soft edge rectangular mask, where each edge can be controlled individually.

Making your own masks in VPT
There are several ways of making your own masks. Either use the draw-tool, which works more or less as in previous versions (I suggest checking out the video tutorial for this), where you basically draw directly into a layer, or draw points directly onto the projected outputs. The draw tool is most useful for making rough masks. You can then refine these masks in you favourite image-app and then import them back into the mask folder.

With VPT 5 there is a new powerful mask editor, which supports up to 16 control points. This lets you very easily make complex masks. When you click on the mask editor button in layer control, the mask editor opens. You select the number of points your mask should have (4,8 or 16), click reset if there is already another mask in the editor, then start moving the points. This is a realtime mask, so you see directly on your projected output what is going on. When you are satisfied with your mask you need to save it. Either you use the autogenerated name or you enter the name of your choice, and click export. The mask is then saved directly into the mask folder.

There are several ways to make even more complex masks. First of all, you can combine the in-layer masks, to get a combination of user created mask, vignette, and edgeblend.
You can also use combine several layers to make more detailed masks. If you want to save this as one mask you could either use a screen capture, or you could take a look at the desktop capture (found in the tab next to live). This requires a bit of fiddling and is not recommended for noobs.
Sometimes it is not practical to have the mask in the same layer as the content you want to mask.
The easiest way to use a layer as a mask is to use the invert mask function (VPT 5.1), use solid with colour black as source for this layer (example: take a look at preset 9 “layerasmask” in the demoproject folder).

Outlines
I get a lot of questions about outlines, because that seems to be what everybody wants to do. I am not planning to add this as a feature as I find this to be a used-up effect, but there is a relatively easy way to do it: Use the mask editor to get the shape of the object you want to create an outline for. Open the mask in an image-app, create a selection based on the mask, and then select stroke selection. In photoshop you can select inside, center,outside for where the stroke applies, you should select inside. In gimp I am not sure if this is possible, so you might need to shrink the selection before you apply the stroke. Save your file and add it either to your mask or video folder.

Matching a layer to a surface or form.
There are some basic tools to get the layer to fit as good as possible with whatever you are projecting onto.
You have the x y positioning, x y scale (the lock function is handy to keep the aspect ratio),  and x,y and z rotation (x and y VPT 5.1 only).

Cornerpin keystoning
To fit a layer to the side of a box or a wall you often need to adjust the corners. This is done very easily in VPT: You make the layer you want to adjust active (using one of the methods discussed earlier), then you simply click directly on the projection output to place the corners where you want them. It is recommended to position and scale your layer as accurately as possible before doing this.
The cornerpin keystoning is based on the assumption that the corner you are working on is in the corresponding quadrant of your layer.
With VPT 5.1 there is now a handy way to lock the corner you want to position by using the keyboard. Hold down one of the following keys while dragging the corner:
q  top left corner
w top right corner
s  bottom right corner
a  bottom left corner

You can also use the numberboxes in the layercontrol to finish the keystoning which is useful for fine-tuning the keystoning.

In some cases you want to adjust the source size and rotation independently of the actual layer size and rotation. For this you use the txrot found in layer control.

(example: take a look at preset 6 “threelayers” in the demoproject folder, which uses keystoning and txrot)

Sources
There are many different types of sources that can be used in the layers. Any source can be routed to any layer, and one source can of course also be used for all the layers. You select source from the dropmenu either in layer overview or in layercontrol.

HINT: To improve framerate it is a good idea to turn off layers you are not using. Simply select OFF in the sourcemenu in the individual layer to disable a layer.

Quicktime sources

There are 8 quicktime sources, named qt 101- qt 108 (101source-108source in the layer dropmenu). As default video content should be inside the video folder in your project folder. It is also possible to drag and drop video folders (VPT 5.1) directly to the different sources (drop the folder onto the menu of the source you want to add the video to). However, VPT does not save the location of any dropped folders, so next time you start up VPT it assumes you are using the default video folder.

Recommended codec: apple photo jpeg 75% quality for most footage, Apple prores 422 LT for HD footage.

To turn on a source click on the sourcename button, it will turn green. Select a clip from the dropmenu next to the sourcename. To view the source in the sourcecontrol either click just to the left of the sourcename, or choose the source from the dropmenu in the sourcecontrol. When a source is selected in sourcecontrol the background of the source gets the same colour.

The default colourspace for VPT is uyvy which is more efficient than argb. However, for certain type of footage you need to use the argb colourspace. This applies to sources using an alphachannel, like GIF animations.
VPT assumes by default your source to be video, not a still. Again this is for efficiency purposes. However, there is no problem to use still images, you just need to set your source to still in the sourcecontrol,there is a video/still toggle. The number next to the toggle is how often the still image should be updated in milliseconds (default is 100 milliseconds).
NB! Sources might not be what they appear to be. Some movies could be a still image converted to a movie.

HINT: To improve framerate it is recommended to turn off unused sources.

HINT: If you are using small layers there is no need to use high resolution clips. To downsample the resolution of your sourceclip select a different resolution from the resolution dropmenu in the sourcecontrol (default is adapt). You can easily see on your output if you have downsampled too much.

Live inputs
There are two live inputs, 109source and 110source. To see the live input activate the live monitor (the live tab in the monitor section). Live inputs tend to slow things down so remember to turn them off when not being used.
(example: take a look at preset 10 “live input” in the demoproject folder)

Live capture
Live inputs can be recorded to disk or sampled into a ram buffer for immediate use.
To capture a live feed, select your live source, make sure it is on, and click the rec button. Click the rec button again to stop the recording. The recording is automatically given a name and added to the video folder and is immediately available for use in the source dropmenu. The names start with xlive and are then numbered from 101 and upwards. The next time you start VPT the naming starts again at 101 so remember to rename your captured files if you want to keep them or else they will be overwritten.
To sample the live feed into a RAM buffer, select live input and click fill to start filling the buffer, it stops by itself when it has filled the 100 frame buffer. To play back the buffer press play, adjust playback direction, speed and loop points (the two last parameters can also be controlled with LFO/midi/osc). Buffer can be selected as a source into a layer.

Solid source (VPT 5.1)

A very practical source if all you want is a solid colour in a layer. You adjust the size of the solid (especially important when combining it with a mask) and how often it should be refreshed (default is usually ok).
(example: take a look at preset 2 “text-solid-noise” in the demoproject folder)

Noise source (VPT 5.1)

This generates a monochrome noise texture at various dimensions. You can adjust dimension and refreshrate.
(example: take a look at preset 2 “text-solid-noise” in the demoproject folder)

Text source (VPT 5.1)

This lets you add text to VPT, either by reading from file, typing in text in the text box or by sending text over osc using /text1/message yourtext.
The text source behaves differently from the other sources as it is rendered directly to a layer position, and is not a source you select from the layer sourcemenu. You select the layer position where you want the text to appear.
If you want the text to appear above all the other layers use 0 as layer number. If you use the same layer number as a layer which is in use it is unpredictable if the text or the layer will be on top, so it is suggested to use a layer number for text which is not used already for another source.
There is a slight difference in how text size is controlled in the windows and mac versions: In windows you control text size by scaling the text. On mac you set the font size.
For a more detailed explanation of the text source take a look at the built-in help.
(example: take a look at preset 2 “text-solid-noise” in the demoproject folder)

FX bus (VPT 5.1)

A new section in VPT 5.1 is the FX bus with 8 FX chains. Each FX chain contains a selection of shaderbased effects which can be used on all the sources. As with VPT in general, the way to use them is based on routing the source through the fx module. You select the source in the menu which starts with in, and select the output in the menu at the bottom of each fx module which starts with out (x01-x16cell). So if you want to send the quicktime source 101source through fx1 and to layer 2 you select 101source as incoming source in fx1, and for instance x01cell as destination. Then you select x01cell as your source in layer 2. The effects works by first activating the button for a particular effect (blur, mblur, brcosa, scalebias) and then adjust the corresponding parameters.
It is possible to make your own fx chains based on the template included in the VPT download. You can then drag and drop your custom fx chain to one of the 8 available slots (drop on the fx label for the module you want to replace).
There is a fxmodule02a ready to be used in the fxchain folder inside the demoproject folder.
(example: take a look at preset 4 “fxchain” in the demoproject folder)

Mix modules

There are also a number of sources in the menu named x01cell up to x16cell. These are general-purpose sources (useful if you are making your own sources in another max patch), but also used by the mixer modules.
The mixer modules simply mixes two sources, either quicktime sources, live or buffer sources. You choose A and B source and destination, which lets you select the mixermodule as source in a layer. So if you use mixer1, you select 1mix as your source in the layer you want to use it (VPT 5.1).
There are several mix modes to choose from, select one from the dropmenu. Mix is a standard crossfade.
(example: take a look at preset 3 “mix-example” in the demoproject folder)

Syphon
For OSX 10.6 or later there is a syphon client, enabling you to use other applications which support syphon (like quartz composer and unity) as a source in VPT.

Create your own sources
A maxmsp/jitter template is provided with the download if you want to create your own source.

Controllers (VPT 5.1)

There has been a significant update to the controller section of VPT. First of all, everything is now organized in the ctrl window, accessed by clicking on the Controllers button in the bottom left corner of VPT.
The controller section consists of several tabs with different types of controllers as well as the router section (expand and collapse by clicking on the router button). You can control basically everything in VPT using the different controllers.
The built-in help files explain most things so here is only an overview.

Router
The router is the hub of the controller moduler. The principle is that you map a controller number (for instance a midi slider with controller number 1) to a particular VPT destination and parameter in the Router section. You an choose between about 60 destinations and about 100 different parameters so it is possible to control almost every aspect of VPT.
First column is the controller number which should correspond to a controller you are using. You can use the same controller value in several rows to let one controller control many parameters at once.
Second column is the destination.
Third column is the list of parameters available for the destination you chose in the second column.
Fourth column shows the format of the controller message (formatted as a osc message).
Fifth and Sixth columns is the range of the values sent to the the particular parameter you want to control. For instance a fade parameter would expect values between 0. and 1., while /layer1/rotx would expect a value between 0 and 360.

midi

The midi tab let´s you configure VPT to use an external midi controller to control VPT. It also contains a section with built-in sliders and buttons, which can either be used as a simulation of your midi setup, or as a controller in itself. For instance, it could be useful for creating submasters. (Example: with the router section expanded, click on circle 2 at the top (where you save the router setups) to see how one controller (slider 1) controls the fade level of three diffferent layers.

lfo

The lfo generators lets you automate the control of VPT. You can combine two lfo´s to create more complex wave forms.
As with the midi controllers you map the lfo output to a particular VPT destination and parameter in the Router section.

osc

VPT can be controlled from other applications or even another computer using the OSC formatted message system. In principle you can build a complete custom interface for VPT  in an application of your choice which supports OSC, like maxmsp, PD or Processing. Included in the template folder in the VPT download are examples for using OSC with maxmsp and Processing, more examples will come later.
This makes it relatively easy to expand the control of VPT to using cameratracking or kinect.

Available osc messages to control parameters in VPT:

osc parameters to the moviesources:
/video /rate /trig /scrub /in /out /loop /loopreset /loopreport /unique /unirefr /argb /start /stop /dim /vol /pan /clipnr /random

osc parameters to the layers:
/fade /pos_x /pos_y /scale_x /scale_y /x1 /y1 /x2 /y2 /x3 /y3 /x4 /y4 /red /green /blue /txrot /blur /levels /avig /edge /mask /solo /blendmode /source /cpreset /name /ratio /solotrig /sourcenr

osc parameters to the mixers:
/A /B /out /mix

osc parameters to the lfos:
/on /phase /speed /wave /wnormal /val /range /lfomix

osc parameters to the built in fx module:
/blur /blurlevel /mblur /mblurlevel /mblur_down /brcosa /br /co /sa /scalebias /scale_r /scale_g /scale_ b /bias_r /bias_g /bias_b /in /out

osc parameters to buffer:
/source /fill /play /dir /speed /range /frame

osc parameters to textmodule (/text1):
/on /message /font /size /align /posx /posy /rotx /roty /rotz /fade /red /green /blue /layer /next /line /linetempo

osc parameters to noise:
/dimx /dimy /speed

osc parameters to sound module:
/matrix /1amp /2amp /3amp /4amp /5amp /6amp /7amp /8amp

osc to serial out (/serialout)
/s1 /s2 /s3 /s4 /s5 /s6 /s7 /s8

osc to VPT (/vpt)
/preset /cue /blackout /fullscreen

VPT also sends out osc messages, giving information about active preset number, loop reports etc. , making it possible to sync external events to VPT events. You can also create custom osc messages, which can either be used to control other applications, or could be used as an alternative way of controlling VPT (by sending to port 6666).

Please note that VPT is only automatically sending out OSC data for some parameters:
/preset,/sequence,/cuetrig, /linedone, /loopreport (need to have loop report enabled), /101-108curclipnr, /101-108menucount, /101-108clipduration, /101-108cliptimeabs(need to have cliptimereport enababled), /101-108cliptime(need to have cliptimereport enababled).

loopback

The loopback section lets you map information about preset, cues as well as cliptime and clip loop report as a controller. So this means you could use the the loop report from 101source to trigger a new random clip from 101source when the clip reaches the end. It also lets you sync parameters to the playback of a movie.

serial

The serial section lets you communicate with a microcontroller like the Arduino, both input and output.
For output you can turn things on/off or dim lights etc, as well as controlling servos. I use this for controlling a simple shutter for the projector, covering the lens when I want it to be completely black.
For input you can use switches, knobs and different sensors as controllers for VPT. Since sensors rarely give a clean signal I have made it easy to tune the sensor by a combination of smoothing the signal, scale the range of the values received from the sensor, as well as the possibillity to use analog input as a trigger (where you can set the threshold). A on/off signal can either be used as a button or a toggle.

Sound output (VPT 5.1)

You can route the sound from your quicktime sources out to up to 8 channels, depending on your sound card. I have also provided a maxmsp patch (in the template section in the VPT download) with the receive points of the A,B,C,D sources so it should be possible to create patches to process the sound further).

Output

Fullscreen
To enter/exit fullscreen use the esc key on your keyboard. The mofo window goes into fullscreen on the screen it appears on so make sure it is on your projector output (which it should be if you have one connected).

Output settings

You can set VPT to automatically enter fullscreen when starting up, as well as starting at a particular preset or cue. You can also specify if menubar and cursor should be visible or not. This settings can be found in the prefs tab, under startup options.
The output tab contains some more advanced settings for adjusting the mofo window, particularly when it is not in fullscreen. You can adjust screen ratio and number of screens, which makes it easier to prepare work when you are not connected to a projector.

Saving
This is probably the most confusing part for people who have not worked with VPT before.
In the file menu there is a save item which is greyed out. This has nothing to do with saving work in VPT, it is simply a menu that comes from max/msp, the program that VPT is made in, and it would be used for saving changes to the actual program, not the contents of VPT.

So, how do you save your project?

Project folders

First of all, in VPT 5, projects are organised into project folders.
A project folder contains your video and mask folder, as well as a preference file, a preset file, a cuelist and a midi preset file. These files contain all the information related to your VPT project.
The first time you start VPT it assumes you uses the default demoproject which is found inside the VPT folder.
One option is to keep using it, just replace the video and mask folders with your own content (but keep the names video and mask for the folders).
Another is to keep the projectfile in another location on your system. The easiest way to get this to work is to just duplicate the demoprojectfolderm and then rename it. You can either keep it inside the VPT folder or move it somewhere else.

You need to tell VPT which projectfolder you are using by going into the prefs tab, and click on the projectpath button. Navigate to your project folder and select. Your project should then load but to be on the safe side I would recommend that you restart VPT, and verify that the filepath is correct (shown in the prefs section).
The projectfolder makes it very easy to move projects to other computers, so it is ideal for sharing projects.

Presets

There is currently no efficient way of rendering the output you create in VPT (that might change hopefully), so when you are using VPT there is a lot of processing going on in realtime. So what do you save then?
You save the current state of VPT into presets. This means all the parameters for all the layers,sources, mix modules, lfos etc are saved everytime you create a preset.
You create a preset by giving it a number and optionally a name and click store. Your saved preset appears in the preset list. By clicking on the different items in the preset list VPT updates all the parameters to the selected preset.
You can make a simple transition between presets in the preset section by specifying a from and to preset and the transition time. If you go from 1 to 5 in 5 seconds, the transition will start at 1, and then interpolate to the next presets (2,3, 4 if they exist) before ending at 5.
The preset list is saved automatically when you close VPT, so in theory you don´t need to save it manually. In case you do worry about losing information while you are working you can simply click the save button at the bottom of the preset section. There is also a autosave option (VPT 5.1) which saves the presetlist every 20 seconds.
(example: take a look at preset 11 “transition1″and 12  “transition2” in the demoproject folder: in the green section of the preset module enter 11 in the from numberbox, 12 in the to numberbox and 5 in the time number box, as seen in the image above. Click the go button to see the transition)

Cuelist

Most users might not need anything else than creating presets and switch between them. There is however an advanced option for created a cuelist, which is very useful in a theatre/dance performance setting or for automated installations.
Basically it is based on the saved presets, then choosing different types of transitions between the preset. Unlike the transition described in the preset section, a transition in the cuelist is an interpolation only between the from and to presets, so a transition from 1 to 5 would not interpolate through intermediate presets.
There is a choice of fade, cut, autofade, autocut, delay and loop.

Fade fades between two presets and then stops. Autofade does the same fade but continues to the next item in the cuelist. The same logic applies to cut and autocut. A delay sets a delaytime before continueing to the next item in the cuelist. Loop lets you create a loop inside the cuelist. The number in the loop cue refers to the cuelist number, not a preset.
As with presets you can either choose to save the cuelist manually by clicking the save button (you are also prompted to save the file if you use the quick edit option), or let VPT save it for you when it closes.

Please refer to the built-in help and tutorial videos for further help.

You can access relevant web links directly from VPT by clicking on the VPT icon in the bottom right corner.

If you have further questions please use the VPT forum, not the comment field of this page.
http://www.nervousvision.com/vptforum/

Advertisement