SGE work to get Glossary working +
[goodguy/cin-manual-latex.git] / parts / Plugins.tex
1 \chapter{Plugins}%
2 \label{cha:plugins}
3 \index{plugins}
4
5 There are realtime effects -- these are the most useful and probably all you will ever need -- and rendered effects.
6 The rendered effects are discussed separately in the \nameref{sec:rendered_effects}  section.
7 Effect plugins modify the track when played, according to how they are set, with no permanent storage of the output except when the project is rendered. There are many Plugins in \CGG{} Infinity which are actually quite easy to use just by experimenting with them. The plugins are shown and selected from the \textit{Resources window} (figure~\ref{fig:video-plugins}). They are described in more detail later.
8
9 \begin{figure}[htpb]
10     \centering
11     \includegraphics[width=1.0\linewidth]{video-plugins.png}
12     \caption{Screencast of the native Video plugins in the default Cinfinity icon set.}
13     \label{fig:video-plugins}
14 \end{figure}
15
16 There is a choice of plugin icons \index{plugins!icons} which can be displayed.
17
18 In \texttt{Settings$\rightarrow$ Preferences$\rightarrow$ Appearance} tab, there is a pulldown for \textit{Plugin icons} where the user can choose between the \textit{original} icons, \textit{regular} or \textit{smoother}, \textit{cinfinity}\protect\footnote{Cinfinity /2 icon set is credited to Sam - Creative Common By -- \url{https://creativhecommons.org/licenses/by/3.0/}} -- the default modernized set, or \textit{cinfinity2} (figure~\ref{fig:audio-plugins}).
19
20 Note that when you change the plugin icons, your session will automatically save the backup, stop, restart, and reload (figure~\ref{fig:plugin-icons}).
21
22 \begin{figure}[htpb]
23     \centering
24     \includegraphics[width=0.6\linewidth]{audio-plugins.png}
25     \caption{Cinfinity2 audio plugins}
26     \label{fig:audio-plugins}
27 \end{figure}
28
29 \begin{figure}[htpb]
30     \centering
31     \begin{tikzpicture}[scale=1, transform shape]
32     \node (img1) [yshift=0cm, xshift=0cm, rotate=0] {\includegraphics[width=0.5\linewidth]{plugin-icons.png}};
33     \node [yshift=-6mm, xshift=-1cm,anchor=east] at (img1.north west) (Preferences) {Preferences Window};
34     \node [yshift=-14mm, xshift=-1cm,anchor=east] at (img1.north west) (Tab) {Tab section};
35     \node [yshift=-34mm, xshift=-1cm,anchor=east] at (img1.north west) (Icon) {Plugin icon choices};
36     \draw [->, line width=1mm] (Preferences) edge  ([yshift=-6mm] img1.north west);
37     \draw [->, line width=1mm] (Tab) edge  ([yshift=-14mm] img1.north west);
38     \draw [->, line width=1mm] (Icon) edge    ([yshift=-34mm] img1.north west);
39     \end{tikzpicture}
40     \caption{Screencast showing the screen to change your plugin icons set}
41     \label{fig:plugin-icons}
42 \end{figure}
43
44 \section{How to Use Plugins}%
45 \label{sec:how_use_plugins}
46
47 \textit{Realtime} effect plugins are listed in the Resources window as \textit{Audio} Effects and \textit{Video} Effects. Effect plugins are used by dragging them from the Resources window onto an audio track if it is an audio effect or video track if it is a video effect. You will see a colored bar \index{plugins!toolbar} appear beneath the track with the plugin name on it. If there is data on the destination track, the effect is applied to the entire track, unless a edit or a region of the track is selected in which case the effect is pasted into that region only. If there is no data on the track the effect is not added.
48
49 Plugins are layered under the track they apply to. When dragging more than one effect onto a track, you will see the effects layering from \textit{top to bottom}, on the bottom of that track. When the track is played back, effects are processed from \textit{top to bottom}. The output of the top effect becomes the input of the bottom effect and so on.
50
51 Instead of dragging from the Resources window, effects may be applied to a track via a popup menu. Right click on a track and select \textit{Attach effect} \index{plugins!attch effect} from the popup. The attach effect dialog gives you more capability than just dragging and dropping. For example, the attach effect dialog lets you attach two more types of effects: \textit{shared effects} and \textit{shared tracks} which are explained in a later section. Select a plugin from the Plugins column and hit the green colored checkmark under the plugins column to attach it. The result is the same as if the effect was dragged from the Resources window.
52
53 After attaching an effect to a track, it often needs to be configured. There are two ways to get to the configuration controls. Click on the magnifying glass \index{plugins!show controls} symbol on the right side of the effect bar -- this is the middle symbol on the bar as you can see in the picture below. Alternatively, you can right click on the effect bar to bring up the effect popup which has a \textit{Show} option. Either method causes the GUI for the effect to appear in a separate window. There will not be a popup if the plugin has no GUI.
54
55
56 Besides the magnifying glass, for Show Controls, on the effect colored bar beneath the track, there are two more symbols.
57
58 \begin{wrapfigure}[2]{r}{0.3\linewidth}
59     \vspace{-3ex}
60     \centering
61     \includegraphics[width=0.7\linewidth]{button-options.png}
62 \end{wrapfigure}
63
64 The rightmost knob is used to Turn Off/Turn \index{plugins!turn on/off} On the effect where the default is On. This is useful to easily see that the plugin is doing what you expect. The leftmost symbol that looks like a gear is for \textit{Preset Edit} \index{plugins!preset edit} and its usage is described in the section \nameref{sec:saved_plugin_preset}.
65
66 \section{Editing Effects}%
67 \label{sec:editing_effects}
68 \index{plugins!editing}
69
70 Many operations exist for manipulating effects once they are on the timeline. Because mixing effects and media is quite complex, the methods used in editing effects are not as concise as cutting and pasting. Some of the editing happens by dragging in/out points, some of the editing happens through popup menus, and some of it happens by dragging effects.
71
72 When enabled, which is the default, and you edit tracks, the effects follow the editing decisions. If you cut from a track, the effect shrinks. If you drag edit in/out points, the effect changes length. This behavior can be disabled by selecting \texttt{Settings$\rightarrow$ Preferences$\rightarrow$ Interface tab$\rightarrow$ Editing section}, see figure~\ref{fig:editing-effects} \index{keyframes reticle}.
73
74 \begin{figure}[htpb]
75     \centering
76     \includegraphics[width=0.9\linewidth]{editing-effects.png}
77     \caption{Screencast showing the menu where Editing Effects behavior is changed.}
78     \label{fig:editing-effects}
79 \end{figure}
80
81 To edit effects, you can move the timeline cursor over the effect borders until it changes to a resize left or resize right icon. In this state, if you drag the end of the effect, it performs an edit just like dragging an edit edge. The five editing behaviors of track trimming \index{trim} apply to effect trimming and they are bound to the mouse buttons that you set in interface preferences as shown in the previous screencast. \textit{Trimming} simply means changes the duration dragging the edges.
82
83 When you perform a trim edit on an effect, the effect boundary is moved by dragging it. Unlike track editing, the effect has no source length. You can extend the end of an effect as much as you want. Also unlike track editing, the starting position of the drag operation does not bind the edit decision to media. The media the effect is bound to does not follow effect edits. Other effects, however, do follow editing decisions made on an effect. You can disable effects from being subject to the edit decisions by using the pulldown \textit{Settings} and toggling off Edit effects. If you drag the end of an effect which is lined up to effects on other tracks, the effects on the other tracks will be edited while the media stays the same. When you drag an effect in from the Resources window you can insert the effect in the portion of the row unoccupied by the trimming operation. In some cases you will want a trimming operation to change only one row of effects. This can be achieved by first positioning the insertion point on the start or end of the effect. Then press the shift key while beginning the trimming operation. This causes the operation to change only one row of effects.
84
85 You can move effects up or down. Every track can have a stack of effects under it. By moving an effect up or down you change the order in which effects are processed in the stack. Go to an effect and right click \index{plugins!RMB on toolbar} to bring up the effect menu. The \textit{Move up} and \textit{Move down} options move the effect up or down. When you are moving effects up or down, be aware that if they are shared as shared effects, any references will be pointing to a different effect after the move operation.
86
87 Finally, there is dragging of effects \index{plugins!dragging}. Dragging effects works just like dragging edits. You must select the arrow in the main window transport buttons line to enter drag and drop mode before dragging effects. Dragging a plugin causes a highlight outline to be drawn over a targetable timeline region, and the plugin can be re-positioned into any plugin track.  The effects snap to media boundaries, effect boundaries, and tracks. If you drag a reference to a shared effect, the reference may point to the wrong effect afterwards.  It is recommended that you re-construct shared effect track references.
88
89 Figure~\ref{fig:drag-effect} showing 3 plugins, two still plugin, two have already been dragged and the \textit{Color 3 Way} in the process of being dragged. Note the gold-colored frame which enables allow \textit{drag and drop} editing mode.
90
91 \begin{figure}[htpb]
92     \centering
93     \includegraphics[width=0.7\linewidth]{drag-effect.png}
94     \caption{Dragging the Color 3 way effect}
95     \label{fig:drag-effect}
96 \end{figure}
97
98 \section{Shared Effects and Shared Tracks}%
99 \label{sec:shared_effect_tracks}
100 \index{plugins!shared effect}
101 \index{plugins!shared tracks}
102
103 Two other effect types available in the Attach Effect dialog are \textit{Shared effects} and \textit{Shared tracks}. In the case of a shared effect, the following conditions must be true:
104
105 \begin{itemize}[noitemsep]
106     \item There must be other effects in the timeline.
107     \item The other effects must be of the same type as the track you are attaching an effect to. That is for audio tracks, effect must be audio and for video tracks, effect must be a video effect.
108     \item The insertion point or selected region must start inside the other effects.
109 \end{itemize}
110
111 Before going into further detail about how to use \textit{Shared effects}, an easier
112 alternative method of application which is especially useful for Audio tracks is
113 available.  In this method, all you have to do is use the \textit{Audio} pulldown and
114 choose \textit{Attach effect} \index{plugins!attach effect}, highlight the effect you would like and make sure the
115 default of \textit{Attach single standalone and share others} is checked on.  It will
116 automatically be a "Shared Effect" on all audio tracks (be sure to disarm any audio
117 tracks that you do not want to have the effect shared on).  This method also works for
118 Video tracks using the \textit{Video} pulldown choice of \textit{Attach effect}.
119
120 In the case of a shared track, there must be another track on the timeline of the same type as the track you are applying an effect to. If you right clicked on a video track to attach an effect, there will not be anything in the shared tracks column if no other video track exists. The same applies equally to audio tracks in that another audio track must exist. Shared tracks are often used as layers for titles, curves and keyframes.
121
122 If shared effects or shared tracks are available, they appear in the shared effects and shared tracks columns when you used the \textit{Attach effect} option (RMB on a track). When the green colored checkmark is clicked OK, anything highlighted in the column is attached under the current track.
123
124 Shared effects and shared tracks allow very unique things to be done. In the case of a shared effect, the shared effect is treated like a copy of the original effect, except that in the shared effect the GUI can not be brought up. All configuration of the shared effect is determined by the GUI of the original effect and only the GUI of the original effect can be brought up.
125
126 When a shared effect is played back, it is processed just like a normal effect except the configuration is copied from the original effect. Some effects detect when they are being shared. These effects determine what tracks are sharing them and either mix the two tracks together or use one track to stage some value.
127
128 When an original track has a shared track as one of its effects, the shared track itself is used as a \textit{realtime} effect. This is more commonly known as \textit{bouncing tracks} but \CGG{} achieves the same operation by attaching shared tracks. The fade and any effects in the shared track are applied to the original track. Once the shared track has processed the data, the original track performs any effects which come below the shared track and then composites it on the output.
129
130 In order to prevent the shared track from mixing the same data as the original track on the output, enable the output \texttt{mute} \index{mute} toggle in the patchbay next to each track for which you do not want to mix on the output. If you are making a video and you do want the shared track to composite the original track's data on the output a second time, the video from the shared track would always appear under the video from the original track, regardless of whether it was on top of the original track. This is because shared tracks are composited in order of their attachment. Since it is part of the original track it has to be composited before the original track is.
131
132 \section{Saved Plugin Presets}%
133 \label{sec:saved_plugin_preset}
134 \index{plugins!preset edit}
135
136 \textit{Presets} and \textit{Factory Presets} for Plugin settings are now combined with the Preset Keyframe Parameters allowing you to choose, apply, delete, and edit your own Presets which can then be easily saved in the file \texttt{\$HOME/.bcast5/Cinelerra\_presets}. In addition to your own saved presets, there are automatically available Factory presets for some plugins, for example the Lens video plugin. The Factory presets are preceded by an asterisk (*) and can not be modified permanently.
137
138 \begin{wrapfigure}[4]{r}{0.3\linewidth}
139     \vspace{-2ex}
140     \centering
141     \includegraphics[width=0.7\linewidth]{preset.png}
142 \end{wrapfigure}
143 Note that using this is directly changing a keyframe object so you will only want to modify parameters you are familiar with. Most of the data is obvious and safe to change.
144
145 A Presets button on the plugin bar to the left of the Controls and On/Off button allows for quick access to this feature. The symbol resembles a slider (figure~\ref{fig:preset02}).
146
147 \begin{figure}[htpb]
148     \centering
149     \begin{tikzpicture}[scale=1, transform shape]
150     \node (img1) [yshift=0cm, xshift=0cm, rotate=0] {\includegraphics[width=0.6\linewidth]{preset02.png}};
151     \node [yshift=-20mm, xshift=-1cm,anchor=east] at (img1.north west) (Green) {A user preset Green};
152     \node [yshift=-67mm, xshift=-1cm,anchor=south east,text width=10em, inner ysep=-3mm] at (img1.north west) (Textbox) {Textbox to type in the title for the chosen preset or name for a new preset.};
153     \node [yshift=-79mm, xshift=-1cm,anchor=north east,text width=10em,inner ysep=-3mm] at (img1.north west) (Save) {Use the Delete, Save or Apply button for operation.};
154     \draw [->, line width=1mm] (Green) edge  ([yshift=-20mm] img1.north west);
155     \draw [->, line width=1mm] (Textbox.south east) --  ([yshift=-67mm] img1.north west);
156     \draw [->, line width=1mm] (Save.north east) --    ([yshift=-79mm] img1.north west);
157     \end{tikzpicture}
158     \caption{Screencast shows 4 Factory presets as preceded by an *.}
159     \label{fig:preset02}
160 \end{figure}
161
162 \section{Some specific details concerning Plugins}%
163 \label{sec:specific_details_plugins}
164
165 These next few sections explain some details about the plugins that are not directly related to actually using them but help to work with them.
166
167 \subsection{How to see short Description of a Plugin}%
168 \label{sub:short_description_plugin}
169 \index{plugins!short description}
170
171 To get a short one or a few lines description of a plugin, mouse over that plugin in the Resources window and a popup appears. You can disable the popup by right-clicking and choosing \textit{Info Off} (shortcut "i"). And again enable it with \textit{Info On}. Some of the plugins may not have any description included. An example screenshot is next (figure~\ref{fig:info-effect}).
172
173 \begin{figure}[htpb]
174     \centering
175     \includegraphics[width=0.8\linewidth]{info-effect.png}
176     \caption{Effect Info for Color 3 Way}
177     \label{fig:info-effect}
178 \end{figure}
179
180 \subsection{Delete Plugins to save Resources Space or make them Unavailable}%
181 \label{sub:delete_plugin_resouces_unavaible}
182
183 Maybe you just don't ever use certain plugins or would prefer to only find the ones that are useful to you. To save space in the Resources Window so you don't have to scroll to find the plugins you want as much, a feature to delete others is available. If you have a System install, you will have to be root for this function to be usable. The plugins will be permanently deleted, but only until you rebuild or download a new set of \CGG{} binaries. To delete a plugin, highlight the plugin you no longer want in the Resources window then press Ctrl-Shift-delete. A small window will come up allowing you to change your mind and red-X out or check-OK to remove plugin. This feature may come in handy if you have personnel working on media for you and you only want them to exercise certain functions. Or maybe you can't remember which is the good \textit{deinterlace} plugin out of the available five or so and want to delete the extras so as not to be confused. The ffmpeg, \textit{ladspa}, and \textit{lv2} plugins can not be deleted in this manner but, of course, you can always turn them off from view by clicking on \textit{Visibility} and unchecking them (figure~\ref{fig:remove-effect}).
184
185 \begin{figure}[htpb]
186     \centering
187     \includegraphics[width=0.6\linewidth]{remove-effect.png}
188     \caption{Remove Deinterlace-CV plugin}
189     \label{fig:remove-effect}
190 \end{figure}
191
192 \subsection{Updatable Icon Image Support}%
193 \label{sub:updatable_icon_image_support}
194 \index{plugins!change icons}
195
196 When running \CGG{} Infinity builtin icons are loaded before the
197 program starts. Png files in the path:\\
198 \texttt{<target\_directory>picon/picon\_set\_name}\\
199 are searched before the images loaded into memory. Override
200 \texttt{icon.png} files must be put into the path:\\
201 \texttt{<target\_directory>/picon/picon\_set\_name}\\
202 There are currently 4 sets of icons and their directory names are
203 \textit{cinfinity} (the default) and \textit{cinfinity2},
204 \textit{original} (the long-time original set), and
205 \textit{smoother} (generally was in use by some of the themes). An
206 example, to replace the cinfinity icon of Blue Banana with a red
207 apple instead, create your \texttt{.png} file as desired, and replace the
208 file in:\\
209 \texttt{<target\_directory>/bin/plugins/picon/cinfinity/bluebanana.png}.
210
211 For most User installs, the \texttt{<plugin\_name>.png} file will be located at:
212
213 \texttt{<cinlib\_path>/bin/plugins/picon/cinfinity} (or cinfinity2, original or smoother)
214
215 For some System installs, the files might be located at:
216
217 \texttt{/usr/lib/cin/plugins/picon/cinfinity}
218
219 (or cinfinity2, original or smoother -- ubuntu distros)
220
221 \texttt{/usr/lib64/cin/plugins/picon/cinfinity}
222
223 (or cinfinity2, original or smoother -- Leap distro)
224
225 \subsection{Details on where to put your own Plugin Icons}%
226 \label{sub:details_put_plugin_icons}
227
228 In order to make the icons available to all themes, which would thus be the default when no theme-specific icon is available, put the png file in the:
229
230 \texttt{<cinlib\_path>/bin/plugins/picon/cinfinity} (or cinfinity2, original or smoother)
231
232 The \CGG{} program looks for a plugin icon in two places:
233
234 \begin{enumerate}
235     \item First, it tries to find a png file in \texttt{<cinlib>/plugins/picon/cinfinity}(2) or original, smoother directory.
236     \item If there is no corresponding \texttt{.png} file for a plugin, the program uses a built-in default:
237     \begin{itemize}
238         \item ordinary video plugins use 3 vertical color bars as a default;
239         \item ffmpeg plugins use the words \textit{FF} on yellow colored background as a default icon;
240         \item audio and ladspa plugins use a green-colored audio wave for a default.
241     \end{itemize}
242 \end{enumerate}
243 \begin{figure}[htpb]
244     \centering
245     \includegraphics[width=0.05\linewidth]{audio-default.png}
246 \end{figure}
247
248 Keep in mind these points for newly created plugin icons:
249
250 \begin{itemize}
251     \item All included icon images become part of open source, in the public domain, and not proprietary.
252     \item The preferred format is $52 \times 52$, $8\,bit$ /color RGB or RGBA, non-interlaced.
253     \item Since plugin icons are used by different themes, it is recommended that a \textit{transparent background} be used. Otherwise some color background that looks good for one theme may not for another.
254     \item In order to test a new icon, you have to have write permission in the: \\
255     \texttt{<cinlib\_path>/plugins} directory so you may have to become the root user to copy the \texttt{.png} file to the correct location.
256     \item If there is currently no theme-specific \texttt{.png} files present, it may be necessary to first create the theme directory in \texttt{<cinlib\_path>plugins} as \texttt{<theme\_name>} in order to put the \texttt{.png} files in that subdirectory.
257     \item Make sure that the \textit{ownership} and file \textit{permissions} match the existing directory and files.
258     \item All ffmpeg icons must begin with \texttt{ff\_<plugin\_name>.png} (Resources window title will still be F\_\dots)
259     \item For ladspa, check in the \texttt{<cin\_config>} directory (\texttt{\$HOME/.bcast5} normally) and look for the text file \texttt{\$HOME/.bcast5/ladspa\_plugins\dots} for the names of the ladspa libraries which correspond to plugin names where the needed name is the basename of the \texttt{.so} file.
260         For example \texttt{pha\-sers\_1217.so} would need to have a \texttt{phasers\_1217.png} file. There may be multiple plugins in a single “so” file which means that you can only have 1 icon to represent all of the plugins in that file; again as in phasers.
261     \item Once you have placed the .png file in the correct spot, you will have to restart \CGG{} to test it.
262     \item To submit your \texttt{.png} file for inclusion into \CGG{} Infinity for all to enjoy, it is best to upload it to any datafilehost and notify the community via email with any informative documentation.
263 \end{itemize}
264
265 \subsection{Example of new Plugin Icon Testing}%
266 \label{sub:example_plugin_icon_testing}
267
268 For a simple test just copy an existing \texttt{<plugin\_name>.png} file into the cinfinity directory with the name \texttt{bluebanana.png} to write over the existing file. This icon will now show up in \CGG{} and still execute the Blue Banana function.
269
270 For an ffmpeg plugin, create \texttt{ff\_loop.png} and copy it to: \\
271 \texttt{<cinlib\_path>/plugins/picon/original}. This icon will show up in \CGG{} if original is selected and execute the \textit{F\_loop} function.
272
273 For a ladspa plugin, the text line in \texttt{\$HOME/.bcast5/ladspa\_plugins}$\dots$ as seen below:
274 2 \texttt{am\_pitchshift\_1433.so} \\
275 \texttt{AM pitchshifter} $1504922321\, 0\, 1\, 0\, 0\, 1\, 0\, 1\, 0\, 1\, 0\, 0$ indicates that you would create the icon: \\ \texttt{<cinlib\_path>/plugins/picon/cinfinity/am\_pitchshift\_1433.png} \\
276 For your own personal plugins, you can create a directory on your system and put any plugin png files you like into that directory. For example, if you want a specialized picon for \textit{F\_aeval}, create a picon named \texttt{ff\_aeval.png} in: \\ \texttt{<cinlib\_path>/plugins/picon/yournamehere.}
277
278 \begin{lstlisting}[style=sh]
279 cd <cinlib>/plugins            # go to the correct directory
280 mkdir -p picon/yournamehere    # create subdirectory if does not exist
281 ls -l picon/*                  # list the picon directories
282                                # check for existence (and permissions)
283 cp yourpicon.png ff_aeval.png  # Copy your example .png file
284 \end{lstlisting}
285
286 Restart cin by changing \texttt{Settings$\rightarrow$ Preferences$\rightarrow$ Appearance} and in \textit{Plugins icons} choose a directory.
287
288 \subsection{Plugins/Effects Visibility}%
289 \label{sub:plugins_effects_visibility}
290 \index{plugins!visibility}
291
292 \CGG{} contains many plugins, especially with the addition of ffmpeg, and it is somewhat difficult to find the one you are looking for in the Resources window. In \CGG{} Infinity, the plugins have been categorized into the following subsets in the \textit{Visibility} section of the Resources window to make it easier to locate a particular one:
293
294 \textit{Audio Effects, \quad Video Effects, \quad Audio Transitions, \quad Video Transitions}
295
296 \begin{figure}[htpb]
297     \centering
298     \includegraphics[width=0.8\linewidth]{visibility01.png}
299     \caption{Screenshot showing on the left hand side the Visibility box with Audio Effects highlighted.}
300     \label{fig:visibility01}
301 \end{figure}
302
303 The \textit{Visibility} tool in the Resources window (figure~\ref{fig:visibility01}) gives you the ability to turn off or on any of several sets of plugins. If you left-click the Visibility box, you will see the various categories of plugins, such as \textit{ladspa}, \textit{ffmpeg}, \textit{audio}, \textit{lv2}, and \textit{video} (figure~\ref{fig:visibility02}).
304
305 \begin{figure}[htpb]
306         \centering
307         \includegraphics[width=0.6\linewidth]{visibility02.png}
308         \caption{Screenshot showing the Visibility categories of plugins with all toggled on and audio highlighted.}
309         \label{fig:visibility02}
310 \end{figure}
311
312 Highlight the set you want to turn on and a check mark appears to show it is active. Highlight again to toggle it off. See the next screenshot which illustrates that all of the plugins are turned off (not visible) except for audio. There is also the ability to add your own personal directory of plugins which will show up here. All you have to do to have these plugins become visible is to create a directory, with some name that is meaningful to you, and put your .png files in your: \\
313 \texttt{cinelerra\_path bin/plugins/<your\_directory\_name>}.
314
315 \subsection{Expanders for Plugin Subtrees in the Resources Window}%
316 \label{sub:expanders_plugin_subtrees}
317
318 To accentuate a set of common plugins, there are \textit{expander} arrows on the left side of the Resources window. You will see these expanders only when in \textit{Display text} mode, not \textit{icon} mode.
319 \CGG{}’s default setup is in the file \texttt{\$CIN\_DAT/expan\-ders.txt} but if the user wants their own specific setup and if the file in \texttt{\$HOME/.\\bcast5/expanders.txt} exists, it will take precedence.
320 If there are recommendations for other relevant categories, they can be added. The subtree structure is applicable to any of the \textit{Video Effects/Transitions} or \textit{Audio Effects/Transitions}. You can not sort once an expansion is in effect (figure~\ref{fig:expander}).
321
322 The \texttt{expanders.txt} file has very specific requirements. The most specific is that there are no blanks -- you must use tabs only. A \# (pound sign) can be used in column 1 to indicate a comment. Here is a short example:
323
324 \begin{figure}[htpb]
325         \centering
326         \includegraphics[width=0.8\linewidth]{expander.png}
327         \caption{Down facing triangle, Right facing triangle = expander; "-" = options}
328 %       the next line causes problems for the HTML version so do not use
329 %       \caption{$\triangledown$,$\triangleright$ = expander; "-" = options}
330         \label{fig:expander}
331 \end{figure}
332
333 \begin{lstlisting}[style=sh]
334 Video Effects
335     - Color_Correction
336         Blue Banana
337                           Color 3 Way
338         Color Balance
339 Audio Effects
340     - Calf
341     - Instruments / Generators
342         L2_Calf Organ
343         L2_Calf Monosynth
344         L2_Calf Fluidsynth
345 \end{lstlisting}
346
347 \subsection{Speed-up of Ffmpeg plugin usage with OPTS files}%
348 \label{sub:speedup_ffmpeg_plugin_opts}
349 \index{plugins!speed-up via options}
350
351 You can speed up some ffmpeg plugins that are quite time-consuming and use a lot of CPU\@. For a specific color-based example, \CGG{} uses 6 primary rendering color models. All of them have 3 components at full scale. Direct usage of a particular ffmpeg plugin from the ffmpeg command line might handle the planar at less than full scale chroma (yuv420), which means there is less data to manipulate. But when cinelerra loads a video it uses full scale color models. In other words:
352
353 \begin{itemize}[noitemsep]
354     \item \CGG{} uses \textit{yuv444}
355     \item ffmpeg uses \textit{yuv420}
356 \end{itemize}
357
358 if using an ffmpeg plugin that uses filters and many passes over the data, the amount of data is a big factor. If you load a file in \CGG{} with a
359
360 \texttt{same\_directory\_path\_and\_filename.opts}
361
362 file containing the following line, the full scale color modeling upgrade will not be performed until after any plugin, and then the render is faster:
363
364 \begin{lstlisting}[style=sh]
365 video_filter=xxxxxx=threads=8 # where xxxxxx is the desired filter
366 \end{lstlisting}
367
368 When the file loads, however, it will initially take longer because it is running through the video filter. The format \textit{rgb} in ffmpeg uses more cpu time. For comparison, ffmpeg line that might be used:
369
370 \begin{lstlisting}[style=sh]
371 ffmpeg -i /tmp/filename.mpeg -threads 15 -vf format=rgb24,xxxxxxs=threads=8 -acodec ac3 -vcodec libx265 - y /tmp/x.mp4
372 \end{lstlisting}
373
374 This converts the input to rgb before xxxxxx runs, and so it too is slower (because there is more color data). You would ordinarily avoid this conversion by omitting the \texttt{format=rgb24} parameter. An example ffmpeg plugin that could easily take advantage of an auxilliary opts file is \textit{nlmeans}.
375
376 \section{Audio Effects - Native}%
377 \label{sec:audio_effects_native}
378 \settocdepth{subsection}
379 \index{audio!plugins}
380
381 \subsection{AudioScope}%
382 \label{sub:audioscope}
383 \index{audioscope}
384
385 Effect rewritten and improved. Convert input audio to video output representing the audio power spectrum. Shows
386 % Yes
387  %\todo{It's OK to use Subsection every plugin?}%
388 you the sound wave.
389
390 \subsection{Chorus}%
391 \label{sub:chorus}
392 \index{chorus}
393
394 It is a multitrack effect, where each track is a channel. For example if you have 4 voices per channel and 2 channels, you will have a total of 8 tracks.
395 It is an effect that modulates the signal, varies the pitch up and down (instead of modulating the phases as for example in the \textit{Flanger} plugin) and creates voices from the original signal and adds them to the Output. You then get a chorus effect, with multiple voices \textit{singing} the same song but with slightly different modulations. Voices not only modulate the original signal but also start with a certain delay. There are two components of delay, \textit{constant delay} and \textit{oscillating delay} (figure~\ref{fig:chorus}).
396
397 \begin{figure}[htpb]
398         \centering
399         \includegraphics[width=0.5\linewidth]{chorus.png}
400         \caption{GUI of configuration for Chorus plugin}
401         \label{fig:chorus}
402 \end{figure}
403
404 \begin{description}
405         \item[Voices per channel]: number of items we want to put in the effect. Using more than 4 voices creates sound artifacts that lose the feel of a human voice choir, but can still be used as an artificial sound effect.
406         \item[Phase offset] (ms): is the constant delay, i.e.\ the amount of delay of the voices compared to the original signal.
407         \item[Depth] (ms): is the oscillating delay, i.e.\ the delay in the oscillation of the various voices from the original signal.
408         \item[Rate] (Hz): is the speed at which we apply the oscillating delay. In other words, the speed at which the oscillations occur.
409         \item[Wetnwss] (db): Indicates how much of the original (dry) signal is taken into account compared to delayed voices.
410 \end{description}
411
412 \subsection{Compressor (Single Band)}%
413 \label{sub:compressor}
414 \index{compressor}
415
416 The audio compressor reduces the dynamic range of the audio, not the amount of data required to store the audio. In \CGG{} the compressor actually performs the function of an expander and compressor of the signal's dynamic range. A third and more sophisticated use serves to highlight the voice with respect to the sound background. It is a multitrack effect and can also be applied as a Shared Effect. (figure~\ref{fig:compressor}).
417
418 \begin{figure}[htpb]
419     \centering
420     \includegraphics[width=0.7\linewidth]{compressor.png}
421     \caption{GUI of configuration for Compressor plugin}
422     \label{fig:compressor}
423 \end{figure}
424
425 The compressor works by calculating the maximum sound level within a certain time period of the current position. The maximum sound level is taken as the input sound level. For every input sound level there is an output sound level specified by the user.
426 The gain at the current position is adjusted so the maximum sound level in the time range is the user specified value.
427 The compressor has a graph which correlates every input sound level to an output level. The horizontal direction is the input sound level in dB. The vertical direction is the output sound level in dB. The user specifies output sound levels by creating points on the graph. Click in the graph to create a point. If two points exist, drag one point across another point to delete it. Moving the point horizontally is equivalent to the \textit{makeup gain} parameter. Note that it is impossible to create a vertical curve; points would be deleted.
428 Put a part of the curve in horizontal means clamping the signal to the same, unique value (as Limiter).
429 The most recent point selected has its values displayed in textboxes (Output and Input) for more precise adjustment.
430 To have the compressor reduce the dynamic range of the audio, make all the output values greater than the input values except 0\,dB. To make the compressor expand the dynamic range of the audio, make all the output values except 0\,dB less than the input values. The algorithm currently limits all sound levels above 0\,dB to 0\,dB, so to get an overloaded effect put a gain effect before the compressor to reduce all the levels and follow it with another gain effect to amplify all the levels back over 0\,dB.
431 The volume (in Db) of the input signal is shown in the \textit{In meter} on the left. Next to it is the \textit{Gain meter} which indicates the gain added (green) or subtracted (red) to the original signal according to our settings.
432
433 \begin{description}
434     \item[Attack secs]: determines where in relation to the current position the maximum sound level is taken and how fast the \textit{gain} is adjusted to reach that peak. It is in seconds. If the reaction time is negative the compressor reads ahead of the current position to get the future peak. The gain is ramped to that peak over one reaction time. This allows it to hit the desired output level exactly when the input peak occurs at the current position. If the reaction time is positive the compressor scans only the current position for the gain and ramps gain over one reaction time to hit the desired output level. It hits the output level exactly one reaction time
435     after detecting the input peak.
436     \item[Release secs]: if the peak is higher than the current level, the compressor ramps the gain up to the peak value. Then if a future peak is less than the current peak it ramps the gain down. The time taken to ramp the gain down can be greater than the time taken to ramp the gain up. This ramping down time is the decay seconds.
437     \item[Trigger type]: the compressor is a multi-channel effect. Several tracks can share one compressor. How the signal from many tracks is interpreted is determined by the \textit{trigger type}. The Trigger type uses the value supplied in the Trigger textbox as the number of the track to use as input for the compressor. This allows a track which is not even heard to determine the loudness of the other tracks. The maximum trigger takes the loudest track and uses it as the input for the compressor. The Total trigger type adds the signals from all the tracks and uses the total as the input for the compressor. This is the most natural sounding compression and is ideal when multiple tracks are averaged into single speakers.
438     \item[Trigger]: This parameter is used in conjunction with trigger type as described previously. Normally only one track is scanned for the input peak. This track is specified by the Trigger. By sharing several tracks and playing with the trigger value, you can make a sine wave on one track follow the amplitude of a drum on another track, for example.
439     \item[Smooth only]: for visualizing what the compressor is doing to the sound-level, this option causes it to replace the sound wave with just the current peak value. It makes it very easy to see how \textit{reaction secs} affects the detected peak values.
440     \item[Gain]: moves the curve in the vertical direction only, to change the gain of the Output.
441     \item[Clear] and \textbf{Reset}:  Reset the parameters to the default values (no compression).
442 \end{description}
443
444 \subsection{Compressor Multi (Multi Band)}%
445 \label{sub:compressor_multi}
446 \index{compressor multi band}
447
448 Refer to Compressor (Single Band) for common theory and options.
449 The normal compressor acts over the entire frequency spectrum. The multi-band allows us to distinguish three frequency ranges (low, med and high) on which to intervene separately and in a more sophisticated way. In other plugins there are four bands instead of three, but we can make very precise adjustments so the three present are enough because they are not fixed. Finally the value of the three corrections are added together in the Output.
450
451 \begin{figure}[htpb]
452         \centering
453         \includegraphics[width=0.7\linewidth]{compressorM.png}
454         \caption{GUI of configuration for Compressor Multi plugin}
455         \label{fig:compressorM}
456 \end{figure}
457
458 The three bands and their range (adjustable as desired) are shown in the frequency graph visible below (Bandwidth:).
459 As a first step you choose the band and adjust its range in the Bandwidth graph, then you go to adjust the compression in the top level graph. In this graph we can copy/paste the curve in the other bands via RMB; so we have a similar basis on which to make the adjustments.
460
461 In figure~\ref{fig:compressorM} we can see the three bands; the one currently active (\textit{Current band: 2}) presents the waveform of the sound signal. The interval goes roughly between 300\,Hz and 4000\,Hz, the edges are vertical because the \textit{stepness} is set to zero. So we have a clear separation between the bands, but by varying the slope we can have some overlapping of the bands for smoother effects. In the top level graph we can see the yellow curve of the active band, but we can also see in the violet the soft lines of the curves of band 1 and 2.
462
463 \begin{description}
464         \item[Solo]: brings only the active band to the Output, silencing the others. So we can make more precise adjustments without listening to the whole effect.
465         \item[Bypass band]: In contrast to Solo, it only brings the sound signals of the two inactive bands to the Output.
466         \item[Freq range]: is used to set bandwidth limits. You act separately on the left and right edge.
467         \item[Steepness]: varies the slope of the edges of the band range. Creates some overlap in the band boundaries.
468         \item[Channel]: is the equivalent of the \textit{Trigger} option in Compressor (single band). Allows you to choose the channel or track to act on.
469         \item[Window size]: Determines the number of samples used in the compression calculation. The more they are, the higher the quality of the result, but the more CPU usage.
470 \end{description}
471
472 \subsection{DC Offset}%
473 \label{sub:dc_offset}
474 \index{dc offset}
475
476 Use this to remove \textit{DC Offset}, which is usually an undesirable characteristic of a recording normally caused by defective equipment. This effect works like a \textit{high pass filter} and has no controls. DC stands for \textit{Direct Current} which is the average amplitude of the waveform. It sounds best when it is absent, represented by zero, so that there is no imbalance in the audio.
477
478 \subsection{Delay Audio}%
479 \label{sub:delay_audio}
480 \index{delay audio}
481
482 In the Delay Audio effect you can specify the number of seconds you want to delay the video track.
483
484 \subsection{DeNoise}%
485 \label{sub:denoise}
486 \index{denoise}
487
488 Reduce audio background noise. There is only 1 parameter which is used to regulate the level dial with a range of 0 to 1.
489
490 \subsection{DenoiseFFT}%
491 \label{sub:denoisefft}
492 \index{denoisefft}
493
494 Noise removal from audio using FFT editing. Set the Denoise Power dial in dB and choose the number of reference samples.
495
496 \subsection{Despike}%
497 \label{sub:despike}
498 \index{despike}
499
500 Detect and eliminate out of range impulse values.
501
502 \begin{description}
503     \item[Maximum level:] slider to set the maximum value in dB above which the frequency cutting takes place.
504     \item[Maximum rate of change:] to adjust peak delete in dB.
505 \end{description}
506
507 \subsection{EQ Graphic}%
508 \label{sub:eq_graphic}
509 \index{EQ graphic}
510
511 Graphic equalizer sets the output levels for specified frequency bands. This effect works by setting control points when you click the left mouse button and drag to the desired value. In the textboxes at the bottom can be seen the frequency of the active control point, the level of the signal to be set by entering the numerical value or by dragging the control point, and the number of samples to act on (figure~\ref{fig:equalizer}).
512
513 \begin{figure}[htpb]
514     \centering
515     \includegraphics[width=0.8\linewidth]{equalizer.png}
516     \caption{Graphic Equalizer audio plugin}
517     \label{fig:equalizer}
518 \end{figure}
519
520 \subsection{EQ Parametric}%
521 \label{sub:eq_parametric}
522 \index{EQ parametric}
523
524 Parametric equalizer shows and outputs levels for \textit{frequency}, \textit{quality}, \textit{level}, \textit{mode}, and \textit{wetness} (figure~\ref{fig:eq_param}).
525
526 \begin{figure}[htpb]
527         \centering
528         \includegraphics[width=0.4\linewidth]{eq_param.png}
529         \caption{EQ Parametric audio plugin}
530         \label{fig:eq_param}
531 \end{figure}
532
533 \subsection{Echo}%
534 \label{sub:echo}
535 \index{echo}
536
537 Echo is reflection of sound. This plugin could be used to add echoing to video of your canyon hike (figure~\ref{fig:echo}).
538
539 \begin{figure}[htpb]
540     \centering
541     \includegraphics[width=0.4\linewidth]{echo.png}
542     \caption{The 3 dials of Echo plugin}
543     \label{fig:echo}
544 \end{figure}
545
546 \begin{description}
547     \item[Level] represents the volume adjustment.
548     \item[Atten] is attenuation which is a general term that refers to any reduction in the echo reflection. Sometimes called \textit{loss}, attenuation is a natural consequence of signal transmission over long distances.
549     \item[Offset] is the lag in the attenuated echo signal. Offset means adding a DC level to a signal. It offsets the signal up or down in a DC sense without changing the size of the AC part of the signal. When you add an audio clip to the Timeline, the clip plays back from the beginning of the source audio file. The point in the audio file where the clip starts playing is called the offset. By default, a clip’s offset is zero, the beginning of the source audio file. You can change the offset so that the clip starts playing from a later point in the source audio file.
550 \end{description}
551
552 \subsection{EchoCancel}%
553 \label{sub:echocancel}
554 \index{echo cancel}
555
556 EchoCancel is the process of removing echos from audio in order to improve the quality. Echo cancel may be needed because an audio recording was done in a room that led to echo generation or there was some kind of unwanted feedback. There are many controls for the EchoCancel plugin which are defined here. However, the first thing you will see when you bring up the plugin, is the top portion that is black which will show a + in the middle when you mouse over it. Once you start playing audio, you will see the cepstrum spectral data inside the window. A cepstrum results from taking the inverse Fourier transform (IFT) of the logarithm of the estimated spectrum of a signal. It is used to identify the period of the echo in the audio. It is recommended to just set the \textit{Mode} to On but the below defined parameters can be utilized by professionals (figure~\ref{fig:echo-cancel}).
557
558 \begin{figure}[htpb]
559     \centering
560     \includegraphics[width=0.8\linewidth]{echo-cancel.png}
561     \caption{GUI for EchoCancel with crosshair and mode set to ON}
562     \label{fig:echo-cancel}
563 \end{figure}
564
565 \begin{description}
566     \item[Normalize:] audio normalization adds variable amounts of gain to an audio recording to bring the average or peak amplitude to a target level (the normal amount), on an ongoing buffer by buffer basis. This is to make the cepstrum graphical data appear between 0 and 1. Checkmark appears if ON.
567     \item[Level:] scale factor used to draw the cepstrum output when normalize is not in effect.
568     \item[History:] number of previous cepstrum outputs redrawn as fading graphical data.
569     \item[X Zoom:] X axis scale factor to magnify low frequency cepstrum graphical output.
570     \item[Damp:] echo envelope decay factor used to smooth the cepstrum/correlation data.
571     \item[Peaks:] number of maximal envelope values used in the echo gain calculation.
572     \item[Cutoff Hz:] low frequency cutoff value to prevent beat frequency (\textit{heterodyne}) echo canceling.
573     \item[Mode:] \textit{MAN}, \textit{Off}, or \textit{On}. When Off is selected, the plugin is not active. When MAN is used, the only one peak is used for the echo gain envelope. It is set by pressing mouse button $1$ in the ceptstrum graphical output. The Gain and Offset are updated as the pointer drag operation resets the indicated gain and offset values. When On is selected, the echo gain envelope is automatically calculated by cepstrum and auto-correlation of the input audio in the last window size audio samples.
574     \item[Windows size:] parameter can be set to \textit{Default}, $1024$, $2048$, \dots \textit{doubled values\dots} up to $262144$.
575     \item[Amplitude:] the cepstrum value at the drag point during manual envelope selection.
576     \item[Gain:] echo gain setting determined by manual selection.
577     \item[Offset:] echo period setting determined by manual selection. The $Hz$ (frequency), $ms$ (millisecond duration), and sample offset (audio samples) as determined by manual selection.
578 \end{description}
579
580 \subsection{Flanger}%
581 \label{sub:flanger}
582 \index{flanger}
583
584 It's a single-track effect. If you apply it to multiple tracks each will work on its own track independently of the others.
585 It consists of making a copy of the original sound wave and then playing it over the original one with a certain delay. The resulting signal (Output) will then be the sum of the two waves and will have peaks where the two values add up and gaps where the two values compensate each other. The result is a more \textit{evanescent} and \textit{metallic} sound. Much, however, depends on the intensity of the effect.
586 The delay introduced consists of two distinct components: the \textit{constant delay} and the \textit{oscillating delay}. Their sum constitutes the total delay of the effect (figure~\ref{fig:flanger}).
587
588 \begin{figure}[htpb]
589         \centering
590         \includegraphics[width=0.6\linewidth]{flanger.png}
591         \caption{GUI of configuration for Flanger plugin}
592         \label{fig:flanger}
593 \end{figure}
594
595 \begin{description}
596         \item[Phase Offset]: it is the constant delay. Once set, its value does not change (unless we change it, for example by use of keyframes) for the duration of the effect.
597         \item[Starting phase] \%: is the point of oscillation where we start the oscillating delay; basically it is the attack value at which the effect starts the calculations. Not to be confused with the point on the timeline where we apply the effect. It only matches this for the 0\% value. The position on the timeline where we want to start the flanger at a given starting phase value can be chosen using keyframes.
598         \item[Depth]: It is the oscillating delay. This value determines the amplitude variation of the delayed (wet) signal phase. This oscillation will be maintained for the entire duration of the effect unless we change it.
599         \item[Rate]: is the speed at which we apply the oscillating delay. Low values indicate a lower oscillation frequency, a high value a rapid succession of oscillations.
600         \item[Wetness]: indicates how much of the original (dry) signal is taken into account compared to the delayed (wet) signal.
601 \end{description}
602
603 \subsection{Freeverb}%
604 \label{sub:freeverb}
605 \index{freeverb}
606
607 Adds effect of multiple decaying echoes to audio signals based on a specific algorithm. Common use of reverb is to simulate music played in a closed room.
608
609 \subsection{Gain}%
610 \label{sub:gain}
611 \index{gain}
612
613 Add gain, input level, to increase/decrease loudness.
614
615 \subsection{Interpolate}%
616 \label{sub:interpolate}
617 \index{interpolate}
618
619 Generate a smooth curve based on sound creating a certain softness. There are no controls.
620
621 \subsection{Invert Audio}%
622 \label{sub:invert_audio}
623 \index{invert audio}
624
625 Reverses the numerical sign of the digital audio. There are no controls.
626
627 \subsection{Live Audio}%
628 \label{sub:live_audio}
629 \index{live audio}
630
631 The Live Audio effect reads audio directly from the sound card input. It replaces any audio on the track so it is normally applied to an empty track. To use Live Audio, highlight a horizontal region of an audio track or define In and Out points. Then drop the Live Audio effect into it. Create extra tracks and attach shared copies of the first Live Audio effect to the other tracks to have extra channels recorded. Live Audio uses the sound driver selected in \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Playback A $\rightarrow$ Audio Out for recording}, but unlike recording it uses the playback buffer size as the recording buffer size and it uses the project sample rate as the sampling rate. These settings are critical since some sound drivers can not record in the same sized buffer they play back in.
632
633 Live audio has been most reliable when ALSA is the recording driver and the playback fragment size is $2048$. Drop other effects after Live Audio to process sound card input in realtime. With live audio there is no read-ahead, so effects like compressor will either delay if they have read-ahead enabled or playback will under-run. A potential problem is that sometimes the recording clock on the sound card is slightly slower than the playback clock. The recording eventually falls behind and playback sounds choppy. Live Audio does not work in reverse.
634
635 \subsection{Loop Audio}%
636 \label{sub:loop_audio}
637 \index{loop audio}
638
639 Loop some number of samples of audio over and over.
640
641 \subsection{Overlay (Audio)}%
642 \label{sub: overlay}
643 \index{overlay audio}
644
645 Overlay has parameter settings of top or bottom for the track and add or multiply for the operation.
646
647 \subsection{Pitch Shift}%
648 \label{sub:pitch_shift}
649 \index{pitch shift}
650
651 Like the time stretching methods, there are three pitch shifting methods: \textit{Pitch shift}, \textit{Resample}, and \textit{Asset info} dialog. Pitch shift is a realtime effect which can be dragged and dropped onto recordable audio tracks. Pitch shift uses a fast Fourier transform (FFT) to try to change the pitch without changing the duration, but this introduces windowing artifacts. Because the windowing artifacts are less obtrusive in audio which is obviously pitch shifted, Pitch Shift is mainly useful for extreme pitch changes. For mild pitch changes, use Resample instead. Another way to change pitch slightly is to go to the Resources window, highlight the media folder, right click on an audio file, click on \textit{Info}, then adjust the sample rate in the Info dialog to adjust the pitch. This method also requires left clicking on the right boundary of the audio tracks and dragging left or right to correspond to the length changes.
652
653 \subsection{Remove Gaps}%
654 \label{sub:remove_gaps}
655 \index{remove gaps}
656
657 Remove silent gap (below $DB$ threshold) which persist for more than the time limit.
658
659 \subsection{ResampleRT}%
660 \label{sub:resamplert}
661 \index{resampleRT}
662
663 Allows you to convert an audio file from one sample rate to another. This effect works similarly to ReframeRT in videos.
664
665 \begin{center}
666     \begin{tabular}{l l}
667         \toprule
668         Input / output > 1 &    fast rate \\
669         Input / output < 1 &    slow rate \\
670         \bottomrule
671     \end{tabular}
672 \end{center}
673
674 \subsection{Reverb}%
675 \label{sub:reverb}
676 \index{reverb}
677
678 Reverb uses reflections of sound to add depth and fullness; the sound will seem to come from a space that can go from a small bare room to large natural valleys, cathedrals, etc. The reverb is made up of a group of echoes that occur at the same time making it feel like a single effect.
679 Basically simulates creation of a large number of reflections, like lots of walls, which build up and then decay. You can use the reverb plugin to mix tracks together to simulate ambiance because it is a multitrack effect.
680 The configuration window (figure~\ref{fig:reverb}) shows a graph of the full band pass filter frequencies.
681
682 \begin{figure}[htpb]
683         \centering
684         \includegraphics[width=0.6\linewidth]{reverb.png}
685         \caption{GUI of configuration for Reverb plugin}
686         \label{fig:reverb}
687 \end{figure}
688
689 \begin{description}
690         \item[Initial signal level](db): Allows you to set the level of the reflected signal. At 0 you start from its maximum level. Decreasing the signal volume will give more presence to the original signal.
691         \item[ms before reflections]: indicates when to start the reflected sounds in relation to the original sound  (delay).
692         \item[First reflection level] (db): the sound level of the reflection that starts first.
693         \item[Last reflection leve] (db): the level of the last reflection. It is weaker than the first.
694         \item[numbers of refelctions]: the number of reflections can be set as desired as long as there is sufficient CPU to handle it. With a few reflections you get closer to the Chorus effect. You can start from values of 100 - 150, up to a maximum of 255.
695         \item[ms of refelction]: Sets the action time of the effect. With high values, the sound is more clear and sharp
696         \item[Low freq of bandpass] and \textbf{High freq of bandpass}: allow you to set the frequency limits (range) on which the effect acts.
697         \item[Steepness of bandpass]: allows you to adjust the slope of the frequency range limits imposed by the previous items. With the value 1.00 we have a vertical edge that clearly separates the range of frequencies on which to act from the remaining ones (as you can see in figure~\ref{fig:reverb}). By sloping the edge we have a certain overlap and a smoother effect.
698         \item[Window]: determines the number of frequency samples taken into account by the effect for its calculations. The higher the number, the smoother the effect; but more CPU is used.
699 \end{description}
700
701 \subsection{Reverse Audio}%
702 \label{sub:reverse_audio}
703 \index{reverse audio}
704
705 Apply reverse audio to an audio track and play it backwards. The sound plays forward. Be aware when reversing audio that the waveform on the timeline does not reflect the actual reversed output.
706
707 \subsection{SoundLevel}%
708 \label{sub:soundlevel}
709 \index{sound level}
710
711 Effect rewritten and improved to handle fragments. Displays the Max/RMS sound level in decibels.
712
713 \subsection{Spectrogram}%
714 \label{sub:Spectrogram}
715 \index{spectrogram}
716
717 Effect rewritten and improved. Visual representation of the sound levels at specified frequencies as they vary with time.
718
719 \subsection{Synthesizer}%
720 \label{sub:Synthesizer}
721 \index{synthesizer}
722
723 Generate synthesizer sounds; to set key data, turn on Generate keyframes while tweaking (figure~\ref{fig:synthesizer}).
724
725 \begin{figure}[htpb]
726     \centering
727     \includegraphics[width=1.0\linewidth]{synthesizer.png}
728     \caption{GUI for Synthesizer}
729     \label{fig:synthesizer}
730 \end{figure}
731
732 \subsection{Time Stretch RT}%
733 \label{sub:time_stretch_rt}
734 \index{time stretch RT}
735
736 Change the speed of an audio signal without affecting its pitch.
737
738 \subsection{Tremolo}%
739 \label{sub:tremolo}
740 \index{tremolo}
741
742 It serves to give various vibes and vitality to the sound by modulating the amplitude of the sound signal and the delay (figure~\ref{fig:tremolo}).
743
744 NOTE: There is often confusion between Tremolo and Vibrato, but the vibrato is the periodic variation of the height of a note (frequency) while the tremolo is the periodic variation of the height (amplitude) of the sound wave.
745
746 \begin{figure}[htpb]
747         \centering
748         \includegraphics[width=0.5\linewidth]{tremolo.png}
749         \caption{GUI of configuration for Tremolo plugin}
750         \label{fig:tremolo}
751 \end{figure}
752
753 \begin{description}
754         \item[Phase offset] (\%): is where the oscillation effect begins. At 0\% we are at maximum volume; to lower the volume, increase the percentage.
755         \item[Depth] (dB): is the oscillation damping value. You can only decrease the level, you cannot increase it.
756         \item[Rate] (Hz): is the speed at which the oscillations are repeated.
757         \item[Waveform]: you can choose waveform algorithms to use in effect calculations.
758 Currently available waveforms are: \textit{Sine}; \textit{Sawtooth}; \textit{Rev Sawtooth}; \textit{Square} and \textit{Triangle}.
759 \end{description}
760
761 \section{Audio Ladspa Effects}%
762 \label{sec:audio_ladspa_effects}
763 \settocdepth{section}
764 \index{ladspa}
765
766 Ladspa effects are supported in realtime and rendered mode for audio. These audio effects are supported since \CGG{} implements the LADSPA interface as accurately as possible. Besides the supplied LADSPA effects\protect\footnote{credit Steve Harris}, additional LADSPA effects can be enabled by setting the \texttt{LADSPA\_PATH} environment variable to the location of your LADSPA plugins:
767
768 \begin{lstlisting}[style=sh]
769 export LADSPA_PATH=/usr/lib/ladspa
770 \end{lstlisting}
771
772 \section[Audio LV2 / Calf Plugins]{Audio LV2 / Calf Plugins\protect\footnote{Optional Feature - OS dependent}}%
773 \label{sec:audio_lv2_calf_plugins}
774 \index{LV2 - Calf}
775
776 LV2 is an open standard for audio plugins using a simple interface with extensions which add functionality to support audio software. These plugins were written by external developers and provide additional audio effects to \CGG{} audio without having to change \CGG{} every time. Because the LV2 plugins are separate from \CGG{} Infinity, if one fails or does not perform as expected, \CGG{} should stay running and you will have to contact the programmers responsible for that plugin for a fix.
777
778 Typically, a user OS has specialized package groups installed. It is difficult to create one build of \CGG{} to accommodate all potential LV2 plugins. Specifically for the \textit{Calf-Studio LV2 plugins}, you should install the \textit{Calf Plugins} package. The user’s computer must have \textit{gtk-2-runtime} installed, which seems to be automatically done already for most distros. For users doing their own builds, you can build \CGG{} without LV2 support by including \texttt{-{}-without-lv2} in the configure step. The default build is \texttt{-{}-with-lv2=yes} and requires that \textit{GTK-2-devel} must be installed or the build will fail and notify you. In addition for some newer distros, you will need to install
779 \textit{lv2-calf-plugins-gui}; for example Fedora version 32.
780
781 LV2 plugins have their own category in the \textit{Audio Plugins Visibility} as lv2. There is a simple text interface which is available via the usual \textit{Show controls} button when the plugin is attached to the audio track. This window has a Reset button to get back to the default settings. To change a value of one of the parameters, highlight that parameter and type in the new value in the topmost text box and then hit Apply to take effect -- the reason for requiring hitting apply is so that the audio is not moving all over the place while you are still typing a value. More easily, you can just move the \textit{pot dial} or the \textit{slider} bar which take effect automatically.
782
783 \CGG{}’s buffer size setting may cause a delay in activation of the changes you make taking effect, so you can lessen the time by using a small buffer. Notice that $1024$ samples at $48000$ samples per sec is only $\frac{1}{50}^{th}$ a second. This is not a lot of time to shuffle a bunch of stuff. Short buffers produce low latency, but no time for complex programs or lots of stacked effects. Bigger buffers allow for more complex setups.
784
785 To set the buffer size:
786
787 \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ tab Playback A $\rightarrow$ section Audio Out $\rightarrow$ variable Playback buffer samples}
788
789 However, be forewarned that due to variability in the lv2 plugin programming code, some of the plugins only work with the minimum buffer size of $1024$. In these cases, what you will see is the main track canvas cursor just bounces back and forth over a very small area in the timeline. This does not crash \CGG{} but you will have to remove the plugin to continue working.
790 You can specify a certain set of LV2 plugins to use by setting \texttt{LV2\_PATH} \index{LV2 path} as shown below before starting \CGG{} -- include a colon ($:$) separator for multiple paths. The default path for most operating systems is \texttt{/usr/lib64/lv2}. To list the system installed lv2 plugins key in: \texttt{lv2ls}.
791
792 \begin{lstlisting}[numbers=none]
793 export LV2_PATH=/tmp/j/balance.lv2/usr/local/lib/lv2/:/usr/local/lv2
794 \end{lstlisting}
795
796 If there is no default \texttt{LV2\_PATH} set automatically, the value will be \texttt{\$CIN\_DAT/\\lv2}, which is a placeholder only so that no lv2 plugins will be loaded. When there is no system \texttt{LV2\_PATH} set it is important to note, that if you do want lv2 plugins loaded, you must set the correct path in:
797
798 \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Interface tab $\rightarrow$ Default LV2 $\rightarrow$ direc\-tory
799     path name}
800
801 When you change this field, cin will automatically restart and load the newly specified lv2 plugins. If when switching \texttt{LV2\_PATH} or if the lv2 audio plugins are not displayed/usable in the Resources window, you can execute a reload via:
802
803 \texttt{Settings $\rightarrow$  Preferences $\rightarrow$ Interface tab $\rightarrow$ Reload plugin index} \index{plugins!reload index}
804 or else before you bring up \CGG{}, delete \texttt{\$HOME/.bcast5/\CGG{}\_\\plugins} so that the plugins get properly reloaded.
805
806 There are some lv2 plugins that display a \textit{glitzy} UI (User Interface); for example the \textit{Calf plugins}. For these LV2 plugins, if you want that to automatically come up without having to click on the UI button on the simplified UI interface, there is a flag to enable that. It is at:
807
808 \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Operations} tab
809
810 then check the \textit{Auto start lv2 gui} Flag
811
812 Below is a screencast showing the auto start gui flag and the \texttt{LV2\_PATH} default directory path on the bottom line. Note the highlighted \textit{Reload plugin index} which will be executed if OKed (figure~\ref{fig:reload}).
813
814 \begin{figure}[htpb]
815     \centering
816     \includegraphics[width=1.0\linewidth]{reload.png}
817     \caption{Reload plugin index in yellow and Auto start lv2 gui unchecked}
818     \label{fig:reload}
819 \end{figure}
820
821 There is also a blacklist that prevents known problematic-for-\CGG{} lv2 plugins from loading to avoid crashes. If others are found to have problems, once informed about them, they will be added to this blacklist. In order to determine which lv2 plugin causes a SEGV on \CGG{} startup, you can start from a terminal window and you will see each plugin that is being loaded and the last one shown before the crash is a bad plugin. However, many of the plugins causing a crash are due to not having been compiled on your current system with the current compiler so may actually work correctly on other user systems and so will not be added to the \CGG{}-wide blacklist. You can either recompile the problematic plugin, or modify your own blacklist which you will have to maintain and save so as not to be written over when loading a new build.
822
823 Note the UI button in the upper right hand corner above the Reset button (figure~\ref{fig:calf}). If you click this button, a glitzy interface window comes up (if available) for changing variable values. It is possible that a bug in the LV2 plugin causes the glitzy window to appear as blank and then die, but in that case the original simple text window might still work -- in either case, if the timeline movement hangs, just detach the plugin to continue your current session. There is an environment variable that you can set,  \texttt{BC\_TRAP\_LV2\_SEGV}, to get a dump of the failure which may be helpful for debugging.
824
825 \begin{figure}[htpb]
826     \centering
827     \includegraphics[width=1.0\linewidth]{calf.png}
828     \caption{Screencast of simple text interface in the middle of the screen for a Calf LV2 plugin}
829     \label{fig:calf}
830 \end{figure}
831
832 When the glitzy ui is up, the simple text window remains up also since it is the \CGG{} side and keeps track of the value changes so they remain in effect for further usage of the plugin. Changes to one or the other will occur in both with the exception of certain features in the glitzy window which are not communicated correctly back to \CGG{}; for example a reset button -- the simple interface Reset button must be used instead. To change values in the glitzy window you use the mouse and move up or down unlike a knob that turns! (Figure~\ref{fig:calf02})
833
834 \begin{figure}[htpb]
835         \centering
836         \includegraphics[width=0.8\linewidth]{calf02.png}
837         \caption{Screencast with a Calf plugin glitzy window that appears when clicking the simple interface UI button.}
838         \label{fig:calf02}
839 \end{figure}
840
841 In order to test a particular plugin without bringing up \CGG{}, especially for ones that do not operate, it is possible to manually display an lv2ui gui with: \\
842 \texttt{/cin-path/lv2ui <lv2-uri>} \\
843 For example:
844
845 \begin{lstlisting}[style=sh]
846 /tmp/cinelerra-5.1/bin/lv2ui http://calf.sourceforge.net/plugins/Flanger
847 \end{lstlisting}
848
849
850 \section[Video Effects --- Native]{Video Effects -- Native}%
851 \label{sec:video_effects_native}
852 \settocdepth{subsection}
853 \index{video!plugins}
854
855 \subsection{1080 to 480}%
856 \label{sub:1080_to_480}
857 \index{1080 to 480}
858
859 Most TV broadcasts are received with a $1920\times1080$ resolution but originate from a $720\times480$ source at the studio. It is a waste of space to compress the entire $1920\times1080$ if the only resolvable details are $720\times480$. Unfortunately resizing $1920\times1080$ video to $720\times480$ is not as simple as shrinking it.
860
861 At the TV station the original $720\times480$ footage was first converted to fields of $720\times240$. Each field was then scaled up to $1920\times540$. The two $1920\times540$ fields were finally combined with interlacing to form the $1920\times1080$ image. This technique allows a consumer TV to display the re-sampled image without extra circuitry to handle $720\times480$ interlacing in a $1920\times1080$ image.
862
863 If you merely deinterlace the $1920\times1080$ images, you would end up with resolution of $720\times240$. The \textit{1080 to 480} effect properly extracts two $1920\times540$ size fields from the image, resizes them separately, and combines them again to restore a $1920\times480$ interlaced image. The scale effect must then be applied to reduce the horizontal size to $960$ or $720$ depending on the original aspect ratio.
864
865 The tracks to which \textit{1080 to 480} is applied need to be at $1920\times1080$ resolution. The project settings in \texttt{settings $\rightarrow$ format} should be at least $720\times480$ resolution. The effect does not know if the first row in the $1920\times1080$ image belongs to the first row of the $720\times480$ original. You have to specify what the first row is in the effect configuration. The output of this effect is a small image in the middle of the original $1920\times1080$ frame. Use the projector to center the output image in the playback.
866
867 Finally, once you have $720\times480$ interlaced video you can either apply \textit{Frames to Fields} or \textit{Inverse Telecine} to further recover original progressive frames.
868
869 \subsection{1080 to 540}%
870 \label{sub:1080_to_540}
871 \index{1080 to 540}
872
873 Extracts two $1920\times540$ fields from $1920\times1080$ image, resizes them separately, and combines them to $1920\times540$ interlaced image.
874
875 \subsection{Aging TV}%
876 \label{sub:aging_tv}
877 \index{Aging TV}
878
879 This effect is the one to use if you want to achieve an old movie or TV show look. It will put moving lines up and down the movie as well as putting snow on the video. Use it along with \textit{Brightness/Contrast} and \textit{Color Balance} to make your movie look like a really old black and white movie. This came from \url{https://effectv.com}.
880
881 \subsection{Alpha}%
882 \label{sub:alpha}
883 \index{Alpha}
884
885 Allows you to apply an alpha value (transparency) to one or more tracks or one or more edits. Being also keyframable, it allows an excellent variety and possibility of use in the most disparate occasions.
886
887 \subsection{Auto Scale}%
888 \label{sub:auto_scale}
889 \index{auto scale}
890
891 Automatically scale to a specified size.
892
893 \subsection{Blue Banana}%
894 \label{sub:blue_banana}
895 \index{blue banana}
896
897 Blue Banana\protect\footnote{credit to Monty Montgomery programmer} is an \textit{HSL Qualifier} \index{HSL Qualifier} (HSL= hue, saturation, lightness), one of the basic tools of any grading software that are based on circumscribing a zone of the frame by extracting a chromatic key and producing a \textit{matte} in the alpha channel (Secondary Color Correction). Blue Banana differs not by creating a real matte, but by creating a \textit{selection mask} exclusively for use within the plugin. The BlueBanana plugin has a couple of useful purposes. It can be used for color transformation or remapping -- by isolating a specific color and then performing color change/correction on only that color (or color ranges). Another useful purpose is for chroma-key filtering, using multiple BlueBanana plugins on the same track. Also, it can be used in conjunction with the mask operation of the Compositor. Usage of BlueBanana may seem complicated at first, but it is necessarily so in order to get enough control to produce the desired effect simply and quickly. Just changing a single color is actually quite easy. BlueBanana is keyframable (figure~\ref{fig:bluebanana}).
898
899 The basic strategy for BlueBanana is to:
900
901 \begin{itemize}
902     \item Select a specific target color.
903     \item Create a selection region by expanding color ranges around that color.
904     \item Optionally reduce or expand the alpha plane as a regional selection mask.
905     \item Optionally apply a color remapping or transformation to the selection.
906     \item Optionally reset the output alpha to opaque, or pass the alpha to another BlueBanana plugin.
907 \end{itemize}
908
909 \begin{figure}[htpb]
910     \centering
911     \includegraphics[width=1.0\linewidth]{bluebanana.png}
912     \caption{Screencast showing the BlueBanana plugin control}
913     \label{fig:bluebanana}
914 \end{figure}
915
916 \subsubsection*{Just a Warning Note:}
917 \label{ssub:warning_note}
918 BlueBanana may use a lot of CPU and Memory because it is doing a lot of work. If you turn off the plugin on the plugin bar below the video track in the main track canvas it will stop using cpu when not in use. Or once you uncheck \textit{Mark Selected Area}, it will no longer be using the cpu to mark the selected color area in realtime while drawing the diagonal animated pattern in the compositor window.
919
920 \subsubsection{Example Usage\protect\footnote{from original message by Rebecca}}
921 \label{sssec:example_usage}
922
923 If you just want to try this, follow these steps.
924
925 \begin{description}
926     \item[First ---] Choose your color.
927     \begin{enumerate}
928         \item Load your video, add the BlueBanana plugin to the track, bring up its control window, and uncheck any checked boxes (mostly just to avoid unexpected results).
929         \item In the Compositor window, choose the eyedropper color picker tool on the left-hand side and click on the area of the image that shows the color you want to change/correct.
930         \item In the BlueBanana plugin window, to the right of hue, click Pick. And if you want to modify saturation and value, also click on the Pick button for them. To see what it does, Pick them also.
931         \item Next, check the Mark Selected Areas box at the top right of the BlueBanana plugin window to see the selected color-matching areas which will become marked in a diagonally striped pattern.
932         \item You can now manually modify your selection in the Color Selection area in the obvious ways for hue, saturation, value and fill. The arrows to each side of the small circle widen the selected area. Move the dot and you move the range. The slider on top of the horizontal color strip shifts like the amount of the strip is dedicated to that part of the color spectrum. Fill will fill more area or less area in your selected region.
933     \end{enumerate}
934     \item[Second ---] Adjust your color choice.
935     \begin{enumerate}
936         \item There are color strips under color Adjustment which will show color changes as you modify values.
937         \item Uncheck Mark Selected Areas and check the Filter Active box to the right of Color Adjustment.
938         \item As needed, you can individually check and uncheck all the various parameters using the boxes to the left of each line. Again, these are intuitive and broadly similar to the above. The arrows at the bottom widen the range, the circle at the bottom moves the range, and the top slider, which is an arrow this time, affects distribution. It provides a little histogram effect to give you an idea of what you're changing. The fade adjusts the level of color blending. The alpha is basically the opacity of your changes.
939     \end{enumerate}
940 \end{description}
941
942 Definition of Wording/Checkboxes/Buttons/Operators are being described next. Some of the commentary was adopted from information provided by \textit{Monty Montgomery} and from questions and answers from email by \textit{Igor Ubuntu}, who did extensive testing.
943
944 \subsubsection*{Operational characteristics for the \textbf{color-related adjusters}:}
945 \label{ssub:operational_characteristic_color}
946
947 \begin{description}
948         \item[left arrow slider] operates the range minimum; the numerical value shows in the left-most textbox.
949         \item[right arrow slider] operates the range maximum; resulting numerical value is in the middle textbox.
950         \item[middle circle slider below] can move the current range up or down and the numerical results will show in the left and middle textbox. Move the dot and you move the range.
951         \item[top pad slider] operates the edge slopes (selection attack/decay) and the value will be displayed in the
952         rightmost textbox. Sharp edges are represented by 0; 100 represents smooth edges.
953         \item[top arrow] affects the distribution skew.
954 \end{description}
955
956 \subsubsection*{Operational characteristics for \textbf{Fill}:}
957 \label{ssub:operational_characteristic_fill}
958
959 \begin{description}
960         \item[left arrow slider] operates mask erosion filling. First textbox value.
961         \item[center up arrow slider] operates the fill skew midpoint. Second textbox value.
962         \item[right arrow slider] operates mask expansion filling. Third textbox value.
963         \item[top pad slider] operates the edge slopes. Right textbox value.
964 \end{description}
965
966 The textboxes are available so that you can directly type in numbers from the \textit{color wheel}. This could be helpful if duplicating previous work as it would be an instantaneous exact numerical match without having to continuously fine-tune the movement of a slider.
967
968 There are two panes separated by long horizontal lines (through the middle of the screen) in the control window of the BlueBanana plugin, clearly visible in the previous screencast. The top pane is first used to create/modify a selection, and the bottom pane is used to operate a change.
969
970 \subsubsection*{Pane 1}
971 \label{ssub:pane1}
972
973 This section is used to select the target color domain. First, a short explanation about alpha. The alpha channel used in BlueBanana is not transparency (\textit{matte}); it is used as the \textit{Selection mask}. Alpha plane is the alpha channel of the current image. So that:
974
975 RGBA = red/green/blue color planes, alpha data plane.
976 YUVA = luma/Cb/Cr color values, alpha data plane.
977
978 The alpha data normally is input to the blending operations in the patchbay overlay mode. The alpha data usually creates the appearance of stacking order, and determines which color planes are visible in the rendered result. When BlueBanana is used, the meaning of the alpha data is changed to the selection. It is useful to think of the alpha data as more solid when it is transparency in blending, and more selected when it is used in BlueBanana. In both cases, the greater the alpha value, the more the effect is expressed.
979
980 Usually, alpha is normalized to a range from $0$ to $1$, zero = no effect, $1$ = total effect, $0.5$ = partial effect. In both cases, alpha is what math people call an auxiliary variable. It is needed, but is not part of the answer. In this case, the answer is the visible rendered result. Alpha is like meta-data.
981
982 Let us now examine the instruments in \textbf{pane 1}:
983
984 \begin{description}
985     \item[Combine Selection] The selection is the intersection or union of two pixel masks. Mathematically, $A$ and $B$ are normalized, (scaled to between $0$ and $1$) and used as selection mask weights.
986
987     $Intersection (\cap) = A\times B$
988
989     $Union (\cup)= A+B-A\times B$
990
991     where $A$ is the input alpha plane as a mask, $1$=selected, $0.4$=partially selected, and $0$=not selected; $B$ is the color selection of trims and feathers made by varying the sliders.
992
993     The result is a new alpha plane, which will be output (if \textit{End Mask} is not set). The $0\dots1$ selection values are used to weight the color transformation filters if/when they are active and operate a change. The color adjustment filters available in Pane \#$2$ can change red, green, blue, and remap hue, saturation, value in the pane. There is also \textit{fade} which applies to the color channels and \textit{alpha} which applies to the resulting alpha plane.
994
995     The basic plan is to either:
996
997     - reduce a selection area by intersection (Combine selection off) $A \times B$
998
999     - increase a selection area by union (Combine selection on) $A+B-A\times B$
1000     \item[Mask Selection] applies the current mask to the selection, such that the mask clips/expands the selection. When mask selection is enabled, the result of the and/or will be stored to the alpha result, but when mask selection is unchecked the mask is ignored and the selection is not modified. The selection is used to weight the effect of the filtering, or to control the output alpha.
1001     \item[End mask] only visible when \textit{Mask Selection} is checked. End Mask causes the entire alpha plane to
1002     be set to $1$. The image becomes opaque. This is usually only set in the last plugin of a stack (the stack may be just one plugin doing only color modification). In the event that a color selection mask is used with multiple, layered BlueBanana filters on the same track, the grouped BlueBanana filters may share a single mask by all enabling Mask Selection, but with only the last BlueBanana enabling End Mask. This usage pattern gives the End Mask control its name.
1003     \begin{description}
1004         \item[End Mask as used in Color Transformation/Remapping:] In many use cases \\
1005         where you are just remapping color, you are still interested in seeing all of the picture. If this is the case, then checking End Mask on the last BlueBanana plugin will show you the entire picture. The alpha plane may be in use as a selection mask, but it may not be wanted as part of the result.
1006         \item[End Mask as used in Chroma-key Filtering:] In cases where the selection is for a chroma-key, you are interested in the alpha channel for blending, like \textit{Normal} or \textit{SrcOver}. So for this usage of the BlueBanana, don't check the End Mask.
1007     \end{description}
1008     \item[Invert Selection] reverse target color domain, which is 1 minus selection.
1009     \item[Mark Selected Areas] when this box is checked, the chosen colors are presented in an animated
1010     diagonally striped pattern.
1011     \item[Hue] select a hue domain; click on the Pick button to select or check the box to the left of hue or uncheck to ignore.
1012     \item[Saturation] select a saturation domain; click on the Pick button to select or check the box to the left.
1013     \item[Value] select a value domain; click on the Pick button to select or check the box to the left.
1014     \item[Fill] will fill more area or less area of your selected region. This describes how it works. Fill control is an automated way of doing grow and shrink on the selected area, to fill in small holes, or get rid of scattered speckles. If none of the Hue, Saturation, or Value sliders are active -- meaning that the whole frame is selected -- the Fill slider will have no effect even when enabled. The word fill will appear ghosted to indicate this.
1015
1016     The three lower handles in the fill slider correspond to \textit{Shrink} (the left hand slider), \textit{Final} (the middle slider), and \textit{Grow} (the right hand slider). These are used in combination to alter the selection by first growing it by the amount specified by the right hand Grow slider, shrinking it to the amount specified by the left hand Shrink slider, and then growing it again to the final size specified by the middle Final slider. The top slider then feathers the resulting selection.
1017     Growing the selection and then shrinking it has the effect of filling small holes in the selected area. Similarly, shrinking and then growing tends to remove small flecks of unwanted selection. The Final slider specifies the overall desired shrinkage or growth of the selection when finished. To specify a pure Grow or Shrink operation, set the Final slider and the Grow/Shrink slider to the same value and leave the other slider at zero.
1018     \item[Pre-erode] this control reverses the order of operation to Shrink, then Grow, then Final. The change is subtle on most images, but overall removes more small features because it first removes flecks before filling in holes.
1019 \end{description}
1020
1021 \subsubsection*{Pane 2}
1022 \label{ssub:pane2}
1023
1024 This section is used to modify the color of your selection. Descriptive commentary for this pane.
1025
1026 \begin{description}
1027     \item[Filter Active] checkbox to indicate that the modifications will be shown.
1028     \item[Color Adjustment ] For Color Adjustment, RGB can be used as color weights while the HSV can transform color.
1029     For the following items there are three sections on the slider. The \textit{center} section represents the nominal $0\%-100\%$ range; the \textit{left} section represents negative values, and the \textit{right} section represents values greater than $100\%$. Values can be out-of-range within BlueBanana without clipping, but they will clip once they leave the plugin.
1030     \item[RGB] affect the color channels individually.
1031     \begin{description}
1032         \item[Red] modification color; click the Reset button to revert to default. Values are reflected in numerical textboxes on the right-hand side.
1033         \item[Green] modification color; click the Reset button to revert to default. Values are reflected in numerical textboxes on the right-hand side.
1034         \item[Blue] modification color; click the Reset button to revert to default. Values are reflected in numerical textboxes on the right-hand side.
1035     \end{description}
1036     \item[HSV] reorient the color spectrum, and affect all of the color channels simultaneously.
1037     \begin{description}
1038         \item[Hue] a single numerical value will appear in the right-side box. Click the Reset button for default.
1039         \item[Saturation] for modifying the saturation; click the Reset button to revert to default. Values are reflected in numerical textboxes on the right-hand side.
1040         \item[Value] for modifying the value; click the Reset button to revert to default. Result is reflected in the numerical textboxes on the right-hand side.
1041     \end{description}
1042     \item[Fade] controls the entire color re-mapping, and does nothing if no color adjustment is active.
1043     \item[Alpha] controls the output alpha (this is not available when End Mask is set); click the Reset button to revert to default. Result is reflected in the numerical textboxes on the right-hand side.
1044 \end{description}
1045
1046 Let's see two examples of HowTo:
1047
1048
1049 \subsubsection*{BlueBanana Use Case \#1: (Color Transform/Remapping)}
1050 \label{ssub:bb_use_case_1}
1051
1052 \begin{itemize}
1053         \item Load a video track, and add the BlueBanana plugin to your video. The alpha channel is usually all opaque. This serves as an initial full screen selection mask.
1054         \item Open the controls, and start with all boxes unchecked. Now reduce the selection using the top pane in intersection mode (that is \textit{Combine Selection} is unchecked) to begin the effect.
1055         \item Use the \textit{eyedropper} on the compositor window to choose a particular color.
1056         \item Click on the 3 plugin Pick boxes on the right side of each line of HSV to get the color selection.
1057         \item Check \textit{Mark Selected Area}. The affected zones will be identified on the composer.
1058         \item Adjust the selection using the HSV and Fill sliders of the top pane. The selection mark will be updated as you operate the controls. The composer mask striping will be strongest as the mask is nearer full selection.
1059         \item Now uncheck \textit{Mask selected area} \& check \textit{Filter Active} to begin Color Adjustment.
1060         \item Enable any needed colorspace modifiers, RGB / HSV sliders, and setup the color changes by moving the sliders. The current output may be the desired output.
1061         \item Enable \textit{Mask Selection} and the alpha output will pass the selection mask to the image alpha channel. This can be used as a very flexible chroma-key filter. It also allows more plugins to be stacked and more selection information to be added, either by intersections or unions with other selections.
1062         \item \textit{End Mask} simply sets the output image alpha to opaque. This is normally used to end a stack of BlueBanana plugins, and render the entire image with a complex selection.
1063 \end{itemize}
1064
1065 \subsubsection*{BlueBanana Use Case \#2:}
1066 \label{ssub:bb_use_case_2}
1067
1068 This case uses stacked BlueBanana plugins working like \textit{chroma-key} filters. It assumes you have already learned how to operate the plugin.
1069
1070 \begin{itemize}
1071         \item Bring up 2 tracks of video media -- one for foreground and one for background.
1072         \item Add 2 BlueBanana plugins on the first track. Turn off all checkboxes in both plugins.
1073         \item On the top plugin, use the top pane to create a selection mask, using \textit{Mark Selected Areas}.
1074         \item Turn off top plugin \textit{Mark Selected Areas}, and disable the top plugin via the plugin title bar on/off.
1075         \item Create another selection using the second plugin's mask, using \textit{Mark Selec\-ted Areas}.
1076         \item Turn on the top plugin. Make sure both plugins \textit{Mark Selected Areas} is off.
1077         \item Check \textit{Mask Selection} and \textit{Filter Active} in both.
1078         \item Check \textit{Combine Selection} on second BlueBanana to see the final results.
1079 \end{itemize}
1080
1081 You will see that there is intersection of the full plane with the first chosen regions, so the $alpha = 0$ everywhere but the area you picked and you see through. And $alpha = 1$, where the intersection selection was 1. The Normal blend shows you the track on top in these regions (the foreground track where $alpha = 1$).
1082
1083 If you are building an alpha selection mask by first intersection and then union, the top BlueBanana should not change the colors or the bottom plugin will need to target the remapped colors since that is the input to the lower BlueBanana.
1084
1085 \subsection{Blur}%
1086 \label{sub:blur}
1087 \index{blur}
1088
1089 This is a Gaussian type blur. Other blur plugins -- \textit{Linear}, \textit{Motion}, \textit{Radial}, and \textit{Zoom} --are described later. This plugin is keyframable. Blur is used to blur a video track via the following parameters:
1090 \begin{description}
1091     \item[Horizontal and vertical] values are used to tell which one of the fields blurring affects; can be both.
1092     \item[Radius] use this dial to define the amount of blur to apply.
1093     \item[Alpha determines radius] use alpha to define the amount of blur to apply. (radius=gray value of alpha)
1094     \item[Blur alpha, red, green, blue] specifies which color channels is to be blurred.
1095 \end{description}
1096
1097 \subsection{BoxBlur}%
1098 \label{sub:boxblur}
1099 \index{boxblur}
1100
1101 Based on ffmpeg’s boxblur, this is a very fast algorithm which can be used to blur horizontal,
1102 vertical, and at a power level.  Simplest usage is to just blur the entire image but with
1103 the following parameters, you can create a specific rectangular section to blur instead.  
1104
1105 \begin{description}
1106     \item[X/Y:] point coordinates of a rectangular box to be blurred. X and Y of 0 are in the
1107 upper left hand corner.  Default to be blurred is the entire image.
1108     \item[Drag:] is used when you want to create just a rectangular area to be blurred rather
1109 than the enire image. If you used keyframes to cover a moving area and had left the Drag box
1110 enabled, you can remove the drag box with \textit{Allow keyframe spanning} whose use is
1111 described in \nameref{sec:allow_keyframes_spanning}.
1112     \item[W/H] the values in these 2 boxes specify the width and height of the drag area box
1113 measured in pixels as shown in the compositor window. You can set these manually and if you
1114 can not see the location of your box, set them to zero because $0$ sets it to the same as the
1115 width/height of the project.
1116     \item[Horiz:] slider goes from $0\, to\, 100$. Increasing this \textit{horizontal} number,
1117 increases the blurriness in the horizontal direction. The default value is 2. You can also use
1118 the mouse wheel to scroll the slider.  There is a clear button on the right to set the value to 0.
1119     \item[Vert:] slider goes from $0\, to\, 100$. Increasing this \textit{vertical} number,
1120 increases the blurriness in the vertical direction.  The default value is 2. You can also use
1121 the mouse wheel to scroll the slider. There is a clear button on the right to set the value to 0.
1122     \item[Power:] the way \textit{Power} works is like stacking up the blur multiple times.
1123 For example, a power of 3 would be like blurring once, then blurring that again, and finally
1124 blurring that a third time. The slider varies from 1 to 10 with 2 being the default value. There
1125 is a clear button on the right to set the value to 1.
1126     \item[Reset:] button to revert to the default values and turn off Drag if it is on.
1127 \end{description}
1128
1129 \subsection{Brightness/Contrast}%
1130 \label{sub:brightness_contrast}
1131 \index{brightness contrast}
1132
1133 \begin{figure}[htpb]
1134         \centering
1135         \includegraphics[width=0.6\linewidth]{brightness.png}
1136         \caption{How it works Brightness and Contrast}
1137         \label{fig:brightness}
1138 \end{figure}
1139
1140 To brighten a dark shot, or add light, use this plugin. Do not overuse the effect or you risk degrading your video quality.
1141 The \textit{Brightness} slider moves up or down the values of the entire channel and corresponds to the \textit{Master Offset} of the various grading programs.
1142 The \textit{Contrast} slider expands or narrows the brightness values of the entire channel; corresponds to the use of the \textit{cursors} (small triangles) in the \textit{Histogram} plugin. Clear icons are present to reset its slider to default without affecting others.
1143 Use the effect along with keyframing to brighten a long shot that is dark at the beginning but bright at the end. Generally you will want to change the brightness and contrast about the same amount (for example -- brightness $28$, contrast $26$) so that your original colors are kept intact. This effect is also keyframable (figure~\ref{fig:brightness}).
1144
1145 \subsection{BurningTV}%
1146 \label{sub:burningtv}
1147 \index{burning TV}
1148
1149 Makes your video burn where there are small light colored patches of video. This came from \url{https://effectv.com}.
1150
1151 \subsection[C41]{C41\protect\footnote{credit Florent Delannoy, original program code author, and Edouard Chalaron}}%
1152 \label{sub:c41}
1153 \index{C41}
1154
1155 The C41 plugin takes a $16\,bit C41$ digital intermediate negative film as input and outputs a positive image. It became necessary because $C-41$ negatives can fade or color-shift over time which was a problem early on. It is still important today because there is a large amount of documentaries, video clips, and other media out there that was shot on super $16$ film. This works for RGB-float, RGB, and also YUV variations.
1156
1157 There are two sets of data -- the scanned input values and your corrected values. Simple functionality of the plugin is to compute the data, transform to get corrected values, then apply that.
1158
1159 Basic usage strategy:
1160 \begin{enumerate}
1161     \item first time the controls come up, nothing is checked and everything is set to $0$
1162     \item check the box \textit{Compute negfix values} to see the current media input values
1163     \item check \textit{Activate processing} and you see a $1-colored$ screen in the Compositor due to zero values
1164     \item check the \textit{Apply values box} to see the input values on the left side propagate to the right side
1165     \item check \textit{Apply default box} if you want to make sure that the borders of the image are not used
1166     \item correct the output values as desired on the applied right side
1167 \end{enumerate}
1168
1169 It is important to note as you play or change the frame, the plugin re-computes the data as you move along, but it is not propagated to the applied side.
1170
1171
1172 \paragraph{Checkboxes:}
1173     \begin{description}
1174         \item[Activate processing] when checked, the c41 operation is used to render the image.
1175         \item[Compute negfix values] computes the current negative values of the image (inside the box).
1176         \item[Show active area] draws horizontal and vertical grid lines displaying the boxed area.
1177         \item[Postprocess] when checked, applies contrast/brightness values as defined in $coef\frac{1}{2}$.
1178     \end{description}
1179 \paragraph{Values:}
1180     \begin{description}
1181         \item[Compute negfix values] (left side) and
1182         \item[negfix values to apply] (right side):
1183         \item[Min/Max R/G/B] minimum and maximum values for Red, Green, and Blue.
1184         \item[Light] value of light; a smaller number is lighter.
1185         \item[Gamma G/B] values for gamma Green and Blue.
1186         \item[Contrast] simple color contrast.
1187         \item[Brightness] white brightness.
1188     \end{description}
1189 \paragraph{Buttons:}
1190     \begin{description}
1191         \item[Apply values] copies computed RGB/Light/Gamma/Contrast/Bright from negfix to applied values.
1192         \item[Apply default box] copies default computed Box column/row from negfix to applied values.
1193     \end{description}
1194 \paragraph{Shading box:} The boxing option allows for calculating the inversion of the digital negatives in a given area of the frame as opposed to the entire frame. The program will automatically calculate the columns and rows to shave from the frame when compute negfix values is checked. A default box area is initially calculated, called the shaving box, based on where the min/max difference in a row/column is less than the program defined tolerance. This row/column minimum and maximum difference must be greater than 0.05. The effect is to cut away the border areas with constant color. If you check the Show active area, you can see the box in the compositor window. The boundary search is constrained to a range of 0.1 to 0.9 times the frame dimensions, to create a 10 percent shaved margin to avoid over-scan and negative edge bleeding. Manual adjustment of the shaving box is controlled via the four sliders on the bottom right which move each of the left, right, top and bottom shaving margins. The slider bar new values automatically take effect as you move the box and you will see the right-hand side applied values change. When you have either the rows or the columns where the minimum slider is greater than or equal to the maximum slider, the default box will be in effect instead.
1195
1196 \paragraph{Optional postprocessing:} In order to have the values of Contrast and Brightness take effect, you must check the Postprocess checkbox.
1197 \begin{description}
1198     \item[Contrast] is the difference in brightness between objects or regions.
1199     \item[Brightness] refers to the overall lightness or darkness of the image.
1200 \end{description}
1201
1202 Figure~\ref{fig:c41} shows the C41 controls on the left and part of the Compositor window with grid lines showing the default shading box since the Show active area box is checked. Changes have been made to the left-hand side original computed values as seen in the right-hand side such as Gamma G which contains the hairline cursor and has a partial red outline value box.
1203
1204 \begin{figure}[htpb]
1205     \centering
1206     \includegraphics[width=0.9\linewidth]{c41.png}
1207     \caption{C41 - Control window and compositor window in action}
1208     \label{fig:c41}
1209 \end{figure}
1210
1211 \subsection{Chroma Key}%
1212 \label{sub:chroma_key}
1213 \index{chroma key}
1214
1215 This effect erases pixels which match the selected color. They are replaced with black if there is no alpha channel and transparency if there is an alpha channel. In this case, you create a matte in the alpha channel, which is not visible to us. The selection of color model is important to determine the behavior (figure~\ref{fig:chroma-key}).
1216
1217 \begin{figure}[htpb]
1218     \centering
1219     \includegraphics[width=0.5\linewidth]{chroma-key.png}
1220     \caption{Chroma Key control window}
1221     \label{fig:chroma-key}
1222 \end{figure}
1223
1224 Chroma key uses either the \textit{lightness} or the \textit{hue} to determine what is erased. Use value singles out only the lightness to determine transparency.
1225 Select a center color to erase using the \textit{Color} button. Alternatively a color can be picked directly from the output frame by first using the \textit{color picker} in the compositor window and then selecting the \textit{Use color picker} button. This sets the chroma key color to the current color picker color.
1226
1227 Be aware that the output of the chroma key is fed back to the compositor, so selecting a color again from the compositor will use the output of the chroma key effect. The chroma key should be disabled when selecting colors with the color picker.
1228
1229 If the lightness or hue is within a certain \textit{threshold} it is erased. Increasing the threshold determines the range of colors to be erased. It is not a simple on/off switch. As the color approaches the edge of the threshold, it gradually gets erased if the \textit{slope} is high or is rapidly erased if the slope is low. The slope as defined here is the number of extra values flanking the threshold required to go from opaque to transparent.
1230
1231 Normally threshold is very low when using a high slope. The two parameters tend to be exclusive because slope fills in extra threshold. The slope tries to soften the edges of the chroma key but it does not work well for compressed sources. A popular softening technique is to use a maximum slope and chain a blur effect below the chroma key effect to blur just the alpha.
1232
1233 \subsection[Chroma Key (HSV)]{Chroma Key (HSV)\protect\footnote{Credit for Plugin by Jerome Cornet \url{http://jcornet.free.fr/linux/chromakey.html}}}%
1234 \label{sub:chroma_key_hsv}
1235 \index{chroma key HSV}
1236
1237 Chroma Key (HSV) (figure~\ref{fig:chroma-key-hsv}) replaces a color with another color or transparency using HSV variables; it is frequently used to remove a color from a video to composite with another image. This process is generally referred to as green screen or blue screen process (because of the color that is keyed out). More information: {\small \url{http://en.wikipedia.org/wiki/Chromakey}}
1238
1239 \begin{figure}[htpb]
1240     \centering
1241     \includegraphics[width=0.55\linewidth]{chroma-key-hsv.png}
1242     \caption{Keying a green screen with Chroma Key (HSV)}
1243     \label{fig:chroma-key-hsv}
1244 \end{figure}
1245
1246 \subsubsection*{Requirements}
1247 \label{ssub:requirements}
1248
1249 The subject in the movie should have a good background. The lighting is crucial and good lighting during production will save you time with much less effort than in post-production.
1250 Here we assume that we have a good video, filmed on green (or blue) screen that we want to use. Important: Make sure you are using a color model that has an alpha channel, such as \textit{RGBA8}, \textit{RGBAFloat}, \textit{YUVA8}. To change color model, go to \texttt{Settings $\rightarrow$ Format $\rightarrow$ Color Model}.
1251
1252 \subsubsection*{Usage}
1253 \label{ssub:usage}
1254
1255 As in any other effect, add it to the timeline in the main window. You can tweak each parameter in order to improve the keying.
1256
1257 Start with \textit{Hue Tolerance} at $10\%$, \textit{Min Bright\-ness} at $0$, \textit{Max bright\-ness} at $100\%$, \textit{Saturation offset} at $0$, \textit{Min Saturation} at $0$, \textit{In Slope} at $0$, \textit{Out Slope} at $0$, \textit{Alpha Offset} at $0$ (that’s mid-way through), \textit{Spill Threshold} at $0$, \textit{Spill Compensation} at $100\%$. At any time, you can check what the Mask looks like by clicking on \textit{Show Mask}. This will output a black and white image of the mask (\textit{matte}).
1258
1259 \begin{description}
1260     \item[Key color:] Select the key color (green, blue, etc) using the color wheel or the color picker. Remember, only the Hue matters, not Saturation or Value. To use the color picker, click on the \textit{color picker} icon in the Compositor window, then click on the color you want in the Compositor window. Finally  in the Chromakey (HSV) parameters window, click on \textit{Use Color Picker}.
1261     \item[Hue Tolerance:] Because there are slight variations in lighting, the background will not be in a uniform key color hue. Increase or decrease the Hue tolerance to mask out the background. If there are dark spots that are keyed out that shouldn’t be, it can be corrected later.
1262     \item[Brightness:] ncrease \textit{Min Brightness} so that only the background is masked out, and not parts of the foreground. You can also reduce \textit{Max Brightness} if some clear areas are keyed out (useful for very dark backgrounds).
1263     \item[Saturation:] Increase \textit{Min Saturation} so that only the background is masked out, and not parts of the foreground. \textit{Saturation Offset} can be used to change this, but for now leave it set to $0$.
1264 \end{description}
1265
1266 Check what it looks like at this stage, your mask should be pretty
1267 clean. Toggle \textit{Show Mask} to check what it looks like, it
1268 should be OK\@. If not, repeat steps $1 to 4$ to get a better
1269 key. The rest of the controls are useful to smear the mask to help
1270 compositing later on. They will help you to make your key look much
1271 cleaner.
1272
1273 \begin{description}
1274     \item[Slope:] For now, the mask is a full on/ full off mask that can be really harsh and not necessarily what you are looking for. \textit{In Slope} and \textit{Out Slope} will help you to smooth that key. In Slope leaves more colors in the mask, Out Slope takes more colors out of the mask. The colors that are borderline in the mask will see their alpha channel reduced by half instead of being completely on or off.
1275     \item[Alpha Offset] This control offsets the whole alpha channel by some amount. Be sure to know what you are doing if you change it from the default value of $0$.
1276     \item[spill light control:] This step helps you remove the green or blue halo around the edges of the mask. It does so by removing the saturation of pixels that have a similar hue to the key color (turning them into grey instead of green or blue). \textit{Spill Compensation} controls the amount of de-saturation. If you start with Spill Compensation at $100\%$, slowly increase the \textit{Spill Threshold} until the remaining green or blue areas turn grey. Then reduce Spill Compensation until the image looks good.
1277 \end{description}
1278
1279 Now the mask is probably still very harsh, so just below the Chromakey (HSV) plugin, add a \textit{Blur} effect, and select only the \textit{Alpha channel}, with a radius of $2$ or $3$ (more if you really want to soften the edges). This will significantly help the keying.
1280
1281 \subsection{Color 3 Way}%
1282 \label{sub:color_3_way}
1283 \index{color 3 way}
1284
1285 Together with \textit{Histogram Bezier / Curves} Color 3 Way is the main tool of Color Grading because you can modify the colors of \textit{Shadows}, \textit{Midtones}, and \textit{Highlights} as desired. Color 3 Way is keyframable (figure~\ref{fig:color3way}).
1286
1287 \begin{figure}[htpb]
1288     \centering
1289     \includegraphics[width=1.0\linewidth]{color3way.png}
1290     \caption{Color 3 Way control window}
1291     \label{fig:color3way}
1292 \end{figure}
1293
1294 \begin{itemize}
1295     \item It allows you to vary the \textit{contrast} of the image using the slider Value, always acting separately on shadows, midtones, and highlights and thus resulting in very precise application.
1296     \item Allows you to automate the \textit{white balance} by simply choosing a neutral color in the output of the Compositing window using the Color Picker and pressing the corresponding button in the plugin.
1297     \item Allows you to vary the \textit{Saturation} with sliders in the same manner as contrast was varied by the Value slider. For istance, to decrease the incidence of color dominants present in the shadows or in the highlights, vary the Saturation.
1298     \item With the \textit{color wheels} you can make very sophisticated adjustments to the shades of the images, in each of the three main areas of shadows, midtones and highlights.
1299     \item Allows you to copy exactly the setting of one zone to the other two zones using \textit{Copy to all} button.
1300     \item In addition to the three reset buttons, each slider and each wheel has its own Clear button, to return it to the default value without affecting the others.
1301 \end{itemize}
1302
1303 This plugin allows maximum control over the result and maximum precision of adjustments when used simultaneously with the control monitors, i.e.\ \textit{Waveform}, \textit{RGB Parade} and \textit{Vectorscope}. It is important to keep in mind that the three zones are not clearly separated, but slightly overlapping. This results in less precision but looks better for more smooth shades. By varying the values on the color wheels all RGB channels are affected simultaneously, which can result in unwanted color dominance. Saturation is also affected and must therefore be monitored.
1304 To use more precisely, drag the \textit{crosshair} with the mouse in the desired area and then adjust in steps of $0.001$ using the up/down and right/left arrows on the keyboard.
1305 The most common use cases (but can be adapted to virtually any situation) of the plugin are:
1306
1307 \begin{itemize}
1308     \item White balancing.
1309     \item Expand/compress contrast.
1310     \item Mitigate under and over exposure.
1311     \item Balance colors, i.e.\ eliminate color dominance.
1312     \item Color matching Shot to Shot.
1313     \item Create a Stylized look.
1314 \end{itemize}
1315
1316 \subsection{Color Balance}%
1317 \label{sub:color_balance}
1318 \index{color balance}
1319
1320 Video Color Balance is a great effect to use along with Brightness/Contrast and Hue/saturation to try to compensate for possible errors in filming (low lighting, for example). It can do so much without greatly lowering the quality of the video. With it you can change the colors being sent to output \textit{CMY} (Cyan, Magenta, Yellow) or \textit{RGB} (Red, Green, Blue). Color Balance is also keyframable.
1321
1322 Since \textit{complementary colors} are neutralized, to eliminate a \textit{color cast}, the pertinent slider is moved in the direction of the complementary color. Clear buttons are present to reset its slider to default without affecting others. If you \textit{Lock parameters} you get the same \textit{Color Offset}, that is the fourth color wheel in the grading programs. The parameters of the plugin are:
1323
1324 \begin{description}
1325     \item[CMY/RGB sliders:] allows you to adjust the colors.
1326     \item[Preserve Luminosity:] Adjusts colors while keeping the overall brightness constant.
1327     \item[Lock Parameters:] works as a Color Offset.
1328     \item[White Balance] used in conjunction with the \textit{color picker} on a neutral color of the output, it will automatically balance the white.
1329 \end{description}
1330
1331 \subsection{ColorSpace}%
1332 \label{sub:color_space}
1333 \index{color space}
1334
1335 This plugin is a tool that can be used to convert your input media, such as a recording from your camera,
1336 from one color space/range to another.  It works for both RGB and YUV as set by your project format.
1337 Options are BT601, BT709, or BT2020 for Color Space input and output and JPEG or MPEG for Color Range
1338 input and output.  The Inverse option checkbox is available in case your media was rendered in the wrong
1339 color space  or range so that you can fix it.
1340
1341 \textbf{Algorithm for conversion} -- where equations is a $3\times3$ matrix multiply
1342
1343 \qquad $output = (input - input\_zero) \times equations + output\_zero$
1344
1345 \textbf{Algorithm for inverse}  -- where equations is a $3\times3$ matrix multiply
1346
1347 \textit{Description}:    invert(equations); swap(input,output); swap(input\_zero,output\_zero)
1348
1349 \qquad $input = (output - output\_zero) \times inverse\_equations + input\_zero$
1350
1351 \begin{figure}[hbtp]
1352     \centering
1353     \includegraphics[width=0.6\linewidth]{colorspace.png}
1354     \caption{ColorSpace control window}
1355     \label{fig:colorspace}
1356 \end{figure}
1357
1358
1359 \subsection{CriKey}%
1360 \label{sub:crikey}
1361 \index{CriKey}
1362
1363 The Chroma Interpolation Key plugin, CriKey, is a regionally based chroma key with interpolation (figure~\ref{fig:crikey}). This is useful when you only want 1 or some specific zones to be defined by the chroma key as opposed to the entire image. Its most significant feature is that you can select several regions of interests and of different colors as opposed to only $1$.
1364
1365 \begin{figure}[htpb]
1366     \centering
1367     \includegraphics[width=0.5\linewidth]{crikey.png}
1368     \caption{three active point created in CriKey}
1369     \label{fig:crikey}
1370 \end{figure}
1371
1372 To start, if not already checked, turn on drag. In the composer window select an area of a certain color by clicking on that point with the \textit{right mouse button} and check to see that it is enabled with an $*$ in the "E" field. The color of the area is used to define the region of interest and then you can use the \textit{threshold} slider to designate the tolerance variation. This creates a region that is the chroma key selection and a fill will be performed in that area, but only within that region. So, say for example, a red colored area was chosen, only the red color inside the region is selected -- not that color red in the entire image. The drag capability makes it easy to check a point before right clicking it to see the effect. You will want to turn off drag when you are finished with CriKey so that it does not interfere with other compositor functions.
1373
1374 \begin{description}
1375     \item[Draw mode:] options let you use \textit{Alpha} for see-thru, \textit{Edge} to just outline the edges of the region, or \textit{Mask} to block. The pixels which match the selected color are replaced by black if Mask is chosen or see-thru/transparent if Alpha.
1376     \item[X, Y:] points coordinate.
1377     \item[Buttons:] \textit{New} to create a new point, \textit{Up/Dn} to move highlighted point up or down \textit{Del} to delete the highlighted point.
1378     \item[Threshold:] slider goes from $0\, to\, 1$. Increasing the threshold, increases the area to be filled or masked. You can also use the mouse wheel to scroll the slider.
1379     \item[Drag:] for ease of use. If you need to clear the Drag enabled, you can easily do this with \textit{Allow keyframe spanning} whose use is described in \nameref{sec:allow_keyframes_spanning}.
1380     \item[Reset:] button to revert to only the default middle point with all others being deleted.
1381     \item[ListBox:] "E" for Enabled with $*$ marking that; "X" is the point’s $x$ coordinate; "Y" is the point’s $y$ coordinate; "T" is the threshold value of $X,Y$ point; \textit{Tag} represents the \# of the selected
1382     point.
1383     \item[Hints:] for usage shortcuts.
1384 \end{description}
1385
1386 \subsubsection*{Some notable caveats}
1387 \label{ssub:some_notable_caveats}
1388
1389 \begin{enumerate}
1390     \item When choosing an area that has variations of the same color within a region, for less work and for the best results, choose an average color in that region instead of an extreme end of that color.
1391     \item If the threshold is set appropriately you can see the edges which is helpful.
1392     \item The mask is computed and shows the fill region.
1393     \item Use the Gradient plugin to substitute a different color for the selected area.
1394 \end{enumerate}
1395
1396 Figure~\ref{fig:crikey01} and figure~\ref{fig:crikey02} shows how moving the Threshold slider with the Point selected blacks out the single region which has the darker brown hills in it. Because the edge was located, any of the same color in the rest of the video would not be blacked out.
1397
1398 \begin{figure}[htpb]
1399     \centering
1400     \includegraphics[width=0.7\linewidth]{crikey01.png}
1401     \caption{The screenshot shows the compositor with some default settings in the controls window.}
1402     \label{fig:crikey01}
1403 \end{figure}
1404
1405 \begin{figure}[htpb]
1406     \centering
1407     \includegraphics[width=0.7\linewidth]{crikey02.png}
1408     \caption{same screenshot with moving Threshold}
1409     \label{fig:crikey02}
1410 \end{figure}
1411
1412 \subsubsection*{Usage steps}
1413 \label{ssub:usage_steps}
1414
1415 \begin{enumerate}
1416     \item Click \textit{Reset} (there will be a single $X,Y$ coordinate point that is in the middle and not enabled)
1417     \item Check to make sure \textit{Drag} is on.
1418     \item In the Compositor, right click on area of interest and an $X,Y$ coordinate will appear in the listbox.
1419     \item Click on the \textit{E} Enabled field next to this latest point and an $*$ asterisk will show.
1420     \item Now you will see an area turn black so use the \textit{Threshold} slider to only black out the area of interest.
1421     \item Repeat steps $3-5$ until you have selected all of the desired areas.
1422     \item Finally, turn off \textit{drag} so as not to interfere with other compositor functions
1423 \end{enumerate}
1424
1425 \subsection{Crop \& Position}%
1426 \label{sub:crop_position}
1427 \index{crop \& position}
1428
1429 It allows you to obtain a rectangle from the frame, whose dimensions are fully adjustable by four sliders for the four sides of the frame. You can also place this rectangle in the canvas using two other sliders for right/left and up/down scrolling. With the Clear buttons we can bring the slider to default values without affecting the other parameters. Unlike the \textit{Crop} tool, the original frame size is not altered and being keyframable allows a wide variety of uses. In figure~\ref{fig:crop_position} the Crop \& Position plugin is compared with the \textit{Crop} tool.
1430
1431 \begin{figure}[htpb]
1432         \centering
1433         \includegraphics[width=1.0\linewidth]{crop_position.png}
1434         \caption{Crop tool and Crop \& Position plugin compared}
1435         \label{fig:crop_position}
1436 \end{figure}
1437
1438 \subsection{DeScratch}%
1439 \label{sub:descratch}
1440 \index{descratch}
1441
1442 The descratch video plugin can be used to remove vertical scratches
1443 from film. It can also be used, after image rotation, to remove
1444 horizontal noise lines that may appear on analog \textit{VHS}
1445 captures. For best results \textit{YUV} should be the video format;
1446 however if your format is \textit{RGB}, it will first be converted
1447 to YUV\@. There are many tuneable parameters necessary to get good
1448 results for your specific film.
1449
1450 Figure~\ref{fig:descratch01} shows a list of the parameter descriptions:
1451
1452 \begin{figure}[htpb]
1453     \centering
1454     \includegraphics[width=0.6\linewidth]{descratch01.png}
1455     \caption{DeScratch control window}
1456     \label{fig:descratch01}
1457 \end{figure}
1458
1459 \begin{figure}[htpb]
1460     \centering
1461     \includegraphics[width=0.5\linewidth]{descratch02.png}
1462     \caption{Various parameters of DeScratch}
1463     \label{fig:descratch02}
1464 \end{figure}
1465
1466 \begin{description}
1467     \item[threshold] instantaneous slope value; chroma difference in numerical pixels.
1468     \item[asymmetry] maximum asymmetry of surrounding
1469     pixels.
1470     \item[Mode] \textit{None}; \textit{Low}=black; \textit{High}=white; \textit{All}=both;
1471     \textit{y} -- processing mode for \textit{luma} plane;
1472     \textit{u}-- processing mode for \textit{chroma u} plane;
1473     \textit{v} -- processing mode for \textit{chroma v} plane.
1474     \item[width min/max] minimal scratch width in pixels and maximum scratch width in pixels.
1475     \item[len min/max] percent minimal scratch length and percent maximum scratch length.
1476     \item[len blur] scaled radius of vertical blur for frame
1477     analysis.
1478     \item[len gap] number of pixels for maximum vertical gap
1479     to be closed.
1480     \item[max angle] maximal angle to vertical in degrees.
1481     \item[fade] percent of how much it fades to and how much it. Uses between before image and blurry image.
1482     \item[border] pixel thickness of border near scratch for partial restoration.
1483     \item[Mark] shows the potential scratch lines for ease of viewing and for debugging. It shows chosen pixels in the color green, close but still rejected in yellow, and extreme pixels in the color red. This makes it easy to vary some parameters to choose more or fewer scratch lines.
1484     \item[Reset] activating this button returns all of the parameters to their default values.
1485 \end{description}
1486
1487 Figure~\ref{fig:descratch} shows a before and after DeScratch scenario. With \textit{Mark} set, you can see the black lines which indicate what the program was looking at to determine the scratches to remove.
1488
1489 \begin{figure}[htpb]
1490     \centering
1491     \includegraphics[width=0.9\linewidth]{descratch.png}
1492     \caption{Original video with scratch; Option Mark selected and Final video}
1493     \label{fig:descratch}
1494 \end{figure}
1495
1496 \subsection{Decimate}%
1497 \label{sub:decimate}
1498 \index{decimate}
1499
1500 This is used to decrease the frame rate of a video. Changing the frame rate means eliminating a frame for any given number of frames ($1 in N$); but if frames that are important for visual continuity are deleted, temporal artifacts arise: flickering, slowdowns, accelerations, etc. The Decimate filter maintains a higher quality because it first eliminates duplicate frames or frames that are most similar, thus limiting the appearance of artifacts. It is often used after the \textit{Invert Telecine} plugin to make the video more smooth.
1501
1502 One use of the decimate effect can be applied to a DVD to convert the 29.97\,\emph{fps} video to the 23.97\,\emph{fps} film rate, but the effect can take any input rate and convert it to any lower output rate. The output rate of decimate is the project frame rate. The input rate is set in the decimate user interface. To convert 29.97\,\emph{fps} progressive video to 23.97\,\emph{fps} film, apply a decimate effect to the track. Set the decimate input rate to 29.97 and the project rate to 23.97.
1503
1504 Keep in mind that every effect layered before decimate, processes video at the decimate input rate and every effect layered after decimate, processes video at the project frame rate. Computationally intensive effects should come below decimate.
1505
1506 \subsection{Deinterlace}%
1507 \label{sub:deinterlace}
1508 \index{deinterlace}
1509
1510 The deinterlace effect has evolved over the years to deinterlacing and a whole lot more. In fact two of the deinterlacing methods, \textit{Inverse Telecine} and \textit{Frames to Fields}, are separate effects. The deinterlace effect offers several variations of line replication to eliminate comb artifacts in interlaced video. It also has some line swapping tools to fix improperly captured video or make the result of a reverse effect display fields in the right order.
1511
1512 \subsection{Deinterlace-CV}%
1513 \label{sub:deinterlace_cv}
1514 \index{deinterlace-cv}
1515
1516 Selection of deinterlacing mode for your video to eliminate comb artifacts (figure~\ref{fig:deinterlace}).
1517
1518 \begin{figure}[htpb]
1519     \centering
1520     \includegraphics[width=0.6\linewidth]{deinterlace.png}
1521     \caption{Pulldown menu}
1522     \label{fig:deinterlace}
1523 \end{figure}
1524
1525 \subsection{Delay Video}%
1526 \label{sub:delay_video}
1527 \index{delay video}
1528
1529 Delay the video by some number of seconds.
1530
1531 \subsection{Denoise Video}%
1532 \label{sub:denoise_video}
1533 \index{denoise video}
1534
1535 Denoise video (figure~\ref{fig:denoise}).
1536
1537 \begin{figure}[htpb]
1538     \centering
1539     \includegraphics[width=0.4\linewidth]{denoise.png}
1540     \caption{Control window of the DeNoise plugin}
1541     \label{fig:denoise}
1542 \end{figure}
1543
1544 \subsection{Difference key}%
1545 \label{sub:difference_key}
1546 \index{difference key}
1547
1548 The difference key creates transparency in areas which are similar between two frames. The Difference key effect must be applied to two tracks. One track contains the action in front of a constant background and another track contains the background with nothing in front of it. Apply the difference key to the track with the action and apply a \textit{shared effect} of it to the track with the background. The track with the background should be muted and underneath the track with the action and the color model should have an alpha channel. It’s hard to get good results.
1549
1550 Pixels which are different between the background and action track are treated as opaque. Pixels which are similar are treated as transparent. Change \textit{threshold} in the difference key window to make more pixels which are not the same color transparent. Change \textit{slope} to change the rate at which the transparency tapers off as pixels get more different. The slope as defined here is the number of extra values flanking the threshold required to go from opaque to transparent. A high slope is more useful with a low threshold because slope fills in extra threshold.
1551 \textit{Use value} causes the intensity of pixels (\textit{luma}) to be compared instead of the color. Applying a \textit{blur} to the top track with just the alpha channel blurred can soften the transparency border (figure~\ref{fig:diff-key}).
1552
1553 \begin{figure}[htpb]
1554     \centering
1555     \includegraphics[width=0.8\linewidth]{diff-key.png}
1556     \caption{Difference key and its problematic output}
1557     \label{fig:diff-key}
1558 \end{figure}
1559
1560 \subsection{DotTV}%
1561 \label{sub:dottv}
1562 \index{dotTV}
1563
1564 Puts various size dots over the picture to simulate TV effect. This came from: {\small \url{https://effectv.com}}.
1565
1566 \subsection{Downsample}%
1567 \label{sub:downsample}
1568 \index{downsample}
1569
1570 Downsampling is the process of reducing the size of an image by throwing out data, reducing sampling rate.
1571
1572 \subsection{Edge}%
1573 \label{sub:edge}
1574 \index{edge}
1575
1576 Display only the edges of the video throughout the image.
1577
1578 \subsection{Fields to frames}%
1579 \label{sub:fields_to_frames}
1580 \index{fields to frame}
1581
1582 See the theory description in the \textit{Frames to Fields} plugin. This effect reads frames at twice the project framerate, combining two input frames into a single interlaced output frame. Effects preceding fields to frames process frames at twice the project frame rate. Each input frame is called a field.
1583
1584 Fields to frames needs to know what field corresponds to what lines in the output frame. The easiest way to figure it out is to try both options in the window. If the input fields are the result of a line doubling process like frames to fields, the wrong setting results in blurrier output. If the input fields are the result of a standards conversion process like \textit{1080 to 480}, the wrong setting will not make any difference.
1585
1586 \subsection{Flip}%
1587 \label{sub:flip}
1588 \index{flip}
1589
1590 This effect flips a video track either vertically or horizontally.
1591
1592 \subsection{Foreground}%
1593 \label{sub:foreground}
1594 \index{foreground}
1595
1596 Whatever the visual content of the frame, the Foreground plugin application applies a uniform color that can be chosen by color picker; color wheel; color presets; the various HSV, RGB, YUV sliders or by entering the hexadecimal value. The alpha slider is not missing either.
1597
1598 \subsection{Frames to fields}%
1599 \label{sub:frames_to_fields}
1600 \index{frames to fields}
1601
1602 \subsubsection*{Theory behind the Frames to Fields and Fields to Frames plugins}
1603 \label{ssub:theory_frames_fields}
1604
1605 Historically, CRT-type TVs used interlaced signals to save bandwidth. An interlaced video consists of two \textit{fields} that are read and drawn on the screen one after the other. Each field must be played at a framerate double that of the resulting video. In two steps the complete frame will be reconstructed.
1606
1607 Frame 1 $\implies$ F1-field1 (\textit{Top} or \textit{Odd}), F1-field2 (\textit{Bottom} or \textit{Even})
1608
1609 Frame 2 $\implies$ F2-field1, F2-field2
1610
1611 Interlaced video reading: $F1-f1$ then $F1-f2$ then $F2-f1$ then $F2-f2$ \dots
1612 There may be visual problems if the Top type interlacing is read according to a Bottom scheme. So it's important to know if a video is Top or Bottom. Generally an \textit{HD} video is Top; a \textit{DV} video (both PAL and NTSC) is Bottom; \textit{SD} (PAL) is Top; \textit{SD} (NTSC) is Bottom (but not always). Instead, high-definition videos need to be more compressed and this contrasts with the interlacing that is little and badly compressible, so modern videos are mostly \textit{progressive}.
1613
1614 \subsubsection*{In \CGG{}}
1615 \label{ssub:in_cin_gg}
1616
1617 \begin{enumerate}
1618     \item upload an interlaced video to the Timeline and Resources and play it for viewing.
1619     \item The video presents visual artifacts because PC monitors are progressive.
1620     \item In the Resources window, open the media \textit{Info} with the right mouse button. Below you can see that the \textit{asset's interlacing} is active. It has four options for settings interlacing type: \textit{Unknown}, \textit{Top Fields first}, \textit{Bottom Fields first}, and \textit{Not interlaced}. If the file is (H)DV type, recognition and configuration is done automatically. All other media types will be set \textit{unknown}. We need to set the type of interlacing, so we have to manually set the interlacing.
1621     \item Now we can to use the \textit{Frames to Fields} plugin, but we have to configure it and act manually.
1622 \end{enumerate}
1623
1624 Now for the practical use of this plugin which applies the operation reverse to the \textit{Fields to Frames} plugin. It extracts the two interlaced fields stored in alternating lines of interlaced source footage and outputs them as separate full frames. The alternating lines missing on each output frame are interpolated.
1625
1626 This plugin is only useful if its output is pulled with doubled framerate with respect to the source footage. One typical usage scenario is to do \textit{masking}, \textit{scaling} and \textit{translating} on interlaced footage without the need to destroy the additional temporal information contained in such source material. This is helpful if your intended target format is interlaced. If on the other hand, you just want to target a progressive display (for example, you create video for display on a computer monitor solely) then it is much more convenient to de-interlace the source material prior to any further processing.
1627
1628 \subsubsection*{Processing interlaced footage without deinterlacing}
1629 \label{ssub:processing_interlace_footage}
1630
1631 \begin{enumerate}
1632     \item Create a new project with doubled frame rate. That is, make it $50\,fps$ if your source footage is $25i$.
1633     In \texttt{Resources $\rightarrow$ Media $\rightarrow$ Info} set the interlaced type (or unknown)
1634     \item Insert your source footage onto a video track in the timeline. Now, \CGG{} will playback each
1635     frame of your footage twice. There will be visual artifacts because the video is interlaced and the
1636     monitor is progressive.
1637     \item Apply the \textit{Frames to Fields} effect. Be sure to choose the correct field order. If we know or believe that the original video is \textit{Top First} let's try it first, but it doesn't have to be the right solution. The only way is to playback and look for visual artifacts.
1638     \item Then apply any further effects afterwards, including translations, scaling, slow motion, precise
1639     frame-wise masking or use of the motion tracker plugin.
1640     \item Render your project to an intermediate clip. Be sure to choose a rather lossless video codec, for
1641     example \textit{Motion-JPEG-A} or even \textit{uncompressed YUV} if you have plenty of storage.
1642     \item Insert the intermediate clip into your original project. Make sure the doubled framerate has been
1643     detected correctly by \CGG{} (by looking in the clip's media \textit{info} in the media resources folder).
1644     \item Apply the \textit{Fields to frames} effect to the intermediate clip. This will combine two adjacent fields
1645     into one interlaced field with the original frame rate.
1646     \item Do the final render on your original project. Now there will be no visual artifacts on the monitor.
1647 \end{enumerate}
1648
1649 \subsection{Freeze Frame}%
1650 \label{sub:freeze_frame}
1651 \index{freeze frame}
1652
1653 In its simplest form, highlight a region of the track to freeze, drop the \texttt{freeze frame} effect on the highlighted region, and the lowest numbered frame in the affected area will play throughout the entire region. Freeze Frame has an enabled option which can be keyframed. Regions of a freeze frame effect which are enabled, repeat the lowest numbered frame since the last keyframe. This has unique possibilities.
1654
1655 \begin{itemize}
1656     \item If a freeze frame effect has a keyframe in the middle of it set to enabled, the frame in the middle is repeated in the entire effect.
1657     \item If a freeze frame effect has several keyframes, each set to enabled, every time a keyframe is encountered the frame under it becomes the frozen one.
1658     \item If a freeze frame effect alternates between enabled and disabled, each time an enabled keyframe is encountered the frame under it is replicated until the next disabled keyframe. The disabled regions play through.
1659 \end{itemize}
1660
1661 \subsection{Gamma}%
1662 \label{sub:gamma}
1663 \index{gamma}
1664
1665 \textit{Log} camera images store colors in a $logarithmic$ scale. The blacks in these images are nearly $0$ and the whites are supposed to be infinity. The graphics card and most video codecs store colors in a $linear$ scale but \CGG{} keeps log camera images in their original logarithmic scale when it renders them. This is necessary because the raw image parser can not always decode the proper gamma ($\gamma$) values for the images. It also does its processing in $16\,bit$ integers, which takes away a lot of information.
1666
1667 Mathematically, the gamma function is exponential
1668 ($output = input^{\gamma}$) and therefore the inverse of the
1669 logarithmic function [$output = \log(input)$]. Actually the formula
1670 used by the \CGG{} plugin is: $output = input^{\frac{1}{\gamma}}$
1671 which allows for a range of values $0 \div 1.0$. The gamma effect
1672 converts the logarithmic colors to linear colors through a
1673 \textit{gamma value} and a \textit{maximum value}. The gamma value
1674 determines how steep the output curve is (i.e.\ the value of the
1675 gamma parameter; for color space Rec709 is $2.4$
1676 ($\frac{1}{\gamma} =0.41\dots$), for sRGB is $2.2$
1677 ($\frac{1}{\gamma} =0.45\dots$), etc.). The maximum value is where
1678 $1.0$ in the output corresponds to maximum brightness in the
1679 input. It serves to avoid clipped values because it allows you to
1680 set the maximum value of the output, $1.0$, whenever range
1681 adjustment is done (see figure~\ref{fig:gamma01}). It is important
1682 to adjust the two parameters accurately in order to avoid undesired
1683 and unexpected effects, such as excessive values, unbalanced image,
1684 incorrect linearization, etc.
1685
1686 \begin{figure}[htpb]
1687     \centering
1688     \includegraphics[width=1.0\linewidth]{gamma01.png}
1689     \caption{settting \textit{Maximun} to $0.6900$}
1690     \label{fig:gamma01}
1691 \end{figure}
1692
1693 The gamma effect has two more parameters to simplify gamma correction. The automatic option causes it to calculate max from the histogram of the image. Use this when making a preview of a long list of images since it changes for every image. The use color picker option uses the value currently in the color picker to set the maximum value. Note that every time you pick a color from the compositor window, you need to click on use color picker to apply the new value.
1694
1695 The best use of the gamma is manually monitoring the waveform as shown in figure~\ref{fig:gamma02}.
1696
1697 \begin{itemize}
1698     \item Look at the highest peak on the \textit{waveform} and measure it with the crosshair observing the numerical value at the top left.
1699     \item Set this value with the \textit{maximum} slider.
1700     \item Then adjust the slider of the \textit{gamma} to our liking, always checking the result on the waveform so to be sure never to exceed the values of clipping, $0 \div 1.0$.
1701 \end{itemize}
1702
1703 \begin{figure}[htpb]
1704     \centering
1705     \includegraphics[width=1.0\linewidth]{gamma02.png}
1706     \caption{Setting \textit{Maximun} to $0.6100$ and \textit{Gamma} to $0.3300$}
1707     \label{fig:gamma02}
1708 \end{figure}
1709
1710 Care must be taken when using gamma correction: if the image carries a specific gamma value, or if it has already been corrected previously (for example automatically in the camera), etc.; then a second application of the gamma leads to excessive and artificial results. Gamma is keyframable.
1711
1712 \subsection{Gradient}%
1713 \label{sub:gradient}
1714 \index{gradient}
1715
1716 The \textit{gradient} effect overlays a smooth color gradient on top of every video frame. It is useful for all sorts of background fills, for partially filtering, adding depth to the image, or for adding moving highlights. The Gradient effect can generate linear or circular color fills / shape. For linear fills, you can choose the \textit{angle}, for circular fills the \textit{center $(X,Y)$} of the created gradient pattern. You can control the \textit{slope} of the color transition by selecting a transition function ($linear$, $logarithmic$, $squared$) and by changing the start (\textit{inner}) and stop (\textit{outer}) radius. Note that both colors used in this color transition can contain an arbitrary \textit{Alpha} value (transparency). All parameters can be keyed and will be interpolated between keyframes.
1717
1718 The first time you use the plugin it may seem complicated, but if you understand that we have to adjust the gradient from an inner spot we choose to an outer spot we also choose, the work will become easy and fast.
1719
1720 \subsubsection*{Use case (Vignette)}
1721 \label{ssub:use_case_vignette}
1722
1723 \begin{enumerate}
1724     \item Setting the shape to radial
1725     \item Setting the rate to Linear (or Log or Square)
1726     \item Position $X$ and $Y$ to center the main figure.
1727     \item Choose inner color=black
1728     \item Adjust inner radius
1729     \item Bring the inner color alpha slider to $0$
1730     \item Choose outer color=black
1731     \item Check that the outer color alpha slider is $1$.
1732     \item Adjust outer radius
1733 \end{enumerate}
1734
1735 \textit{Note:} The inner and outer colors are visibly mixed in the gradient area. If you want to make a vignetting of only black, you must set the two colors to black and then make the inner one transparent so that it does not cover the figure.
1736
1737 \subsection{HistEQ}%
1738 \label{sub:histeq}
1739 \index{histEQ}
1740
1741 Remap colors using blended histogram weights. Figure~\ref{fig:histeq} shows the GUI and the results in a split screen.
1742
1743 \begin{figure}[htpb]
1744     \centering
1745     \includegraphics[width=0.8\linewidth]{histeq.png}
1746     \caption{Control window and split screen}
1747     \label{fig:histeq}
1748 \end{figure}
1749
1750 Histeq equalizes the colorspace through use of a \textit{histogram equalization algorithm} -- a technique for adjusting image intensities to enhance contrast. Parameters are:
1751
1752 \begin{description}
1753     \item[Gain:] when set to $1$, the colorspace is best effort. If the gain is set to $0$, the result is the entire regression line of the color map.
1754     \item[Blend:] goes between a straight and a twisted line.
1755     \item[Split output:] diagonally shows in the compositor, the new results on the left and old on the right.
1756     \item[Plot bins/lut:] displays a plot of the result.
1757 \end{description}
1758
1759 \subsection{Histogram}%
1760 \label{sub:histogram}
1761 \index{histogram}
1762
1763 The histogram allows an immediate view of the contrast amplitude of an image with its distribution of \textit{luma} and \textit{colors} values. If the columns of values occupy the whole range $0-100\%$ then we have maximum contrast; if the range is smaller the contrast is smaller. If most of the values are on the right of the histogram you have an image with highlights at the limit with values clamped to $1.0$. This is called \textit{overexposure}. However, if most of the values are moved to the left, with the limit of the values clamped to $0$, we have a lowlight image and we talk about \textit{underexposure}. Histogram is keyframble (figure~\ref{fig:histogram}).
1764
1765 \begin{figure}[htpb]
1766     \centering
1767     \includegraphics[width=0.9\linewidth]{histogram.png}
1768     \caption{Master Histogram and RGB Histogram}
1769     \label{fig:histogram}
1770 \end{figure}
1771
1772 The Histogram is always performed in floating point RGB regardless of the project color space. The histogram has two sets of transfer parameters: the \textit{input transfer} and the \textit{output transfer}. The input transfer has value on the horizontal axis of $x$; it is a scale of values ranging from 0 to 255 in the case of an $8\,bit$ image, or it can have normalized values in the range ($0-1.0$) or even be a scale in percentage ($0-100\%$). In the output transfer (the $y\,axis$) is represented the number of times (that is, $y$) a given value $x$ appears. A higher column ($y$ greater) indicates that many pixels have the corresponding value $x$; a lower column indicates that fewer pixels have that value. On the left we have the minimum value $0$, which is the black point. On the right we have the maximum value $1.0$ which is the white point. The intermediate values pass smoothly from one extreme to the other. The three important points (including the midtones, i.e.\ the Master Offset) are indicated by cursors (small triangles) at the base of the histogram. You can adjust them to change the values of the three points if you want.
1773
1774 There are 4 possible histograms in the histogram viewer. The red, green, blue histograms show the input histograms for red, green, blue and multiply them by an input transfer to get the output red, green, blue. Then the output red, green, blue is scaled by an output transfer. The scaled red, green, blue is converted into a value and plotted on the value histogram. The value histogram thus changes depending on the settings for red, green, blue. The value transfers are applied uniformly to R, G, B after their color transfers are applied. Mathematically, it is said that the values of $x$ are linked to the values of $y$ by a transfer function. This function is represented by a line that leaves the values of $x$ and $y$ unchanged, but we can intervene by modifying this line with the cursors.
1775
1776 You need to select which transfer to view by selecting one of the channels on the top of the histogram. You can also choose whether to display the master, i.e.\ only the values of the \textit{luma}, or show the \textit{Parade}, i.e.\ the three RGB channels. You can switch from one to the other with the two buttons in the upper right corner. The input transfer is defined by a graph overlaid on the histogram; this is a straight line. Video entering the histogram is first plotted on the histogram plot, then it is translated so output values now equal the output values for each input value on the input graph.
1777
1778 After the input transfer, the image is processed by the output transfer. The output transfer is simply a minimum and maximum to scale the input colors to. Input values of $100\%$ are scaled down to the output's maximum. Input values of $0\%$ are scaled up to the output minimum. Input values below $0$ are always clamped to $0$ and input values above $100\%$ are always clamped to $100\%$. Click and drag on the output gradient's triangles to change it. It also has textboxes to enter values into.
1779
1780 Enable the \textit{Automatic} toggle to have the histogram calculate an automatic input transfer for the red, green, and blue but not the value. It does this by scaling the middle $99\%$ of the pixels to take $100\%$ of the histogram width. The number of pixels permitted to pass through is set by the \textit{Threshold} textbox. A threshold of $0.99$ scales the input so $99\%$ of the pixels pass through. Smaller thresholds permit fewer pixels to pass through and make the output look more contrasty.
1781 \textit{Plot histogram} is a checkbox that enables plotting the histogram.
1782 \textit{Split output} is a checkbox that enables a diagonal split showing in the compositor.
1783 \textit{Reset} returns the four curves to their initial state (neutral) as well as the Value/RGB histogram buttons.
1784
1785 The histogram plugin ordinarily applies a value for a single frame.  A
1786 new feature modifies histogram to show values for a selection of frames.
1787 You use several frames in a video that you want to use the \textit{average}
1788 color to determine the color you want the rest of the video to be.  When
1789 there is a large light or color variation within a range of a few frames,
1790 you spend a lot of time correcting each frame when it would be better to
1791 just get an average value to use.  If you want, then you can make a LUT for
1792 that set of frames instead of each frame.
1793
1794 It works by selecting the area on the timeline for
1795 which you would like to see the Histogram averaged and then click on the
1796 \textit{Frames} button in the Histogram plugin.
1797 The parameters are:
1798 \textit{Linear to Log} slider: frequency in Linear range to Log range; default is 50\%, but if you want it to be the same as the Videoscope or Histogram Bezier, set the slider all the way to Log.  The variation is by 10\% steps.  Linear generally represents what the eye sees in the real world.  Log is an exponential look where the small numbers are represented more - that is, the leading digit.
1799 \textit{Frames} button: if a Selection is set on the timeline, the number of frames
1800 will be calculated and shown in the box next to it.
1801 \textit{Frame Count box}: type in the number of frames you want to be looked at
1802 starting at the insert marker or use the up/down counter.
1803 \textit{Clear Frames} icon: reset the frame count to the default value of 0.
1804
1805 A side note: by using a number of frames, you can get a \textit{dissolve-like
1806 transition effect}.
1807
1808 \paragraph{Theory:} 
1809
1810 A histogram is a bunch of \textit{bins} (accumulators) that count the number of times a particular pixel channel intensity occurs in an image. Dim are on the left, bright on the right.
1811
1812 The number of bins used depends on the color model bit depth:
1813
1814 \begin{description}
1815         \item[Histogram:] 256 for rgb8 and 65536 for all others.
1816         \item[Bezier:] 256 for rgb8/yuv8 and 65536 for all others.
1817         \item[Scopes:] always uses 65536
1818 \end{description}
1819
1820 All of the bins are scanned when the graph is plotted.  What is shown
1821 depends on which plugin is used:
1822
1823 \begin{description}
1824         \item[Histogram:] was max of the bins in the pixel range, now is the sum
1825         \item[Bezier:] is the max of the bins in the pixel range
1826         \item[Scopes:] is the max of the bins in the pixel range
1827 \end{description}
1828
1829 When the color space and the bin size are the same, all of the values
1830 increment the indexed bins.  When the color is the result of yuv $\rightarrow$ rgb conversion, the results \textit{spread} if there are more bins than colors.  This is the same effect you see when you turn on \textit{smoothing} in the vectorscope histogram.
1831
1832 The \textit{total} pixels for each value is approximately the same, but the \textit{max} value depends on the color quantization.  More colors increment more bins.  Fewer colors increment fewer bins.  In both cases, the image size has the same
1833 number of pixels.  The fewer color case increments the used bins, and skips the
1834 unused bins.  This sums all of the pixels into fewer bins, and the bins have
1835 higher values. That is the \textit{rgb} vs \textit{yuv} case, fewer vs more bins are used.
1836
1837 To report something more consistent, has been changed the reported value to
1838 the \textit{sum} of the accumulated counts for the bins reporting a pixel bar on the
1839 graph. The effect of this is to do this:
1840
1841 \begin{center}
1842         \begin{tabular}{ l l c r r }
1843                 \hline
1844                 1 &  & & & \\
1845                 1 &  & & 1 & \\
1846                 000100 & 3 pixels & vs & 001000& 3 pixels \\
1847                 \hline
1848         \end{tabular}
1849 \end{center}
1850
1851 On the left, the course color model piles all 3 pixels into one bin.  max
1852 value 3
1853
1854 On the right, the fine color model puts the counts into 2 bins, max 2, sum 3
1855
1856 So, by reporting the sum the shape of the results are more similar.
1857
1858
1859 \subsection{Histogram Bezier / Curves}%
1860 \label{sub:histogram_bezier_curves}
1861 \index{histogram Bezier}
1862
1863 Histogram Bézier allows an immediate view of the contrast amplitude of an image with its distribution of luma and colors values using a piecewise linear method. In addition it uses a Bézier curve (parametric) on the histogram plot. When mapping color spaces, it has a variety of presentations to get smoother transitions and more pleasing output. It uses more general remapping, not just straight lines but more contour lines. Curves are perhaps the most powerful and sophisticated tool for color correction. For some repetitive details, see the previous description of the Histogram plugin. Histogram Bézier is keyframable.
1864
1865 The input graph is edited by adding and removing any number of points. Click and drag anywhere in the input graph to create a point and move it. Click on an existing point to make it active and move it. The active point is always indicated by being filled in. The active point's input X and output Y values are given in textboxes on top of the window. The input and output color of the point can be changed through these textboxes. Points can be deleted by first selecting a point and then dragging it to the other side of an adjacent point. They can also be deleted by selecting them and hitting delete (figure~\ref{fig:bezier}).
1866
1867 \begin{figure}[htpb]
1868     \centering
1869     \includegraphics[width=0.9\linewidth]{bezier.png}
1870     \caption{Histogram Bezier / Curves}
1871     \label{fig:bezier}
1872 \end{figure}
1873
1874 \begin{itemize}
1875     \item \textit{Master} (value) and \textit{R}, \textit{G}, \textit{B} histograms.
1876     \item Textbox for input $x$ (\textit{input}) and input $y$ (\textit{output}).
1877     \item \textit{Output min} and \textit{output max}: sets black or white points. If you use both points it works as Master/Color
1878     Offset. Values can also be less than $0$ and greater than $1.0$.
1879     \item Scale for \textit{contrast range}: sets with cursors shown as little triangles.
1880     \item \textit{Automatic} and \textit{Threshold}: enable the Automatic toggle to have the histogram calculate an automatic input transfer for the red, green, and blue but not the value. It does this by scaling the middle $99\%$ of the pixels to take $100\%$ of the histogram width. The number of pixels permitted to pass through is set by the Threshold textbox. A threshold of $0.99$ scales the input so $99\%$ of the pixels pass through. Smaller thresholds permit fewer pixels to pass through and make the output look more contrasty.
1881     \item \textit{Reset:} returns the four curves to their initial state (neutral).
1882     \item \textit{Split picture:} a checkbox that enables a diagonal split showing in the compositor.
1883     \item \textit{Interpolation:} type of algorithm for the parametric curves; linear, polynomial and Bezier.
1884 \end{itemize}
1885
1886 Curves are used by introducing \textit{control points} simply with
1887 the left mouse button and adjusting the value by dragging and
1888 dropping. If you drag along the horizontal line only, you change the
1889 value of $x$ and you can read this value in the input $x$
1890 textbox. If you drag along the vertical line only, you change the
1891 value of $y$ and you can read the value in the input $y$
1892 textbox. This is the output value. The newly clicked control point
1893 becomes active and is full green in color. To delete a point we have
1894 to make it active and then press the Del key, or we can drag the
1895 point beyond the position of another control point to its right or
1896 left or, finally, pressing RMB\@. The control points corresponding to
1897 the black point and the white point are automatically created from
1898 the beginning, to fix their values and prevent clipping.
1899
1900 Curves are generally adjusted by introducing several control points, some to be kept fixed (as anchors) to prevent curve modification beyond them, and others to be dragged to make the desired correction. The power of the curves lies in being able to circumscribe a small interval at will and intervene only on this without involving the remaining parts of the frame. The precision with which you can work is such that you can almost arrive at a secondary color correction.
1901
1902 The most used type of modification is to create a \textit{S curve}. There can be a lot of shapes that use the S curve; the simplest is to create a control point in the shadows, one in the midtones (anchors) and one in the highlights. Moving the highlight point upwards and the shadow point downwards increases the contrast, making the image sharper and improving the color rendering. With the type of \textit{linear} curve you can make hard adjustments, similar to the result of the use of \textit{Color 3 Way}, even if this acts on the color wheel (Hue) while the curves act on individual RGB channels.
1903
1904 The \textit{Polynomial} and \textit{Bézier} types introduce \textit{control handles} that allow for more sophisticated and smoother adjustments. The quality of the result is much better, but they require more experience for their optimal use. Extending the handles away from the control point increases the \textit{radius} of the curve at that point. By varying the angle of the handles we change the \textit{tangent} and thus the curvature of the curve below. The difference between Polynomial and Bézier lies in the underlying mathematics, but for practical purposes the use is similar.
1905
1906 Some examples of the use of curves to demonstrate the variety of possible interventions (figure~\ref{fig:ex-bezier}):
1907
1908 \begin{figure}[htpb]
1909         \centering
1910         \includegraphics[width=0.8\linewidth]{ex-bezier.png}
1911         \caption{Gain Up/Down; clamp; S-Shaped curve and Luma Key}
1912         \label{fig:ex-bezier}
1913 \end{figure}
1914
1915 \begin{itemize}
1916     \item Scale the image values by increasing the white point or decreasing the white point (gain up and gain down).
1917         You can decide the scaling value with the formula: $(Input \div Output) = Scale Factor$
1918     \item Limit a value beyond a certain point of brightness (clamp to the value $0.587$ in the figure).
1919     \item S-shaped curve to increase contrast without changing the black and white point (i.e.\ without \textit{clipping}).
1920     \item Make a real \textit{Luma Key} by bringing a certain value of gray to $100\%$ (white) and lowering everything else to $0\%$ (black). The slope of the two sides indicates how much we want to fade the edges of the matte obtained.
1921 \end{itemize}
1922
1923 \subsection{HolographicTV}%
1924 \label{sub:holographictv}
1925 \index{holographicTV}
1926
1927 Incoming objects are projected like holovision seen in the movie Stars Wars as in R2-D2's video message projector of the Princess Leia. You need a movie or background image and above it a track containing the figure on which to apply the effect. This must have a transparent background. There are no configuration parameters; it only has to be applied to the upper track (figure~\ref{fig:holographictv}).
1928
1929 This effect originated from {\small \url{https://effectv.com}}.
1930
1931 \begin{figure}[htpb]
1932     \centering
1933     \includegraphics[width=0.8\linewidth]{holographictv.png}
1934     \caption{Holographic messages in CinGG!}
1935     \label{fig:holographictv}
1936 \end{figure}
1937
1938 \subsection{Hue saturation}%
1939 \label{sub:hue_saturation}
1940 \index{hue saturation}
1941
1942 With this effect you can change hue, saturation and value. The parameters are modified using 3 simple sliders. The \textit{hue} control shifts the colors circularly in the color plane, normally resulting in false colors. The \textit{saturation} control can be used to reduce color footage to black and white. The \textit{value} control makes any given colors more bright or more subdued. Clear buttons are present to reset its slider to default without affecting others.
1943
1944 \subsection{Interpolate Bayer}%
1945 \label{sub:interpolate_bayer}
1946 \index{interpolate bayer}
1947
1948 Uses a Bayer filter algorithm to interpolate (estimate) missing color information. This is needed for some cameras where each pixel location only has an R or G or B value instead of all R, G, and B values for each location. The algorithm creates values for each of the three colors at every location by smearing (interpolating) each set of partial R, G and B values to create values at every pixel location.
1949
1950 \subsection{Interpolate Video}%
1951 \label{sub:interpolate_video}
1952 \index{interpolate video}
1953
1954 \subsubsection*{Theory}
1955 \label{ssub:theory}
1956
1957 Each video has its own framerate. If we want to change it (for \textit{timelapse} or \textit{slow motion}) the best thing is to shoot the scene with suitable framerate. But even in post production we can do something. The simplest method is to remove some frames to speed up the movie or add some to slow it down (from now on, for simplicity we will consider only the timelapse). Needless to say, the result is not smooth and the viewer will notice it immediately. A better method is to use the interpolation, mediating the pairs of frames that alternate. For example, if we have a sequence of frames $1, 2, 3, 4, 5, 6, 7, 8\dots$ we can make a timelapse mixing frames $1$ and $2$, $3$ and $4$, $5$ and $6$, $7$ and $8$ and so on. So we will have a new sequence of $4$ frames instead of the initial $8$: $\underline{12, 34, 56, 78}\dots$ We will get $50\%$ acceleration but it will always be of bad quality because of the too rough blending between the pairs of frames. Blending can be improved by weighing it differently by $50\% frame 1 + 50\% frame 2$, but the result is still unsatisfactory. Further improvements can be achieved by using $logarithmic$ or $exponential$ interpolation instead of $linear$ interpolation. But the most sophisticated methods that lead to better results are based on \textit{optical flow analysis}. These analyses the movement of circumscribed areas over a given period of time. With this method the intermediate frames do not derive from an approximate blending, but from the calculation of the \textit{vector} of the motion between two frames that determines the displacement (\textit{warping}) of the moving figure in the new intermediate frame. \textit{Interpolate Video} works this way.
1958
1959 \subsubsection*{Practice}
1960 \label{ssub:practice}
1961
1962 The practical use of \textit{Interpolate Video} is a little different than the theory. The interpolate effect tries to create the illusion of a higher frame rate from source footage of very low framerates by averaging frames over time. It averages two input frames for each output frame. You choose a zone to be evaluated (\textit{macroblock size}) and a radius (\textit{search radius}) where you can search for this macroblock in the following frames. The \textit{Use optic flow} button is activated and playback starts. The plugin will calculate the motion vector (which can be made visible by the \textit{draw motion vectors} button) and apply it to intermediate frames. This operation is CPU intensive. Once the analysis is done, we can scroll the video by unchecking the two buttons and obtaining the desired result. There are two ways of specifying the input frames. You can specify an input frame rate which is lower than the project frame rate (\textit{imput frames per seconds}). This causes input frames to be taken at even intervals. You can also specify keyframe locations as the positions of the input frames (\textit{use keyframes as input}). In this mode the output frame rate is used as the input frame rate and you just create keyframes wherever you want to specify an input frame.
1963
1964 \subsection{Inverse Telecine}%
1965 \label{sub:inverse_telecine}
1966 \index{inverse telecine}
1967
1968 This is the most effective deinterlacing tool when the footage is a video transfer of a film. This can be used to solve the problem, i.e., undo the damage caused by making film into a TV broadcast.
1969 That process came about because film is at 24\,\emph{fps} while TV is at 29.97\,\emph{fps} and fields are at 60.
1970 So the film was converted from 24\,\emph{fps} to 60\,\emph{fps}.
1971 Roughly speaking, converting every 4 frames into 5 frames plus a slight slow down in speed.
1972 Then the 60\,\emph{fps} was down-sampled to 30\,\emph{fps} by extracting odd and even lines and interlacing the lines.
1973 This process is referred to as \textit{three-two pull down} ($3:2$ pull down) in filmmaking and television production for the post production process of transferring film to video.
1974 The three-two pull down is where the telecine adds a third video field (a half frame) to every second video frame, but the untrained eye cannot see the addition of this extra video field.
1975 The \texttt{IVTC} effect is primarily a way to convert \textit{interlaced} video to \textit{progressive} video.
1976 It reverses the effect of three patterns of interlacing. In the next lines \texttt{A}, \texttt{B}, and \texttt{C} represent fields.
1977
1978 \texttt{A AB BC CD D}
1979
1980 \texttt{AB CD CD DE EF}
1981
1982 \texttt{Automatic}
1983
1984 The first two options are fixed patterns and affected by the pattern \textit{offset} and \textit{odd field first} parameters. The last option creates several combinations of lines for each frame and picks the most progressive combination. It is a brute force algorithm that is trying to resample the lines. This technique does not rely on a pattern like other techniques and is less destructive but the timing is going to be jittery because of the lack of a frame rate reduction. In order to smooth out the timing, you need to follow \textit{inverse telecine} with a \textit{decimate} effect.
1985
1986 \subsection{Invert Video}%
1987 \label{sub:invert_video}
1988 \index{invert video}
1989
1990 Invert video is a method of reversing the colors of a video track. The four parameters refer to channels -- \textit{Red}, \textit{Blue}, \textit{Green}, \textit{Alpha}. A very common use is to invert the alpha channel to change transparency.
1991
1992 \subsection{Lens}%
1993 \label{sub:lens}
1994 \index{lens}
1995
1996 Create the effect of looking through a lens.
1997
1998 \begin{description}
1999     \item[R, G, B, A Field of View:] quantity of deformation of the relative fields. Often used with \texttt{Lock} to simultaneously affect the 4 fields.
2000     \item[Aspect Ratio:] determines the aspect ratio that you intentionally set.
2001     \item[Radius:] radius of curvature of the distortion. At minimum, it is a sphere (\textit{fish eye}) and at maximum, it is a rectangle (no distortion).
2002     \item[Center X, Y:] determines the coordinates of the center of the sphere. It can be made visible with \textit{Draw Center}.
2003     \item[Mode:] determines the type of distortion. The choice is between \textit{sphere shrink}, \textit{sphere stretch}, \textit{rectilinear shrink} and \textit{rectlinear stretch}.
2004     \item[Interpolation] determines the interpolation algorithm; from the fastest and least precise \textit{Nearest}, passing through \textit{BiLinear} to the better \textit{BiCubic}.
2005 \end{description}
2006
2007 \subsection{Linear Blur}%
2008 \label{sub:linear_blur}
2009 \index{linear blur}
2010
2011 This effect acts only in one direction which can vary up to an angle of $180\degree$ with these parameters:
2012
2013 \begin{figure}[htpb]
2014         \centering
2015         \includegraphics[width=0.8\linewidth]{linear.png}
2016         \caption{For clarity of presentation only 2 fields are shown}
2017         \label{fig:linear}
2018 \end{figure}
2019
2020 \begin{description}
2021     \item[Length:] distance between original image and final blur step; corresponds to the distance of the fields.
2022     \item[Angle:] angle of motion in one direction for linear blur
2023     \item[Steps:] number of blur steps to be used in the calculation. Increasing the number takes more CPU.
2024     \item[Channels:] R,G,B,A.
2025     \item[Clear] With the Clear buttons we can bring the slider to default values without affecting the other parameters.
2026 \end{description}
2027
2028 Figure~\ref{fig:linear} shown here has the parameters: $Length=19$, $Angle=25$, and $Steps=2$.
2029
2030 \subsection{Live Video}%
2031 \label{sub:live_video}
2032 \index{live video}
2033
2034 This effect reads video directly from the capture card input. It replaces any video on the track so it is normally applied to an empty track. Only one \textit{Live Video} effect can exist at any time on the timeline. It can not be shared by more than one track. The configuration for the capture card is taken from the recording preferences. Go to \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Recording} to set up the capture card.
2035
2036 In the \textit{Video In} section where it says \textit{Record driver}, it should be set to either \textit{Video4Linux2} or \textit{IEC 61883}. Other video drivers have not been tested with Live Video and probably will not work. For live video, the selection for \textit{File} Format and \textit{Video} needs to be set to a format the timeline can use. The file format must be Quicktime for Linux and video recording must be enabled for it. Click on the wrench to set the video compression.
2037
2038 The video compression depends on the recording driver. For the \textit{Video4Linux2} recording driver, the compression must be \textit{Motion JPEG A}. For the \textit{IEC 61883} driver, the compression must be \textit{DV}. This gets the driver to generate output in a color model that the timeline can use. Some cards provide color and channel settings. Live video takes the color settings from the values set in the Video In window. Go to \texttt{File $\rightarrow$ Record} to bring up the recording interface and the Video In window. Values set in the Video in window are used by Live Video. Any channels the capture card supports need to be configured in the Video In interface since the same channels are used by the Live Video effect.
2039
2040 With the video recording configured, highlight a horizontal region of a video track or define in and out points. Then drop the Live Video effect into it. Drop other effects after Live Video to process the live video in realtime. For best results, you should use OpenGL and a video card which supports GL shading language. Go to \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Playback $\rightarrow$ Video Out} to enable the OpenGL driver.
2041
2042 \subsection{Loop video}%
2043 \label{sub:loop_video}
2044 \index{loop video}
2045
2046 Sections of video can be looped by dropping a loop effect on them. Contrary to the \texttt{settings $\rightarrow$ loop playback} option, the loop effects can be rendered where the \texttt{settings $\rightarrow$ loop playback} option can not be. The loop effects are also convenient for short regions.
2047
2048 The loop effects have one option: the \textit{number of frames} or \textit{samples} to loop. This specifies the length of the region to loop starting from either the beginning of the effect or the latest keyframe. The region is replicated for the entire effect.
2049
2050 Every time a keyframe is set in a loop effect, the keyframe becomes the beginning of the region to loop. Setting several keyframes in succession causes several regions to loop. Setting a single keyframe causes the region after the keyframe to be looped throughout the effect, no matter where the keyframe is. The end of an effect can be looped from the beginning by setting the keyframe near the end.
2051
2052 \subsection{Motion51}%
2053 \label{sub:motion51}
2054 \index{Motion51}
2055
2056 This plugin compensates for unwanted motion and stabilizes the picture. The \textit{Motion51} Plugin simplifies motion stabilization so that without a lot of tweaking you can easily achieve reasonable results, either by using the defaults or varying a single parameter. Since the motion in every clip is specific, there are some additional parameters useful to adjust the settings accordingly. 
2057 The Motion51 plugin uses different methods for tracking than the other motion plugins. Motion Stabilization is very useful if you have jittery video, for example when taken from a car window, or while walking.
2058
2059 The better results require more samples. Setting the \textit{sample set size} is probably the most important setup change. Also, when computing motion compensation, the entire history of the image motion is important, and so it is desirable to enable the playback setting \textit{play every frame} in order to get good results. When every frame has to be processed, it can be time-consuming. Reasonable results are possible with small sample sets. After setup, the sample size can be increased to produce a high quality rendered result.
2060
2061 \subsubsection*{Description of what the program is doing}
2062 \label{ssub:description_program_doing}
2063
2064 The motion is detected by \textit{sampling} the video image in a circular field. This size and placement of the sample region defaults to most of the image area. When the \textit{draw vectors} feature is enabled, the outer line trace encloses the searched region. The dotted circles define the target pixel set as the reference sample. The image is sampled using the circle pattern in a grid search. The best match is used to find the center and amount of rotation to transform the current image so that the reference area motion is canceled.
2065
2066 The amount of sampling does not significantly change for smaller or larger search areas. This means that a wide area can be searched just as easily as smaller areas. The main parameter which determines how hard it looks at the image is the \textit{samples} parameter. It represents the number of possible rotations, as well as the search precision. More samples mean more precision, and less jitter, but the program will run more slowly (figure~\ref{fig:motion51}).
2067
2068 \begin{figure}[htpb]
2069     \centering
2070     \includegraphics[width=0.9\linewidth]{motion51.png}
2071     \caption{Motion51 plugin window with its default options set.}
2072     \label{fig:motion51}
2073 \end{figure}
2074
2075 The Samples box at the top is most often the only parameter that you may want to vary.
2076
2077 \subsubsection*{Program Parameters Description follows}
2078 \label{ssub:program_parameters_description}
2079
2080 \begin{description}
2081     \item[X11-OpenGL:] setting can speed up the computation significantly in some cases when hardware OpenGL is available.
2082     \item[Samples:] is the number of pixels which the software will examine to stabilize the picture. The sample set is arranged in 4 equal concentric circular sets. Each sample dot represents content and position for a pattern matching test. Setting the samples to larger values improves the match by adding lots of placement possibilities. The samples/pixels that will be utilized are distributed throughout the selected area -- this is seen within the circles drawn when Draw Vectors is enabled. See figure~\ref{fig:motion51}.
2083     \item[Draw vectors:] demonstrates the search operation of motion stabilization. When enabled, the outer search boundary (oval), the search grid area (rectangle), and the reference sample (circles) are visible. 4 concentric circles show the reference sample set (target). You will also see an arrow in the center of the circle which shows each image displacement from frame to frame. When you render the video using the motion plugin, these dots/lines/circles are drawn into the rendered output. Draw vectors helps to visualize the meaning of the parameters to aid in setup. You should disable Draw Vectors before the final rendering.
2084     \item[Sample Radius:] is the radius of a circle that denotes the area of the sample locations. It is expressed as a percentage of the smallest image edge. For example, if it is set to $50\%$, then the circle will overlap about $\frac{1}{2}$ of the image. This does not change the number of samples. It does change the area from where the samples are gathered. If you have Draw vectors on, you can see the faint outline of a circle used for the radius.
2085     \item[Center X/Y:] is the center position of the sample circle, as a percentage of image width and height.
2086     This is useful to reset the reference focal point in cases where the important feature target is off-center.
2087     When both $X$ and $Y$ are set to $50\%$, the samples will be used from around the center of the video.
2088     \item[Search W/H:] determines the width and height of the rectangular area used for the grid pattern search. Samples are taken by moving the center of the circles in a grid pattern.
2089     \item[Horiz/Vert shake limit:] (Shaking refers to image translation) determines translation constraints. If the motion determined by the search exceeds the limit, it is clipped to a value that is at the limit boundary. For example, if the match indicates that the motion is $60\%$ off the reference target, but the limit is $50\%$, then the actual translation used will be limited to only $50\%$.
2090     \item[Shake fade:] determines how fast the translation cancellation fades away, and the image resettles to its actual appearance. Every frame that is processed accumulates the motion of the past. The amount of the past motion which is applied is reduced by the fading factor. The current match is then added to the fading past motion history. Fading works fast. It is applied every frame. So if fade is $10\%$, and no new motion occurs in the input, the history will be $90\%, 81\%, 73\%, 66\%\dots$ and in $30$ frames only $4.2\%$ of the past motion will be present in the effect. Fading insures that the image will eventually settle re-centered when the image motion ends.
2091     \item[Twist limit:] (Twisting refers to image rotation) determines the rotation constraints. If the rotation determined by the search exceeds the limit, it is clipped to the limit boundary. Its operation is similar to the shake limits.
2092     \item[Twist fade:] determines how fast the rotation cancellation fades away, and the image resettles to its actual appearance. Its operation is similar to the shake fade.
2093     \item[Enable Tracking:] caches the search results in a file so that subsequent playback does not have to be recalculated. When tracking is enabled, before a frame is processed the frame number is used to look for cached results. If cache data is available, it is used. If no data is available, the frame is processed by the motion tracking search, and the results are added to the cache file. If tracking is not enabled, the data is always sourced from the motion tracking search and the tracking file is not updated.
2094     \item[Tracking file:] is the name of the file which will contain the calculated values to be saved. Note that the default is \texttt{/tmp/motion51} which can be hazardous, since a system crash or a reboot can delete \texttt{/tmp} files.
2095     \item[Reset Defaults:] button is used to revert to the initial defaults built into the program.
2096     \item[Reset Tracking:] will delete the current Tracking file and disables tracking so that any previously calculated values are no longer available. However, because motion stabilization can often be cpu intensive, if the default file already exists, it will create a file name from the loaded asset.
2097     \item[Play Every Frame:] shows if you are Currently using: Play every frame. For best results, set play every frame. This can be set in \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Playback A} Tab in the \textit{Video out} section.
2098 \end{description}
2099
2100 \subsection{Motion}%
2101 \label{sub:motion}
2102 \index{Motion}
2103
2104 The \textit{motion tracker} is almost a complete application in itself. The motion tracker tracks two types of motion: \textit{translation} and \textit{rotation}. It can track both simultaneously or one only. It can do $\frac{1}{4}$ pixel tracking or single pixel tracking. It can stabilize motion or cause one track to follow the motion of another track. Although the motion tracker is applied as a realtime effect, it usually must be rendered to see useful results. The effect takes a long time to precisely detect motion so it is very slow.
2105
2106 Motion tracker works by using one region of the frame as the region to track (Match Box). It compares this region between $2$ frames to calculate the motion. This region can be defined anywhere on the screen. Once the motion between $2$ frames has been calculated, a number of things can be done with that \textit{motion vector}. It can be scaled by a user value and clamped to a maximum range. It can be thrown away or accumulated with all the motion vectors leading up to the current position.
2107
2108 To save time the motion result can be saved in a file for later reuse, recalled from a previous calculation, or discarded. The motion tracker has a notion of $2$ tracks, the \textit{master} layer and the \textit{target} layer. The \textit{master} layer is where the comparison between $2$ frames takes place. The \textit{target} layer is where motion is applied either to track or compensate for the motion in the \textit{master} layer (figure~\ref{fig:motion}).
2109
2110 \begin{figure}[ht]
2111         \centering
2112         \includegraphics[width=0.9\linewidth]{motion.png}
2113         \caption{Motion plugin GUI}
2114         \label{fig:motion}
2115 \end{figure}
2116
2117 Motion tracking parameters:
2118
2119 \begin{description}
2120     \item[Track translation] Enables translation operations. The motion tracker tracks $X$ and $Y$ motion in the \textit{master} layer and adjusts $X$ and $Y$ motion in the \textit{target} layer.
2121
2122     \item[Translation block size] For the translation operations, a block is compared to a number of neighboring blocks to find the one with the least difference. The size of the Match Box to search for is given by this parameter.
2123     \item[Translation search radius] The size of the area to scan for the translation block.
2124     \item[Translation search steps] Ideally the search operation would compare the translation block with every other pixel in the \textit{Translation search radius}. To speed this operation up, a subset of the total positions is searched. Then the search area is narrowed and re-scanned by the same number of search steps until the motion is known to $\frac{1}{4}$ pixel accuracy.
2125     \item[Translation direction] Tracking translation is possible in any direction, or in horizontal or vertical direction only, depending on this selection.
2126     \item[Block X, Y] These coordinates determine the center of the translation block based on percentages of the width and height of the image. The center of the block should be part of the image which is visible at all times.
2127     \item[Maximum absolute offset] The amount of motion detected by the motion tracker is unlimited if this is $100$. If it is under $100$ the amount of motion is limited by that percentage of the image size.
2128     \item[Motion settling speed] The motion detected between every frame can be accumulated to form an absolute motion vector. Settling speed determines how fast the accumulated translation fades away, and the image resettles to its actual appearance. If the settling speed is 0\% the total absolute vector is added to the next frame. So every frame that is processed accumulates the whole motion of the past. If the settling speed is 100\% the absolute vector is cancelled completely, adding no past translation to the next frame. If the settling speed is intermediate between 0\% and 100\% the absolute vector is downscaled by (100 $-$ settling amount) before being added to the next frame.
2129     \item[Track rotation] Enables rotation operations. The motion tracker tracks rotation in the \textit{master} layer and adjusts rotation in the \textit{target} layer.    
2130     \item[Rotation search radius] This is the maximum angle of rotation from the starting frame the rotation scanner can detect. The rotation scan is from this angle counterclockwise to this angle clockwise. Thus the \textit{Rotation search radius} is half the total range scanned.
2131     \item[Rotation search steps] Ideally every possible angle would be tested to get the rotation. To speed up the rotation search, the \textit{Rotation search radius} is divided into a finite number of angles and only those angles compared to the starting frame. Then the search radius is narrowed and an equal number of angles is compared in the smaller radius until the highest possible accuracy is achieved. Normally you need one search step for every degree scanned. Since the rotation scanner scans the \textit{Rotation search radius} in two directions, you need two steps for every degree in the search radius to search the complete range.
2132     \item[Rotation center] Usually this parameter is zero, and the rotation search
2133     range is $+/-$ \textit{Rotation search radius}.  Otherwise, it shifts the rotation search range to the area of angles between (\textit{Rotation center} $-$ \textit{Rotation search radius}) and (\textit{Rotation center} $+$ \textit{Rotation search radius}).
2134     \item[Maximum angle offset] The total accumulated amount of rotation is unlimited
2135     if this is 90 degrees.  If it is under 90, the total amount of rotation is
2136     limited by the given maximum angle.
2137     \item[Rotation settling speed] This parameter determines how fast the accumulated
2138     rotation fades away.  Analogously to the \textit{Motion settling speed}, if it is 0\%,
2139     the total accumulated rotation is added to the next frame, and every frame
2140     accumulates the whole rotation of the past.  If the settling speed is 100\%,
2141     no past rotation is added to the next frame.  If the settling speed is
2142     intermediate between 0\% and 100\%, the amount of accumulated rotation is
2143     downscaled by (100 $-$ settling amount) before being added to the next frame.
2144     \item[Motion noise level] This parameter allows to compensate such undesirable
2145     behavior when motion tracker wildly springs away because some outlying area
2146     of a noisy picture becomes accidentally more "similar" to the reference
2147     picture than the right one.  If noise level is set to 0\% (its normal value),
2148     then it is not taken into account at all.  When it is set to 100\%, then
2149     similarity of the match block contents is totally ignored, and the current
2150     motion vector will be zero.  An intermediate value between 0\% and 100\%
2151     defines the proportional noise level between minimum and maximum difference
2152     of all examined match block positions.  From all such positions whose
2153     difference is found below noise level, that one is chosen which has the
2154     shortest translation relative to the reference frame.
2155     \item[Rotation noise level] This parameter has similar meaning to the \textit{Motion noise level}.  It influences rotation tracking.  If set to 0\% (its normal value),
2156     it is not taken into account.  The 100\% setting completely suppresses
2157     rotation detection.  An intermediate value between 0\% and 100\% defines the
2158     proportional noise level between minimum and maximum difference of all
2159     examined rotated match blocks from that of the reference picture.  From all
2160     rotation angles whose match block differences are found below noise level,
2161     that one is chosen which has the minimum rotation angle relative to the
2162     reference frame.    
2163     \item[Draw vectors] When translation is enabled, $2$ boxes are drawn on the frame. One box represents the translation block. Another box outside the translation block represents the extent of the \textit{Translation search radius}. In the center of these boxes is an arrow showing the translation between the $2$ master frames. When rotation is enabled, a single box the size of the rotation block is drawn rotated by the amount of rotation detected.
2164     \item[Two pass tracking] Although this parameter can be enabled at any time, it is useful only while simultaneous tracking both translation and rotation, when
2165     the rotation amount is large.  The normal tracking algorithm firstly
2166     examines translation, then rotation.  However, comparison of a strongly
2167     tilted picture with the reference one can lead to rather inaccurate
2168     determination of the translation vector.  The subsequent determination of
2169     rotation will be also inexact because of the preceding translation error.  The
2170     second tracking pass, if enabled, refines translation and rotation.
2171     
2172     If motion and/or rotation noise level is set above 0\% and \textit{Two pass tracking}
2173     is enabled, then both noise levels affect the first tracking pass only.
2174     During the second tracking pass of two pass tracking both noise levels are
2175     ignored.
2176     
2177     It should be noted that two pass tracking is not twice slower than the usual
2178     single pass tracking.  Actually it is only about 40\% slower.  As the second
2179     pass serves only for motion refinement, it starts from the reduced search
2180     range for block positions and rotation angles.  And, as the first pass only
2181     yields an approximate position, which will be later refined during the
2182     second pass, it skips subpixel position search and examines rotation angles
2183     with the accuracy reduced to 1 degree.
2184     \item[Track single frame] When this option is used the motion between a single
2185     starting frame and the frame currently under the insertion point is
2186     calculated.  The starting frame is specified in the \textit{Frame number} box.  The
2187     motion calculated this way is taken as the absolute motion vector.  The
2188     absolute motion vector for each frame replaces the absolute motion vector
2189     for the previous frame.  \textit{Settling speed} has no effect on it since it does
2190     not contain any previous motion vectors.  Playback can start anywhere on the
2191     timeline since there is no dependence on previous results.  We talk about
2192     \textit{Keep shape} and it is the most precise way to calculate the motion vector;
2193     but it only works well when the object to be traced does not change along
2194     the clip, remaining identical in shape, size and luminance.
2195     
2196     Strong rotation of the picture can also have a bad impact on the tracking
2197     accuracy.  If it is the case, accuracy can be significantly improved by
2198     enabling \textit{Two pass tracking}.
2199     
2200     \item[Frame number] The number of the reference frame used for motion tracking in
2201     the \textit{Track single frame} mode is specified in this input field.  Frame
2202     number is set as the 0-based absolute number starting from the very
2203     beginning of the whole timeline.  Instead of manual calculating, it is
2204     possible to get \textit{Frame number} directly from the current cursor position by
2205     pressing the \textit{Get current} button.
2206     
2207     \item[Get current] Pressing this handy button provides a convenient way to set the
2208     \textit{Frame number} parameter to the value of the current cursor position.
2209     
2210     \item[Add (loaded) offset from tracked frame] This toggle can help when the tracked
2211     object changes shape, leaves the screen area or becomes obscured by other
2212     objects somewhere in the middle of the \textit{Motion} effect.  Sometimes it can help
2213     also if a strong rotation causes the motion tracker to miss the right
2214     tracked object and wildly spring away.
2215     
2216     To overcome this problem, one has to define two keyframes: the first one at
2217     the start of the \textit{Motion} effect, the second shortly before the problematic
2218     location in the clip.  At the first keyframe one defines the \textit{Motion} effect
2219     parameters as usual, the \textit{Add offset} toggle being switched off.  At the
2220     second keyframe the match block can be redefined to cover another region of
2221     the picture which remains visible during the following part of the effect.
2222     The \textit{Frame number} parameter should be set several frames before position of this second keyframe, and the \textit{Add offset} toggle switched on.
2223     
2224     After defining the two keyframes (even more can be added in the similar way)
2225     one switches at all the defined keyframes \textit{Calculation} mode to \textit{Save coords
2226     to tracking file}, \textit{Action} mode to \textit{Do Nothing}, rewinds the timeline cursor
2227     to the beginning of the \textit{Motion} effect, and starts playback.  The determined
2228     motion vectors will be written to the tracking file, the \textit{Add offset}
2229     parameter having no effect during the \textit{save} stage.
2230     
2231     After playback finishes and all the relevant motion vectors are saved in the
2232     tracking file, one switches at all the defined keyframes \textit{Calculation} mode to
2233     \textit{Load coords from tracking file}, \textit{Action} mode to whatever one needs, rewinds again to the beginning of the \textit{Motion} effect and starts playback or
2234     rendering.  After reaching the second keyframe, where \textit{Add offset} was
2235     switched on, the program continues to follow the second object adding the
2236     total motion and rotation, accumulated so far.
2237     
2238     Of course, the \textit{Add offset} toggle can be used in the \textit{Track single frame} mode only.  In the other tracking modi such a technics is unnecessary.
2239     \item[Track previous frame] Causes only the motion between the previous frame and
2240     the current frame to be calculated (\textit{Follow shape}).  This is added to an
2241     absolute motion vector to get the new motion from the start of the sequence
2242     to the current position.  After every frame processed this way, the block
2243     position is shifted to always cover the same region of the image.  Playback
2244     must be started from the start of the \textit{Motion} effect in order to accumulate
2245     all the necessary motion vectors.  This method is less precise because you
2246     have error propagation between frames.  However, it is essential when the
2247     object changes shape, size or luminance.  Possible inaccuracies caused by
2248     rotation of the picture can partly be reduced by enabling \textit{Two pass tracking}
2249     \item[Previous frame same block] This is useful for stabilizing jerky camcorder footage. In this mode the motion between the previous frame and the current frame is calculated. Instead of adjusting the block position to reflect the new location of the image, like \textit{Track Previous Frame} does, the block position is unchanged between each frame. Thus a new region is compared for each frame.
2250     \item[Master layer] This determines the track which supplies the frames for the
2251     motion calculation.  If it is \textit{Bottom} the bottom track of all the tracks
2252     sharing this effect is the \textit{master} layer.  Then the top track of all the
2253     tracks is the \textit{target} layer.  And vice versa, if the \textit{master} layer is \textit{Top},
2254     then the \textit{target} layer is bottom.
2255     \item[Calculation] This determines whether to calculate the motion at all and
2256     whether to save it to disk.  If it is \textit{Don't Calculate} the motion calculation is skipped.  If it is \textit{Recalculate} the motion calculation is performed every  time each frame is rendered.  If it is \textit{Load coords from tracking file}, the motion vectors are loaded  from a previous \textit{save} calculation.  If the previous \textit{save} calculation does not provide the data for the currently processed frames, a new motion  calculation is performed for that frames.  If \textit{Calculation} mode is \textit{Save coords to tracking file} the motion vectors can be still loaded from disk if the previously
2257     calculated data exist.  Otherwise, a new motion calculation is performed,
2258     and the calculated motion vectors are saved.
2259     \item[Tracking file] This parameter determines the name of the file where the
2260     motion data are saved and/or loaded from.  By default it is \texttt{/tmp/motion}
2261     but it can have any name and reside anywhere on the disk.  \textit{Tracking file} is
2262     a text file where each line contains four numbers: the absolute frame number
2263     (0-based integer), the X and Y translation displacements of subpixel
2264     precision (a subpixel is $\frac{1}{4}$ pixel in size, and to give integer values of X and Y these subpixel coords are multiplied by 4), and the rotation angle in
2265     degrees (as a floating point value).  The user may have different tracking
2266     files for different timeline regions, it is possible to do any manipulations
2267     on them if necessary and even manually edit in a text editor.
2268     \item[Generate tracking file name] This handy pushbutton suggests a tracking file
2269     name based on the name of the current asset.  It helps to maintain more
2270     different tracking files with unique but predictable names used in the same
2271     project.  When tracking file name is changed (either via the pushbutton or
2272     after entering it in the corresponding input field), the contents of that
2273     files (both the old and the new ones) remains unchanged.
2274     \item[Clear tracking file contents] The values and meaning of the saved motion data depend on such a bunch of parameters, they can be even edited manually, so
2275     one can hardly predict whether the outdated motion vectors are to be reset
2276     or left untouched.  Therefore the existing motion data are never altered
2277     implicitly (only newly calculated data may be added).  And, should the user
2278     need to reset them here and right now, it is possible to clear the given
2279     tracking file contents explicitly by pressing this pushbutton.
2280     
2281     As protection against accident clearing tracking file contents, right before
2282     clearing the program ensures closing the current tracking file and renames
2283     it to the same name with the suffix \texttt{.old}.  This way, the user can undo an erroneous clearing action by manual restoring the saved file.
2284     \item[Action] Once the motion vector is known this determines whether to move the \textit{target} layer opposing the motion vector or following the motion vector. If it is \textit{Do Nothing} the \textit{target} layer is untouched. If it is \textit{Track\dots} the \textit{target} layer is moved by the same amount as the \textit{master} layer. This is useful for matching titles to objects in the frame. If it is \textit{Stabilize\dots} the \textit{target} layer is moved opposite to the motion vector. This is useful for stabilizing an object in the frame. The \textit{Motion} operations can be accurate to single pixels or subpixels by changing the \textit{Action} setting.
2285 \end{description}
2286
2287 As motion tracking works consistently only in the \textit{Play every frame} mode,
2288 the corresponding info on the current playback mode is shown in the bottom
2289 right edge of the effect dialog.  The needed playback mode is defined in the
2290 Preferences dialog of \CGG{} main window.
2291
2292 \subsubsection*{Secrets of motion tracking}
2293 \label{ssub:secrets_motion_tracking}
2294
2295 Since it is a very slow effect, there is a method to applying the motion tracker to get the most out of it. First disable playback for the track to do motion tracking on. Then drop the effect on a region of video with some motion to track. Then rewind the insertion point to the start of the region. Set \textit{Action $\rightarrow$ Do Nothing}; set \textit{Calculation $\rightarrow$ Don't calculate}; enable \textit{Draw vectors}. Then enable playback of the track to see the motion tracking areas.
2296
2297 Enable which of translation motion or rotation motion vectors you want to track. By watching the compositor window and adjusting the \textit{Block X, Y} settings, center the block on the part of the image you want to track. It is advisable to choose elements that have evident edges in the $x$ and $y$ directions because the calculations are made on these coordinates. Then set \textit{search radius}, \textit{block size} and \textit{block coordinates} for translation and rotation.
2298
2299 Once this is configured, set \textit{Calculation} to \textit{Save coords} and do test runs through the sequence to see if the motion tracker works and to save the motion vectors. Next, disable \textit{Draw vectors}, set the motion \textit{Action} to perform on the \textit{target} layer and change \textit{Calculation} to \textit{Load coords}.
2300
2301 When using a single starting frame to calculate the motion of a sequence (\textit{Keep Shape}), the starting frame should be a single frame with the least motion to any of the other frames. This is rarely frame $0$. Usually it is a frame near the middle of the sequence. This way the search radius need only reach halfway to the full extent of the motion in the sequence. The suitable reference frame number can be defined conveniently via the \textit{Get current} pushbutton.
2302
2303 Summarizing:
2304
2305 \begin{enumerate}
2306         \item In the Master Layer create and save the tracking file:
2307         \begin{itemize}
2308                 \item \textit{Draw vectors}: checked
2309                 \item \textit{Action}: Do Nothing
2310                 \item \textit{Calculation}: Save coords to Tracking File
2311         \end{itemize}
2312         \item Clone the track, which becomes the Target Layer. The \textit{Motion} plugin will also be copied.
2313                 \begin{itemize}
2314                         \item \textit{Draw vectors}: unchecked
2315                         \item \textit{Action}: Do Nothing
2316                         \item \textit{Calculation}: Load coords from Tracking File
2317                 \end{itemize}
2318         \item Add a third track to place the video of the object to be superimposed. Add the shared effects of the \textit{Motion} plugin taken from the Master Layer.
2319                 \begin{itemize}
2320                         \item \textit{Draw vectors}: unchecked
2321                         \item \textit{Action}: Track Subpixel
2322                         \item \textit{Calculation}: Load coords from Tracking File
2323                 \end{itemize}
2324 \end{enumerate}
2325
2326 If the motion tracker is used on a render farm, \textit{Save coords} and \textit{Previous frame} mode will not work. The results of the \textit{Save coords} operation are saved to the hard drives on the render nodes, not the master node. Future rendering operations on these nodes will process different frames and read the wrong coordinates from the node filesystems. The fact that render nodes only visualize a portion of the timeline also prevents \textit{Previous frame} from working since it depends on calculating an absolute motion vector starting on frame $0$.
2327
2328 \subsubsection*{2 step motion tracking}
2329 \label{ssub:2_step_motion_tracking}
2330
2331 The method described above is \textit{two-step motion tracking}. One step is used just to calculate the motion vectors. A second step is used to apply the motion vectors to the footage. This is faster than a single pass because errors in the motion vector calculation can be discovered quickly. This also allows the motion tracking to use a less demanding colormodel like \textit{RGB888} in the scanning step and a more demanding colormodel like \textit{RGB Float} in the action step. The scanning step takes much longer than action. This has the disadvantage of not being practical for extremely long sequences where some error is acceptable and the picture quality is low to begin with, like stabilizing camcorder footage.
2332
2333 The slower method is to calculate the motion vectors and apply them simultaneously. This method can use one track as the motion vector calculation track and another track as the target track for motion vector actions. This is useful for long sequences where some error is acceptable.
2334
2335 \subsubsection*{Pre-processing the shot}
2336 \label{ssub:pre_processing_shot}
2337
2338 \begin{enumerate}
2339     \item The \textit{Motion} plugin uses \textit{luminance} to do its own calculations, so we can edit the clip to enhance contrast and make it easier to calculate motion vectors. You can even create a copy of the monochrome clip and optimize it for the plugin. It lengthens the time but minimizes errors. The saved file can then be used for the original clip.
2340     \item  Correct lens distortion, especially if the object to be tracked moves to the edges of the frame.
2341     \item Study the entire shot well: if necessary, divide it into many edits, each with its own \textit{Motion} plugin. For example, if the object to be tracked leaves the frame or is covered by some other element or changes in shape, size or rotation. You can try to use the \textit{Offset Tracking} technique described below.
2342 \end{enumerate}
2343
2344 \subsubsection*{Using blur to improve motion tracking}
2345 \label{ssub:blur_improve_motion_tracking}
2346
2347 With extremely noisy or interlaced footage, applying a blur effect before the motion tracking can improve accuracy. Either save the motion vectors in a tracking pass and disable the blur for the action pass or apply the blur just to the \textit{master} layer. You can even use a copy of the track formed only by the channels of Red + Green, because the channel of Blue is the noisiest. Another trick is to enlarge the Match Box to minimize the effect of noise.
2348
2349 \subsubsection*{Using histogram to improve motion tracking}
2350 \label{ssub:histogram_improve_motion_tracking}
2351
2352 A histogram is almost always applied before motion tracking to clamp out noise in the darker pixels. Either save the motion vectors in a tracking pass and disable the histogram for the action pass or apply the histogram just to the \textit{master} layer. Finally, you can use the histogram to increase contrast.
2353
2354 \subsubsection*{Using two pass tracking to improve accuracy and stability}
2355 \label{ssub:two_pass_improve_accuracy}
2356
2357 A common source of inaccuracy when tracking single frame is rotation of the
2358 picture.  Ideally, the motion vectors should be determined by checking all
2359 possible rotation angles at every possible match block location.  But such
2360 an algorithm would be unacceptably slow.  Therefore the program finds for
2361 each frame the translation vector first, and then the rotation angle.  A
2362 strong rotation can prevent motion tracker from finding accurate translation
2363 displacements.  Then the subsequent rotation search will be also inaccurate
2364 because translation has been estimated not sufficiently well.  In the \textit{Two
2365 pass tracking} algorithm the first, coarse estimation of translation and
2366 rotation is followed by the second, refinement pass yielding more exact
2367 motion vectors.
2368
2369 Sometimes, particularly if the amount of rotation is large, the translation
2370 tracker can lose its right object and wildly spring away.  Then the
2371 following strategy may help.
2372
2373 Firstly switch \textit{Two pass tracking} off, \textit{Track rotation} off, set \textit{Motion noise level} to zero.  Switch \textit{Draw vectors} on, \textit{Action: Do Nothing}, \textit{Calculation: Save coords to tracking file}.  Start playback and watch if the motion tracker has problems finding the right displacements (you can also examine the tracking file afterwards on the existence of discontinuities in coordinates).  If there are such, try to increase \textit{Motion noise level}, let's say, to 10\% or 20\%, \textit{clear tracking file contents}, repeat playback and look if tracker does not spring away any more.  A single pass translation tracking can be relatively fast, while tracking rotation is expensive.
2374
2375 When a sufficient motion noise level is found, switch \textit{Track rotation} on, \textit{Two
2376 pass tracking} on, \textit{clear tracking file contents} and perform the complete
2377 translation + rotation tracking pass.  As the refinement pass uses
2378 restricted search area and ignores the noise level parameters, the result
2379 should be more stable and accurate.
2380
2381 \subsubsection*{Possible sources of errors}
2382 \label{ssub:possible_sources_errors}
2383
2384 \begin{description}
2385     \item[Search radius too small:] the traced object moves too fast with respect to the size of the search box set.
2386     \item[Search radius too large:] The search box is so large that it also collects other similar items in the frame.
2387     \item[Occlusions:] the traced object is temporarily hidden by some other element. \textit{Offset tracking} or splitting of the video into several homogeneous clips is required.
2388     \item[Focus change:] you may get errors if the object changes its focus. The video must be divided into several homogeneous clips.
2389     \item[Motion Blur:] blurs the object making the calculation of the motion vector less precise. Very little can be done.
2390     \item[Shape change:] you can use \textit{Track previous frame} or the subdivision of the video in more homogeneous clips.
2391     \item[Lighting change:] Contrast change can produce errors. \textit{Track previous frame} or color correction can be used to return to the initial illumination.
2392 \end{description}
2393
2394 \subsubsection*{Tracking stabilization in action}
2395 \label{ssub:tracking_stabilization_action}
2396
2397 This is an explanation of how to stabilize a video as in the case of a video taken from a vehicle.
2398
2399 First select on the timeline the part of the footage you want to stabilize, using the in and out points. Then apply the \textit{Motion} effect on that part of the video. Select the \textit{Previous frame same block} option. That option is recommended for stabilizing jerky camcorder footage. Its goal is not to \textit{follow} an object. The block stays exactly at the same place during all the effect length.
2400
2401 Enlarge the block and select almost half the size of the video. Select the \textit{Stabilize subpixel} option as it will give a finer stabilization. Reduce the \textit{Maximum absolute offset} value to limit the stabilization amplitude. You probably prefer to get a non-perfect stabilization on some places on the video rather than having a very large black border on one side of the picture during big shakes. Set the \textit{Translation search steps} value to $128$. Increasing that value will not give a better result and only considerably increases the rendering time. Make sure the \textit{Draw vectors} option is selected, and render the part of the video where the \textit{Motion} effect is applied.
2402
2403 If the result is good, deselect the \textit{Draw vectors} option so that the block and vectors are not drawn anymore on the video. Then, render your video to a \texttt{.dv} file, and import it into your project. You will notice the video is stabilized but there are black borders which appear on sides of the frame. You have to \textit{zoom in} and define projector keyframes to move the projector around the screen, in order to remove those black borders. The more your footage is jerky, the more you have to zoom in to discard the black borders. That is why the result is better with HDV footage than with DV footage.
2404
2405 An interesting side note about \textit{Add offset} usage is explained next\protect\footnote{credit Pierre Marc Dumuid}
2406
2407 To stabilize video, the \textit{Motion} plugin uses a \textit{tracking frame} to which to track to and a region within that frame to track (generally an object in the background) in the current frame.  When the region is obscured, often by something in the foreground or by leaving the screen, then the motion compensation would fail, and the video jumps all over the place.
2408
2409 You set a second region to track, and then \textit{add offset}.
2410
2411 This shows how it is used.  It works very well:
2412
2413 \begin{verbatim}
2414 ------k-------k-----------------
2415 ^      ^^
2416 A      BC
2417
2418 A - object1 is visible in the background up until C
2419 B - (the frame before C) has both object1 and object2 visible
2420 C - has only object2 visible
2421 \end{verbatim}
2422
2423 \begin{enumerate}
2424     \item Make a keyframe and set to track object1.
2425     \item Make a keyframe at C and track frame at B, set to track object2.
2426     \item Set keyframe at C to add offsets that were calculated at B.
2427 \end{enumerate}
2428
2429 \subsubsection*{Tips}
2430 \label{ssub:tips}
2431
2432 \begin{enumerate}
2433     \item The motion vector is a text file located in \texttt{/tmp}. We can open it with a plain editor and modify the wrong $X\,Y$ coordinates, i.e.\ those that deviate from the linearity, to correct the errors that always happen when we perform a motion tracking (jumps). It can be a long and tedious job, but it leads to good results.
2434     \item You can try tracking using reverse playback of the track. Sometimes it may lead to a better calculation.
2435 \end{enumerate}
2436
2437 \subsection{Motion 2 Point}%
2438 \label{sub:motion_2_point}
2439 \index{Motion 2 Point}
2440
2441 Motion plugin using 2 \textit{Match box} for tracking. For theory and explanations refer to the \hyperref[sub:motion]{Motion} plugin.
2442
2443 \subsection{Motion Blur}%
2444 \label{sub:motion_blur}
2445 \index{Motion Blur}
2446
2447 Uses X/Y camera automation vectors to apply a linear blur trailing camera direction due to movement.
2448 \begin{description}
2449     \item[Length] distance between original image and final blur step; corresponds to the distance of the fields.
2450     \item[Steps] number of blur steps to be used in the calculation. Increasing the number takes more CPU.
2451 \end{description}
2452
2453 \subsection{Oil painting}%
2454 \label{sub:oil_painting}
2455 \index{oil painting}
2456
2457 This effect makes video tracks appears as a painting. It can be controlled by \textit{Radius} slider and \textit{intensity of colors} can be chosen as an option.
2458
2459 % Leave the Video and Audio parenthesis due to latex2html dual conflict
2460 \subsection{Overlay (Video)}%
2461 \label{sub:overlay}
2462 \index{overlay video}
2463
2464 This effect can combine several tracks by using the so called Overlayer. This is a basic internal device normally used by \CGGI{} to create the dissolve transitions and for compositing the final output of every track onto the output bitmap. The Overlayer has the ability to combine one or several image layers on top of a bottom layer. It can do this combining of images in several different (and switchable) output modes such as \textit{Normal}, \textit{Additive}, \textit{Subtractive}, \textit{Multiply} (Filter), \textit{Divide}, \textit{Max} and \textit{Replace}. For a detailed list refer to the on \hyperref[cha:overlays]{Overlays} chapter  -- PorterDuff.
2465
2466 The \textit{overlay} plugin enables the use of this Overlayer device in the middle of any plugin stack, opening endless filtering and processing possibilities. It is only useful as a \textit{shared plugin} (i.e.\ a multitrack plugin). To use the overlay plugin:
2467
2468 \begin{enumerate}
2469     \item Add the effect to Track A.
2470     \item Choose \textit{attach effect} from the context menu of another track (Track B).
2471     \item Choose Track A: Overlay as a shared plugin.
2472     \item Manipulate the plugin parameters in Track A.
2473 \end{enumerate}
2474
2475 \subsection{Perspective}%
2476 \label{sub:perspective}
2477 \index{perspective}
2478
2479 The \textit{perspective} plugin (aka Corner Pinning) allows you to change the perspective of an object and is used to make objects appear as if they are fading into the distance. Basically, you can get a different view. A transformation is used which preserves points, lines, and planes as well as ratios of distances between points lying on a straight line.
2480
2481 In (figure~\ref{fig:perspective}) you can see that there are four options for the endpoints used for the edges.
2482
2483 \begin{figure}[htpb]
2484     \centering
2485     \includegraphics[width=0.5\linewidth]{perspective.png}
2486     \caption{perspective control window}
2487     \label{fig:perspective}
2488 \end{figure}
2489
2490 \begin{description}
2491     \item[Default] if OpenGL is being used with your graphics card, this will be the option in effect. If no OpenGL, then it will be Cubic.
2492     \item[Nearest] using software, nearest neighbor can look step-py.
2493     \item[Linear] software implementation of a linear algorithm.
2494     \item[Cubic] smoothest looking on the
2495     edges and considered the best.
2496 \end{description}
2497
2498 Key Presses for using the Perspective plugin:
2499
2500 \begin{tabular}{l l}
2501     \toprule
2502     Left mouse button & drags the corner that is closest to current location \\
2503     Alt key + left mouse & translates the perspective; drags the whole image \\
2504     Shift key + left mouse & zooms the perspective \\
2505     Alt+Shift + left mouse & translates view but does not change output \\
2506     \bottomrule
2507 \end{tabular}
2508
2509 Note that the red color lines in the box show the composer boundary.
2510
2511 In order to see endpoints that go off the screen, you can use the zoom slider which changes only the zoom view and does nothing else. The slider uses a logarithmic scale ranging from $\frac{1}{100} to 100$.  Although not shown in the 
2512 image here, each endpoint is labeled in yellow with 1-4 and the Current X
2513 endpoint is shown in the menu to make it easier to tell which point is in play.
2514
2515 Figure~\ref{fig:perspective01} show the results of the 4 different smoothing options.
2516
2517 \begin{figure}[hbtp]
2518     \centering
2519     \includegraphics[width=0.8\linewidth]{perspective01.png}
2520     \caption{Clockwise: Nearest; Linear; OpenGL and Cubic}
2521     \label{fig:perspective01}
2522 \end{figure}
2523
2524 Just a side note about the possibility of ending up with a divide by 0 case when manipulating
2525 the endpoints.  Sometimes this results in a single frame anomaly but you can workaround this
2526 by setting the X value for the middle keyframe of a series to just a little more than 0,
2527 such as .01 so that dividing by 0 is avoided. The actual cause of the problem is that the
2528 interpolated X1..X4 auto coordinates used by perspective eventually have x1==x2, x3==x4, so
2529 that all points x are scaled by zero. Another solution is to tweak the frame count to an even
2530 number, so that the center is not over the point where x1==x2, x3==x4, or perturb the midpoint
2531 position a little so that the answers are not exactly zero.
2532
2533 \subsection{Polar}%
2534 \label{sub:polar}
2535 \index{polar}
2536
2537 The \textit{Polar} effect bends and warps your video in weird ways. Mathematically, it converts your video from either \textit{polar} coordinates to \textit{rectangular} coordinates, or the reverse. With the Clear buttons we can bring the slider to default values without affecting the other parameters.
2538
2539 \subsection{RGB-601}%
2540 \label{sub:rgb-601}
2541 \index{rgb-601}
2542
2543 For analog video or MPEG (including DVD) output, the maximum range for R,G,B is $[16,235]$ ($8\,bit$). For YUV, the maximum range for intensity (\textit{Y}) is $[16, 235]$ ($8\,bit$). This range corresponds to gray levels from $6\%$ to $92\%$. When rendering, values outside of these ranges will be clipped to these limits.
2544
2545 To render to MPEG, add the \textit{RGB-601} effect to all video tracks where material uses the full intensity scale ($0-100\%$), and enable \textit{RGB$\rightarrow$601} compression. Consider adding the \textit{Videoscope} effect after RGB-601 to see how RGB-601 affects your dynamic range. To preview how your rendered MPEG would look without \textit{RGB$\rightarrow$601} compression, instead enable \textit{601$\rightarrow$RGB} expansion and you will observe a noticeable contrast increase. Although RGB-601 will reduce contrast in your video tracks, the contrast will be restored during MPEG playback.
2546
2547 \subsection{RGBShift}%
2548 \label{sub:rgb-shift}
2549 \index{rgb shift}
2550
2551 Most cameras take the light coming into the lens, and convert that into $3$ sets of numbers, one for Red (R), one for Green (G), and one for Blue (B). Some of the older cameras were composed of $3$ sensors and originally the RGB sensors were on $3$ separate planes and had to be aligned. If they were misaligned in the video, you can use \textit{RGBShift} to get them realigned. To move a specific color up/down, modify the \textit{dy} value using the slider bar in the RGBShift window. To move a color left/right, modify the corresponding \textit{dx} value. Clear buttons are present to reset its slider to default without affecting others. Note that the current values of the RGBShift are maintained in the \texttt{.bcast5} defaults file and will be retained across sessions. If using the YUV color space, you will want to use \textit{YUVShift} instead. Figure~\ref{fig:rgbshift} showing RGB shift before and after.
2552
2553 \begin{figure}[hbtp]
2554     \centering
2555     \includegraphics[width=0.8\linewidth]{rgbshift.png}
2556     \caption{Bad Misaligned color and after color aligned}
2557     \label{fig:rgbshift}
2558 \end{figure}
2559
2560 \subsection{Radial Blur}%
2561 \label{sub:radial_blur}
2562 \index{radial blur}
2563
2564 Radial blur is a \textit{Bokeh} effect that creates a whirlpool which simulates a swirling camera. You can vary the location, type, and quality of the blur.
2565
2566 \begin{figure}[hbtp]
2567         \centering
2568         \includegraphics[width=0.8\linewidth]{radial.png}
2569         \caption{For clarity of presentation only 2 fields are shown}
2570         \label{fig:radial}
2571 \end{figure}
2572
2573 \begin{description}
2574     \item[X,Y] center of the circle of movement.
2575     \item[Angle] angle of motion in one direction.
2576     \item[Steps] number of blur steps to be used in the calculation; increasing this number uses more CPU.
2577     \item[Clear] to reset its slider to default without affecting others.
2578 \end{description}
2579
2580 Figure~\ref{fig:radial} has the parameters: $Angle=-35$ and $Steps=2$.
2581
2582
2583 \subsection{ReframeRT}%
2584 \label{sub:reframert}
2585 \index{reframeRT}
2586
2587 ReframeRT changes the number of frames in a sequence of video
2588 directly from the timeline. The faster method for getting the same
2589 results as this plugin is to use the \textit{speed curve} which was
2590 a later addition. But if you need very precise results,
2591 \textit{ReframeRT} is most useful. There are two ways to do this,
2592 which can be selected from the checkboxes in the configuration
2593 GUI\@. The first \textit{Stretch} mode changes the number of frames in
2594 the sequence, and therefore its length, but not the framerate. The
2595 \textit{Downsample} mode instead keeps the length of the movie by
2596 varying the framerate.  It is important to understand that the
2597 plugin works by varying the frames, the possible change of
2598 \textit{fps} is only a side effect of the creation of new frames due
2599 to interpolation.
2600
2601 \subsubsection*{Stretch}%
2602 \label{ssub:stretch}
2603 \index{stretch}
2604
2605 Stretch mode multiplies the current frame number of its output by the \textit{scale factor} to arrive at the frame to read from its input. The scaling factor is not entered directly but using a number of \textit{input} frames to be divided by the number of \textit{output} frames.
2606
2607 \vspace{1ex} \texttt{Scale factor (SF) = Input frames / Output frames}
2608
2609 \[\frac{1}{8} \Rightarrow scale\, factor = 0.125 \qquad (slow\, motion)\]
2610
2611 For slow motion we leave 1 for the frames of the input and we increase the number of frames of the output (for example putting 8 for the output we have slow motion $8\times$, with $SF=\frac{1}{8}=0.125$). For fast motion we leave 1 for the output and we increase the number for the input (for example 8 to have $8\times$, with $SF=\frac{8}{1}=8$). Another possibility is to put the frame rate of the media (e.g 120 fps) in the input and the project frame rate in the output (e.g 30 fps) or the opposite.
2612
2613 The stretch mode has the effect of changing the length of output video by the inverse of the scale factor. If the scale factor is greater than $1$, the output will end before the end of the sequence on the timeline. If it is less than $1$, the output will end after the end of the sequence on the timeline. The ReframeRT effect must be lengthened to the necessary length to accommodate the scale factor. Change the length of the effect by clicking on the endpoint of the effect and dragging.
2614
2615 Although stretch mode changes the number of the frames read from its
2616 input, it does not change the framerate of the input. Effects before
2617 ReframeRT assume the same frame rate as ReframeRT\@.  In stretch
2618 mode to create a fast play effect enter a value greater than $1$ to
2619 get accelerated playback.  For a slow motion effect, use ReframeRT
2620 in stretch mode with a value less than $1$.
2621
2622 \textit{Example:} you have a clip that you want to put in slow motion. The clip starts at $33.792\, seconds$ and ends at $39.765$. The clip is $5.973\, seconds$ long. You want to play it at $\frac{4}{10}^{ths}$ normal speed. You divide the clip length by the playback speed ($5.973\div0.4$) to get a final clip length of $14.9325\,seconds$. You create an in point at the start of your clip: $33.792\,seconds$. You put an out point $14.9325\,seconds$ later, at $48.7245\,seconds$ ($33.792 + 14.9325$). You attach a \texttt{ReframeRT} effect, set it to $0.4$ and stretch. You change the out point at $48.7245$ to an in point. You start your next clip after the slow motion effect at the $48.7245$ out point. You can do this without making any calculations by first applying the effect and then lengthening or shortening the bar to where the stretched movie ends.
2623
2624 Now in the timeline we have the affected part of the plugin where we see the slow/fast effect, and the continuation of the timeline from where the plugin ends. We then have to select the interval on which the plugin acts and render it or transform it into a nested clip or nested asset. In this way we can replace or overlap it with the part of the timeline that originally included all of the part we wanted to slow down/speed up.
2625
2626 \subsubsection*{Downsample}%
2627 \label{ssub:downsample}
2628 \index{downsample}
2629
2630 Downsample mode does not change the length of the output sequence. It multiplies the frame rate of the output by the scale factor to arrive at a frame rate to read the input. This has the effect of replicating the input frames so that they only change at the scaled frame rate when sent to the output. It does not change the length of the sequence. If the scale factor is $0.5$ and the output frame rate is $30 \,fps$, only $15$ frames will be shown per second and the input will be read at $15 \,fps$. Downsample is only useful for scalefactors below $1$, hence the name downsample.
2631
2632 Downsample mode changes the frame rate of the input as well as the number of the frame to read, so effects before ReframeRT see the $frame rate \times scale factor$ as their frame rate. If the scale factor is $2$ and the output frame rate is $30$, the input frame rate will be $60$ and the input frame number will by doubled. This will not normally do anything, but some input effects may behave differently at the higher frame rate.
2633
2634 \subsubsection*{Other important points}%
2635 \label{ssub:other_important_points}
2636
2637 \begin{itemize}
2638     \item ReframeRT uses the fps indicated in \texttt{Settings $\rightarrow$ Format $\rightarrow$ fps} project and not the \texttt{fps} of the assets.
2639     \item It can be associated with Nested Clips.
2640     \item As an alternative to ReframeRT you can use the \textit{speed curve}, or change the framerate in \texttt{Resources $\rightarrow$ info} and in the \texttt{Project}.
2641     \item It is keyframmable.
2642     \item ResampleRT with the same settings is used to act on audio tracks.
2643 \end{itemize}
2644
2645 \subsection{Reroute}%
2646 \label{sub:reroute}
2647 \index{reroute}
2648
2649 The \textit{Reroute} plugin enables you to selectively transfer the Alpha channel or the Components (RGB or YUV) or both from a \textit{source} track to a \textit{target} track, partially overwriting the target's contents. It works as a \textit{shared plugin}. The typical usage scenario is to build up a possibly animated Mask in one track and then to transfer the Alpha channel to another content track.
2650
2651 \subsection{Reverse video}%
2652 \label{sub:reverse_video}
2653 \index{reverse video}
2654
2655 Media can be reversed on the timeline in realtime. This is not to be confused with using the reverse playback on the transport panel. The \texttt{reverse} effects reverse the region covered by the effect regardless of the transport direction. The region to be reversed is first determined by what part of the track the effect is under and second by the locations of keyframes in the effect. The reverse effects have an enabled option which allows you to set keyframes. This allows many possibilities.
2656
2657 Every enabled keyframe is treated as the start of a new reversed region and the end of a previous reversed region. Several enabled keyframes in succession yield several regions reversed independent of each other. An enabled keyframe followed by a disabled keyframe yields one reversed region followed by a forward region.
2658
2659 \subsection{Rotate}%
2660 \label{sub:rotate}
2661 \index{rotate}
2662
2663 The \textit{Rotate} filter can rotate the video in $90$ degree increments or by any number of degrees through use of the \textit{wheel} and about any \textit{pivot point}. It can also reverse and flip the video.
2664
2665 \subsection{Rumbler}%
2666 \label{sub:rumbler}
2667 \index{rumbler}
2668
2669 The \textit{Rumbler} plugin can be used to create dream-like or earthquake-like noise in the video. It creates noise by jiggling the corners through use of perspective transformation at the corners. The algorithm used is:
2670
2671 \[Rumbler\,(value) = (value\, at\, time) + amplitude \times (random\, generator)\]
2672
2673 The random generator varies from $-0.5\, to\, 0.5$. The rumble perturbs the normal values at time points which occur rate times a second. The values used between the rumble points are interpolated, so that the value jiggles rate times a second, by as much as the rumble amplitude. The time unit is frames per second. The corners are in units of percent width/height (figure~\ref{fig:rumbler}).
2674
2675 \begin{figure}[hbtp]
2676     \centering
2677     \includegraphics[width=0.45\linewidth]{rumbler.png}
2678     \caption{Rumbler control window}
2679     \label{fig:rumbler}
2680 \end{figure}
2681
2682 Screencast shows:
2683
2684 \textit{Time jittering} - $20\, fps$ 1 time a second.
2685 \textit{Corners jittering} - $25\%$  $5$ times a second.
2686 Using \textit{random seed} $0$ for a rumble sequence.
2687
2688 Plugin variables:
2689
2690 \begin{description}
2691     \item[Rumbler:] gain applied to random rumbler.
2692     \item[Rate:] number of times per second.
2693     \item[Time:] number of frames per rate times a second; if 0 has no effect on results.
2694     \item[Space:] corners jiggling in percentage per rate times a second; if 0 has no effect on results.
2695     \item[Seq:] is a random seed number; any reasonable positive or negative number you choose.
2696 \end{description}
2697
2698 \subsection{SVG via Inkscape}%
2699 \label{sub:svg_via_inkscape}
2700 \index{SVG via Inkscape}
2701
2702 This plugin allows the user to manipulate an SVG (scalable vector graphics) image with \textit{Inkscape} without having to leave the program. The associated \CGG{} window provides the ability to change the DPI, the Out $x/y$ coordinates, and the Out w/h values. For more information on use of inkscape, refer to: {\small \url{https://inkscape.org/develop/about-svg/}}
2703
2704 \begin{description}
2705     \item[DPI] is Dots per inch and it represents the resolution of the SVG image. Since the image is scaled with interpolation mode linear, the edges will look blurry when the input resolution is lower than the output resolution. You can either set the desired \textit{DPI value} in the window or use the tumbler on the integer text box, then use the \textit{update dpi} button to have the change take effect. Changing DPI causes the entire image to be re-exported via inkscape. DPI changes cause adjustments in the resolution, speed of re-import, and storage needed for the image data.
2706     \item[Out\_x/Out\_y] allow for changing the location of the SVG via the $x$ or $y$ coordinates.
2707     \item[Out\_w/Out\_h]  The scaling is controlled by width and height as they are normal parameters to overlay.
2708 \end{description}
2709
2710 \begin{figure}[hbtp]
2711         \centering
2712         \includegraphics[width=1.0\linewidth]{svg.png}
2713         \caption{Control window and Inkscape}
2714         \label{fig:svg}
2715 \end{figure}
2716
2717 Figure~\ref{fig:svg} shows the menu options plugin window and the SVG image in the Inkscape window.
2718
2719 \subsection{Scale}%
2720 \label{sub:scale}
2721 \index{scale}
2722
2723 Reduce or expand the image size depending on the ratio.
2724
2725 \begin{description}
2726     \item[Size] Height and Width in pixel; plus pulldown menu with preset.
2727     \item[Scale] Aspect ratio
2728     \item[Constrain ratio] Lock height to width rate
2729 \end{description}
2730
2731 \subsection{Scale Ratio}%
2732 \label{sub:scale_ratio}
2733 \index{acale ratio}
2734
2735 With the Scale Ratio plugin you can manipulate your video to maintain the pixel aspect ratio (proportional geometry), possibly for a different output Display device (figure~\ref{fig:scaleratio}).
2736
2737 \begin{figure}[hbtp]
2738     \centering
2739     \includegraphics[width=0.5\linewidth]{scaleratio.png}
2740     \caption{Many parameters of scale ratio}
2741     \label{fig:scaleratio}
2742 \end{figure}
2743
2744 \textit{In R} and \textit{Out R} representing the current input and output aspect ratios. Use the arrows to change to your desired values. Next you have the \textit{In W/H} and the \textit{Out W/H} for Width and Height. In the middle of the plugin on the right-hand side, you can set the Scale type of \textit{None}, \textit{Scaled}, \textit{Cropped}, \textit{Filled}, \textit{Horiz edge} and \textit{Vert edge}. The top part (aspect ratio data) is used to compute the bottom part when the Apply button is pressed. The bottom part allows you to reposition the image input or output to customize the results. When the in/out aspect ratios are different, the output must be cropped or filled to fit the output and maintain pixel square appearance. Left and right sides of the bottom portion show the \textit{Source} and the \textit{Destination X, Y, W, H} values. As you change the values on the left side, you can see how this will affect the output as you observe the results in the compositor window. For example, as you change the values for \textit{SrcY} in a \textit{cropped} Scale scenario, you see up/down movement.
2745
2746 \subsection{Selective Temporal Averaging}%
2747 \label{sub:selective_temporal_averaging}
2748 \index{selective temporal averaging}
2749
2750 This plugin is designed to smooth out non-moving areas of a video clip (figure~\ref{fig:staveraging}).
2751 \vspace{2ex}
2752 \begin{wrapfigure}[18]{O}{0.4\linewidth}
2753    \vspace{-2ex}
2754     \includegraphics[width=0.9\linewidth]{staveraging.png}
2755     \caption{STA control window}
2756     \label{fig:staveraging}
2757 \end{wrapfigure}
2758
2759 \textit{Denoise} is generally done on a spatial basis, mediating the values of a group of adjacent pixels to achieve greater uniformity. The effectiveness of Denoise can be increased by also introducing a \textit{time average} between a group of successive frames. The union of these two phases is the basis of the plugin. In fact the smoothing is performed by averaging the color component for each pixel across a number of frames. The smoothed value is used if both the standard deviation and the difference between the current component value and the average component value are below a threshold. The standard deviation is a mathematical index used to estimate the variance of a group of pixels: at high values corresponds more variation of the pixels and therefore more noise.
2760
2761 The \textit{Selective Temporal Averaging} plugin plays on the homogenization of the values of a group of pixels in a group of frames, based on a threshold below which the original values are left and above which the average is performed and then the noise reduction.
2762
2763 The \textit{average} and \textit{standard deviation} are calculated for each of the components of the video. The type of components averaged is determined by the color model of the entire project. The average and standard deviation of the frames can be examined by selecting the specific radio button in the plugin options window.
2764 The region over which the frames are averaged is determined by either a \textit{fixed offset} or a \textit{restart marker system}. In a restart marker system, certain keyframes are marked as beginning of sections. Then for each section, the frames surrounding the current frame are used as the frames to average over, except when approaching the beginning and end of a section, where the averaging is performed over the $N$ beginning or ending frames respectively.
2765
2766 An example of common usage is to select the number of frames you wish to average.
2767
2768 \begin{enumerate}
2769     \item Enter a reasonable number of frames to average (for example, $10$).
2770     \item Select the \textit{Selective Temporal Averaging} method and enter $1$ and $10$ for all the \textit{Av. Thres.} and \textit{S.D. Thres.} respectively. This basically causes all pixels to use the average value.
2771     \item Turn the \textit{mask} for the first component on. This should make the whole frame have a solid color of that specific component.
2772     \item Slowly reduce the \textit{S.D. Thres.} value. As you do so, you will notice that the regions vastly different from the average will have a flipped mask state. Continue to reduce the threshold until you reach the point at which non-moving regions of the video have a flipped masked state. This value is known as the \textit{noise-floor} and is the level of natural noise generated by the CCD in the camera.
2773     \item Repeat the same procedure for the \textit{Av. Thres.}
2774     \item Turn off the \textit{mask}.
2775     \item Repeat this for all channels.
2776 \end{enumerate}
2777
2778 \subsection{Sharpen}%
2779 \label{sub:Sharpen}
2780 \index{sharpen}
2781
2782 Sharpen the video, either the \textit{luminance}, \textit{horizontal}, or \textit{interlace}. With the Clear buttons we can bring the slider to default values without affecting the other parameters.
2783
2784 \subsection{Shift Interlace}%
2785 \label{sub:shift_interlace}
2786 \index{shift interlace}
2787
2788 Shift the interlace lines using \textit{odd} or \textit{even}. With the Clear buttons we can bring the slider to default values without affecting the other parameters.
2789
2790 \subsection{Sketcher}%
2791 \label{sub:Sketcher}
2792 \index{sketcher}
2793
2794 Now you can sketch \textit{lines}, \textit{curves} or \textit{shapes}, on your video in different colors using various pen widths and pen type with the \texttt{sketcher} plugin. You can even fill them. You can do rotations and scaling and apply two anti-aliasing modes; single and double. Getting started is fairly easy -- simply hold down the \textit{shift key} while using the \textit{left mouse button} to create a bunch of points in the compositor window. However, to do more than that you will need to understand the buttons and options or you may end up with unexpected results.
2795
2796 (figure~\ref{fig:sketcher}) shows the Sketcher gui and the sketch lines/curves created in the Compositor.
2797
2798 \begin{figure}[hbtp]
2799     \centering
2800     \includegraphics[width=1.0\linewidth]{sketcher.png}
2801     \caption{Sketcher control window and sketch on Compositor}
2802     \label{fig:sketcher}
2803 \end{figure}
2804
2805 In the screencast, note the Sketcher window gui \textit{Curve top section} and the \textit{Point bottom section}. The pink circle sketch is $id\,\#1$ in the curve section. Since $id\,\#2$ is highlighted in the Curve section, the X/Y coordinates in the Point section below show the points used to create the blue shape. Point 6 is selected so we see