Effects that begin with the characters F\_ are effects that are part of the FFmpeg software
as opposed to those coded within the \CGG{} program. These are discussed separately in
\nameref{sec:ffmpeg_audio_video_plugins}.
-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.
+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.
\begin{figure}[htpb]
\centering
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}).
-Note that when you change the plugin icons, your session will automatically save the backup, stop, restart, and reload (figure~\ref{fig:plugin-icons}).
-
-\begin{figure}[htpb]
+\begin{figure}[H]
\centering
\includegraphics[width=0.6\linewidth]{audio-plugins.png}
\caption{Cinfinity2 audio plugins}
\label{fig:audio-plugins}
\end{figure}
+Note that when you change the plugin icons, your session will automatically save the backup, stop, restart, and reload (figure~\ref{fig:plugin-icons}).
+
\begin{figure}[htpb]
\centering
\begin{tikzpicture}[scale=1, transform shape]
\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 (wipe selection or In/Out points) in which case the effect is pasted into that region only. If there is no data on the track or no selected region set, the effect is not added.
-Plugins are layered under the track they apply to. When dragging more than one effect onto an armed 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. "The pipeline in Cinelerra's\protect\footnote{credit to Original Creator} plugin design is the \textit{pull} method. The rendering pipeline starts at the final output and the final steps in the rendering pipeline are reading the data from disk. Every step in the rendering chain involves requesting data from the previous step. When the rendering pipeline eventually requests data from a plugin chain, each plugin requests data from the plugin before it. This is less intuitive than the push method but is much more powerful. Realtime plugins written using the pull method can change the rate data is presented to the viewer and the direction of playback. The pull method allows plugins to take in data at a higher rate than they send it out." Side note: if you want to avoid the automatic \textit{top to bottom} application of plugins, you can take advantage of \textit{nested assets} to manipulate the order the plugins are applied (see \ref{sec:nesting_clips_and_assets}).
+Plugins are layered under the track they apply to in what is referred to as the effect bar. Do a double click on the effect bar to select the effect region. When dragging more than one effect onto an armed 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. "The pipeline in Cinelerra's\protect\footnote{credit to Original Creator} plugin design is the \textit{pull} method. The rendering pipeline starts at the final output and the final steps in the rendering pipeline are reading the data from disk. Every step in the rendering chain involves requesting data from the previous step. When the rendering pipeline eventually requests data from a plugin chain, each plugin requests data from the plugin before it. This is less intuitive than the push method but is much more powerful. Realtime plugins written using the pull method can change the rate data is presented to the viewer and the direction of playback. The pull method allows plugins to take in data at a higher rate than they send it out." Side note: if you want to avoid the automatic \textit{top to bottom} application of plugins, you can take advantage of \textit{nested assets} to manipulate the order the plugins are applied (see \ref{sec:nesting_clips_and_assets}).
Instead of dragging from the Resources window, effects may be applied to a single armed track or a region via a popup menu. On the entire track or on a region determined by a selection wipe or by the In/Out points, right click 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.
One more method to apply an effect on all armed tracks of the same type (video or audio) is to use the \textit{Video} or \textit{Audio} pulldown \textit{Attach Effect} option. This brings up a menu which has a useful checkbox to \textit{Attach single standalone and share others} (see \ref{sec:shared_effect_tracks}). The default setting is checked on.
+
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.
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}).
-\begin{figure}[htpb]
+\begin{figure}[H]
\centering
- \begin{tikzpicture}[scale=1, transform shape]
+ \begin{tikzpicture}[scale=0.7, transform shape]
\node (img1) [yshift=0cm, xshift=0cm, rotate=0] {\includegraphics[width=0.6\linewidth]{preset02.png}};
\node [yshift=-20mm, xshift=-1cm,anchor=east] at (img1.north west) (Green) {A user preset Green};
\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.};
\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.
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}).
-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. A short example of what the txt file looks like is shown below.
-
-\begin{figure}[htpb]
+\begin{figure}[H]
\centering
- \includegraphics[width=0.8\linewidth]{expander.png}
+ \includegraphics[width=0.55\linewidth]{expander.png}
\caption{Down facing triangle, Right facing triangle = expander; "-" = options}
% the next line causes problems for the HTML version so do not use
% \caption{$\triangledown$,$\triangleright$ = expander; "-" = options}
\label{fig:expander}
\end{figure}
+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. A short example of what the txt file looks like is shown below.
+
\begin{lstlisting}[style=sh]
Video Effects
-Favorites
For users running \CGG{} using the AppImage, to make an initial copy of expanders.txt, execute the
following lines on /tmp:
\begin{lstlisting}[numbers=none]
- git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
+ git clone --depth 1 git://git.cinelerra-gg.org/goodguy/cinelerra.git cinelerra5
cp /tmp/cinelerra5/cinelerra-5.1/expanders.txt $HOME/.bcast5/expanders.txt
\end{lstlisting}
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}.
+\subsection{Floating-point pipeline and plugins}%
+\label{sub:pipeline_fp_plugins}
+
+\CGG{} runs internally in 32-bit floating-point and thus can read and process values outside the range $(0 - 1.0f)$ (\textit{illegal} values, they need the final \textit{conforming} step to comply with the \textit{legal} values). However, there are plugins and tools that can introduce clipping that must be taken into account to keep the whole pipeline which preserves the original values. The limited plugins are: \textit{Blur; Color 3 Way} (partially); \textit{Color Space; Foreground; Histogram} (partially); \textit{Histogram Bezier; Title; Videoscope} (partially).
+
\section{Audio Effects - Native}%
\label{sec:audio_effects_native}
\settocdepth{subsection}
Refer to Compressor (Single Band) for common theory and options.
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.
+The three bands and their range (adjustable as desired) are shown in the frequency graph visible below (Bandwidth:).
+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.
+
+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.
+
\begin{figure}[htpb]
\centering
\includegraphics[width=0.7\linewidth]{compressorM.png}
\label{fig:compressorM}
\end{figure}
-The three bands and their range (adjustable as desired) are shown in the frequency graph visible below (Bandwidth:).
-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.
-
-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.
-
\begin{description}
\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.
\item[Bypass band]: In contrast to Solo, it only brings the sound signals of the two inactive bands to the Output.
\label{sub:live_audio}
\index{live audio}
-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.
+The Live Audio effect reads audio directly from the sound card input in real time. 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.
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.
LV2\protect\footnote{Optional Feature - OS dependent} 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.
-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. Note that because the Calf Plugins have a graphics UI interface which is dependent on specific hardware, they will not work with AppImage. 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
+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
\textit{lv2-calf-plugins-gui}; for example Fedora version 32.
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.
/tmp/cinelerra-5.1/bin/lv2ui http://calf.sourceforge.net/plugins/Flanger
\end{lstlisting}
+If using the AppImage version and the Calf/LV2 plugins are not working for you, try doing the
+following which has been shown to work on Ubuntu 16.
+
+\begin{enumerate}
+ \item Copy the "calf" and "lv2" folders from /usr/lib/ to /home/user/plugins\_lv2-calf\_for\_Cin/.
+ \item After starting up \CGG{}, change Settings-> Preferences...-> Interface tab, Default LV2\_PATH to
+ \$HOME/plugins\_lv2-calf\_for\_Cin/lv2 .
+ \item In the /home/user/plugins\_lv2-calf\_for\_Cin/lv2/ directory remove any of the plugins that do not seem to work.
+\end{enumerate}
\section[Video Effects --- Native]{Video Effects -- Native}%
\label{sec:video_effects_native}
Automatically scale to a specified size.
+\subsection{Blend Algebra and Blend Program}%
+\label{sub:blend_algebra}
+\index{blend algebra}
+
+The Blend Algebra/Blend Program plugins provide the advanced feature of combining and modifying color pixels and transparencies of several tracks according to a mathematic algorithm written entirely by the user in the form of compact and simple piece of code. Such user defined algorithms (blend functions) are compiled, dynamically linked and immediately executed inside \CGG{} on the fly without the need to restart the application, reload the project, reattach plugins, and so on.
+
+The following description is based on the \texttt{~/cinelerra-5.1/doc/README.blendalg} that accompanies the code by the author of both the code and the document. It is the authoriative documentation; the most detailed/original source and has additional commentary and programming information. If you encounter problems or confusion when using these plugins, always refer directly to that document \href{https://cinelerra-gg.org/download/testing/BlendPluginExamples/README.blendalg}{here}. If running \CGG{} from an \textit{AppImage}, testing has shown that it should work as well as if run from a build - just be aware of filename extensions that appear by default in the input field for the funtion name and change them accordingly.
+
+The idea behind these plugins\protect\footnote{credit to Georgy} is that the user can program sufficiently short and simple blending algorithms, called \textit{Functions}, by following detailed instructions with very little programming skills required.
+Blend Algebra and Blend Program come with a library of Functions (\textit{System Library}) that mimic the 30 overlay effects found in the Patchbay or Overlay plugins. The user can modify these Functions as needed or create new ones.
+To look at these example functions, there is an \texttt{Edit...} button in the respective plugin dialog. You will need a text editor to do so, which by default is \textit{emacs} if it is installed. If not, you can set your favorite editor via the corresponding environment variable in a terminal (\texttt{export CIN\_EDITOR='name editor'}) and then start \CGG{} from that same terminal.
+
+If you can not wait to get started, checkout these examples \href{https://cinelerra-gg.org/download/testing/BlendPluginExamples/Examples.txt}{here}. You will also find test projects to \href{https://cinelerra-gg.org/download/testing/BlendPluginExamples}{download} to learn more about the plugins and to see the various ways they can be used to create your own functions.
+
+Both plugins, Blend Algebra and Blend Program, are similar. They are described together along with their differences. The main difference between the two plugins is that Blend Algebra is like a function; it combines its arguments (tracks) and yields the result which is placed into the single track configured for output. However, Blend Program does not produce a function result, but instead directly modifies its arguments. If more than one track is to be modified, Blend Program is the only choice. If a single track is to be processed, Blend Program is the best choice and might run slightly faster. Any Blend Algebra function can be rewritten to become a Blend Program function. But if a function processes several tracks and modifies only one, it will run faster in Blend Algebra which has more controls in its plugin dialog.
+
+How the plugin works is defined by the user. The word \textit{function} is used to denote this for either of the two plugins throughout this description.
+These functions are for their plugins the same as the plugin shared objects in the main \CGG{} binary. But these functions are simple enough that they can be easily written by users and manipulated in binary or in source form.
+The plugins make it possible to have a user library and a system library of functions. Thus, an experienced user can have a number of such functions to reuse in many projects.
+
+The plugin is attached to a track as usual. Generally, it needs several tracks as arguments and it has to be attached to the additional tracks as a shared effect.
+
+All the parameters described below are keyframable, including user functions themselves. The top area of the dialog menu deals with programmatic aspects.
+The middle area of the dialog is color specific.
+The bottom area of the dialog has controls for the argument track ordering,
+similar to that of the Overlay plugin.
+
+
+\begin{figure}[H]
+ \begin{center}
+ \includegraphics[scale=0.5]{Blend_Algebra.png}
+ \includegraphics[scale=0.5]{Blend_Program.png}
+ \caption{Blend Algebra and Blend Program GUI}
+ \end{center}
+\end{figure}
+
+\subsubsection*{Blend programming environment}
+\label{ssub:blend_prog_env}
+
+\begin{description}
+ \item[Function] This textbox contains the filename of the user's function source text. The most convenient method to select the function is via the \texttt{Attach...} dialog, but you can just enter its filename directly. If the function pathname does not start with '/', it is interpreted relative to the main project directory. An empty function name means that no function will be executed and the tracks will remain unchanged. If the entered filename does not exist, again nothing will be done, but in this case the user can create a source file via the \texttt{Edit...} button. An error message will be shown when a directory is selected in the file selection dialog instead of a filename.
+ Although you can use any filename, it is highly recommended to use distinct suffixes: \texttt{.ba} for Blend Algebra, \texttt{.bp} for Blend Program or you will have to keyin specific filenames in some cases.
+ \item[Attach...] This button opens the file selection dialog menu as usual for Cinelerra. By default it shows only files with the recommended suffixes (\texttt{*.ba} or \texttt{*.bp}), although this can be changed by specifying a filter. The user can select an existing file or enter a filename. You can exit the dialog with \texttt{Cancel} so that nothing is changed or with \texttt{OK} for changes to be in effect. In that case, the selected function will be set as current, and its name will appear in the \textit{Function: input field} above. An error message will be shown if the user presses \texttt{Edit...} with an empty function name or when a directory is selected in file selection dialog instead of a filename.
+ If the entered filename does not end with \texttt{.ba} or \texttt{.bp}, the corresponding suffix will be appended automatically. If you use a filename with another suffix or none at all, you have to change the name directly in the \textit{Function: input field} after exiting the File Selection window.
+
+\end{description}
+
+\begin{figure}[H]
+ \centering
+ \includegraphics[width=1.0\linewidth]{blend_attach_window.png}
+ \caption{File Selection window}
+ \label{fig:file_selection_window}
+\end{figure}
+
+\begin{description}
+ \item The file selection dialog menu has six additional buttons specific to the Blend Algebra/Blend Program plugins. The three buttons on top left change the current directory; the three buttons on bottom left do simple file operations.
+ \begin{description}
+ \item[=>Project] display the files in the project directory (where the main project .xml file resides).
+ \item[=>Userlib] display the files in the user library.
+ \item[=>Syslib] display the files in the system library.
+ \item[Copy to project] copies the currently selected function source file into the project directory.
+ \item[Copy to userlib] copies the currently selected function source file into the user library. There is no button to copy a function into the system library because the system library is meant for functions distributed with Cinelerra, which can get overwritten on reinstallation or upgrade. For details on "copying to/from" project, userlib, or syslib, see
+"User library, System library, and Cinelerra Project directories" in a subsequent section.
+
+ \item[Edit...] This is used in the same way as the Edit... in the main plugin window as described next.
+ \end{description}
+ \item[Edit...] Open the currently selected function source file in the configured external editor. The editor that will be used is defined by the environment variable \texttt{\$CIN\_EDITOR}, with emacs being the default if not redefined. It must be a windowed editor, like \textit{GNU Emacs} (default), or KDE's \textit{Kate}, or \textit{Gedit}, or ancient \textit{Xedit}, not a bare console editor like \textit{vi}.
+ \begin{lstlisting}[style=sh]
+ export CIN_EDITOR=kate
+ export CIN_EDITOR=gedit
+ ...
+
+ $ ~/cinelerra5/cinelerra-5.1/bin/./cin
+ \end{lstlisting}
+ If using a console editor, it must be defined to run in a terminal emulator, like \textit{xterm}, or KDE's \textit{Konsole}, for example:
+ \begin{lstlisting}[style=sh]
+ export CIN_EDITOR='konsole -e vi'
+ $ ~/cinelerra5/cinelerra-5.1/bin/./cin
+ \end{lstlisting}
+ This is the same \texttt{Edit...} button as in the file selection window of the \texttt{Attach...} button.
+ \item[Refresh] The external editor is started in the background so after editing and saving a function, the user can leave the editor in that window. Alternatively the user can edit a function outside of \CGG{}. In order not to check modification times of all the functions on each video frame, \CGG{} has to know when a function can get changed. That is what pressing \texttt{Refresh} is for. It indicates that now is the time to check functions, and to recompile some of them. You can expect immediate recompilation of the function which is under the timeline cursor (if any), that is if the source became newer than the shared object. But any other functions not under the cursor will not be recompiled until first access.
+ \item[Detach] This button clears the function name in the \textit{Function: input field} and if there was a function in effect, it will be cleared in the tracks.
+ \item[Color Space:] Here is defined in which color space the frame pixels are to be passed to the function. The obvious choice is the default \texttt{auto} so that you will be working in the color space which is required by the function itself. In addition, RGB, YUV, and HSV color spaces are supported as well as the choice \texttt{of project}. With this choice, you will be working in the native color space of the project (as defined in \texttt{Settings $\rightarrow$ Format}). If the required color space does not match the native one, pixel color components will be transformed to the required space as floating point numbers. After returning from the function, pixels of the result will be transformed back to the native color space of the project.
+ \item[Parallelize processing] This checkbox, ON by default, lets you execute user function code in a parallelized (multithreading) manner, provided that the function itself supports this. It is described further on as to how the function code is executed.
+\end{description}
+
+\subsubsection*{Supplementary color selection}
+\label{ssub:sup_color_selction}
+
+There may be illegal floating point operations in the user's code, such as division by zero producing infinity, or square root from minus unity producing NaN (not-a-number). Even if only legal finite floating point numbers are computed, the results may go out of range. This dialog section controls what to do in such cases.
+
+\begin{description}
+ \item[Clip color values] If this checkbox is on, which is the default, first the function results will be clipped to range. Clipping takes place before back transformation to the project color space. The bounds are defined as follows:
+ \begin{lstlisting}[style=sh]
+ RGB: [0.0 .. 1.0] for R, G, B
+ YUV: [0.0 .. 1.0] for Y, [-0.5 .. +0.5] for U, V
+ HSV: [0.0 .. 360.0] for H, [0.0 .. 1.0] for S, V
+ Transparency: [0.0 .. 1.0] for Alpha
+ \end{lstlisting}
+ If the project color space is \texttt{RGB(A)-8 Bit} or \texttt{YUV(A)-8 Bit}, clipping occurs unconditionally because of intrinsically restricted dynamic range of 8-bit storage per channel. For \texttt{RGB(A)-FLOAT} clipping can be switched off. What occurs with unclipped pixels later, depends on further destinations in the internal video processing pipeline. Moreover, displaying drivers handle unclipped colors differently. For example, an RGB pixel with unclipped red component\texttt{ R=-1.0} and two other components \texttt{G=B=0.0} is displayed as black (that is with \textit{R} clipped to zero) by the OpenGL driver, but as red (that is taken with opposite sign, \textit{R=1.0}) by the X11 driver. Explicit clipping in the plugin eliminates such driver dependency.
+ \item[Chroma key or substitution color:] Even after optional clipping, there can still remain some non-finite results, like NaN. These results are bad and should be eliminated as soon as possible. If any of color components or alpha channel is NaN, the complete pixel (all components) is replaced with the configured color and the configured opacity.
+\textit{Substitution color} is passed as additional arguments to user functions and can be used for artistic purposes, such as chroma keying.
+ \item[Select key color...] This button opens \textit{color selection} dialog to select the color which will be used as substitution for NaNs or infinities in the results.
+ \item[Get from color picker] Use this button to copy the color selected earlier in the color picker tool of the \CGG{} Compositor window.
+ \item[Substitution opacity:] The slider sets the opacity (\textit{alpha-channel}) value to be used together with substitution color. Substitution color and opacity are passed as additional arguments to user functions and can also be used for artistic purposes.
+\end{description}
+
+
+\subsubsection*{Processed tracks arrangement}
+\label{ssub:processed_tracks}
+
+\begin{description}
+ \item[Track order:] If the plugin is attached to N tracks, its user functions get pixels of the tracks numbered from 0 to N-1. This defines which of the tracks is to be the first (i.e. number 0), either \textit{top} or \textit{bottom}, much like in the \textit{Overlay} plugin.
+ \item[Output track:] This defines into which track (\textit{top} or \textit{bottom}) the result will be placed, similar to the Overlay plugin. This control applies to \textit{Blend Algebra} only.
+ \item[Hide input tracks, use output exclusively] If this checkbox is \texttt{ON} (the default), frames of the tracks the plugin is attached to are cleared and then replaced by the function result. If the checkbox is \texttt{OFF}, only the output track frame is replaced by the result; all the other tracks are left unchanged. By comparison, the Overlay plugin has no such option and its input tracks are always cleared as in the \textit{on} state. This control applies to the \textit{Blend Algebra} plugin only.
+\end{description}
+
+All the parameters are keyframable, including user functions themselves. That is, a plugin can have several functions attached at the same time and switch between them while rendering. The color and alpha channels of the substitution (key) color are interpolated between keyframes; the other parameters are switched.
+
+\subsubsection*{User library, System library and Project directories}
+\label{ssub:user_library}
+
+The user library directory is that defined by the environment variable \texttt{\$CIN\_USERLI}B, or if not defined, \texttt{\$HOME/.bcast5lib} as a fallback default. The functions for Blend Algebra reside there in the subdirectory \texttt{dlfcn/ba} and for Blend Program in \texttt{dlfcn/bp} (\textit{dlfcn} stands for \textit{dynamic loaded function}). Having user functions in such a library in a single place makes it convenient to reuse the same functions in different projects. The \texttt{Copy to userlib} button in the \texttt{Attach...} file selection dialog is handy to save such functions in the user library for future use.
+
+The reason to define user library \texttt{\$HOME/.bcast5lib} by default (and not \texttt{\$HOME/.bcast5}) is the following. There is a common workaround: if a newer version of \CGG{} does not start, to delete \texttt{\$HOME/.bcast5} completely. Doing so, all user functions would be deleted if they were saved there.
+
+The system library is defined by the environment variable \texttt{\$CIN\_DAT}, the \CGG{} installation path, and under the same subdirectories \texttt{dlfcn/ba} or \texttt{dlfcn/bp}. System library is meant for functions distributed with \CGG{}.
+
+When a complete project is to be exported, or fed to a render farm, it is often necessary to place all the resources under the same directory where the project \texttt{.xml} file resides. If some functions are used which reside elsewhere (for example, in a user library), they could not be found after exporting the project to another computer. The \texttt{Copy to project} button in the\texttt{ Attach...} file selection dialog is used to copy such functions to the project directory in a convenient manner.
+
+
+\subsubsection*{Syntax of Blend Algebra / Blend Program functions}
+\label{ssub:syntax_blend}
+
+Blend Algebra/Blend Program functions are written in C, and with usage of a set of special cpp macros hiding from the user all the Cinelerra internals. This approach makes it easy to write functions of moderate complexity with almost no background in C programming. All macros defined for user functions are written in capital letters. A typical Blend Algebra function consists of the following logical blocks.
+
+\begin{lstlisting}[style=sh]
+ <optional static variable definitions>
+
+ BLEND_ALGEBRA_INIT
+
+ <macros and/or C statements for the INIT (preparation) phase will be executed once before processing of each frame>
+
+ BLEND_ALGEBRA_PROC
+
+ <macros and C statements for the PROC (processing) phase will be executed repeatedly for each pixel in the frame>
+
+ BLEND_ALGEBRA_END
+\end{lstlisting}
+
+The macro \texttt{BLEND\_ALGEBRA\_STOP} terminates execution of the \texttt{INIT} or \texttt{PROC} phase immediately and returns to the calling plugin.
+
+The structure of a Blend Program function is the same, only the word \texttt{ALGEBRA} in all macros must be changed to \texttt{PROGRAM}. The following macros can be used in the \text{INIT} phase:
+
+\begin{lstlisting}[style=sh]
+ COLORSPACE_RGB
+ COLORSPACE_YUV
+ COLORSPACE_HSV
+\end{lstlisting}
+
+
+Use any of these COLORSPACE statements to declare the working color space inside the user function. If there is no such declaration, the native color space of the project (RGB or YUV) will be used.
+
+\texttt{REQUIRE\_TRACKS} (<n of tracks>) \newline
+Declares the minimum required number of tracks the function uses. If the effect is attached to more tracks, it is fine. If there are less tracks, it is an error and the function is not executed. The absence of such declaration means that the function can process any number of tracks (one or more).
+
+\texttt{PARALLEL\_SAFE} \newline
+This declaration means that it is safe to execute the function in parallel. Without this statement the function will be executed sequentially, independent of the state of the \textit{parallelization} checkbox in the plugin GUI.
+
+The following special variables (macros) can be used for queries:
+
+\texttt{PARALLEL\_REQUEST} \newline
+1 == parallelization requested in the GUI \\
+0 == parallelization switched off
+
+\texttt{TOTAL\_TRACKS} \newline
+The actual number of tracks passed to the function.
+
+\texttt{HAS\_ALPHA} \newline
+1 == the project color space has alpha channel (transparency)
+
+\texttt{WIDTH, HEIGHT} \newline
+The dimensions of processed frames in numbers of pixels.
+
+The following variables (macros) can be used in the PROC phase.
+In addition to the next variables, \texttt{TOTAL\_TRACKS, HAS\_ALPHA, WIDTH, HEIGHT} can be used as well. \newline
+
+\hrule
+Color (and alpha) components of pixel from i-th track. Track numbering is \textit{0-based}, as standartized for C arrays. So, the first track has number 0, the last one - number TOTAL\_TRACKS-1. All the color components are floating point values of the C type 'float'.
+Here the letters R, G, B, H, S, V, etc. are for readability. If the user has declared \texttt{COLORSPACE\_RGB}, and then written something like H(i), it does not mean that he should get the H-component of color autoconverted to the HSV color space. Actually R, Y, H are mutually identical to the 1-st color component, so are G, U, S to the 2-nd, and B, V to the 3-rd one.
+\begin{lstlisting}[style=sh]
+ R(i), G(i), B(i)
+ Y(i), U(i), V(i)
+ H(i), S(i), V(i)
+ A(i)
+\end{lstlisting}
+
+\hrule
+Corresponding color components of the key (substitution) color in the working color space of the function and the opacity slider.
+\begin{lstlisting}[style=sh]
+ KEY_R, KEY_G, KEY_B
+ KEY_Y, KEY_U, KEY_V
+ KEY_H, KEY_S, KEY_V
+ KEY_A
+\end{lstlisting}
+
+\hrule
+Color components for the result, for Blend Algebra only. Blend Programs return no result so do not have these definitions.
+\begin{lstlisting}[style=sh]
+ R_OUT, G_OUT, B_OUT
+ Y_OUT, U_OUT, V_OUT
+ H_OUT, S_OUT, V_OUT
+ A_OUT
+\end{lstlisting}
+
+\hrule
+Integer X and Y coordinates of the current pixel in its frame, in the ranges of [0 .. WIDTH] and [0 .. HEIGHT], respectively.
+\begin{lstlisting}[style=sh]
+ PIX_X, PIX_Y
+\end{lstlisting}
+
+\hrule
+These macros clip color components of the i-th track to the bounds appropriate in the respective color space.
+\begin{lstlisting}[style=sh]
+ CLIP_RGB(i)
+ CLIP_YUV(i)
+ CLIP_HSV(i)
+ CLIP_RGBA(i)
+ CLIP_YUVA(i)
+ CLIP_HSVA(i)
+ CLIP_A(i)
+\end{lstlisting}
+
+\hrule
+Clip all color components (including alpha) for all tracks.
+\begin{lstlisting}[style=sh]
+ CLIP_RGB_ALL
+ CLIP_YUV_ALL
+ CLIP_HSV_ALL
+\end{lstlisting}
+
+\hrule
+Like clipping track color components, but for the result of a Blend Algebra function (not relevant for Blend Programs).
+\begin{lstlisting}[style=sh]
+ CLIP_RGB_OUT
+ CLIP_YUV_OUT
+ CLIP_HSV_OUT
+ CLIP_RGBA_OUT
+ CLIP_YUVA_OUT
+ CLIP_HSVA_OUT
+ CLIP_A_OUT
+\end{lstlisting}
+
+Clipping is done according to the inherent bounds of the respective color space as follows:
+\begin{lstlisting}[style=sh]
+ RGB: [0.0 .. 1.0] for R, G, B
+ YUV: [0.0 .. 1.0] for Y, [-0.5 .. +0.5] for U, V
+ HSV: [0.0 .. 360.0] for H, [0.0 .. 1.0] for S, V
+ Transparency: [0.0 .. 1.0] for Alpha
+\end{lstlisting}
+\texttt{H} color channel of HSV is brought into range by repeated rotation around 360 degrees; all the others by simple clipping. \newline
+
+\texttt{ABS(x), SQR(x), MAX(x,y), MIN(x,y)} absolute value, square, max and min values for floating point arguments. Can be used in any phase of a function. \newline
+
+\texttt{TO\_RAD(x), TO\_DEG(x)} conversion from degrees to radians and vice versa. \newline
+
+\hrule
+Both macros clip the 'x' argument to bounds between y and z. CLIP returns value leaving x unchanged. CLAMP assigns that value to x.
+\begin{lstlisting}[style=sh]
+ CLIP(x,y,z)
+ CLAMP(x,y,z)
+\end{lstlisting}
+\hrule
+
+All the macros are defined in the text header \texttt{\$CIN\_DAT/dlfcn/BlendAlgebraStart} for Blend Algebra and the analogous header \texttt{BlendProgramStart} for Blend Program in the same \texttt{dlfcn} subdirectory of the Cinelerra installation directory. These headers are prepended to the user functions during compilation. The user with a basic C knowledge can easily understand what happens in these headers.
+
+Of course, you can use any valid C statements inside user functions. As they are linked with \texttt{-lm}, the standard C math library and with glibc, almost any mathematical or C library function can be called. C-style comments can also be used, and are welcome.
+
+\subsubsection*{The compilation script}
+\label{ssub:compliation_script}
+
+Compilation of Blend Algebra and Blend Program functions is carried out by a Perl script \texttt{BlendAlgebraCompile.pl} and \texttt{BlendProgramCompile.pl}. Both scripts are distributed in the \texttt{dlfcn} subdirectory of \texttt{\$CIN\_DAT}, the Cinelerra installation directory. Like the famous \texttt{ContextManual.pl} script of Context Help, the system script at the first call is copied into \texttt{\$CIN\_CONFIG (\$HOME/.bcast5)} where it can be edited by the user and adapted according to their needs.
+
+While a regular compilation, the script works in that directory where the function source file resides. First, the \texttt{BlendAlgebraStart/BlendProgramStart} header is prepended to the source to produce an intermediate file with the \texttt{.c} suffix. This C source is compiled by the system C compiler (gcc by default) and linked with \texttt{-lm} to produce the shared object ready for dynamic loading (attaching to the plugin).
+
+Usually the script is executed by the respective \CGG{} plugin when a user function is to be compiled. But the script can also be run by the user explicitly. Execution can be controlled by options starting with the '-' character, the first argument not starting with '-' being the function name to compile. The following options are recognized:
+
+ \textit{ -compile} do not check modification time, compile unconditional \newline
+ \textit{ -cfile} do not remove intermediate .c file \newline
+ \textit{ -opt} add optimizing options to compiler command line \newline
+ \textit{ -debug} add debugging options to compiler command line \newline
+ \textit{ -warn} add warning options to compiler command line \newline
+ \textit{ -edit} open function source in text editor \newline
+ \textit{ -verbose} verbose execution \newline
+ \textit{ -noapi} do not copy itself to \texttt{\$HOME/.bcast5} \newline
+ \textit{ -h, -help, -?} print short help and current configuration \newline
+
+\subsubsection*{Environment variables influencing plugin configuration}
+\label{ssub:environment_variabiles}
+
+In the beginning of the script some variables can be redefined according to the user's needs: the C compiler executable, compiler options for optimization or debugging, and text editor executable.
+These environment variables are taken into account in various places in Blend Algebra/Blend Program plugins.
+
+\texttt{\$CIN\_CC}: C compiler executable (default: gcc) \newline
+\texttt{\$CC}: C compiler executable if \texttt{\$CIN\_CC} is not defined (default: gcc) \newline
+\texttt{\$CIN\_EDITOR}: text editor (default: emacs) \newline
+\texttt{\$CIN\_DAT} (set by Cinelerra binary): Cinelerra installation directory. The Blend Algebra / Blend Program system library with scripts, headers, and functions distributed with Cinelerra resides in the subdirectory \texttt{\$CIN\_DAT/dlfcn}. \newline
+\texttt{\$CIN\_CONFIG} (set by Cinelerra binary): user's config directory, usually \\ \texttt{\$HOME/.bcast5}. \newline
+\texttt{\$CIN\_USERLIB}: user's library (default: \texttt{\$HOME/.bcast5lib}). User's functions reside in the subdirectory \texttt{\$CIN\_USERLIB/dlfcn}. \newline
+
+\subsubsection*{What comes in the plugins}
+\label{ssub:what_comes_plugins}
+
+In the distribution 30 Blend Algebra functions are provided for all the 30 \CGG{} overlay modes according to the formula defined in the CinelerraGG manual. In principle, they are not needed as the built in overlayer engine is OpenGL accelerated and runs faster. Nevertheless, these functions can be handy as starting examples for users who may like to modify the formula in some way. Furthermore, their behavior differs from that of the standard overlayer in several aspects:
+
+\begin{itemize}
+ \item Overlayer produces different results in RGB and YUV color spaces; Blend Algebra yields identical results independently of color space of the project.
+ \item In RGB(A) FLOAT color space, overlayer results can get out of range and then be rendered differently depending on the display driver used. Blend Algebra clipping, when switched on, can prevent this undesirable effect.
+ \item Overlayer always clears its input frames. In Blend Algebra the user has a choice, either to clear them, or to leave them intact.
+\end{itemize}
+
+There are several example functions from totally different areas of application: a user programmable plugin is a really universal tool and can be handy in unexpected cases. A programmer can sometimes make use of this plugin when creating new effects. It has the big advantage that you can more quickly test different combinations without spending time to restart \CGG{}, recompile it, reload project, and reattach plugins, etc. See the examples \href{https://cinelerra-gg.org/download/testing/BlendPluginExamples/Examples.txt}{here}.
+
+There is the \texttt{ydiff.ba} function, actually representing the complete \textit{ydiff} application running inside a plugin.
+In addition, there is a Transition example,
+and 2 more function examples showing use of the Blend Programs: the \texttt{chromakey.bp} and \texttt{background.bp} functions. They too serve as excellent starting points for further user experimentation. The usage of the provided functions is either self evident or briefly
+described in the comments of their source files.
+
+NOTE: \texttt{make install} copies the functions into Cinelerra's bin directory in source (\texttt{*.ba, *.bp}) and binary (\texttt{*.so}) forms via \texttt{cp -a}, to preserve modification times of the files. Otherwise, if modification time of the function source accidentally becomes newer than that of its binary, the plugin will repeatedly try to recompile the function. If they are installed system-wide so that the user has no permission to modify them, such recompilations will fail.
+
+
+\subsubsection*{Caveats}
+\label{ssub:caveats}
+
+User's functions can have bugs. Most probable bugs in a user function can be illegal arithmetic such as division by zero or logarithm of a negative number (FPE, floating exception), and out of bounds indexation of arrays (usually leading to SEGV). Most modern processors do not generate FPE. Instead, they generate NaN as the result of an illegal arithmetic instruction. After calling user functions, the plugins test the results not to be NaN and replace them with the configured substitution color if necessary.
+
+SEGV is more problematic. If the user has written in his function, let's say, \texttt{REQUIRE \_TRACKS(2)}, and then accessed \texttt{R(1000000}), most likely the Cinelerra binary will crash. Although theoretically it could be possible to trap SEGV via \texttt{sigaction()/setjmp() /longjmp()}, in Cinelerra it is problematic. In a multithreaded application, which Cinelerra is, only one signal handler for all its threads at the same time is allowed, and Cinelerra already has a SEGV handler which can not be overwritten. So the user is responsible for his indexation bugs, which can easily occur in off-by-one errors, like referencing elements such as \texttt{R(TOTAL\_TRACKS)} (the last legal element being \texttt{R(TOTAL\_TRACKS-1)}), or \texttt{R(i)} where i has been decremented to -1.
+
+The user is allowed to call any C function from the -lm and glibc libraries. But some functions are not thread safe (which means \texttt{PARALLEL\_SAFE} macro should not be used) and some others have undesired side effects. For example, should the user write inside his function something like \texttt{exit(R(0));}, Cinelerra would immediately halt. The user is left to imagine what would happen after the following expressione:
+
+\begin{lstlisting}[style=sh]
+ R_OUT = R (system ("killall -9 X"));
+\end{lstlisting}
+
+\subsubsection*{Hardware acceleration}
+\label{ssub:hardware_acceleration}
+
+Blend Algebra/Blend Program functions are not hardware accelerated which means that the function algorithm is not programmed as an OpenGL shader. However, functions can be parallelized using the load balancing engine of Cinelerra, and can be compiled with optimization (this is switched on by default). The default optimizing option (defined in \texttt{BlendAlgebraCompile.pl} and \texttt{BlendProgramCompile.pl}) is \texttt{-O2}. One can redefine it to \texttt{-O3} or \texttt{0fast}. It has to be noted that using \texttt{0fast} or \texttt{-ffast-math} options can lead to ignoring some IEEE rules for floating point math, for example some intrinsic tests on infinities or NaN which can yield unpredictable results.
+
+\subsubsection*{Debugging}
+\label{ssub:debugging_blend}
+
+Although user's function can be compiled with debugging option such as \texttt{-g} or \texttt{-ggdb}, debugging functions can be tricky. The programmer can set a breakpoint into the function only after its code has been loaded in memory by the plugin, and set another breakpoint into plugin only after that plugin itself has been attached to a track. Moreover, a function can get detached from memory under some conditions, and then its breakpoints will be lost.
+
+Debugging printout inside the \texttt{PROC} phase, although possible, would seem too verbose: the \texttt{PROC} phase would be called for full-HD footage 2073600 times per frame! Here perhaps one could make use of \texttt{PIX\_X, PIX\_Y} coordinates at some selected place like in the example:
+
+\begin{lstlisting}[style=sh]
+ if (PIX_X == 320 && PIX_Y == 200)
+\end{lstlisting}
+
+% printf ("%f %f %f\n", R(0), G(0), B(0));}
+
+\subsubsection*{Portability}
+\label{ssub:portability}
+
+The current implementation should be portable as long as you have a working C compiler such as gcc, the default to compile \CGG{}, or clang which has been known to work; but other compilers may be compatible as well. Portability to other architectures that are Unix-like and ELF based should work, but not Windows.
+
+NOTE: For developers who want to take advantage of creating a plugin to generate an effect in the same manner as Blend Algebra/Blend Program, please reference \nameref{sec:ba_bp_workflow}. This methodology makes it easier for the programmer to more quickly test different combinations without spending time to restart \CGG{}, recompile it, reload your project, reattach plugins, and so on.
+
+
\subsection{Blue Banana}%
\label{sub:blue_banana}
\index{blue banana}
Blue Banana\protect\footnote{credit to Monty Montgomery programmer} is an \textit{HSL Qualifier} \index{HSL Qualifier} (HSL= Hue, Saturation, Luminance; HSV in our plugin, with V = Value), 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 three H, S and V sliders are called \textit{qualifiers}. 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}).
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=1.0\linewidth]{bluebanana.png}
+ \caption{Screencast showing the BlueBanana plugin control}
+ \label{fig:bluebanana}
+\end{figure}
+
The basic strategy for BlueBanana is to:
\begin{itemize}
\item Optionally reset the output alpha to opaque, or pass the alpha to another BlueBanana plugin.
\end{itemize}
-\begin{figure}[htpb]
- \centering
- \includegraphics[width=1.0\linewidth]{bluebanana.png}
- \caption{Screencast showing the BlueBanana plugin control}
- \label{fig:bluebanana}
-\end{figure}
-
\subsubsection*{Just a Warning Note:}
\label{ssub:warning_note}
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.
\begin{enumerate}
\item There are color strips under color Adjustment which will show color changes as you modify values.
\item Uncheck Mark Selected Areas and check the Filter Active box to the right of Color Adjustment.
- \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.
+ \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 are changing. The fade adjusts the level of color blending. The alpha is basically the opacity of your changes.
\end{enumerate}
\end{description}
RGBA = red/green/blue color planes, alpha data plane.
YUVA = luma/Cb/Cr color values, alpha data plane.
-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.
+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 then 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.
-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.
+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. Note that the "alpha" slider works with both "Filter Active" and "Mask Selection" checkboxes
+checked. The "Filter Active" checkbox enables the options: red, green, blue, hue, saturation, value, fade, alpha. If "Mask Selection" is not checked "alpha" will not work.
Let us now examine the instruments in \textbf{pane 1}:
\label{sub:blur}
\index{blur}
-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:
+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. If the original source has values outside the range $(0 -1.0f)$, the plugin will always produce clipping. Blur is used to blur a video track via the following parameters:
\begin{description}
\item[Horizontal and vertical] values are used to tell which one of the fields blurring affects; can be both.
\item[Radius] use this dial to define the amount of blur to apply.
\item[Alpha determines radius] use alpha to define the amount of blur to apply. (radius=gray value of alpha)
\item[Blur alpha, red, green, blue] specifies which color channels is to be blurred.
\end{description}
+If you are getting confusing results with old projects it may be a
+result of the discontinued parameter \textit{alpha determines radius}.
+For compatibility reasons and for possible future development it
+has been left in the code but hidden in the plugin's GUI.
+The parameter for \textit{alpha determines radius} is
+\texttt{A\_KEY}, which can be 0 or 1. When you press the
+\texttt{Reset} button in the Blur plugin window \texttt{A\_KEY=0}.
+
+Old projects may have saved that parameter (A\_KEY) to 1 instead
+of 0 and that may present a problem so you should do one of
+the following workarounds to change it to 0. Then be sure to save
+your project with these changes applied.
+\begin{enumerate}
+ \item Click on the \textit{Reset} button in the dialogue/controls popup box and re-enter any of your other parameter desired values.
+ \item OR in the \CGG{} program, open the project. Click on the cog icon
+(\textit{Preset edit}) of the Blur effect bar and the \textit{Keyframe
+parameters} window is open. There, you can see the A\_KEY parameter
+and change it: select the \texttt{A\_KEY} parameter and in the
+\texttt{Edit value} box, change it from 1 to 0, then press the \texttt{OK}
+button.
+\end{enumerate}
\subsection{BoxBlur}%
\label{sub:boxblur}
\end{description}
\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.
-\paragraph{Optional postprocessing:} In order to have the values of Contrast and Brightness take effect, you must check the Postprocess checkbox.
-\begin{description}
- \item[Contrast] is the difference in brightness between objects or regions.
- \item[Brightness] refers to the overall lightness or darkness of the image.
-\end{description}
-
-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.
-
\begin{figure}[htpb]
\centering
\includegraphics[width=0.9\linewidth]{c41.png}
\label{fig:c41}
\end{figure}
+\paragraph{Optional postprocessing:} in order to have the values of Contrast and Brightness take effect, you must check the Postprocess checkbox.
+\begin{description}
+ \item[Contrast] is the difference in brightness between objects or regions.
+ \item[Brightness] refers to the overall lightness or darkness of the image.
+\end{description}
+
+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.
+
\subsection{Chroma Key}%
\label{sub:chroma_key}
\index{chroma key}
-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}).
+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}).
\begin{figure}[htpb]
\centering
\label{fig:chroma-key}
\end{figure}
-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 (Luma Key).
-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.
+Chroma key uses either the lightness or the hue to determine what is erased. \textit{Use value} singles out only the lightness to determine transparency (Luma Key).
+
+\textit{Color section}
+
+Select a key 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.
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.
-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.
+\textit{Key parameters section}
+
+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; it's a range color. 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. The \textit{Default} button returns Threshold to the value $10.0$; Slope to the value $0.0$; and Color to black (\#ff000000). The \textit{Reset} button and the \textit{reset} icons next to the sliders always return to the value $0.0$. Before the sliders are the \textit{input boxes} so that the precise numerical values can be written.
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.
-\subsection[Chroma Key (HSV)]{Chroma Key (HSV)}%
-\label{sub:chroma_key_hsv}
-\index{chroma key HSV}
+\subsection[Chroma Key (Avid)]{Chroma Key (Avid)}%
+\label{sub:chroma_key_avid}
+\index{chroma key Avid}
-Chroma Key (HSV)\protect\footnote{Credit for Plugin by Jerome Cornet \url{http://jcornet.free.fr/linux/chromakey.html}} (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}}
+Chroma Key (Avid)\protect\footnote{Credit for Plugin by Jerome Cornet; credit to original creator for major upgrade and credit to SGE for adaption and improvements. Avid is a trademark of Avid Technology, Inc.} (figure~\ref{fig:chroma-key-hsv-avid}) 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 background color that is keyed out. More information is at: {\small \url{http://en.wikipedia.org/wiki/Chromakey}}.
\begin{figure}[htpb]
- \centering
- \includegraphics[width=0.55\linewidth]{chroma-key-hsv.png}
- \caption{Keying a green screen with Chroma Key (HSV)}
- \label{fig:chroma-key-hsv}
+ \centering
+ \includegraphics[width=0.55\linewidth]{chroma_key_avid.png}
+ \caption{Windows config for Chroma Key (Avid/HSV)}
+ \label{fig:chroma-key-hsv-avid}
\end{figure}
\subsubsection*{Requirements}
\label{ssub:requirements}
-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. Another tip is to use a low-compressed, intraframe codec with as high a color depth as possible. In case of YUV-type source signal, it is better to have subsampling $4:4.4$ or $4:2:2$.
-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}.
+The subject in the timeline video 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. Another tip is to use a low-compressed, intraframe codec with as high a color depth as possible. In case of YUV-type source, it is better to have subsampling $4:4:4$ or $4:2:2$.
+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}. Any manipulations with alpha masks in \CGG{} require a bottom track with some opaque background, otherwise the transparent holes are displayed as if the same track without transparency is located under it.
\subsubsection*{Usage}
\label{ssub:usage}
-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.
+As in any other effect, drag it to the timeline in the main window. You can tweak each parameter in order to improve the keying.
-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}).
+To understand how the plugin parameters work, we need to refer to the HSV color wheel (foreground color) in figure~\ref{fig:hsv_color_wheel}. You may want to first apply the \nameref{sub:color_swatch} plugin which is very helpful in determining which variables should be modified. Consider that this is an abstract example; in the real world we will be dealing with much more complicated masks.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.9\linewidth]{hsv_color_wheel.png}
+ \caption{Various parameters in the 'Color' and 'Key Parameters' sections.}
+ \label{fig:hsv_color_wheel}
+\end{figure}
+
+The left half has Saturation from 0 in the center to 100 on the edges. An example of a green screen is shown here. The right half has brightness from 0 (center) to 100 on the edges. The example of a blue screen is given here. The key color is the radius of the wheel, and its angle determines the hue. The Hue Tolerance is the arc of a circle (a wedge) that includes the radius. The wedge is the color range (mask) that we want to eliminate by keying, its shape is precise and easy to understand. The Brightness are the inner/outer extremes of the wedge; if the inner value (Min) is 0, then it coincides with the center point, if the outer value (max) is 100 then it coincides with the arc on the circumference. With intermediate values we will have masks similar to the one shown in the figure. Min Saturation is the distance from the center, along the Hue radius, from which we want to impose saturation with the value 0. It will be the value from which keying starts. Saturation Offset is an additional cut we make to the inner part of the wedge from the Min Saturation value. All of these adjustments allow us to establish a range of colors (Mask) that perfectly matches the background (the wedge in the example in the figure~\ref{fig:hsv_color_wheel}) that we want to eliminate. This is a precision operation, and it is not rare to return to the parameter combination several times to refine the mask.
+
+\qquad \textit{Color section}
+
+In this section of the configuration window, you choose the key color and have the ability to see the mask created.
+
+\begin{description}
+ \item[Color...] Select the key color (green, blue, or whatever) using the color wheel or the color picker. 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 (Avid) parameters window, click on \textit{Use Color Picker}. You will need to disable ChromaKey (Avid) plugin when using the Color Picker on the Compositor window.
+ \item[Show Mask] The plugin does not create a true matte in the alpha channel, but creates a mask. Activating this option will show the foreground as a white (opaque) shape while the background in transparency. You will be able to control the extent of the mask, any jagged edges, small white areas within the mask or small transparency areas within the foreground, which are to be removed.
+\end{description}
+
+\qquad \textit{Key parameters section}
+
+In this section we expand the mask to a range of colors close to color key and refine the selection by also taking advantage of brightness and saturation.
\begin{description}
- \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}.
- \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.
- \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).
- \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$.
+ \item[Hue Tolerance:] Because there are slight variations in lighting in real cases, the background will not be in a uniform key color hue. Increase or decrease the Hue tolerance to mask out the background. In determining the hue range, it is useful to use the Color Swatch plugin in \textit{constant brightness} mode and with \textit{Draw Source} active, which allows us to see the pixels of the figure, making us choose which ones to let into the mask (keying out) and which ones not. If there are dark spots that are keyed out that shouldn’t be, it can be corrected later (With the \texttt{Mask} tool; this operation is called the \textit{Garbage Matte}).
+ \item[Brightness:] It allows the color range (Mask) to be better defined by exploiting the differences in brightness between background and foreground. This could be referred to as a Luma Key within the Chroma Key. Increase \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).
+ \item[Saturation:] Saturation allows the color range (Mask) to be better defined by exploiting the differences in saturation between background and foreground. Since the best results are obtained by keying pure colors, it may come in handy to eliminate the less saturated colors (proper to the foreground) while leaving the more saturated colors (proper to the background, i.e. Green/Blue Screen) to the keying action. Increase \textit{Saturation Start} so that only the background is masked out, and not parts of the foreground. \textit{Saturation Line} can be used to change this, because it acts similarly to Min Brightness. It could be said that Saturation Start concerns only the key color (wedge's vertex), while Saturation Line concerns the range of Hue tolerance. But it is best to start by leaving it at $0$.
\end{description}
Check what it looks like at this stage, your mask should be pretty
clean. Toggle \textit{Show Mask} to check what it looks like, it
-should be OK\@. If not, repeat steps $1 to 4$ to get a better
+should be OK\@. If not, repeat steps in the Key parameters section to get a better
key. The rest of the controls are useful to smear the mask to help
compositing later on. They will help you to make your key look much
cleaner.
+\qquad \textit{Mask tweaking section}
+
+In this section you intervene on the already created mask with edge smoothing and transparencies.
+
\begin{description}
- \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.
- \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$.
- \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.
+ \item[Slope:] For now, the mask is a full on/full off mask that can be really harsh on the edges and not necessarily what you are looking for. \textit{In Slope} and \textit{Out Slope} will help you to smooth that key. In Slope acts on the inner side of the edges by grading them with keying (background) colors. It leaves more colors in the mask. Out Slope acts on the outer side of the edges by grading them with the foreground colors. It takes more colors out of the mask. Basically, the colors that are borderline in the mask will see their alpha channel reduced by half instead of being completely on or off.
+ \item[Alpha Offset:] This control offsets the whole alpha channel by some amount, from -100=full opacity to +100=full transparency. Be sure to know what you are doing if you change it from the default value of $0$.
\end{description}
-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.
+\qquad \textit{Spill light control section}
+
+In this section we try to make halos, reflections and parasitic lights present on the foreground less noticeable via spill suppression.
+
+\begin{description}
+ \item[Spill saturation:] Similar to Saturation Start, indicates the starting point from which spill suppression begins. It works if Saturation Start is > 0 because it acts only from that value, with the effect of retracting the starting point moving away from the Saturation Start value toward the center of the color wheel (white). This has the consequence of creating a small area beyond the edge of the wedge where spill suppression acts. Generally you set it with a small random value > 0 and then return to it after setting Spill Angle.
+ \item[Spill Angle:] Spill Angle is the main parameter of spill suppression because it causes a very noticeable effect. Basically, it is an area that extends beyond the edge of the mask, increasing its angle and thus its size. In this area (which is a gradient) pixels of the reflections of the key color (green, for example) are mixed with pixels of the adjacent color (cyan on one side and yellow on the other, because we always refer to the HSV color wheel). The suppression effect replaces green pixels with adjacent ones, taking into account the gradient. This parameter, in addition to the spill saturation, softens the edges of the mask without resorting to desaturation to gray or white of the green pixels, which create a more visible detachment. It should not be overdone so as not to compromise the color balance of the entire figure.
+ \item[Desature Only:] It takes the parameters of Spill Saturation and Spill Angle but instead of copying the neighboring colors over the green pixels, it applies a simple desaturation of the green pixels that become gray and then totally white. The effect is more noticeable and noisy because it creates a halo around the figure.
+\end{description}
+
+In the lower part we find various buttons:
+
+\begin{description}
+ \item[Store:] Stores the complete current parameter set in memory.
+ \item[Recall:] Sets all the parameters to the values, memorized previously by Store.
+ \item[Exchange:] Swaps current values and Store'd values of the parameters.
+ \item[Undo:] Restores all the parameters to the undo'ed values.
+ \item[Reset:] Reset to default values.
+\end{description}
+
+All buttons work globally on the whole parameter set. Each time the ChromaKey dialog is opened, the \textit{Store} values are cleared and reset to default. Therefore, if you press \textit{Recall} having not pressed Store beforehand, it will do the same as \textit{Reset}. Each time the dialog is closed, the Store values are forgotten (reset to defaults). As long as the dialog remains opened, Store values remain intact, even if the current timeline position changes. The operations on distinct parameters (turning sliders etc.) do not update the \textit{Undo} values. The following operations update values for subsequent Undo: Global Recall, Exchange, Reset buttons (but not the buttons which reset individual parameters), opening the dialog, and moving current position in the timeline.
+
+Now the mask is probably still very harsh, so just below the Chromakey (Avid) 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.
+
+\subsection[Chroma Key (HSV)]{Chroma Key (HSV)}%
+\label{sub:chroma_key_hsv}
+\index{chroma key HSV}
+
+Chroma Key (HSV)\protect\footnote{Credit for Plugin by Jerome Cornet \url{http://jcornet.free.fr/linux/chromakey.html}} (figure~\ref{fig:chroma-key-hsv}) replaces a color with another color or transparency using HSV variables. This plugin is replaced by the better Chroma Key (Avid) and is maintained only for reasons of compatibility with old projects.
+Refer to Chroma Key (Avid) for theory and parameter descriptions, which are quite similar, except the description of spill suppression, which differs considerably.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.55\linewidth]{chroma-key-hsv.png}
+ \caption{Windows config for Chroma Key (HSV)}
+ \label{fig:chroma-key-hsv}
+\end{figure}
+
+\qquad \textit{Spill light control section}
+
+In this section we try to make halos, reflections and parasitic lights present on the foreground less noticeable.
+
+\begin{description}
+ \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 of the foreground that have a similar hue to the key color, turning them into gray instead of green or blue. The hues to be desaturated are set with \textit{Spill Threshold}, the degree of desaturation is set with \textit{Spill Compensation}. In order for Spill compensation to work, Spill Threshold must be > 0. If you start with Spill Compensation at $100\%$, slowly increase the \textit{Spill Threshold} until the remaining green or blue areas turn gray. Then reduce Spill Compensation until the image looks good.
+\end{description}
\subsection{Color 3 Way}%
\label{sub:color_3_way}
\item Create a Stylized look.
\end{itemize}
-When using the X11 graphics driver and RGBA-FLOAT color model, this plugin allows for greater than (0 - 1.0f) values. This does not work when using X11-OpenGL because it is an 8-bit limited driver. Both the Color wheels and the Saturation and Value sliders will make it possible to work with HDR video.
+When using the X11 graphics driver and RGBA-FLOAT color model, this plugin allows for greater than (0 - 1.0f) values (\textit{illegal} values). This does not work when using X11-OpenGL because it is an 8-bit limited driver. Illegal values will only work for the color wheel, while the Value and Saturation sliders are always clipped to 1.0f.
\subsection{Color Balance}%
\label{sub:color_balance}
from one color space/range to another. It works for both RGB and YUV as set by your project format.
Options are BT601, BT709, or BT2020 for Color Space input and output and JPEG or MPEG for Color Range
input and output. The Inverse option checkbox is available in case your media was rendered in the wrong
-color space or range so that you can fix it.
+color space or range so that you can fix it. By its nature, this plugin will always cause clipping on values above 1.0f.
+
+\begin{figure}[H]
+ \centering
+ \includegraphics[width=0.6\linewidth]{colorspace.png}
+ \caption{ColorSpace control window}
+ \label{fig:colorspace}
+\end{figure}
\textbf{Algorithm for conversion} -- where equations is a $3\times3$ matrix multiply
\qquad $input = (output - output\_zero) \times inverse\_equations + input\_zero$
-\begin{figure}[hbtp]
- \centering
- \includegraphics[width=0.6\linewidth]{colorspace.png}
- \caption{ColorSpace control window}
- \label{fig:colorspace}
-\end{figure}
+\subsection[Color Swatch]{Color Swatch}%
+\label{sub:color_swatch}
+Color Swatch is mainly used together with the two chroma key plugins. It should be applied first so that its output becomes the input for the chroma key.
+
+\begin{description}
+ \item[Constant Brightness:] creates the HSV color wheel in which the brightness is constant and you can only move the Brightness slider.
+ \item[Costant Saturation:] creates the HSV color wheel in which saturation is constant and you can only move the Saturation slider.
+ \item[Angle:] turns the HSV color wheel by a certain angle.
+ \item[Draw Source:] is analogous to vectorscope; shows the pixels of the upper track (figure + background = source) superimposed on the HSV color wheel. It basically displays the source colors that are also present in the color wheel, but not the others. You can easily see which colors fall within the wedge (mask) and are therefore extracted, while those outside make up the unextracted figure. This makes it easier to adjust the key color and the hue range according to our needs.
+\end{description}
\subsection{CriKey}%
\label{sub:crikey}
Denoise video (figure~\ref{fig:denoise}).
-\begin{figure}[htpb]
+\begin{figure}[H]
\centering
\includegraphics[width=0.4\linewidth]{denoise.png}
\caption{Control window of the DeNoise plugin}
\label{sub:difference_key}
\index{difference key}
+\begin{figure}[H]
+ \centering
+ \includegraphics[width=0.65\linewidth]{diff-key.png}
+ \caption{Difference key and its problematic output}
+ \label{fig:diff-key}
+\end{figure}
+
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.
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.
\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}).
-\begin{figure}[htpb]
- \centering
- \includegraphics[width=0.8\linewidth]{diff-key.png}
- \caption{Difference key and its problematic output}
- \label{fig:diff-key}
-\end{figure}
-
\subsection{DotTV}%
\label{sub:dottv}
\index{dotTV}
\label{sub:foreground}
\index{foreground}
-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, or by entering the hexadecimal value.
-In addition there are HSV, RGB, YUV, and alpha sliders to vary the color accordingly.
+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, or by entering the hexadecimal value. In addition there are HSV, RGB, YUV, and alpha sliders to vary the color accordingly. If the original source has values outside the range $(0 -1.0f)$, the plugin will always produce clipping.
\subsection{Frames to fields}%
\label{sub:frames_to_fields}
\label{sub:histogram_bezier_curves}
\index{histogram Bezier}
-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 (bins). 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. The scale is given in percent ($0 - 100\% \pm 10\%$). The default curve is Log type and can use either RGB or YUV sources without implementing conversions.
+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 (bins). 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. The scale is given in percent ($0 - 100\% \pm 10\%$). The default curve is Log type and can use either RGB or YUV sources without implementing conversions. If the original source has values outside the range $(0 -1.0f)$, the plugin will always produce clipping.
NOTE: Histogram Bezier may give results that are not congruent with Histogram plugin. To understand the difference in behavior see the Theory section in Histogram plugin.
This effect acts only in one direction which can vary up to an angle of $180\degree$ with these parameters:
-\begin{figure}[htpb]
+\begin{figure}[H]
\centering
\includegraphics[width=0.8\linewidth]{linear.png}
\caption{For clarity of presentation only 2 fields are shown}
\label{sub:live_video}
\index{live video}
-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.
+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.
+There is a limitation when both Audio and Video use DV, in that you can not use this plugin at the same time as \textit{Live Audio}.
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.
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.
-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.
+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 which will make it possible to process video input in real time.
\subsection{Loop video}%
\label{sub:loop_video}
\begin{description}
\item[Target Track:] you can choose between \textit{Top} and \textit{Bottom}.
- \item[Operation:] you can choose between \textit{Replace Target} (component + alpha channels); \textit{Components Only} (color channels only) and \textit{Alpha Replace} (alpha channel only)
+ \item[Operation:] you can choose between \textit{Replace Target}, \textit{Components Only} and \textit{Alpha Replace}.
+ \begin{itemize}
+ \item \textit{replace Target} (component + alpha channels), this allows you to have the ability to overwrite everything on the target track with the source track where the the plugins are inserted.
+ \item \textit{Components only} (color channels only), replace the RGB or YUV components of the target track by the RGB or YUV components of the source track. The Alpha of the target track does not change.
+ \item \textit{Alpha replace} (alpha channel only), only the Alpha of the target track is changed but the components are not. This makes it easy to create an alphs channel on a track and then use that to apply it easily to another track.
+ \end{itemize}
\end{description}
It works as a 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 target track.
\label{sub:swap_channels}
\index{swap channels}
-Swap R G, B, Alpha with another color channel.
+Swap color, R G B, and Alpha channels with another channel or even turn channels off completely.
\subsection{Threshold}%
\label{sub:threshold}
Time average is one effect which has many uses besides creating trail patterns of moving objects (figure~\ref{fig:timeaverage}).
The main use is reducing noise in still images (or in the motionless parts of a video). Merely point a video camera at a stationary subject for $30$ frames, capture the frames, and average them using time average and you will have a high quality print. In floating point color models, time average can increase the dynamic range of low quality cameras.
-Inside the time average effect is an accumulation buffer and a divisor. A number of frames are accumulated in the \textit{accumulation} buffer and divided by the divisor to get the average (for $10$ accumulated frames the divisor is $10$). Because the time average can consume large amounts of memory, it is best applied by first disabling playback for the track, dropping the time average in it, configuring time average for the desired number of frames, and re-enabling playback for the track.
-
\begin{figure}[hbtp]
\centering
\includegraphics[width=0.3\linewidth]{timeaverage.png}
\label{fig:timeaverage}
\end{figure}
+Inside the time average effect is an accumulation buffer and a divisor. A number of frames are accumulated in the \textit{accumulation} buffer and divided by the divisor to get the average (for $10$ accumulated frames the divisor is $10$). Because the time average can consume large amounts of memory, it is best applied by first disabling playback for the track, dropping the time average in it, configuring time average for the desired number of frames, and re-enabling playback for the track.
+
\begin{description}
\item[Frames count] this determines the number of frames to be accumulated in the accumulation buffer. Ranges from $1 to 1024$ frames.
\item[Accumulate] this outputs the accumulation buffer without dividing it.
\label{sub:title}
\index{title}
-The \textit{Titler} allows you to add text from within \CGG{}. It has many configuration capabilities. Often it is convenient to apply the plugin on a separate track (shared or not), in order to make it independent from the video track and have more freedom in editing and configuration. For example, you can apply the \textit{Rotation} plugin to rotate the title without rotating the underlying video. Another thing to keep in mind when using the Titler plugin is that it works on the \textit{temporary} and therefore it is not affected by Camera movements (curves), but only by Projector movements.
+The \textit{Titler} allows you to add text from within \CGG{}. It has many configuration capabilities. Often it is convenient to apply the plugin on a separate track (shared or not), in order to make it independent from the video track and have more freedom in editing and configuration. For example, you can apply the \textit{Rotation} plugin to rotate the title without rotating the underlying video. Another thing to keep in mind when using the Titler plugin is that it works on the \textit{temporary} and therefore it is not affected by Camera movements (curves), but only by Projector movements. If the original source has values outside the range $(0 -1.0f)$, the plugin will always produce clipping.
The titler has standard options for font, size, and style plus many options as described next (figure~\ref{fig:title01})
\label{fig:videoscope01}
\end{figure}
-When using the X11 graphics driver and RGBA-FLOAT color model, Videoscope allows you to display greater than (0 - 1.0f) values to accomodate HDR. This does not work when using X11-OpenGL because it is an 8-bit limited driver. The display will stop at -10\% or +110\%, but there is no clipping. For example, by varying the brightness all out-of-range values become visible on Waveform, even over 110\%. However you must disable the "smooth" option which always causes clipping.
+If the original source has values outside the range $(0 -1.0f)$, the plugin will always produce clipping. The display will stop at -10\% or +110\%, but there is no clipping. For example, by varying the brightness all out-of-range values become visible on Waveform, even over 110\%. However you must disable the "smooth" option which always causes clipping.
The Videoscope menu window has many options.
The Vectorscope displays \textit{hue} (angle on the color wheel) and \textit{saturation} (radius). Each pixel in the source image is drawn as a point on the color wheel. The distance from the center is the color saturation. Gray values are close to the center, and high saturation values are near the perimeter ($100\%$). In the center there is pure white ($0\%$). By clicking with the mouse on the color wheel a radius and circle will appear whose values of hue and saturation are shown in the pop-up box at the bottom right of the window, similar to the values of $X$ and luminance of the Waveform and RGB Parade (figure~\ref{fig:videoscope05}).
-\begin{figure}[hbtp]
+\begin{figure}[H]
\centering
- \includegraphics[width=0.8\linewidth]{videoscope05.png}
+ \includegraphics[width=0.75\linewidth]{videoscope05.png}
\caption{Vectorscope (with H/S pop-up box) and VectorWheel (with 3 default grids)}
\label{fig:videoscope05}
\end{figure}
-Note that when you choose \textit{VectorWheel} from \textit{Scopes} pulldown, you can choose between different grids in the \textit{Settings} pulldown. In addition, any number of user-supplied grid patterns can be added in the form of a square image of type png. The user can design and maintain individual grid overlays for various purposes. The user would keep their overlays in a safe spot on their disk and make a copy of them in the \texttt{\{cinelerra\_pathname\}/bin/plugins/scopes} every time a new version of \CGG{} is installed.
+Note that when you choose \textit{VectorWheel} from \textit{Scopes} pulldown, you can choose between different grids in the \textit{Settings} pulldown. In addition, any number of user-supplied grid patterns can be added in the form of a square image of type png. The user can design and maintain individual grid overlays for various purposes. The user would keep their overlays in a safe spot on their disk and make a copy of them in the \texttt{\{cinelerra\_pathname\}/bin /plugins/scopes} every time a new version of \CGG{} is installed.
Generally the Vectorscope has the following uses:
\label{fig:yuvshift}
\end{figure}
-This effect is used for YUV input video from older cameras using $3$ sensors. It is possible to have misalignment of the $3$ sets of numbers: \textit{Y}, which represents the luminance or brightness component, and for \textit{U} and \textit{V} representing the chrominance (color) components. If they were misaligned in the video, you can use \textit{YUVShift} to realign. To move a specific component up/down, modify the \textit{dy} value using the slider bar in the RGBShift window. To move a component left/right, modify the corresponding \textit{dx} value. For maximum precision you can use the input box. With the \textit{Clear} buttons we can bring the slider to default values without affecting the other parameters. If you are using an RGB color space, you will want to use the \textit{RGBShift} effect instead.
+This effect is used for YUV input video from older cameras using $3$ sensors. It is possible to have misalignment of the $3$ sets of numbers: \textit{Y}, which represents the luminance or brightness component, and for \textit{U} and \textit{V} representing the chrominance (color) components. If they were misaligned in the video, you can use \textit{YUVShift} to realign. To move a specific component up/down, modify the \textit{dy} value using the slider bar in the YUVShift window. To move a component left/right, modify the corresponding \textit{dx} value. For maximum precision you can use the input box. With the \textit{Clear} buttons we can bring the slider to default values without affecting the other parameters. If you are using an RGB color space, you will want to use the \textit{RGBShift} effect instead.
Figure~\ref{fig:yuvshift} (top) shows the blue \textit{U} component aligned too far to the right/down. And the red \textit{V} component is misaligned too far to the right/down. Note the \textit{U\_dx} current slider bar set to $0$ as shown by the input box value in the YUVShift plugin window. All components are currently at zero.
A corrected video image is shown in the bottom. Now the red and blue colors are correctly aligned. Note how \textit{U\_dx} is now at $+26$ and \textit{V\_dx} is now $+41$ to realign the image.
To build findobject and the other plugins using OpenCV, access the src using git:
\begin{lstlisting}[style=sh]
-git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
+git clone --depth 1 git://git.cinelerra-gg.org/goodguy/cinelerra.git cinelerra5
\end{lstlisting}
To use the latest version, the method for creating a tarball is:
\textit{PuzzleObj} makes a puzzle out of an image. You can make the puzzle pieces smaller or larger with the Pixels slider bar. The Iterations slider bar allows for varying morphing distance (figure~\ref{fig:opencv}).
-\begin{figure}[htpb]
+\begin{figure}[H]
\centering
\includegraphics[width=0.8\linewidth]{opencv.png}
\caption{FlowObj; GaborObj (before and after) and PuzzleObj}
projects / goodguy / cin-manual-latex.git / blobdiff