Add a section about the new frame analyzer.

diff --git a/analyzer.rst b/analyzer.rst
new file mode 100644 (file)
index 0000000..09f6240
--- /dev/null
+++ b/analyzer.rst
@@ -0,0 +1,88 @@
+The frame analyzer
+==================
+
+Maintaining signal integrity throughout a chain can be surprisingly tricky;
+a number of quite devices, even expensive ones, do not properly pass
+input pixels unchanged to the output even when no processing is requested.
+(Commonly, this is due to misunderstandings of how Y'CbCr is to be calculated,
+or that one end or the other is doing something wrong in the HDMI handshake.)
+This means that it can be useful to verify that there are no subtle color shifts,
+and that the entire 0–255 brightness range is both being input and output.
+
+The **frame analyzer**, new in Nageru 1.6.0 and available from the video menu,
+can help with this.  It allows you to look at any input, grab a frame (manually
+or periodically), and then hover over specific pixels to look at their RGB
+values. When you're done, simply close it, and it will stop grabbing frames.
+
+Synthetic tests and common problems
+-----------------------------------
+
+If your input is synthetic, such as from a computer, you may want to use an
+image such as this one as your test source (simply right-click and save):
+
+.. image:: images/wedges.png
+
+This contains both whites/grays evenly spaced across the entire range
+(0, 13, 27, 40, 54, 67, 81, 94, 107, 121, 134, 148, 161, 174, 188, 201,
+215, 228, 242, 255), and the same for red, green and blue (although
+with slightly fewer steps: 255, 238, 221, 204, 187, 170, 153, 136,
+119, 102, 85, 68, 51, 34, 17, 0). (You can also use any other picture
+where you know the right pixel values, of course.)
+
+Using the frame analyzer, you can simply look at each value to see if the input
+matches the expected values. Being off-by-one (or even occasionally two)
+is normal due to Y'CbCr rounding errors, but more than this indicates that
+something in your chain is doing something wrong with the pixel values.
+Common errors include:
+
+  * Dark values becoming entirely black (crushed blacks), and similarly
+    with light values becoming entirely white (blown-out highlights).
+    This indicates full-range input being interpreted as limited-range.
+  * Black becoming some non-black dark (e.g. 16) or white becoming some
+    non-white light (e.g. 235). This indicates the opposite problem,
+    i.e., limited-range input being interpreted as full-range. Nageru
+    never defaults to full input range, so this should be rare
+    unless you set full range yourself.
+  * Pure-color inputs no longer being pure-color (e.g. a pure red
+    getting some green and blue). This indicates wrong choice of Y'CbCr
+    coefficients.
+  * Black and white coming through correctly, but midtones being too
+    light or too dark. This indicates a wrong gamma ramp.
+
+Nageru cannot correct arbitrary input problems, but the most common ones
+can be fixed by selecting a different *input interpretation* for the card in question.
+Simply right-click the input, and you can choose from a variety of
+different ones. Optionally, check the settings on your sending device
+to see if they can be corrected, as this is usually a better choice
+than forcing Nageru to interpret the output in a nonstandard way.
+
+
+Non-synthetic inputs
+--------------------
+
+If your input is non-synthetic, like a camera, it is harder to spot
+problems. However, the *RGB histogram* can sometimes be of help,
+especially when it comes to spotting range problems. For instance,
+limited range being wrongly interpreted as full range will look
+something like the picture on the right, where the lower and upper
+ranges are unused (although sometimes, it only affects the lower
+part):
+
+.. image:: images/rgb-histogram.png
+
+(Note that even side-by-side, it's not that easy to spot how much duller the
+image on the right is without looking at the histogram. However, when switching
+back and forth, for instance between multiple cameras of the same scene,
+the difference can be quite dramatic.)
+
+Similarly, if your scene is over- or underexposed, you may see values piling up
+near the one of extremes (0 or 255). If this persists, it usually means you
+should adjust the exposure on your camera if possible. If the exposure is
+correctly set, or you see values piling up on *both* 0 and 255 at the same
+time, it may either mean that the scene has too much dynamic range for your
+camera to handle, or that it sends full-range Y'CbCr when it should have been
+sending limited-range.
+
+Finally, note that the section on :ref:`measuring HDMI/SDI latency <measuring-latency>` 
+describes another useful trick (looping) you can use to verify correctness, assuming
+you have a card capable of HDMI/SDI output.

