2. Fundamentals of PHOTON and its User Interface

Quick tutorial

2.1 User Interface Visibility

By default PHOTON’s interface will not be visible on start-up. This is due to the fact that on some configurations (when the Display Master operation mode is selected) every physical output of the graphic card will be used to display content.
  • Press [Tab] to hide or view PHOTON’s UI.

2.2 Layer Rendering Order

In PHOTON, the rendering order is organized from top to bottom. This means the lowest item in the list will always be the last one rendered, and as a result it will be placed on top of the composition. This applies to both the Timeline module (where compositing is done) and the 3D Scene list.
It is important to remember that the logic of PHOTON’s rendering order is the inverse of Adobe’s image compositing applications.

2.3 Virtual and Physical Screens

PHOTON has been designed to facilitate the creation of shows that involve complex programming, signal distribution and display of video content, and also include interactions with various sensor feeds or external devices.
A key characteristic of a powerful, efficient and easy to use software designed specifically for video projection in stage productions should be to represent reality as accurately as possible. Therefore, PHOTON is based on a virtual representation of a physical stage’s three-dimensional space and its components. The virtual counterparts of projectors, screens, LED displays, lighting fixtures and stage props can be found in the 3D Scene module (see Section 2 3D Scene in Chapter 2 Setting Up a Show).
The properties of the virtual components included in the 3D Scene can be manipulated so they will perfectly match their physical counterparts. Notably, it is through the creation of these correlations that PHOTON is able to apply geometric corrections on a video feed to match the positioning and orientation of projectors and screens during a stage production.
This particular approach explains a lot about the software’s structure. In a PHOTON project, technical components coexist in different ways (physical and virtual), but also across different modules in the software. PHOTON Screens are a perfect example of this, in that they act as pivot points between different PHOTON modules and the stage space.
Screens simultaneously correspond to:
  • physical screens in the stage space;
  • virtual representations of the physical screens in the 3D Scene module;
  • content assignation structures in the Timeline module.
Screens in the Timeline can hold many layers, where multiple media clips can be placed sequentially. Whenever a new Screen is created in the 3D Scene, it will create its own dedicated content assignation structure in the Timeline.
This impacts the way video content is produced, programmed and shown. Instead of working in one large video space that will be cut up for many projectors, you work directly on separate Screens. Placing a media file on the Timeline in a Screen will automatically display the file’s content on its physical counterpart.

2.4 Internal and External Data Exchange

PHOTON’s parameters and their corresponding UI representations (such as sliders and number boxes) have been designed to support mapping internally (across the software) and externally.
Data sent from one point to another can be intercepted and changed using a mathematical function. For example, it could be rescaled for a new context.
Data can also be wrapped and sent through various protocols (UDP, PSN or MIDI) so they will be accepted by a wide variety of devices and software.
PHOTON’s Mapping Manager module is dedicated to data exchange. Through a series of tables you will be able to map scaled data from UI components, an external keyboard, or MIDI and OSC devices directly to any other UI component (see Section 9 Mapping Manager in Chapter 4 Programming a Show).
UI components can also be linked to time-based markers and then animated through PHOTON’s Keyframe Editor (see Section 8 Keyframe Editor in Chapter 4 Programming a Show).
PHOTON’s FX Editor module can also be the place where you will connect data generated by a portion of the system to an effector situated elsewhere through a dataflow visual programming environmentSome of the FX Editor module building blocks can access the properties of objects created in the 3D Scene as well as tracking data generated by ALBION.

2.5 Metric System Only

The Metric System is the only system of measurement used in PHOTON. Each square of the 3D Scene grid is a square meter. To get accurate readings in the 3D Scene’s Projection Study mode, all of the 3D objects need to be declared in meters.
All of the readings the software provides, all of the transformations it performs and all of the data linked to stage automation will also be expressed using the Metric System.
VYV will never provide or accept translations to Imperial units of measurement because the Imperial system is considered obsolete by most authorities.
The meter is the length of the path travelled by light in a vacuum during an interval of 1/299,792,458 of a second.

2.6 Real-Time Everywhere

PHOTON was built entirely on real-time processes. Since our product is mainly used for live multimedia productions, we focused on building a system that specializes in real-time delivery, and is able to adapt to on-the-spot changes that characterize this type of presentation.
Interactivity is at the very core of PHOTON, which makes it stand out amongst other media servers. All parameters are exposed and can be changed without any rendering time, making PHOTON an ideal tool when instantaneous action is required.
At VYV it is against our philosophy to limit the user in any way. This means there is no cap to the number of modules, media files and treatment processes a user can deploy in a PHOTON Project. However, this means it is the project programmer’s responsibility to ensure that the system’s frame rate does not drop below a specific threshold. (Depending on the circumstances, this could mean 60, 50, 30, 25 or 24 fps.)

2.7 Normalized Values

