\chapter{Plugins}%
\label{cha:plugins}
-There are realtime effects --- these are the most useful and probably all you will ever need --- and rendered effects. The rendered effects are discussed separately in the Rendered Effects \todo{internal link 1}%
-section. 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 Cinelerra-GG 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.
+There are realtime effects --- these are the most useful and probably all you will ever need --- and rendered effects.
+The rendered effects are discussed separately in the \nameref{sec:rendered_effects} section.
+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 Cinelerra-GG 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
\includegraphics[width=0.7\linewidth]{images/button-options.png}
\end{wrapfigure}
-The rightmost knob is used to \texttt{Turn Off/Turn On} the effect where the default is On. This is useful to easily see that the plugin is doing what you expect. The leftmost symbol that looks like a gear is for \textit{Preset Edit} and its usage is described in the section Saved Plugin Presets.
- \todo{internal link 2}%
+The rightmost knob is used to \texttt{Turn Off/Turn On} the effect where the default is On. This is useful to easily see that the plugin is doing what you expect. The leftmost symbol that looks like a gear is for \textit{Preset Edit} and its usage is described in the section \nameref{sec:saved_plugin_preset}.
\section{Editing Effects}%
\label{sec:editing_effects}
Many operations exist for manipulating effects once they are on the timeline. Because mixing effects and media is quite complex, the methods used in editing effects are not as concise as cutting and pasting. Some of the editing happens by dragging in/out points, some of the editing happens through popup menus, and some of it happens by dragging effects.
-When enabled, which is the default, and you edit tracks, the effects follow the editing decisions. If you cut from a track, the effect shrinks. If you drag edit in/out points, the effect changes length. This behavior can be disabled by selecting \texttt{Settings$\rightarrow$ Preferences$\rightarrow$ Interface tab$\rightarrow$ Editing section} (figure~\ref{fig:editing-effects}).
+When enabled, which is the default, and you edit tracks, the effects follow the editing decisions. If you cut from a track, the effect shrinks. If you drag edit in/out points, the effect changes length. This behavior can be disabled by selecting \texttt{Settings$\rightarrow$ Preferences$\rightarrow$ Interface tab$\rightarrow$ Editing section}, see figure~\ref{fig:editing-effects}.
\begin{figure}[htpb]
\centering
\section{Saved Plugin Presets}%
\label{sec:saved_plugin_preset}
-\textit{Presets} and \textit{Factory Presets} for Plugin settings are now combined with the Preset Keyframe Parameters allowing you to choose, apply, delete, and edit your own Presets which can then be easily saved in the file \texttt{\$HOME/.bcast5/Cinelerra\_presets}. In addition to your own saved presets, there are automatically available Factory presets for some plugins, for example the Lens video plugin. The Factory presets are preceded by an asterisk (*) and can not be modified permanently.
+\textit{Presets} and \textit{Factory Presets} for Plugin settings are now combined with the Preset Keyframe Parameters allowing you to choose, apply, delete, and edit your own Presets which can then be easily saved in the file \texttt{\$HOME/.bcast5/Cinelerra\_\\presets}. In addition to your own saved presets, there are automatically available Factory presets for some plugins, for example the Lens video plugin. The Factory presets are preceded by an asterisk (*) and can not be modified permanently.
-\begin{wrapfigure}[3]{r}{0.3\linewidth}
- \vspace{-4ex}
+\begin{wrapfigure}[4]{r}{0.3\linewidth}
+ \vspace{-2ex}
\centering
\includegraphics[width=0.7\linewidth]{images/preset.png}
\end{wrapfigure}
For some System installs, the files might be located at:
-\texttt{/usr/lib/cin/plugins/picon/cinfinity} (or cinfinity2, original or smoother) (ubuntu distros)
+\texttt{/usr/lib/cin/plugins/picon/cinfinity}
+
+(or cinfinity2, original or smoother --- ubuntu distros)
+
+\texttt{/usr/lib64/cin/plugins/picon/cinfinity}
-\texttt{/usr/lib64/cin/plugins/picon/cinfinity} (or cinfinity2, original or smoother) (Leap distro)
+(or cinfinity2, original or smoother --- Leap distro)
\subsection{Details on where to put your own Plugin Icons}%
\label{sub:details_put_plugin_icons}
\item If there is currently no theme-specific \texttt{.png} files present, it may be necessary to first create the theme directory in \texttt{<cinlib\_path>plugins} as \texttt{<theme\_name>} in order to put the \texttt{.png} files in that subdirectory.
\item Make sure that the \textit{ownership} and file \textit{permissions} match the existing directory and files.
\item All ffmpeg icons must begin with \texttt{ff\_<plugin\_name>.png} (Resources window title will still be \texttt{F\_\dots})
- \item For ladspa, check in the \texttt{<cin\_config>} directory (\texttt{\$HOME/.bcast5} normally) and look for the text file \texttt{\$HOME/.bcast5/ladspa\_plugins\dots} for the names of the ladspa libraries which correspond to plugin names where the needed name is the basename of the \texttt{.so} file. For example \texttt{phasers\_1217.so} would need to have a \texttt{phasers\_1217.png} file. There may be multiple plugins in a single “so” file which means that you can only have 1 icon to represent all of the plugins in that file; again as in phasers.
+ \item For ladspa, check in the \texttt{<cin\_config>} directory (\texttt{\$HOME/.bcast5} normally) and look for the text file \texttt{\$HOME/.bcast5/ladspa\_plugins\dots} for the names of the ladspa libraries which correspond to plugin names where the needed name is the basename of the \texttt{.so} file.
+ For example \texttt{pha\-sers\_1217.so} would need to have a \texttt{phasers\_1217.png} file. There may be multiple plugins in a single “so” file which means that you can only have 1 icon to represent all of the plugins in that file; again as in phasers.
\item Once you have placed the .png file in the correct spot, you will have to restart Cinelerra to test it.
\item To submit your .png file for inclusion into Cinelerra-GG Infinity for all to enjoy, it is best to upload it to any datafilehost and notify the community via email with any informative documentation.
\end{itemize}
\subsection{Expanders for Plugin Subtrees in the Resources Window}%
\label{sub:expanders_plugin_subtrees}
-To accentuate a set of common plugins, there are \textit{expander} arrows on the left side of the Resources window. You will see these expanders only when in \textit{Display text} mode, not \textit{icon} mode. Cinelerra’s default setup is in the file \texttt{\$CIN\_DAT/expanders.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}).
+To accentuate a set of common plugins, there are \textit{expander} arrows on the left side of the Resources window. You will see these expanders only when in \textit{Display text} mode, not \textit{icon} mode.
+Cinelerra’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. Here is a short example:
\label{sub:audioscope}
Convert input audio to video output representing the audio power spectrum. Shows
- \todo{It's OK to use Subsection every plugin?}%
+% Yes
+ %\todo{It's OK to use Subsection every plugin?}%
you the sound wave.
\subsection{Compressor}%
export LV2_PATH=/tmp/j/balance.lv2/usr/local/lib/lv2/:/usr/local/lv2
\end{lstlisting}
-If there is no default \texttt{LV2\_PATH} set automatically, the value will be \texttt{\$CIN\_DAT/lv2}, which is a placeholder only so that no lv2 plugins will be loaded. When there is no system \texttt{LV2\_PATH} set it is important to note, that if you do want lv2 plugins loaded, you must set the correct path in:
+If there is no default \texttt{LV2\_PATH} set automatically, the value will be \texttt{\$CIN\_DAT/\\lv2}, which is a placeholder only so that no lv2 plugins will be loaded. When there is no system \texttt{LV2\_PATH} set it is important to note, that if you do want lv2 plugins loaded, you must set the correct path in:
-\texttt{Settings$\rightarrow$Preferences$\rightarrow$Interface tab$\rightarrow$ Default LV2$\rightarrow$ directory \\
+\texttt{Settings$\rightarrow$Preferences$\rightarrow$Interface tab$\rightarrow$ Default LV2$\rightarrow$ direc\-tory
path name}
When you change this field, cin will automatically restart and load the newly specified lv2 plugins. If when switching \texttt{LV2\_PATH} or if the lv2 audio plugins are not displayed/usable in the Resources window, you can execute a reload via:
-\texttt{Settings$\rightarrow$ Preferences$\rightarrow$ Interface tab$\rightarrow$ Reload plugin index} \\
-or else before you bring up cinelerra, delete \texttt{\$HOME/.bcast5/Cinelerra\_plugins} so that the plugins get properly reloaded.
+\texttt{Settings$\rightarrow$ Preferences$\rightarrow$ Interface tab$\rightarrow$ Reload plugin in\-dex}
+or else before you bring up cinelerra, delete \texttt{\$HOME/.bcast5/Cinelerra\_\\plugins} so that the plugins get properly reloaded.
There are some lv2 plugins that display a \textit{glitzy} UI (User Interface); for example the \textit{Calf plugins}. For these LV2 plugins, if you want that to automatically come up without having to click on the UI button on the simplified UI interface, there is a flag to enable that. It is at:
\item Add 2 BlueBanana plugins on the first track. Turn off all checkboxes in both plugins.
\item On the top plugin, use the top pane to create a selection mask, using \texttt{Mark Selected Areas}.
\item Turn off top plugin \texttt{Mark Selected Areas}, and disable the top plugin via the plugin title bar on/off.
- \item Create another selection using the second plugin's mask, using \texttt{Mark Selected Areas}.
+ \item Create another selection using the second plugin's mask, using \texttt{Mark Selec\-ted Areas}.
\item Turn on the top plugin. Make sure both plugins \texttt{Mark Selected Areas} is off.
\item Check \texttt{Mask Selection} and \texttt{Filter Active} in both.
\item Check \texttt{Combine Selection} on second BlueBanana to see the final results.
Makes your video burn where there are small light colored patches of video. This came from \url{https://effectv.com}.
-\subsection{C41\protect\footnote{credit Florent Delannoy, original program code author, and Edouard Chalaron}}%
+\subsection[C41]{C41\protect\footnote{credit Florent Delannoy, original program code author, and Edouard Chalaron}}%
\label{sub:c41}
The C41 plugin takes a $16\,bit C41$ digital intermediate negative film as input and outputs a positive image. It became necessary because $C-41$ negatives can fade or color-shift over time which was a problem early on. It is still important today because there is a large amount of documentaries, video clips, and other media out there that was shot on super $16$ film. This works for RGB-float, RGB, and also YUV variations.
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)\protect\footnote{Credit for Plugin by Jerome Cornet http://jcornet.free.fr/linux/chromakey.html}}%
+\subsection[Chroma Key (HSV)]{Chroma Key (HSV)\protect\footnote{Credit for Plugin by Jerome Cornet http://jcornet.free.fr/linux/chromakey.html}}%
\label{sub:chroma_key_hsv}
Chroma Key (HSV) (figure~\ref{fig:chroma-key-hsv}) replaces a color with another color or transparency using HSV variables; it is frequently used to remove a color from a video to composite with another image. This process is generally referred to as green screen or blue screen process (because of the color that is keyed out). More information: \url{http://en.wikipedia.org/wiki/Chromakey}
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.
-Start with \texttt{Hue Tolerance} at $10\%$, \texttt{Min Brightness} at $0$, \texttt{Max brightness} at $100\%$, \texttt{Saturation offset} at $0$, \texttt{Min Saturation} at $0$, \texttt{In Slope} at $0$, \texttt{Out Slope} at $0$, \texttt{Alpha Offset} at $0$ (that’s mid-way through), \texttt{Spill Threshold} at $0$, \texttt{Spill Compensation} at $100\%$. At any time, you can check what the Mask looks like by clicking on \texttt{Show Mask}. This will output a black and white image of the mask (\textit{matte}).
+Start with \texttt{Hue Tolerance} at $10\%$, \texttt{Min Bright\-ness} at $0$, \texttt{Max bright\-ness} at $100\%$, \texttt{Saturation offset} at $0$, \texttt{Min Saturation} at $0$, \texttt{In Slope} at $0$, \texttt{Out Slope} at $0$, \texttt{Alpha Offset} at $0$ (that’s mid-way through), \texttt{Spill Threshold} at $0$, \texttt{Spill Compensation} at $100\%$. At any time, you can check what the Mask looks like by clicking on \texttt{Show Mask}. This will output a black and white image of the mask (\textit{matte}).
\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 \texttt{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 \texttt{Use Color Picker}.
\begin{figure}[htpb]
\centering
- \includegraphics[width=0.8\linewidth]{images/descratch02.png}
+ \includegraphics[width=0.6\linewidth]{images/descratch02.png}
\caption{Various parameters of DeScratch}
\label{fig:descratch02}
\end{figure}
This is used to decrease the frame rate of a video. Changing the frame rate means eliminating a frame for any given number of frames ($1 in N$); but if frames that are important for visual continuity are deleted, temporal artifacts arise: flickering, slowdowns, accelerations, etc. The Decimate filter maintains a higher quality because it first eliminates duplicate frames or frames that are most similar, thus limiting the appearance of artifacts. It is often used after the \texttt{Invert Telecine} plugin to make the video more smooth.
-One use of the decimate effect can be applied to a DVD to convert the $29.97\,fps$ video to the $23.97\,fps$ film rate, but the effect can take any input rate and convert it to any lower output rate. The output rate of decimate is the project frame rate. The input rate is set in the decimate user interface. To convert $29.97\,fps$ progressive video to $23.97\,fps$ film, apply a decimate effect to the track. Set the decimate input rate to $29.97$ and the project rate to $23.97$.
+One use of the decimate effect can be applied to a DVD to convert the 29.97\,\emph{fps} video to the 23.97\,\emph{fps} film rate, but the effect can take any input rate and convert it to any lower output rate. The output rate of decimate is the project frame rate. The input rate is set in the decimate user interface. To convert 29.97\,\emph{fps} progressive video to 23.97\,\emph{fps} film, apply a decimate effect to the track. Set the decimate input rate to 29.97 and the project rate to 23.97.
Keep in mind that every effect layered before decimate, processes video at the decimate input rate and every effect layered after decimate, processes video at the project frame rate. Computationally intensive effects should come below decimate.
\begin{figure}[htpb]
\centering
\includegraphics[width=0.8\linewidth]{images/diff-key.png}
- \caption{Control window of the DeNoise plugin}
+ \caption{Difference key and its problematic output}
\label{fig:diff-key}
\end{figure}
\subsection{HolographicTV}%
\label{sub:holographictv}
-Incoming objects are projected like holovision seen in the movie Stars Wars as in R2-D2's video message projector of the Princess Leia. You need a movie or background image and above it a track containing the figure on which to apply the effect. This must have a transparent background. There are no configuration parameters; it only has to be applied to the upper track (figure~\ref{fig:holographictv}). This effect originated from \url{https://effectv.com}.
+Incoming objects are projected like holovision seen in the movie Stars Wars as in R2-D2's video message projector of the Princess Leia. You need a movie or background image and above it a track containing the figure on which to apply the effect. This must have a transparent background. There are no configuration parameters; it only has to be applied to the upper track (figure~\ref{fig:holographictv}).
+
+This effect originated from \url{https://effectv.com}.
\begin{figure}[htpb]
\centering
\subsection{Inverse Telecine}%
\label{sub:inverse_telecine}
-This is the most effective deinterlacing tool when the footage is a video transfer of a film. This can be used to solve the problem, i.e., undo the damage caused by making film into a TV broadcast. That process came about because film is at $24\,fps$ while TV is at $29.97\,fps$ and fields are at $60$. So the film was converted from 24 fps to $60\,fps$. Roughly speaking, converting every $4$ frames into $5$ frames plus a slight slow down in speed. Then the $60\,fps$ was down-sampled to $30\,fps$ by extracting odd and even lines and interlacing the lines. This process is referred to as \textit{three-two pull down} ($3:2$ pull down) in filmmaking and television production for the post production process of transferring film to video.
+This is the most effective deinterlacing tool when the footage is a video transfer of a film. This can be used to solve the problem, i.e., undo the damage caused by making film into a TV broadcast.
+That process came about because film is at 24\,\emph{fps} while TV is at 29.97\,\emph{fps} and fields are at 60.
+So the film was converted from 24\,\emph{fps} to 60\,\emph{fps}.
+Roughly speaking, converting every 4 frames into 5 frames plus a slight slow down in speed.
+Then the 60\,\emph{fps} was down-sampled to 30\,\emph{fps} by extracting odd and even lines and interlacing the lines.
+This process is referred to as \textit{three-two pull down} ($3:2$ pull down) in filmmaking and television production for the post production process of transferring film to video.
The three-two pull down is where the telecine adds a third video field (a half frame) to every second video frame, but the untrained eye cannot see the addition of this extra video field.
-The \texttt{IVTC} effect is primarily a way to convert \textit{interlaced} video to \textit{progressive} video. It reverses the effect of three patterns of interlacing. In the next lines \texttt{A}, \texttt{B}, and \texttt{C} represent fields.
+The \texttt{IVTC} effect is primarily a way to convert \textit{interlaced} video to \textit{progressive} video.
+It reverses the effect of three patterns of interlacing. In the next lines \texttt{A}, \texttt{B}, and \texttt{C} represent fields.
\texttt{A AB BC CD D}
The \texttt{motion tracker} is almost a complete application in itself. The motion tracker tracks two types of motion: \textit{translation} and \textit{rotation}. It can track both simultaneously or one only. It can do $\frac{1}{4}$ pixel tracking or single pixel tracking. It can stabilize motion or cause one track to follow the motion of another track. Although the motion tracker is applied as a realtime effect, it usually must be rendered to see useful results. The effect takes a long time to precisely detect motion so it is very slow.
-Motion tracker works by using one region of the frame as the region to track. It compares this region between $2$ frames to calculate the motion. This region can be defined anywhere on the screen. Once the motion between $2$ frames has been calculated, a number of things can be done with that \textit{motion vector}. It can be scaled by a user value and clamped to a maximum range. It can be thrown away or accumulated with all the motion vectors leading up to the current position.
+Motion tracker works by using one region of the frame as the region to track (Match Box). It compares this region between $2$ frames to calculate the motion. This region can be defined anywhere on the screen. Once the motion between $2$ frames has been calculated, a number of things can be done with that \textit{motion vector}. It can be scaled by a user value and clamped to a maximum range. It can be thrown away or accumulated with all the motion vectors leading up to the current position.
-To save time the motion result can be saved for later reuse, recalled from a previous calculation, or discarded. The motion tracker has a notion of $2$ tracks, the \textit{master} layer and the \textit{target} layer. The master layer is where the comparison between $2$ frames takes place. The target layer is where motion is applied either to track or compensate for the motion in the master layer.
+To save time the motion result can be saved in a file for later reuse, recalled from a previous calculation, or discarded. The motion tracker has a notion of $2$ tracks, the \textit{master} layer and the \textit{target} layer. The master layer is where the comparison between $2$ frames takes place. The target layer is where motion is applied either to track or compensate for the motion in the master layer.
Motion tracking parameters:
\begin{description}
\item[Track translation] Enables translation operations. The motion tracker tracks $X$ and $Y$ motion in the master layer and adjusts $X$ and $Y$ motion in the target layer.
- \item[Translation block size] For the translation operations, a block is compared to a number of neighboring blocks to find the one with the least difference. The size of the block to search for is given by this parameter.
+ \item[Translation block size] For the translation operations, a block is compared to a number of neighboring blocks to find the one with the least difference. The size of the Match Box to search for is given by this parameter.
\item[Translation search radius] The size of the area to scan for the translation block.
\item[Translation search steps] Ideally the search operation would compare the translation block with every other pixel in the translation search radius. To speed this operation up, a subset of the total positions is searched. Then the search area is narrowed and re-scanned by the same number of search steps until the motion is known to $\frac{1}{4}$ pixel accuracy.
\item[Block X, Y] These coordinates determine the center of the translation block based on percentages of the width and height of the image. The center of the block should be part of the image which is visible at all times.
\item[Rotation search radius] This is the maximum angle of rotation from the starting frame the rotation scanner can detect. The rotation scan is from this angle counterclockwise to this angle clockwise. Thus the rotation search radius is half the total range scanned.
\item[Rotation search steps] Ideally every possible angle would be tested to get the rotation. To speed up the rotation search, the rotation search radius is divided into a finite number of angles and only those angles compared to the starting frame. Then the search radius is narrowed and an equal number of angles is compared in the smaller radius until the highest possible accuracy is achieved. Normally you need one search step for every degree scanned. Since the rotation scanner scans the rotation search radius in two directions, you need two steps for every degree in the search radius to search the complete range.
\item[Draw vectors] When translation is enabled, $2$ boxes are drawn on the frame. One box represents the translation block. Another box outside the translation block represents the extent of the translation search radius. In the center of these boxes is an arrow showing the translation between the $2$ master frames. When rotation is enabled, a single box the size of the rotation block is drawn rotated by the amount of rotation detected.
- \item[Track single frame] When this option is used the motion between a single starting frame and the frame currently under the insertion point is calculated. The starting frame is specified in the Frame number box. The motion calculated this way is taken as the absolute motion vector. The absolute motion vector for each frame replaces the absolute motion vector for the previous frame. Settling speed has no effect on it since it does not contain any previous motion vectors. Playback can start anywhere on the timeline since there is no dependence on previous results.
- \item[Track previous frame] Causes only the motion between the previous frame and the current frame to be calculated. This is added to an absolute motion vector to get the new motion from the start of the sequence to the current position. After every frame processed this way, the block position is shifted to always cover the same region of the image. Playback must be started from the start of the motion effect in order to accumulate all the necessary motion vectors.
+ \item[Track single frame] When this option is used the motion between a single starting frame and the frame currently under the insertion point is calculated. The starting frame is specified in the Frame number box. The motion calculated this way is taken as the absolute motion vector. The absolute motion vector for each frame replaces the absolute motion vector for the previous frame. Settling speed has no effect on it since it does not contain any previous motion vectors. Playback can start anywhere on the timeline since there is no dependence on previous results. We talk about \textit{Keep shape} and it is the most precise way to calculate the motion vector; but it only works well when the object to be traced does not change along the clip, remaining identical in shape, size and without rotation.
+ \item[Track previous frame] Causes only the motion between the previous frame and the current frame to be calculated (\textit{Follow shape}). This is added to an absolute motion vector to get the new motion from the start of the sequence to the current position. After every frame processed this way, the block position is shifted to always cover the same region of the image. Playback must be started from the start of the motion effect in order to accumulate all the necessary motion vectors. This method is less precise because you have error propagation between frames. However, it is essential when the object changes shape or size or rotates.
\item[Previous frame same block] This is useful for stabilizing jerky camcorder footage. In this mode the motion between the previous frame and the current frame is calculated. Instead of adjusting the block position to reflect the new location of the image, like Track Previous Frame does, the block position is unchanged between each frame. Thus a new region is compared for each frame.
\item[Master layer] This determines the track which supplies the starting frame and ending frame for the motion calculation. If it is Bottom the bottom track of all the tracks sharing this effect is the master layer. The top track of all the tracks is the target layer.
\item[Calculation] This determines whether to calculate the motion at all and whether to save it to disk. If it is \textit{Don't Calculate} the motion calculation is skipped. If it is \textit{Recalculate} the motion calculation is performed every time each frame is rendered. If it is \textit{Save} the motion calculation is always performed but a copy is also saved. If it is \textit{Load}, the motion calculation is loaded from a previous save calculation. If there is no previous save calculation on disk, a new motion calculation is performed.
Since it is a very slow effect, there is a method to applying the motion tracker to get the most out of it. First disable playback for the track to do motion tracking on. Then drop the effect on a region of video with some motion to track. Then rewind the insertion point to the start of the region. \texttt{Set Action$\rightarrow$ Do Nothing}; \texttt{Set Calculation$\rightarrow$ Don't calculate}; Enable \texttt{Draw vectors}. Then enable playback of the track to see the motion tracking areas.
-Enable which of translation motion or rotation motion vectors you want to track. By watching the compositor window and adjusting the \texttt{Block x,y} settings, center the block on the part of the image you want to track. Then set \texttt{search radius}, \texttt{block size}, and \texttt{block coordinates} for translation and rotation.
+Enable which of translation motion or rotation motion vectors you want to track. By watching the compositor window and adjusting the \texttt{Block x,y} settings, center the block on the part of the image you want to track. It is advisable to choose elements that have evident edges in the $x$ and $y$ directions because the calculations are made on these coordinates. Then set \texttt{search radius}, \texttt{block size} and \texttt{block coordinates} for translation and rotation.
Once this is configured, set the calculation to \texttt{Save coords} and do test runs through the sequence to see if the motion tracker works and to save the motion vectors. Next, disable playback for the track, disable \texttt{Draw vectors}, set the motion action to perform on the target layer and change the calculation to \texttt{Load coords}. Finally enable playback for the track.
-When using a single starting frame to calculate the motion of a sequence, the starting frame should be a single frame with the least motion to any of the other frames. This is rarely frame $0$. Usually it is a frame near the middle of the sequence. This way the search radius need only reach halfway to the full extent of the motion in the sequence.
+When using a single starting frame to calculate the motion of a sequence (Keep Shape), the starting frame should be a single frame with the least motion to any of the other frames. This is rarely frame $0$. Usually it is a frame near the middle of the sequence. This way the search radius need only reach halfway to the full extent of the motion in the sequence.
If the motion tracker is used on a render farm, Save coords and previous frame mode will not work. The results of the save coords operation are saved to the hard drives on the render nodes, not the master node. Future rendering operations on these nodes will process different frames and read the wrong coordinates from the node filesystems. The fact that render nodes only visualize a portion of the timeline also prevents previous frame from working since it depends on calculating an absolute motion vector starting on frame $0$.
The slower method is to calculate the motion vectors and apply them simultaneously. This method can use one track as the motion vector calculation track and another track as the target track for motion vector actions. This is useful for long sequences where some error is acceptable.
+\subsubsection*{Pre-processing the shot}
+\label{ssub:pre_processing_shot}
+
+\begin{enumerate}
+ \item The motion plugin uses \textit{luminance} to do its own calculations, so we can edit the clip to enhance contrast and make it easier to calculate motion vectors. You can even create a copy of the monochrome clip and optimize it for the plugin. It lengthens the time but minimizes errors. The saved file can then be used for the original clip.
+ \item Correct lens distortion, especially if the object to be tracked moves to the edges of the frame.
+ \item Study the entire shot well: if necessary, divide it into many edits, each with its own Motion plugin. For example, if the object to be tracked leaves the frame or is covered by some other element or changes in shape, size or rotation. You can try to use the \textit{Offset Tracking} technique described below.
+\end{enumerate}
+
\subsubsection*{Using blur to improve motion tracking}
\label{ssub:blur_improve_motion_tracking}
-With extremely noisy or interlaced footage, applying a blur effect before the motion tracking can improve accuracy. Either save the motion vectors in a tracking pass and disable the blur for the action pass or apply the blur just to the master layer.
+With extremely noisy or interlaced footage, applying a blur effect before the motion tracking can improve accuracy. Either save the motion vectors in a tracking pass and disable the blur for the action pass or apply the blur just to the master layer. You can even use a copy of the track formed only by the channels of Red + Green, because the channel of Blue is the noisiest. Another trick is to enlarge the Match Box to minimize the effect of noise.
\subsubsection*{Using histogram to improve motion tracking}
\label{ssub:histogram_improve_motion_tracking}
-A histogram is almost always applied before motion tracking to clamp out noise in the darker pixels. Either save the motion vectors in a tracking pass and disable the histogram for the action pass or apply the histogram just to the master layer.
+A histogram is almost always applied before motion tracking to clamp out noise in the darker pixels. Either save the motion vectors in a tracking pass and disable the histogram for the action pass or apply the histogram just to the master layer. Finally, you can use the histogram to increase contrast.
+
+\subsubsection*{Possible sources of errors}
+\label{ssub:possible_sources_errors}
+
+\begin{description}
+ \item[Search radius too small:] the traced object moves too fast with respect to the size of the search box set.
+ \item[Search radius too large:] The search box is so large that it also collects other similar items in the frame.
+ \item[Occlusions:] the traced object is temporarily hidden by some other element. \textit{Offset tracking} or splitting of the video into several homogeneous clips is required.
+ \item[Focus change:] you may get errors if the object changes its focus. The video must be divided into several homogeneous clips.
+ \item[Motion Blur:] blurs the object making the calculation of the motion vector less precise. Very little can be done.
+ \item[Shape change:] you can use \textit{Track previous frame} or the subdivision of the video in more homogeneous clips.
+ \item[Lighting change:] Contrast change can produce errors. \textit{Track previous frame} or color correction can be used to return to the initial illumination.
+\end{description}
\subsubsection*{Tracking stabilization in action}
\label{ssub:tracking_stabilization_action}
\item Set keyframe at C to add offsets that were calculated at B.
\end{enumerate}
-\subsubsection*{Tip}
-\label{ssub:tip}
+\subsubsection*{Tips}
+\label{ssub:tips}
-The motion vector is a text file located in \texttt{/tmp}. We can open it with a plain editor and modify the wrong $X\,Y$ coordinates, i.e. those that deviate from the linearity, to correct the errors that always happen when we perform a motion tracking (jumps). It can be a long and tedious job, but it leads to good results.
+\begin{enumerate}
+ \item The motion vector is a text file located in \texttt{/tmp}. We can open it with a plain editor and modify the wrong $X\,Y$ coordinates, i.e. those that deviate from the linearity, to correct the errors that always happen when we perform a motion tracking (jumps). It can be a long and tedious job, but it leads to good results.
+ \item You can try tracking using reverse playback of the track. Sometimes it may lead to a better calculation.
+\end{enumerate}
\subsection{Motion 2 Point}%
\label{sub:motion_2_point}
\subsection{Overlay}%
\label{sub:overlay}
-This effect can combine several tracks by using the so called Overlayer. This is a basic internal device normally used by Cinelerra GG Infinity to create the dissolve transitions and for compositing the final output of every track onto the output bitmap. The Overlayer has the ability to combine one or several image layers on top of a bottom layer. It can do this combining of images in several different (and switchable) output modes such as \textit{Normal}, \textit{Additive}, \textit{Subtractive}, \textit{Multiply} (Filter), \textit{Divide}, \textit{Max} and \textit{Replace}. For a detailed list refer to the chapter on Overlay Modes
-\todo{internal link 3}
---- PorterDuff.
+This effect can combine several tracks by using the so called Overlayer. This is a basic internal device normally used by Cinelerra GG Infinity to create the dissolve transitions and for compositing the final output of every track onto the output bitmap. The Overlayer has the ability to combine one or several image layers on top of a bottom layer. It can do this combining of images in several different (and switchable) output modes such as \textit{Normal}, \textit{Additive}, \textit{Subtractive}, \textit{Multiply} (Filter), \textit{Divide}, \textit{Max} and \textit{Replace}. For a detailed list refer to the on \nameref{cha:overlays} chapter --- PorterDuff.
The \texttt{overlay} plugin enables the use of this Overlayer device in the middle of any plugin stack, opening endless filtering and processing possibilities. It is only useful as a \textit{shared plugin} (i.e. a multitrack plugin). To use the overlay plugin:
\begin{enumerate}
\item Add the effect to Track A.
\item Choose \textit{attach effect} from the context menu of another track (Track B).
- \item Choose Track A:Overlay as a shared plugin.
+ \item Choose Track A: Overlay as a shared plugin.
\item Manipulate the plugin parameters in Track A.
\end{enumerate}
\subsection{Perspective}%
\label{sub:perspective}
-The \texttt{perspective} plugin allows you to change the perspective of an object and is used to make objects appear as if they are fading into the distance. Basically, you can get a different view. A transformation is used which preserves points, lines, and planes as well as ratios of distances between points lying on a straight line.
+The \texttt{perspective} plugin (aka Corner Pinning) allows you to change the perspective of an object and is used to make objects appear as if they are fading into the distance. Basically, you can get a different view. A transformation is used which preserves points, lines, and planes as well as ratios of distances between points lying on a straight line.
In (figure~\ref{fig:perspective}) you can see that there are four options for the endpoints used for the edges.
\label{sub:timefront}
Space-temporal warping enables time to flow differently at different locations in the video (figure~\ref{fig:timefront}).
-\begin{wrapfigure}[12]{O}{0.3\linewidth}
- \vspace{-4ex}
+\begin{wrapfigure}[13]{O}{0.3\linewidth}
+ \vspace{-2ex}
\includegraphics[width=0.8\linewidth]{images/timefront.png}
\caption{Temporal bands for Timefront}
\label{fig:timefront}
\begin{description}
\item[Drag] initial default checkbox is \texttt{off} so that the Title plugin will work as it always has.
\begin{description}
- \item[Anchors] When you turn on the Drag feature, nine different anchors/handles will appear on compositor window. The \textit{middle anchor} allows you to drag your title wherever you want in the compositor window ($X, Y coordinates$). The other 8 handles, drawn as arrows in each corner and in the middle of each side, let you change the size of the drag area box so that your title is within that area if it fits and as it is directed.
+ \item[Anchors] When you turn on the Drag feature, nine different anchors/handles will appear on compositor window. The \textit{middle anchor} allows you to drag your title wherever you want in the compositor window ($X, Y$ coordinates). The other 8 handles, drawn as arrows in each corner and in the middle of each side, let you change the size of the drag area box so that your title is within that area if it fits and as it is directed.
\item[W/H] the values in these 2 boxes specify the size of the drag area box measured in pixels as shown in the compositor window. You can set these manually and if you can't see the location of your box or find your handles, set them to zero because $0$ sets it to the same as the width/height of the media.
The Drag effect ignores all boundaries, including the \textit{Title Safe Region} of the Compositor so that if you drag your titles off the screen, it will look like they disappeared completely. Reset X and Y to reasonable values to have it reappear. The Title \textit{text}, \textit{background}, and \textit{pngs} are applied on a single layer so that they will drag together as an entity. All of the Title capabilities work in conjunction with dragging so if you want to justify the title, you can still use the \textit{Left/Center/Right/Top/Mid/Bottom} within the drag area. Be sure to turn off Drag when rendering or the box will show in the video; keep in mind that drag bars do not appear until there is some text in the text box and you can not actually drag until the Title window controls are available.
\end{description}
\begin{description}
\item[Background] in this box you can keyin the name of a file of the type that cinelerra accepts and use that file as a background for your Title characters. This will be seen in the compositor window on top of the video that is loaded in the main track canvas. Besides typing in the filename, you must also check the checkbox. This makes it easy to turn it \texttt{on} and \texttt{off} to see what it looks like. Next to the background box is a \texttt{Loop} checkbox. If the background file takes less time than the main track canvas video to run, you can turn on the loop checkbox so that it runs over and over again to match the time size of your video.
\item[Stroker] to add \textit{pen strokes} to the text letters, adjust the stroke width numerically. This looks particularly nice on certain fonts and with a negative adjustment of the \texttt{Drop shadow}.
- \item[Unicode Insertion] if you want to enter a special character like the mathematical \textit{summation} symbol, you can use the unicode equivalent to do so. \texttt{Ctrl-Shift-U} followed by $2022$ and a carriage return is an example of the bullet. Refer to section 40.11 for details.
+ \item[Unicode Insertion] if you want to enter a special character like the mathematical \textit{summation} symbol, you can use the unicode equivalent to do so. Press \texttt{Ctrl-Shift-U} followed by $2022$ and a carriage return is an example of the bullet. Refer to section \hyperref[sec:textbox_non_std_character_unicode]{17.5} for details.
\item[Popup Helper] put your cursor where you want to add an attribute, then right mouse will bring up a list of the available attributes for you to choose, along with a submenu to choose from. The program will insert that attribute for you and all you have to add is a value when required! (see figure~\ref{fig:title02}).
\end{description}
The current set of fonts in cinelerra's directory will be automatically included and will be the default set if this environment variable is not set. Keep in mind that if you add a lot of fonts, it will considerably slow down the startup every time you bring up the Title plugin.
-If you want to only have a limited number of fonts set up, you can manipulate the cinelerra directory directly at \texttt{<cinelerra\_install\_path> /bin/plugins/fonts}. Here you will find the default set of fonts that come with the install. Copy any other fonts you would like to include here with read permission, delete any fonts you do not want to have, then execute \texttt{mkfontscale} which creates the file \texttt{fonts.scale} that cinelerra will read. However, the next time you install a new version of cinelerra GG, your changes will be written over so you will have to make sure to save them elsewhere and then re-establish.
+If you want to only have a limited number of fonts set up, you can manipulate the cinelerra directory directly at \texttt{<cinelerra\_install\_path> /bin/plug\-ins/fonts}.
+Here you will find the default set of fonts that come with the install. Copy any other fonts you would like to include here with read permission, delete any fonts you do not want to have, then execute \texttt{mkfontscale} which creates the file \texttt{fonts.scale} that cinelerra will read. However, the next time you install a new version of cinelerra GG, your changes will be written over so you will have to make sure to save them elsewhere and then re-establish.
If you have problems with a specific font or set of fonts, there is a debug option available to determine which font is an issue. When starting cinelerra, you should set up the variable:
\vspace{1ex}
\begin{lstlisting}[language=bash]
-export BC_FONT_PATH=: (the : “colon” removes all automatic system and cinelerra fonts)
-export BC_FONT_PATH=:/usr/share/fonts (remove all fonts and then add /usr/shar/fonts)
+export BC_FONT_PATH=: #(the : "colon" removes all automatic system and cinelerra fonts)
+export BC_FONT_PATH=:/usr/share/fonts #(remove all fonts and then add /usr/shar/fonts)
\end{lstlisting}
One last item of information about fonts that may lead to some confusion. The checkbox for Bold and Italic will occasionally be ghosted out if no bold or italic version of the selected font is available. This is no guarantee, but currently as good as it can get due to inconsistency in the creation of fonts. It is mostly just a hint. If boxes are checkmarked, but ghosted, you can not uncheck until you change to a font that does not ghost out the boxes. If you use the popup helper with the boxes checked, and attempt to keyin a font that does not have the bold/italic attribute as checked, the font will be considered illegal.
\item Precise adjustments can be made by measuring the values on the waveform with the crosshair (by click with \texttt{LMB}, and reading numeric values on top left of the window) and reporting these numbers in the effects window (\textit{Histogram Bézier/Curves}, for example).
\end{enumerate}
-For instance, if you are looking for maximum contrast range, adjust the \texttt{Brightness/Contrast} levels to align the darkest point on the scope with the $0\%$ level and the brightest portion with $100\%$. Anything above $100\%$ is over saturated. Limits which may be highlighted with checkbox controls.
+For instance, if you are looking for maximum contrast range, adjust the \texttt{Bright\-ness/Contrast} levels to align the darkest point on the scope with the $0\%$ level and the brightest portion with $100\%$. Anything above $100\%$ is over saturated. Limits which may be highlighted with checkbox controls.
\subsubsection*{HDTV or sRGB (ITU-R BT.709)}%
\label{ssub:hdtv_srgb_bt709}
To build findobject and the other plugins using opencv, access the src using git:
\begin{lstlisting}[language=bash]
-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}
then configure the build, but add the \texttt{- -with-opencv} configure parameter.
\item download the corresponding distro static tarball;
for example for arch:
\end{enumerate}
+
\url{https://cinelerra-gg.org/download/tars/cinelerra-5.1-arch-{date}-x86_64-static.txz}
- \todo{How make a new line into the link?}
+
\begin{enumerate}[resume]
\item create a temporary directory on your computer;
\item \texttt{cd} that-directory;
The following steps were used to set up the example in figure~\ref{fig:findobj}.
\begin{enumerate}
- \item For best results, set \textit{Play every frame} in \texttt{Settings$\rightarrow$ Preferences$\rightarrow$ Playback A}.
+ \item For best results, set \textit{Play every frame} in \texttt{Settings$\rightarrow$ Preferences$\rightarrow$ Play\-back A}.
\item Load 3 tracks of png/jpg files – this is one of the more useful working cases:
\begin{itemize}
\item $1^{st}$ track should be the \textit{scene}; that is the output
\label{fig:stylize}
\end{figure}
-\section{FFmpeg Audio and Video Plugins\protect\footnote{credit to WPfilmmaker for the Ffmpeg info description lines taken from his contributed pdf}}%
+\section[FFmpeg Audio and Video Plugins]{FFmpeg Audio and Video Plugins\protect\footnote{credit to WPfilmmaker for the Ffmpeg info description lines taken from his contributed pdf}}%
\label{sec:ffmpeg_audio_video_plugins}
Cinelerra GG Infinity currently comes with more than $140$ of the video plugins and $55$ of the audio plugins developed by the FFmpeg project \url{www.ffmpeg.org}. These plugins do not have a GUI with buttons like the rest of plugins, therefore to change settings it is necessary to change the variables by hand by highlighting the \textit{option}, typing a value in the \textit{Range} box, and then hitting the \textit{Apply} button. Many of these plugins provide tooltips at the bottom right corner of the window when the option is highlighted. A \textit{slider} bar and a \textit{dial} for numerical values can be used to easily vary the values which take effect immediately.
\textbf{F\_yuvtestsrc:} Generate YUV test pattern.\\
\textbf{F\_zoompan:} Applies Zoom \& Pan effect.
-\section{Rendered Effects\protect\footnote{This capability is going to be deleted in the future unless receive notification of need to keep}}%
+\section[Rendered Effects]{Rendered Effects\protect\footnote{This capability is going to be deleted in the future unless receive notification of need to keep}}%
\label{sec:rendered_effects}
Besides the Realtime effects, as has been described in the previous sections, another type of effect is performed on a section of the track and the result stored somewhere before it is played back. The result is usually pasted into the track to replace the original data. The rendered effects are not listed in the resources window but instead are accessed through the \texttt{Audio$\rightarrow$ Render effect and Video$\rightarrow$ Render effect} menu options. Each of these menu options brings up a dialog for the rendered effect. In the Select an effect dialog is a list of all the realtime and all the rendered effects. The difference here is that the realtime effects are rendered to disk and not applied under the track. Rendered effects apply to only one type of track, either audio or video. If no tracks of the type exist, an error pops up.
projects / goodguy / cin-manual-latex.git / blobdiff