Credit Andrea - explanations on Clipping with Plugins mostly as pertains to HDR

diff --git a/parts/Introduction.tex b/parts/Introduction.tex
index 0f2c2f4dc255ccb7df5e57dbb06e01f60499e72a..b9175b95de79f28cd3c32b7f26b509e7fc662fa0 100644 (file)
--- a/parts/Introduction.tex
+++ b/parts/Introduction.tex
@@ -142,11 +142,12 @@ programmers.
                     \item Title plugin virtually unlimited script size with many changeable attributes such as size, blink, color.
                     \item Motion Graphics using the Sketcher plugin to create elements such as ellipses, rectangles and shapes for simpler motion graphics.
                     \item Open EDL for editing clips, nested clips, and xml files while working on a Project.
                     \item Title plugin virtually unlimited script size with many changeable attributes such as size, blink, color.
                     \item Motion Graphics using the Sketcher plugin to create elements such as ellipses, rectangles and shapes for simpler motion graphics.
                     \item Open EDL for editing clips, nested clips, and xml files while working on a Project.

-                   \item File by Reference; To be able to modify the original source during editing (which in this case, becomes destructive).
+                        \item File by Reference; To be able to modify the original source during editing (which in this case, becomes destructive).

                     \item The Vectorscope option in the Videoscope plugin allows for the use of any number of user-supplied grid patterns as an Overlay.
                     \item Hardware acceleration with vaapi and vdpau for computers with graphics hardware meeting certain criteria.
                     \item Bump Autos is a new type of keyframe automation that allows you to easily create and manage keyframes intervals in Speed, Fade and Camera/Projector-XYZ curves.
                     \item The Vectorscope option in the Videoscope plugin allows for the use of any number of user-supplied grid patterns as an Overlay.
                     \item Hardware acceleration with vaapi and vdpau for computers with graphics hardware meeting certain criteria.
                     \item Bump Autos is a new type of keyframe automation that allows you to easily create and manage keyframes intervals in Speed, Fade and Camera/Projector-XYZ curves.

-                   \item One of the only Linux NLEs that handles and renders RGB, 444, 422 and 420 at 8, 10 and more-bit footage as opposed to working in only 8-bit (which introduces some artifacts like banding); both in Full Range Color and limited Broadcast Range Color.
+                                        \item One of the only Linux NLEs that handles and renders RGB, 444, 422 and 420 at 8, 10 and more-bit footage as opposed to working in only 8-bit (which introduces some artifacts like banding); both in Full Range Color and limited Broadcast Range Color.
+                    \item \CGG{} runs internally in 32-bit floating-point and thus can read and process HDR media.

                     \item The Blend Algebra/Blend Program plugins provide the advanced feature of combining and modifying color pixels and transparencies of several tracks according to a mathematic algorithm written entirely by the user in the form of compact and simple piece of code. Such user defined algorithms (blend functions) are compiled, dynamically linked and immediately executed inside Cinelerra on the fly without the need to restart the application, reload the project, reattach plugins, etc. 
                 \end{itemize}
 \end{description}
                     \item The Blend Algebra/Blend Program plugins provide the advanced feature of combining and modifying color pixels and transparencies of several tracks according to a mathematic algorithm written entirely by the user in the form of compact and simple piece of code. Such user defined algorithms (blend functions) are compiled, dynamically linked and immediately executed inside Cinelerra on the fly without the need to restart the application, reload the project, reattach plugins, etc. 
                 \end{itemize}
 \end{description}

diff --git a/parts/Plugins.tex b/parts/Plugins.tex
index 8661d2667a60690154c87e78745d9e3c62a7c71f..b711e39d36a2b02633b9feadb31a24fd46564931 100644 (file)
--- a/parts/Plugins.tex
+++ b/parts/Plugins.tex
@@ -422,6 +422,11 @@ ffmpeg -i /tmp/filename.mpeg -threads 15 -vf format=rgb24,xxxxxxs=threads=8 -aco
 
 This converts the input to rgb before xxxxxx runs, and so it too is slower (because there is more color data). You would ordinarily avoid this conversion by omitting the \texttt{format=rgb24} parameter. An example ffmpeg plugin that could easily take advantage of an auxilliary opts file is \textit{nlmeans}.
 
 
 This converts the input to rgb before xxxxxx runs, and so it too is slower (because there is more color data). You would ordinarily avoid this conversion by omitting the \texttt{format=rgb24} parameter. An example ffmpeg plugin that could easily take advantage of an auxilliary opts file is \textit{nlmeans}.
 