diff --git a/gettingstarted.rst b/gettingstarted.rst
index 68edc81605f53f7e8ab53412c9d72514cf6100d4..c6ce91d5941cab74c550b1f9470703a63faf05de 100644 (file)
--- a/gettingstarted.rst
+++ b/gettingstarted.rst
@@ -123,6 +123,8 @@ The video menu contains the following elements:
     You can achieve the same effect as this option by sending
     SIGHUP to the Nageru process.
 
+  * **Open frame analyzer:** See :doc:`analyzer` for more information.
+
   * **Change x264 bitrate:** See :doc:`streaming` for more information.
 
   * **HDMI/SDI output device, HDMI/SDI output resolution:** See :doc:`hdmisdi`
@@ -172,6 +174,16 @@ The options presented are as follows:
    cards that can handle it in hardware), but a simple option (“Scan”)
    is available to try all modes in turn until a signal is received.
 
+ * **Input interpretation:** Choose how the Y'CbCr values in the input signal
+   are to be interpreted. *Auto* will choose whatever is correct (as per the
+   appropriate standards) for the current video mode, but occasionally,
+   devices will get this wrong, and you will need to change this setting
+   to get correct colors. You can use the *--input-ycbcr-interpretation=*
+   command-line option to achieve the same effect.
+
+   See :doc:`analyzer` for figuring out if you need to change this.
+   If unsure, leave it unchanged.
+
  * **Use as audio source:** See the :doc:`audio <audio>` page for more
    information. For simple audio only; unavailable in multichannel mode.
 

diff --git a/hdmisdi.rst b/hdmisdi.rst
index 064fe85aef8c90cbc6ddf75ec846c31b6d1b14d6..30fc5eef5256f8222b1d09cf782a4dc05226014e 100644 (file)
--- a/hdmisdi.rst
+++ b/hdmisdi.rst
@@ -164,6 +164,8 @@ Audio and video queue lengths do not need to match exactly; the two streams
 and for HDMI/SDI output.
 
 
+.. _measuring-latency:
+
 Measuring latency
 .................
 
@@ -200,7 +202,9 @@ delays that don't happen within Nageru itself, like any external converters,
 delays in the input driver, etc.. (It can also act as a sanity check to make
 sure your A/V chain passes the signal through without quality degradation,
 if you first set up a static picture as a signal and then switch to the loop
-input to verify that the signal stays stable without color shifts e.g. [#]_)
+input to verify that the signal stays stable without color e.g. shifts [#]_.
+See the section on :ref:`the frame analyzer <analyzer>` for other ways of
+debugging signal integrity.)
 
 For this, the *timecode output* is useful; you can turn it on from the Video
 menu, or through the command-line flag *--timecode-stream*. (You can also

diff --git a/images/context-menu.png b/images/context-menu.png
index 3d6b55dd6cb3150cff3d5d52e908066ce48f199f..c3d7c928650e5ce3c7ec8bf00f2728e13d57837c 100644 (file)
Binary files a/images/context-menu.png and b/images/context-menu.png differ

diff --git a/images/rgb-histogram.png b/images/rgb-histogram.png
new file mode 100644 (file)
index 0000000..a303978
Binary files /dev/null and b/images/rgb-histogram.png differ

diff --git a/images/wedges.png b/images/wedges.png
new file mode 100644 (file)
index 0000000..539122a
Binary files /dev/null and b/images/wedges.png differ

diff --git a/index.rst b/index.rst
index f33bfc959b8a5f186f4338e53a8a0e1ecd3e84fd..1932e3f98ae8a20043151f4695c7f95150f8f2c4 100644 (file)
--- a/index.rst
+++ b/index.rst
@@ -14,6 +14,7 @@ Contents:
    gettingstarted
    hardware
    audio
+   analyzer
    streaming
    hdmisdi
    theme