From d9f1278097e427e8ba2ac4889e08568b3696843a Mon Sep 17 00:00:00 2001 From: "Steinar H. Gunderson" Date: Mon, 29 May 2017 18:41:22 +0200 Subject: [PATCH] Add a section about the new frame analyzer. --- analyzer.rst | 88 +++++++++++++++++++++++++++++++++++++++ gettingstarted.rst | 12 ++++++ hdmisdi.rst | 6 ++- images/context-menu.png | Bin 15970 -> 17078 bytes images/rgb-histogram.png | Bin 0 -> 566826 bytes images/wedges.png | Bin 0 -> 1345 bytes index.rst | 1 + 7 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 analyzer.rst create mode 100644 images/rgb-histogram.png create mode 100644 images/wedges.png diff --git a/analyzer.rst b/analyzer.rst new file mode 100644 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 ` +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 68edc81..c6ce91d 100644 --- 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