+\subsection{Pipeline HDR and plugins}%
+\label{sub:pipeline_hdr_plugins}
+
+\CGG{} runs internally in 32-bit floating-point and thus can read and process HDR media. However, there are plugins and tools that can introduce clipping that must be taken into account to keep the whole pipeline in HDR. The limited plugins are: \textit{Blur; Color 3 Way} (partially); \textit{Color Space; Foreground; Histogram} (partially); \textit{Histogram Bezier; Title; Videoscope} (partially).
+

 \section{Audio Effects - Native}%
 \label{sec:audio_effects_native}
 \settocdepth{subsection}
 \section{Audio Effects - Native}%
 \label{sec:audio_effects_native}
 \settocdepth{subsection}


@@ -1543,7 +1548,7 @@ If you are building an alpha selection mask by first intersection and then union
 \label{sub:blur}
 \index{blur}
 
 \label{sub:blur}
 \index{blur}
 

-This is a Gaussian type blur. Other blur plugins -- \textit{Linear}, \textit{Motion}, \textit{Radial}, and \textit{Zoom} --are described later. This plugin is keyframable. In case the frame is HDR, this plugin introduces a clip to prevent pixel values outside the normalized range (0, 1.0f). Blur is used to blur a video track via the following parameters:
+This is a Gaussian type blur. Other blur plugins -- \textit{Linear}, \textit{Motion}, \textit{Radial}, and \textit{Zoom} --are described later. This plugin is keyframable. Blur is used to blur a video track via the following parameters:

 \begin{description}
     \item[Horizontal and vertical] values are used to tell which one of the fields blurring affects; can be both.
     \item[Radius] use this dial to define the amount of blur to apply.
 \begin{description}
     \item[Horizontal and vertical] values are used to tell which one of the fields blurring affects; can be both.
     \item[Radius] use this dial to define the amount of blur to apply.


@@ -1888,7 +1893,7 @@ Since \textit{complementary colors} are neutralized, to eliminate a \textit{colo
 This plugin is a tool that can be used to convert your input media, such as a recording from your camera,
 from one color space/range to another.  It works for both RGB and YUV as set by your project format.
 Options are BT601, BT709, or BT2020 for Color Space input and output and JPEG or MPEG for Color Range
 This plugin is a tool that can be used to convert your input media, such as a recording from your camera,
 from one color space/range to another.  It works for both RGB and YUV as set by your project format.
 Options are BT601, BT709, or BT2020 for Color Space input and output and JPEG or MPEG for Color Range

-input and output. In case the frame is HDR, this plugin introduces a clip to prevent pixel values outside the normalized range (0, 1.0f). The Inverse option checkbox is available in case your media was rendered in the wrong
+input and output.  The Inverse option checkbox is available in case your media was rendered in the wrong

 color space  or range so that you can fix it.
 
 \begin{figure}[H]
 color space  or range so that you can fix it.
 
 \begin{figure}[H]


@@ -2158,7 +2163,7 @@ This effect flips a video track either vertically or horizontally.
 \index{foreground}
 
 Whatever the visual content of the frame, the Foreground plugin application applies a uniform color that can be chosen by color picker, color wheel, color presets, or by entering the hexadecimal value.
 \index{foreground}
 
 Whatever the visual content of the frame, the Foreground plugin application applies a uniform color that can be chosen by color picker, color wheel, color presets, or by entering the hexadecimal value.

-In addition there are HSV, RGB, YUV, and alpha sliders to vary the color accordingly. In case the frame is HDR, this plugin introduces a clip to prevent pixel values outside the normalized range (0, 1.0f).
+In addition there are HSV, RGB, YUV, and alpha sliders to vary the color accordingly.

 
 \subsection{Frames to fields}%
 \label{sub:frames_to_fields}
 
 \subsection{Frames to fields}%
 \label{sub:frames_to_fields}


@@ -2335,8 +2340,14 @@ The histogram allows an immediate view of the contrast amplitude of an image wit
     \label{fig:histogram}
 \end{figure}
 
     \label{fig:histogram}
 \end{figure}
 

-The Histogram is always performed in floating point RGB regardless of the project color space, but with clipping at 1.0. When using the X11 graphics driver and RGBA-FLOAT color model, Histogram allows you to read pixels value greater than (0 - 1.0f), But these values are not displayed in the Compositor window. to accomodate HDR. This does not work when using X11-OpenGL because it is an 8-bit limited driver. The display will stop at +110\%, but there is no clipping. By lowering
-the brightness all out-of-range values become visible (tone mapping), even those initially above 110\%.
+The Histogram is always performed in floating point RGB regardless of
+the project color space, but with clipping at 1.0. When using the X11
+graphics driver and RGBA-FLOAT color model, Histogram allows you to
+display greater than (0 - 1.0f) values to accomodate HDR. This does
+not work when using X11-OpenGL because it is an 8-bit limited driver.
+The display will stop at +110\%, but there is no clipping. By lowering
+the brightness all out-of-range values become visible, even those
+initially above 110\%.

 
 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).
 
 
 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).
 