Most of the UI components in PHOTON, such as sliders, are normalized so their values range from 0. to 1.. We decided to normalize values in this way to facilitate data exchange between modules and data treatment using mathematical functions. One of the notable exceptions to this rule is the measurement of degrees, which range from 0. to 360..

2.8 UI Components Lexicon

A few terms describing UI components will be used regularly throughout PHOTON’s technical documents. Some of the terms might be self-explanatory; others have a meaning that is specific to PHOTON’s UI. We decided it would be best to provide definitions for all of them.


A module denotes a structure in PHOTON dedicated to a group of similar tasks. For example, the I/O Module is dedicated to the exchange of data between PHOTON and external third-party devices. Along with the underlying methods, routines and behaviors dictated by the code’s structure, a module will always have its own window containing various widgets such as sliders, toggles, menus, and checkboxes that allow the user to modify parameters, launch tasks, etc.
  • Modules can be accessed through the File, System and Show dropdown menus or through shortcuts beginning with the [Alt] key.


A window is a rectangular frame that contains various widgets such as sliders, toggles, menus and checkboxes that will allow the user to modify parameters, launch tasks, etc. Windows can be divided in sections or can contain tabs.
  • To select a window and focus on one of its components, [Left-Click] anywhere inside it. When selected, the window frame will turn red.
  • To move the window around, [Alt+Click-Drag] inside the window.
  • If you launched a module but the window does not seem to appear, press [F3]. PHOTON will redraw all windows.
  • To minimize a window, left-click on the minus sign located at the top right corner of the window.
  • To maximize a window, left-click on the plus sign located at the top right corner of the window.
  • To close a window, left-click on the x sign located at the top right corner of the window.

Window Section

A window section is a subdivision of a window used to regroup widgets that are meant to work in conjunction with the execution of a task. For example: a list of clickable items and a button used to add items in the list would be located in the same window section. Window sections are generally preceded by a title and are delimited by a faded rectangular frame.


Some modules encompass more features than others. Windows tied to these modules will usually feature tabs: clickable components that facilitate switching between different panels. Panels accessible through tabs regroup coherent sets of widgets targeting a specific aspect of their module.
  • Tabs located in the I/O Manager window feature a small pin icon.
  • These tabs can be “unpinned” from the module’s window and displayed in an independent window by a [Left-Click] on the pin icon.


Lists are structured unidimensional sets of items. In PHOTON, the items contained in a list are identified by faded gray rectangles containing the item’s name or ID. The items usually support various interactions. They can be re-ordered through click-drag. A right-click on a list item will open a contextual menu offering various options.
Main menus are located at the very top of PHOTON’s main window (the black background that exists independently from the other modules). They either provide access to the software’s various modules or allow the user to perform operations like saving their current project.
A dropdown menu appears as a white rectangular frame with a name or a currently selected option written in white. A downward or right pointing arrow will indicate that the menu is clickable and will provide the user with many options.

Contextual Menu

Contextual menus are activated by performing a right-click on a UI component such as an item in a list or a slider. Contents of a contextual menu will vary depending on the nature of the UI component affected by the right-click.


Sliders are either unidimensional or bidimensional widgets used to graphically and numerically represent the value set for a parameter. They are discussed in more detail later in this section of PHOTON’s technical documents (see Section 2.11 Slider Types and Behaviors in Chapter 1 Prerequisites).


A toggle is a widget that allows the user to set a parameter’s Boolean value (On/Off). Represented by a clickable rectangular frame, toggles are often used to indicate whether or not a particular option is activated. If an option is activated, the toggle’s rectangular frame will be highlighted.


Buttons are widgets that can be clicked. They are used in various ways and their functions are represented by icons or names.


Checkboxes are used in conjunction with items in a list to indicate if they are selected to be inside or outside a set before applying an operation.

2.9 Renaming Labels

Most item labels can be renamed in PHOTON.
There are two methods for renaming labels:
  • Double-click to put the slider in edit mode, which lets you type in the desired name; or,
  • Single-click to focus on the item label and then press [F2] to put the slider in edit mode, which lets you type in the desired name.

2.10 Main Menu Bar

PHOTON’s Main Menu Bar provides access to the software’s main modules. The modules are categorized based on their functions.
  • Use the Main Menu Bar to gain access to the various modules that will allow you to build a PHOTON project.

2.11 Saving Methods

Saving in PHOTON may differ in some ways from what you might be accustomed to in other software. PHOTON’s Default Save {File > Save Default} writes in the main memory slot used for backing up a PHOTON Project’s files (using the .phd file extension).
The Default Save is automatically loaded when PHOTON starts.
The Default Save is automatically overwritten when PHOTON quits. A new save is created in the same memory slot, with the project’s current data.
All types of Saves strictly include PHOTON’s data. None of the media files or 3D objects will be backed up through any of the saving methods.
All saves will be located in ...VYV\photon\projects\current_project_name\config\...
  • A PHOTON Save is divided into 3 files:
    • a .phd file (PHOTON Data)
    • a .io file (all the configurations of your input and output devices)
    • a .uuc file (UI configurations; your current Workspace)
  • There are 3 ways to save your PHOTON Project.
    • Save Default [Ctrl+S]
    • Save Incremental [Ctrl+Alt+S]
    • Save Project… [Ctrl+Shift+S]
  • We recommend you to save regularly and use all of the methods.

