\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. Here is a short example:
+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]
\centering
\begin{lstlisting}[style=sh]
Video Effects
+ -Favorites
+ Brightness/Contrast
+ Title
+ VideoScope
- Color_Correction
Blue Banana
Color 3 Way
L2_Calf Fluidsynth
\end{lstlisting}
+NOTE: The capability to put the expanders.txt file in \texttt{./bcast5} (see \nameref{sec:bcast5}) allows for customizations such as grouping favorite plugins in one section so that they can be recalled more quickly. For this purpose, the \textit{Favorites} section has been included at the top of Video Effects, the contents can be changed as desired. Once your modified file is saved to hard disk as \$HOME/.bcast5/expanders.txt it will remain in use on every update as long as you do not delete it or remove the .bcast subdirectory.
+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
+ cp /tmp/cinelerra5/cinelerra-5.1/expanders.txt $HOME/.bcast5/expanders.txt
+\end{lstlisting}
+
\subsection{Speed-up of Ffmpeg plugin usage with OPTS files}%
\label{sub:speedup_ffmpeg_plugin_opts}
\index{plugins!speed-up via options}
\index{delay audio}
In the Delay Audio effect you can specify the number of seconds you want to delay the video track.
+An alternative ffmpeg plugin is F\_adelay.
\subsection{DeNoise}%
\label{sub:denoise}
\item[Damp:] echo envelope decay factor used to smooth the cepstrum/correlation data.
\item[Peaks:] number of maximal envelope values used in the echo gain calculation.
\item[Cutoff Hz:] low frequency cutoff value to prevent beat frequency (\textit{heterodyne}) echo canceling.
- \item[Mode:] \textit{MAN}, \textit{Off}, or \textit{On}. When Off is selected, the plugin is not active. When MAN is used, the only one peak is used for the echo gain envelope. It is set by pressing mouse button $1$ in the ceptstrum graphical output. The Gain and Offset are updated as the pointer drag operation resets the indicated gain and offset values. When On is selected, the echo gain envelope is automatically calculated by cepstrum and auto-correlation of the input audio in the last window size audio samples.
+ \item[Mode:] \textit{MAN}, \textit{Off}, or \textit{On}. When Off is selected, the plugin is not active. When MAN is used, the only one peak is used for the echo gain envelope. It is set by pressing mouse button $1$ (LMB) in the ceptstrum graphical output. The Gain and Offset are updated as the pointer drag operation resets the indicated gain and offset values. When On is selected, the echo gain envelope is automatically calculated by cepstrum and auto-correlation of the input audio in the last window size audio samples.
\item[Windows size:] parameter can be set to \textit{Default}, $1024$, $2048$, \dots \textit{doubled values\dots} up to $262144$.
\item[Amplitude:] the cepstrum value at the drag point during manual envelope selection.
\item[Gain:] echo gain setting determined by manual selection.
Allows you to convert an audio file from one sample rate to another. This effect works similarly to ReframeRT in videos.
\begin{center}
- \begin{tabular}{l l}
+ \begin{tabular}{ll}
\toprule
Input / output > 1 & fast rate \\
Input / output < 1 & slow rate \\
\item Allows you to automate the \textit{white balance} by simply choosing a neutral color in the output of the Compositing window using the Color Picker and pressing the corresponding button in the plugin.
\item Allows you to vary the \textit{Saturation} with sliders in the same manner as contrast was varied by the Value slider. For istance, to decrease the incidence of color dominants present in the shadows or in the highlights, vary the Saturation.
\item With the \textit{color wheels} you can make very sophisticated adjustments to the shades of the images, in each of the three main areas of shadows, midtones and highlights.
- \item Allows you to copy exactly the setting of one zone to the other two zones using \textit{Copy to all} button.
+ \item Allows you to copy exactly the setting of one zone to the other two zones using \textit{Copy to all} button. With this option, it is like using a fourth wheel called \textit{OffSet} in other programs.
\item In addition to the three reset buttons, each slider and each wheel has its own Clear button, to return it to the default value without affecting the others.
\end{itemize}
\begin{itemize}
\item Look at the highest peak on the \textit{waveform} and measure it with the crosshair observing the numerical value at the top left.
- \item Set this value with the \textit{maximum} slider.
+ \item Set this value with the \textit{maximum} slider or \textit{textbox}.
\item Then adjust the slider of the \textit{gamma} to our liking, always checking the result on the waveform so to be sure never to exceed the values of clipping, $0 \div 1.0$.
\end{itemize}
\label{fig:histeq}
\end{figure}
-Histeq equalizes the colorspace through use of a \textit{histogram equalization algorithm} -- a technique for adjusting image intensities to enhance contrast. Parameters are:
+If the histogram is as wide as the entire range ($0 - 1.0$), the image is high contrast. If the range is small (i.e., the values are close together) the contrast is small. In this case HistEQ is used to distribute the few clustered values across the entire range ($0 - 1.0$), increasing the contrast of the frame.
+In order to do this HistEQ equalizes the colorspace through use of a \textit{histogram equalization algorithm}. Parameters are:
\begin{description}
\item[Gain:] when set to $1$, the colorspace is best effort. If the gain is set to $0$, the result is the entire regression line of the color map.
\label{sub:histogram}
\index{histogram}
-The histogram allows an immediate view of the contrast amplitude of an image with its distribution of \textit{luma} and \textit{colors} values. If the columns of values occupy the whole range $0-100\%$ then we have maximum contrast; if the range is smaller the contrast is smaller. If most of the values are on the right of the histogram you have an image with highlights at the limit with values clamped to $1.0$. This is called \textit{overexposure}. However, if most of the values are moved to the left, with the limit of the values clamped to $0$, we have a lowlight image and we talk about \textit{underexposure}. Histogram is keyframble (figure~\ref{fig:histogram}).
+The histogram allows an immediate view of the contrast amplitude of an image with its distribution of \textit{luma} and \textit{colors} values. If the columns of values occupy the whole range $0-1.0$ (also expressed as a percentage above the graph) then we have maximum contrast; if the range is smaller the contrast is smaller. In fact, contrast is mathematically given by the highest value of the abscissa minus the lowest value. If the values are similar and close together, the difference is smaller and the lower the contrast. If most of the values are on the right of the histogram you have an image with highlights at the limit with values clamped to $1.0$. This is called \textit{overexposure}. However, if most of the values are moved to the left, with the limit of the values clamped to $0$, we have a lowlight image and we talk about \textit{underexposure}. This plugin is a tool for Primary Color Correction, that is, affecting the entire frame. Histogram is keyframable (figure~\ref{fig:histogram}).
\begin{figure}[htpb]
\centering
\label{fig:histogram}
\end{figure}
-The Histogram is always performed in floating point RGB regardless of the project color space. The histogram has two sets of transfer parameters: the \textit{input transfer} and the \textit{output transfer}. The input transfer has value on the horizontal axis of $x$; it is a scale of values ranging from 0 to 255 in the case of an $8\,bit$ image, or it can have normalized values in the range ($0-1.0$) or even be a scale in percentage ($0-100\%$). In the output transfer (the $y\,axis$) is represented the number of times (that is, $y$) a given value $x$ appears. A higher column ($y$ greater) indicates that many pixels have the corresponding value $x$; a lower column indicates that fewer pixels have that value. On the left we have the minimum value $0$, which is the black point. On the right we have the maximum value $1.0$ which is the white point. The intermediate values pass smoothly from one extreme to the other. The three important points (including the midtones, i.e.\ the Master Offset) are indicated by cursors (small triangles) at the base of the histogram. You can adjust them to change the values of the three points if you want.
+The Histogram is always performed in floating point RGB regardless of the project color space. The histogram has two sets of transfer parameters: the \textit{input transfer} and the \textit{output transfer}. The input transfer has value on the horizontal axis of $x$; it is a normalized scale of values ranging from 0 - 1.0 (which for a depth color of 8 bits corresponds to the range 0 - 255, for 10 bits corresponds to 0 - 65536, etc). The output transfer (the $y axis$) represents the height of the column where a given value $x$ appears. A higher column ($y$ greater) indicates that many pixels have the corresponding value $x$; a lower column indicates that fewer pixels have that value. On the left we have the minimum value $0$, which is the black point. On the right we have the maximum value $1.0$ which is the white point. The intermediate values pass smoothly from one extreme to the other. The three important points (including the midtones) are indicated by cursors (small triangles) at the base of the histogram. You can adjust them to change the values of the three points if you want. Acting on the white or black point involves horizontal shifts only; acting on the midtones triangle also involves vertical movements leading to a "gamma" correction of the curve (Linear to Log or Reverse Log or vice versa). Further down is an additional bar with related cursors and textboxes. It is used to adjust input and output values (on the vertical).
-There are 4 possible histograms in the histogram viewer. The red, green, blue histograms show the input histograms for red, green, blue and multiply them by an input transfer to get the output red, green, blue. Then the output red, green, blue is scaled by an output transfer. The scaled red, green, blue is converted into a value and plotted on the value histogram. The value histogram thus changes depending on the settings for red, green, blue. The value transfers are applied uniformly to R, G, B after their color transfers are applied. Mathematically, it is said that the values of $x$ are linked to the values of $y$ by a transfer function. This function is represented by a line that leaves the values of $x$ and $y$ unchanged, but we can intervene by modifying this line with the cursors.
+There are 4 possible histograms in the histogram viewer. The red, green, blue histograms show the input histograms for red, green, blue and multiply them by an input transfer to get the output red, green, blue. Then the output red, green, blue is scaled by an output transfer. The scaled red, green, blue is converted into a value and plotted on the value histogram. The value histogram thus changes depending on the settings for red, green, blue. The value transfers are applied uniformly to R, G, B after their color transfers are applied. Mathematically, it is said that the values of $x$ are linked to the values of $y$ by a transfer function. This function, by default, is represented by a line that leaves the values of $x$ and $y$ unchanged, but we can intervene by modifying this line with the cursors or the textboxes.
You need to select which transfer to view by selecting one of the channels on the top of the histogram. You can also choose whether to display the master, i.e.\ only the values of the \textit{luma}, or show the \textit{Parade}, i.e.\ the three RGB channels. You can switch from one to the other with the two buttons in the upper right corner. The input transfer is defined by a graph overlaid on the histogram; this is a straight line. Video entering the histogram is first plotted on the histogram plot, then it is translated so output values now equal the output values for each input value on the input graph.
-After the input transfer, the image is processed by the output transfer. The output transfer is simply a minimum and maximum to scale the input colors to. Input values of $100\%$ are scaled down to the output's maximum. Input values of $0\%$ are scaled up to the output minimum. Input values below $0$ are always clamped to $0$ and input values above $100\%$ are always clamped to $100\%$. Click and drag on the output gradient's triangles to change it. It also has textboxes to enter values into.
+After the input transfer, the image is processed by the output transfer. The output transfer is simply a minimum and maximum to scale the input colors to. Input values of $1.0$ are scaled down to the output's maximum. Input values of $0$ are scaled up to the output minimum. Input values below $0$ are always clamped to $0$ and input values above $1.0$ are always clamped to $1.0$. Click and drag on the output gradient's triangles to change it. It also has textboxes to enter values into.
-Enable the \textit{Automatic} toggle to have the histogram calculate an automatic input transfer for the red, green, and blue but not the value. It does this by scaling the middle $99\%$ of the pixels to take $100\%$ of the histogram width. The number of pixels permitted to pass through is set by the \textit{Threshold} textbox. A threshold of $0.99$ scales the input so $99\%$ of the pixels pass through. Smaller thresholds permit fewer pixels to pass through and make the output look more contrasty.
-\textit{Plot histogram} is a checkbox that enables plotting the histogram.
-\textit{Split output} is a checkbox that enables a diagonal split showing in the compositor.
+Enable the \textbf{Automatic} toggle to have the histogram calculate an automatic input transfer for the red, green, and blue but not the value. It does this by scaling the middle $99\%$ of the pixels to take $100\%$ of the histogram width. The number of pixels permitted to pass through is set by the \textit{Threshold} textbox. A threshold of $0.99$ scales the input so $99\%$ of the pixels pass through. Smaller thresholds permit fewer pixels to pass through and make the output look more contrasty.
+\textit{Plot histogram} is a checkbox that enables plotting the histogram. It can be useful because having a histogram that changes in real-time can use a lot of system resources for computation. In this case it is enabled only at times when it is needed.
+\textit{Split output} is a checkbox that enables a diagonal split showing in the compositor, so we can see the effects of the changes from the original frame.
\textit{Reset} returns the four curves to their initial state (neutral) as well as the Value/RGB histogram buttons.
+\textbf{Linear to Log} slider: frequency in Linear range to Log range; default is 50\%, but if you want it to be the same as the Videoscope or Histogram Bezier, which are of type Log, set the slider all the way to Log. The variation is by 10\% steps. Linear generally represents what the eye sees in the real world. Log is an exponential look where the small numbers are represented more - that is, the leading digit.
+
The histogram plugin ordinarily applies a value for a single frame. A
new feature modifies histogram to show values for a selection of frames.
You use several frames in a video that you want to use the \textit{average}
there is a large light or color variation within a range of a few frames,
you spend a lot of time correcting each frame when it would be better to
just get an average value to use. If you want, then you can make a LUT for
-that set of frames instead of each frame.
-
+that set of frames instead of each frame.\\
It works by selecting the area on the timeline for
which you would like to see the Histogram averaged and then click on the
-\textit{Frames} button in the Histogram plugin.
-The parameters are:
-\textit{Linear to Log} slider: frequency in Linear range to Log range; default is 50\%, but if you want it to be the same as the Videoscope or Histogram Bezier, set the slider all the way to Log. The variation is by 10\% steps. Linear generally represents what the eye sees in the real world. Log is an exponential look where the small numbers are represented more - that is, the leading digit.
-\textit{Frames} button: if a Selection is set on the timeline, the number of frames
-will be calculated and shown in the box next to it.
-\textit{Frame Count box}: type in the number of frames you want to be looked at
-starting at the insert marker or use the up/down counter.
-\textit{Clear Frames} icon: reset the frame count to the default value of 0.
+\textbf{sum frames} button in the Histogram plugin. If a Selection is set on the timeline, the number of frames will be calculated and equalized to the mean value.
A side note: by using a number of frames, you can get a \textit{dissolve-like
transition effect}.
\paragraph{Theory:}
-A histogram is a bunch of \textit{bins} (accumulators) that count the number of times a particular pixel channel intensity occurs in an image. Dim are on the left, bright on the right.
+A digital image is a matrix of ($N x N$) pixels. Each pixel can have a (integer) luminance or luma ($x_i$) value ranging from $0$ to $L-1$. Generally we have $L = 2^{m}$ values of x, with m = depth of color bit. $0 = x_{0}$ is the black point. $L-1 = x_{L-1}$ is the white point. Mathematically we can act on the values of x with various transformation functions. The generic formula is:
+
+\qquad \( y = T(x) \)
+
+with:
+
+y = luma value after transformation
+x = initial luma value
+T = transformation operator
+
+The T function in the case of a histogram is:
+
+\qquad \( y = \dfrac{p(x_{i})}{width} = \dfrac{max_i}{a} \)
+
+$p(x_{i}$ is the transformation that expresses the probability of an image pixel to have a given luma value $x_{i}$. This is referred to as the frequency of the value or the number of occurrences of the value (count = $max_i = bin_{i}$ area $A_i$); y is the height of the bin. The total probability of all pixels in the image is 1 (100\%):
+
+\qquad \( \sum_{i=0}^{L-1}{p(x_{i})} = 1 \)
+
+Trivially, the function $p(x_{i})$ can be thought of as counting the recurrences of the value $x_{i}$ in the $bin_i$.
+The histogram is similar to a bar graph (not the same: the histogram uses continuous data, the bar graph uses discrete data) and on the abscissa it shows $x_{i}$ values and on the ordinate $y_{i}$. Each x in a range value is treated as independent of neighboring values so it is considered as an isolated unit called an "accumulator" or "bin." It is on the bins that we count the occurrence of the $x_{i}$ value ($max_i$), which gives us precisely the value $p(x_{i})$. The Histogram is called a bar graph because a value of x is actually an interval between $x_{i}$ and the next value $(x_{i+\varepsilon})$. Because x has continuous values computed in floating point and normalized interval $0 - 1.0$ is used, there is no solution of continuity between one bin and another and the boundaries are decided a priori, usually based on bit depth color. The bin concept is fundamental because it is the basis on which we can do mathematical calculations. In fact, the area of the bin is the frequency (count or $max_i$) in which that value occurs; the width of the bin is the different values within the range we consider. With 8 bits of depth color we have 256 bins; then we collect the values of x from the initial value 0 up to and including 1; then from 1 up to and including 2; and so on up to the last bin, which ranges from 254 to and including 255. It is clear, then, that the continuous luma values are bounded in a range and made to become discrete values on which it is easier to perform calculations. The width of a bin is given by the formula:
+
+$width = a_i = x_{max_i} - x_{min_i}$
+
+Having established the depth color, the bin width is always the same (a) for every $bin_i$:
+
+$a_i = a = \dfrac{range}{\# bins}$
+
+For a depth color of 8 bits we have (normalized range $0 - 1.0$):
+
+$a_{8bit} = \dfrac{(1.0-0)}{256} = 1/256$
+
+For a depth color of 10 bits or more we have:
+
+$a_{10bit} = \dfrac{(1.0-0)}{65536} = 1/65536$
+
+Wider bins have a higher count (because they gather more $x_{i}$). Narrower bins have a lower $max_i$ (because they contain less $x_{i}$; neighboring values ($x_{i+\varepsilon}$) are distributed in neighboring bins).
+To recap: in \CGG{} histogram is a bunch of \textit{bins} (accumulators) that count the number of times a particular pixel channel intensity (luma, $x_{i}$) occurs in an image. The plugin scans all the pixels in the frame, counting the frequencies in each given bin ($max_i$). Knowing the width of the bins (a) then it is easy to get the height of $bin_i$ (y). In fact, the bins are rectangles, and you can apply the area formula from which to derive the height:
+
+$A_i = max_i = Base \times High = a \times y_i$
+
+Hence:
+
+$y_i = \dfrac{max_i}{a}$
-The number of bins used depends on the color model bit depth:
+Dim bins are on the left, bright bins on the right.
+You can have discordance of results, looking in the scopes, either by switching from Histogram to Histogram Bezier or after a conversion between color spaces (with associated change in depth color). The number of bins used depends on the color model bit depth:
\begin{description}
- \item[Histogram:] 256 for rgb8 and 65536 for all others.
- \item[Bezier:] 256 for rgb8/yuv8 and 65536 for all others.
+ \item[Histogram:] 256 for rgb8 and 65536 for all others
+ \item[Bezier:] 256 for rgb8/yuv8 and 65536 for all others
\item[Scopes:] always uses 65536
\end{description}
-All of the bins are scanned when the graph is plotted. What is shown
-depends on which plugin is used:
+All of the bins are scanned when the graph is plotted. What is shown on the graph, in the Compositor window, and finally on the scopes, depends on which plugin is used:
\begin{description}
- \item[Histogram:] was max of the bins in the pixel range, now is the sum
+ \item[Histogram:] was max of the bins in the pixel range, now is the sum (to make it congruent with Bezier and the Scopes)
\item[Bezier:] is the max of the bins in the pixel range
\item[Scopes:] is the max of the bins in the pixel range
\end{description}
-When the color space and the bin size are the same, all of the values
-increment the indexed bins. When the color is the result of yuv $\rightarrow$ rgb conversion, the results \textit{spread} if there are more bins than colors. This is the same effect you see when you turn on \textit{smoothing} in the vectorscope histogram.
+Another difference in behavior is regarding the type of curve, whether Linear or Log:
-The \textit{total} pixels for each value is approximately the same, but the \textit{max} value depends on the color quantization. More colors increment more bins. Fewer colors increment fewer bins. In both cases, the image size has the same
-number of pixels. The fewer color case increments the used bins, and skips the
-unused bins. This sums all of the pixels into fewer bins, and the bins have
-higher values. That is the \textit{rgb} vs \textit{yuv} case, fewer vs more bins are used.
+\begin{description}
+ \item[Histogram:] the curve is Linear, but it is editable with the Linear/Log slider
+ \item[Bezier:] the curve is Log
+ \item[Scopes:] the curve is Log
+\end{description}
+
+This diversity also leads to different visual results from Histogram Bezier.
-To report something more consistent, has been changed the reported value to
-the \textit{sum} of the accumulated counts for the bins reporting a pixel bar on the
-graph. The effect of this is to do this:
+When the color space and the bin size are the same, all of the values increment the indexed bins. But if we start from YUV type edits, the plugin will automatically do the conversion to RGB. When the color is the result of yuv $\rightarrow$ rgb float conversion, we go from 256 bins of YUV to 65536 bins of RGB Float and the results \textit{spread} if there are more bins than colors. This is the same effect you see when you turn on \textit{smoothing} in the vectorscope histogram.
+
+The \textit{total} pixels for each value is approximately the same, but the \textit{max} value depends on the color quantization. More colors increment more bins. Fewer colors increment fewer bins. In both cases, the image size has the same number of pixels. So the pixels will distribute into more bins if you go to a higher depth color; those bins will have a lower count. The fewer color case increments the used bins, and skips the unused bins. This sums all of the pixels into fewer bins, and the bins have higher values. That is the \textit{rgb} vs \textit{yuv} case, fewer vs more bins are used. To get more consistent visual feedback (and on scopes), the concept of sum was used instead of the maximum number of occurrences (max).
+
+To report something more consistent, the reported value has been changed from the original code to be the \textit{sum} of the accumulated counts for the bins reporting a pixel bar on the
\begin{center}
- \begin{tabular}{ l l c r r }
+ \begin{tabular}{clccr}
\hline
1 & & & & \\
1 & & & 1 & \\
- 000100 & 3 pixels & vs & 001000& 3 pixels \\
+ 000100 & 3 pixels & vs & 0011000& 3 pixels \\
\hline
\end{tabular}
\end{center}
-On the left, the course color model piles all 3 pixels into one bin. max
-value 3
-
-On the right, the fine color model puts the counts into 2 bins, max 2, sum 3
+On the left, the course color model piles all 3 pixels into one bin, max
+value 3.
+On the right, the fine color model puts the counts into 2 bins, max 2, sum 3.
-So, by reporting the sum the shape of the results are more similar.
+So, by reporting the sum the shape of the results are more similar to graph.
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.5\linewidth]{sum.png}
+ \caption{Sum count Vs max count}
+ \label{fig:sum}
+\end{figure}
\subsection{Histogram Bezier / Curves}%
\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. 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.
+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.
+
+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.
The input graph is edited by adding and removing any number of points. Click and drag anywhere in the input graph to create a point and move it. Click on an existing point to make it active and move it. The active point is always indicated by being filled in. The active point's input X and output Y values are given in textboxes on top of the window. The input and output color of the point can be changed through these textboxes. Points can be deleted by first selecting a point and then dragging it to the other side of an adjacent point. They can also be deleted by selecting them and hitting delete (figure~\ref{fig:bezier}).
\label{sub:holographictv}
\index{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}).
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.55\linewidth]{holographictv.png}
+ \caption{Holographic messages in CinGG!}
+ \label{fig:holographictv}
+\end{figure}
+
+Incoming objects are projected like holovision seen in the movie Stars Wars as in R2-D2's video message projector of the Princess Leia (figure~\ref{fig:holographictv}). 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.
This effect originated from {\small \url{https://effectv.com}}.
-\begin{figure}[htpb]
- \centering
- \includegraphics[width=0.8\linewidth]{holographictv.png}
- \caption{Holographic messages in CinGG!}
- \label{fig:holographictv}
-\end{figure}
\subsection{Hue saturation}%
\label{sub:hue_saturation}
Every time a keyframe is set in a loop effect, the keyframe becomes the beginning of the region to loop. Setting several keyframes in succession causes several regions to loop. Setting a single keyframe causes the region after the keyframe to be looped throughout the effect, no matter where the keyframe is. The end of an effect can be looped from the beginning by setting the keyframe near the end.
+\subsection{Mirror}%
+\label{sub:mirror}
+\index{Mirror}
+
+The Mirror plugin splits the image along a line, an axis, and reflects one side onto the other.
+When the \texttt{Enable Reflection Center} option is checked you can move the position of this axis, using $X\%$ and/or $Y\%$ slider and/or textbox: $X\%$ for the horizontal position and $Y\%$ for the vertical position. Mainly in the Mirror effect there are 2 cases: with or without the \textit{Enable Reflection Center} checked.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.7\linewidth]{mirror.png}
+ \caption{Possible combinations with both Horizontal and Vertical checked}
+ \label{fig:mirror}
+\end{figure}
+
+When the \textit{Enable Reflection Center} option is UNCHECKED, the used reflection is on the center of the image (i.e. $X=50\%$, $Y=50\%$) and the options about \textit{Reflection Center}, $X\%$ and $Y\%$, are disabled (grayed).
+The Horizontal option reflects the left side of the image on the right. If the \texttt{Swap LEFT-RIGHT side} option is checked then the right side to the left will be reflected.
+The Vertical option reflects the top on the bottom. If the \texttt{Swap TOP-BOTTOM side} option is checked then the bottom to the top will be reflected.
+There are special combinations when both Horizontal and Vertical checkboxes are enabled (and\textit{ Enable Reflection Center} is always UNchecked, of course). You can see those combinations in the figure~\ref{fig:mirror}.
+
+When the \textit{Enable Reflection Center} option is CHECKED the options about \textit{Reflection Center}, i.e. $X\%$ and $Y\%$, are enabled, and the two "Swap ... side" options are disabled and hidden. These two "Swap ... side" are disabled because the $X\%$ and $Y\%$ allow the swap side feature automatically. The $X\%$ and $Y\%$ positions move the center of the reflection to fit to the user's need.
+
\subsection{Motion51}%
\label{sub:motion51}
\index{Motion51}
\begin{figure}[ht]
\centering
- \includegraphics[width=0.9\linewidth]{motion.png}
+ \includegraphics[width=0.99\linewidth]{motion.png}
\caption{Motion plugin GUI}
\label{fig:motion}
\end{figure}
Key Presses for using the Perspective plugin:
-\begin{tabular}{l l}
- \toprule
+\begin{tabular}{ll}
+ \hline
Left mouse button & drags the corner that is closest to current location \\
Alt key + left mouse & translates the perspective; drags the whole image \\
Shift key + left mouse & zooms the perspective \\
Alt+Shift + left mouse & translates view but does not change output \\
- \bottomrule
+ \hline
\end{tabular}
Note that the red color lines in the box show the composer boundary.
There is no \textit{undo} recorded between gui updates. It is recommended that you use the option "b" to save a backup if you get to a place where you want to make sure you do not lose your sketch.
-\begin{center}
- \small
\begin{longtable}{{m{12em}m{13em}m{12em}}}
\caption{Sketcher controls}
\label{tabular:sketcher_controls} \\ % note that double backslash is mandatory here
Del button in Curve section \\
\bottomrule
\end{longtable}
-\end{center}
\subsubsection*{Other Button and Label Descriptions}%
\label{ssub:other_button_label_description}
To include graphical elements like \textit{logos}, you may want to import your title as a PNG image (alpha channel transparency is possible), move it with camera and projector or add effects.
-\subsubsection*{Adding fonts to the titler}%
-\label{ssub:adding_fonts_to_titler}
-
-The X Window system originally did not have a suitable font renderer for video. It also is restricted to the current bit depth. It does not have a convenient way to know which fonts work with the suitable font renderer in the desired bit depth. The easiest way we have found to support fonts in the titler is to have a directory for them at \texttt{/usr/lib/cinelerra/fonts}.
-
-The titler supports mainly \textit{TTF}, true type fonts. It supports others but TTF are the most reliable. AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}.
-
- To add true type fonts, copy the \texttt{.TTF} files to the fonts directory. In that directory run
-\vspace{1ex}
-\begin{lstlisting}[style=sh]
- # /usr/lib/cinelerra/fonts
- ttmkfdir && mv fonts.scale fonts.dir
-\end{lstlisting}
-and restart \CGG{}. The new fonts should appear. The usage of ttmkfdir changes frequently so this technique might not work. It is
-important to note that because there are checkboxes for both Bold and Italic, the pulldown will not include these specific fonts
-as an addition to a Regular font. They will be used via the checkboxes but not viewed in the pulldown.
-
-If the video is displayed on a consumer TV, the outer border is going to be cropped by $5\%$ on each side. To avoid text which is too close to the edge looking bad, you may want to enable the \textit{title-safe} tool in the compositor window. The text should not cross the inner rectangle.
-
\subsubsection*{Some recently added options}%
\label{ssub:some_recently_added_options}
\item[Attributes] in the Text box where you type your Title information, you can now change several attributes to give you plenty of flexibility (figure~\ref{fig:title02}). Each of these special attributes begin with an open angle bracket < and ends with a closing angle bracket >. Until the closing angle bracket is keyed in, the actual characters you type, will be seen in the compositor window. In addition, if you do not use the exact syntax or you keyin a filename that is not available, all of the characters will continue to show up. This helps to see what needs to be fixed or is missing. The attributes usage is described in the table below.
\end{description}
-\begin{center}
- \small
\begin{longtable}{{m{6em}m{14em}m{14em}}}
\caption{Titler attributes}
\label{tabular:titler_attributes} \\ % note that double backslash is mandatory here
color name such as RED from \textit{<cin\_path>/guicast/colors.h} &
Or use the hex value like \textit{\#a000a0}; color-hex.com shows examples \\\midrule
font &
- exact name from \textit{Font} pulldow &
+ exact name from \textit{Font} pulldown &
When you set font, bold/size and italic will be as currently set up \\\midrule
alpha &
floating-point number between 0 and 1&
Turn off smooth for chroma key
\\\bottomrule
\end{longtable}
-\end{center}
These attributes stay in effect until you change them or reset them. Additional cpu time is needed for the \textit{blink} attribute because it requires redrawing every frame and for the background option described below. Note that some Title window controls can not be set, such as Justify and Outline color. The lines below are examples for testing purposes. The accompanying screenshot displays the corresponding \CGG{} output.
\begin{description}
\item[Background] in this box you can keyin the name of a file of the type that \CGG{} accepts and use that file as a background for your Title characters (media video or image). 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 \textit{On} and \textit{Off} to see what it looks like. Next to the background box is a \textit{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. By default the background image will occupy the whole frame, but if we activate \textit{drag} mode and create a box of the desired size, the image will occupy only the box leaving the rest of the frame visible.
\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 \textit{Drop shadow}.
+ \item[Text: chars:] to output and update the number of characters already used. The only limit to the number of characters based on a count of single $8\, bit$ characters is the available resources on the user computer available for \CGG{} use. Keep in mind that unicode or other special characters may consist of $2$ to $4$ $8\,bit$ bytes. Also, newlines are a character and any of the attributes you use count in the total. There is now a horizontal scroll bar as well as the vertical one in the textbox and they only appear when there are more lines or characters than can fit in the original sized textbox.
\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 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}
\subsubsection*{Font Choice}%
\label{ssub:font_choice}
+The X Window system originally did not have a suitable font renderer for video. It also is restricted to the current bit depth. It does not have a convenient way to know which fonts work with the suitable font renderer in the desired bit depth. The easiest way we have found to support fonts in the titler is to have a directory for them at \texttt{/usr/lib/cinelerra/fonts}.
+Or if not system installed, at \texttt{<cinelerra\_install\_path>/bin/plug\-ins/fonts}.
In order to choose a font faster, you can keyin the first few characters of the font name, being sure to use capital characters if used since it is case-sensitive. The steps to follow are:
\item keyin the first character(s) of the desired font and you will see the first match become highlighted;
\item you can see the characters you keyed in the upper right corner of the fonts.
\end{enumerate}
+It is important to note that because there are checkboxes for both Bold and Italic, the pulldown will not include these specific fonts
+as an addition to a Regular font. They will be used via the checkboxes but not viewed in the pulldown.
+
+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.
+
+Also of note, if the video is displayed on a consumer TV, the outer border is going to be cropped by $5\%$ on each side. To avoid text which is too close to the edge looking bad, you may want to enable the \textit{title-safe} tool in the compositor window. The text should not cross the inner rectangle.
\subsubsection*{Font Addition / Font Subtraction}%
\label{ssub:font_addition_subtraction}
-Some of the system fonts are automatically included in the set of fonts being used by \CGG{}. The easiest way to add additional fonts for the Title plugin's set, is to use ones available in specific directories on your computer as long as they have a \texttt{fonts.scale} file already set up. You can run \texttt{mkfontscale} to create this file within that directory. In order to include a specific directory you set an environment variable before starting \CGG{} which stays in effect until it is unset or until the next reboot. Below is the method and an example.
+If using a compiled build (that is, NOT an AppImage) to add true type fonts, copy the \texttt{.TTF} files to the fonts directory at \texttt{/usr/lib/cinelerra/fonts}
+or if not system installed, at \texttt{<cinelerra\_install\_path>/bin/plug\-ins/fonts}. In that directory run
+\vspace{1ex}
+\begin{lstlisting}[style=sh]
+ # /usr/lib/cinelerra/fonts
+ ttmkfdir && mv fonts.scale fonts.dir
+\end{lstlisting}
+and restart \CGG{}. The new fonts should appear. However, keep in mind that 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.
+The usage of ttmkfdir changes frequently so this technique might not work. The titler supports mainly \textit{TTF}, true type fonts. It supports others such as OTF, but TTF are the most reliable.
+
+AppImage does not provide this specific method unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}.
+However, if you use Ubuntu Studio 2304 with AppImage, you can easily add font files directly to ~/.fonts and you will have all of these available in the Title fonts list. And, there may be other operating systems with specific implementations that also allow for this easier methodology to add additional fonts.
+
+Some of the system fonts are automatically included in the set of fonts being used by \CGG{}. The easiest way to add additional system or other application available fonts for the Title plugin's set, is to use ones available in specific directories on your computer as long as they have a \texttt{fonts.scale} file already set up. You can run \texttt{mkfontscale} to create this file within that directory. In order to include a specific directory you set an environment variable before starting \CGG{} which stays in effect until it is unset or until the next reboot. Below is the method and an example.
\vspace{1ex}
\begin{lstlisting}[style=sh]
The current set of fonts in \CGG{}'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 \CGG{} directory directly at \texttt{<cinelerra\_install\_path> /bin/plug\-ins/fonts}.
+If you want to only have a limited number of fonts set up, you can manipulate the \CGG{} 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 \CGG{} will read. However, the next time you install a new version of \CGG{}, 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 \CGG{}, you should set up the variable:
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.
-Text: chars is output and updated to indicate the number of characters already used. The only limit to the number of characters based on a count of single $8\, bit$ characters is the available resources on the user computer available for \CGG{} use. Keep in mind that unicode or other special characters may consist of $2$ to $4$ $8\,bit$ bytes. Also, newlines are a character and any of the attributes you use count in the total. There is now a horizontal scroll bar as well as the vertical one in the textbox and they only appear when there are more lines or characters that can fit in the original sized textbox.
-
\subsubsection*{Kerning}%
\label{ssub:kerning}
\label{fig:tracer-01}
\end{figure}
-\begin{figure}[hbtp]
- \centering
- \includegraphics[width=0.7\linewidth]{tracer-02.png}
- \caption{Rug in the top picture is traced in order to black it out or replace later}
- \label{fig:tracer-02}
-\end{figure}
-
\begin{description}
\item[New] to create a new point.
\item[Up/Dn] to move highlighted point up or down.
\item[Mouse wheel + shift] scale the outline, centered on cursor.
\end{description}
+\begin{figure}[hbtp]
+ \centering
+ \includegraphics[width=0.7\linewidth]{tracer-02.png}
+ \caption{Rug in the top picture is traced in order to black it out or replace later}
+ \label{fig:tracer-02}
+\end{figure}
+
Be sure to uncheck \textit{Draw} and \textit{Drag} before rendering so that the lines do not show in the video output.
\label{sub:yuv411}
\index{yuv411}
-Modify the 411 yuv to look like 420 color space instead. If the edit to which the effect is applied is not YUV type, a red warning message will appear.
+YUV411 plugin\protect\footnote{credit Eric Olson}
+modifies the 411 yuv to look like 420 color space instead. If the edit to which the effect is applied is not YUV type, a red warning message will appear.
\subsection{YUVShift}%
\label{sub:yuvshift}
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:
projects / goodguy / cin-manual-latex.git / blobdiff