@@ -2441,7 +2452,7 @@ So, by reporting the sum the shape of the results are more similar to Bezier.
 \label{sub:histogram_bezier_curves}
 \index{histogram Bezier}
 
 \label{sub:histogram_bezier_curves}
 \index{histogram Bezier}
 

-Histogram Bézier allows an immediate view of the contrast amplitude of an image with its distribution of luma and colors values using a piecewise linear method (bins). In addition it uses a Bézier curve (parametric) on the histogram plot. When mapping color spaces, it has a variety of presentations to get smoother transitions and more pleasing output. It uses more general remapping, not just straight lines but more contour lines. Curves are perhaps the most powerful and sophisticated tool for color correction. For some repetitive details, see the previous description of the Histogram plugin. Histogram Bézier is keyframable. The scale is given in percent ($0 - 100\% \pm 10\%$). In case the frame is HDR, this plugin introduces a clip to prevent pixel values outside the normalized range (0, 1.0). The default curve is Log type and can use either RGB or YUV sources without implementing conversions.
+Histogram Bézier allows an immediate view of the contrast amplitude of an image with its distribution of luma and colors values using a piecewise linear method (bins). In addition it uses a Bézier curve (parametric) on the histogram plot. When mapping color spaces, it has a variety of presentations to get smoother transitions and more pleasing output. It uses more general remapping, not just straight lines but more contour lines. Curves are perhaps the most powerful and sophisticated tool for color correction. For some repetitive details, see the previous description of the Histogram plugin. Histogram Bézier is keyframable. The scale is given in percent ($0 - 100\% \pm 10\%$). The default curve is Log type and can use either RGB or YUV sources without implementing conversions.

 
 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.
 
 
 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.
 

diff --git a/parts/Quickstart.tex b/parts/Quickstart.tex
index 803567820c79badcdb7e0a471e261b4963ce55f7..ade751eba6bc07bce994b9f9fd7b4a8da5424bad 100644 (file)
--- a/parts/Quickstart.tex
+++ b/parts/Quickstart.tex
@@ -516,6 +516,12 @@ A color space is a subspace of the absolute CIE XYZ color space that includes al
 
 The camera sensors are always RGB and linear. Generally, those values get converted to YUV in the files that are produced, because it is a more efficient format thanks to chroma subsampling, and produces smaller files (even if of lower quality, i.e. you lose part of the colors data). The conversion is nonlinear and so it concerns the "transfer characteristic" or gamma. The encoder gets input YUV and compresses that. It stores the transfer function as metadata if provided.
 
 
 The camera sensors are always RGB and linear. Generally, those values get converted to YUV in the files that are produced, because it is a more efficient format thanks to chroma subsampling, and produces smaller files (even if of lower quality, i.e. you lose part of the colors data). The conversion is nonlinear and so it concerns the "transfer characteristic" or gamma. The encoder gets input YUV and compresses that. It stores the transfer function as metadata if provided.
 

+\subsection{HDR}%
+\label{sub:hdr}
+
+\CGG{} runs internally in 32-bit floating-point and thus can read and process HDR media. However, there are plugins and tools that can introduce clipping that must be taken into account to keep the whole pipeline in HDR. The manual indicates which plugins limit pixel values in the range $(0, 1.0)$. The easiest way to see if a media is HDR is to use the \texttt{eyedroppe}r tool (Get Color) in the Compositor window.
+If we use HDR media and need to do a Tone Mapping to make the pixel values fall within the range $(0, 1.0)$, we can use the \texttt{Blender Program} plugin and, inside it, load the function (found in \texttt{=>Syslib}) \textit{tone\_mapping.bp}. Instructions for using this function can be found \href{https://cinelerra-gg.org/download/testing/BlendPluginExamples/Examples.txt}{here} at example 6.
+

 \subsection{CMS}%
 \label{sub:cms}
 
 \subsection{CMS}%
 \label{sub:cms}