Save Default

PHOTON uses the Default Saves as its standard way of backing up your progress while working on a project.
  • If you select {File > Save Default} or press [Ctrl+S] the current state of your project will overwrite the file that was previously saved as the Default Save. Therefore, Default Saves are destructive.
  • By selecting {File > Load Default} or by pressing [Ctrl+L] you will revert your project to the previous state that was saved in the Default Save.
Furthermore, if you let PHOTON quit properly, by letting the Windows console finish its process, your project will automatically be saved as a Default Save. Note that the Default Save is also the save that will be loaded when PHOTON starts.

Load Default

  1. 1.
    Select {File > Load Default} or press [Ctrl+L] to load the version of the project currently saved in the Default Save memory slot. A Confirm Load Project dialog box will open and ask “Are you sure you want to reload the last default save?”
  2. 2.
    Click on the [Yes] button to reload the last default save.Click the [No] button if you decide to keep on working with your project in its current state.

Save Incremental

Save Incremental is the newest and fastest way to save. It incrementally creates new save files.
  • By selecting {File > Save incremental} or by pressing [Ctrl+Alt+S] you will automatically create a saved project file without prompting a Windows file dialog.
The save will be named as follows:
Example: Myproject_20180305_185423
The date and time is determined by the local server’s operating system.

Save Project…

The Save Project command lets you save specially named versions of your project when it’s in a state that you want to keep as a backup.
  • Selecting {File > Save Project...} or press [Ctrl+Shift+S] to prompt a Windows dialog that lets you name the project save.
Save Project is an inalterable step, a backup of your PHOTON Project’s data at a specific point, except if you manually delete it or choose to replace it.

Load Project

  • Select {File > Load Project...} or press [Ctrl+Shift+L] to prompt a Windows file explorer that lets you access previous versions of your project created through any of the save methods.
  • To load a previous version of your project, select the desired project file from Windows file explorer and click the [Open] button.

2.12 Slider Types and Behaviors

PHOTON uses three kinds of sliders depending on the type of data it needs to represent.

1D Slider

Allows you to control a large variety of parameters in the software. This UI component’s value can be modified by sliding the bar horizontally within the defined zone.
The 1D Slider can be edited in the following ways:
  • Left-Click+Drag changes the value within the hardcoded range.
  • [Ctrl+Left-Click+Drag] changes the value, with the option to exceed the hardcoded range.
  • [Shift+Left-Click+Drag] changes the value within the hardcoded range at a slower pace to achieve more precision (10 times slower).
  • [Ctrl+Shift+Left-Click+Drag] changes the value at a slower pace (100 times), with the option to exceed the hardcoded range.
  • Double-Click puts the slider in edit mode and lets you type in the desired value.
  • Single-Click to focus on the slider, followed by [F2] puts the slider in edit mode and lets you type in the desired value.
Extended range and 100 times pace reduction only work with 1D Sliders.

2D Slider

Allows you to control a large variety of parameters in the software, such as size or position values. This UI component’s value can be modified by sliding the cross horizontally and vertically within the defined zone.
The 2D Slider can be edited in the following ways:
  • Left-Click+Drag changes the value within the hardcoded range.
  • [Shift+Left-Click+Drag] changes the value within the hardcoded range at a slower pace to achieve more precision (10 times slower).
  • Double-Click] puts the slider in edit mode and lets you type in the desired value.
  • Single-Click to focus on the slider, followed by [F2] puts the slider in edit mode and lets you type in the desired value.
  • [Tab] allows you to cycle your selection through the 2 values.

Time Slider

The Time Slider allows you to control timing parameters in the software by sliding the bar horizontally within the defined zone. For example, it will allow you to modify the In and Out of clips and media.
The Time Slider can be edited in the following ways:
  • By clicking on the [In] button, you will set the current time of the Timeline’s Playhead to the Time Slider.
  • Left-Click+Drag changes the value within the hardcoded range.
  • [Shift+Left-Click+Drag] changes the value within the hardcoded range at a slower pace (10 times).
  • Double-Click puts the slider in edit mode and lets you type in the desired value.
  • Single-Click to focus on the Time Slider, followed by [F2] puts the slider in edit mode and lets you type in the desired value.
In edit mode, the Time Slider can be affected by using the basic (+) and (-) math commands.
  • By inputting +n you will add n frames up to 99. For frames greater than 99., time will be segmented as hh:mm:ss:ff.
  • By inputting -100 you will remove 1 second 00 frames.
The Time Slider is the only slider to show this behavior.