Histogram

Histogram(clip clip [, string mode] [, float factor])

A multipurpose audio/video analysis tool, which supports the following modes:

Classic (waveform) mode, the default;
Levels YUV histogram mode;
Color and Color2 vectorscope modes;
Luma special viewing mode;
Audiolevels audio level meter; and
Stereo, StereoOverlay, and StereoY8 audio graphs.

Classic mode

Histogram

Available in YUV mode only. This will add a per-line luminance graph (usually called a Waveform Monitor) on the right side of the video, increasing clip.Width by 256. The left side of the graph represents luma=0 and the right side represents luma=255. Values outside the valid CCIR-601 range are shown with a brown/yellowish color background; a greenish line represents Y=128.

If you prefer to see luma=0 on bottom and luma=255 on top, use this:

TurnRight.Histogram.TurnLeft

Levels mode

Histogram("levels")

Available in all planar modes, except Y8. This mode will display three histograms on the right side of the video frame, increasing clip.Width by 256. This will show the distribution of the Y, U and V components in the current frame.

The top graph displays the Y (luma) distribution of the frame, where the left side represents Y=0 and the right side represents Y=255. Values outside the valid CCIR601 range have been indicated with faded colors; Y=128 has been marked with a dotted line. The vertical axis shows the number of pixels for a given luma (Y) value.

The middle graph is similar, and displays the U component; the bottom graph displays the V component.

The factor option (100.0 by default) specifies how the histograms are displayed, exaggerating the vertical scale. It is specified as percentage of the total population (that is number of luma or chroma pixels in a frame). For example:

Histogram("levels", 0.5)

NOTE, factor is an unnamed optional argument;
Histogram(mode="levels", factor=0.5) will not work, but Histogram("levels", 0.5) works fine.

Color mode

Histogram("color")

Available in all planar modes except Y8. This mode will display the chroma values (U/V color placement) in a two dimensional graph (called a vectorscope) on the right side of the video frame, increasing clip.Width by 256. It can be used to read of the hue and saturation of a clip. At the same time it is a histogram: the whiter a pixel in the vectorscope, the more pixels of the input clip correspond to that chroma value. The lighter background denotes the valid CCIR-601 range.

Histogram("color") output with added labels

The vectorscope image to the left has labels added for the U and V axes and degrees of hue. Spots have also been added, showing 75% saturated ColorBars. The U component is displayed on the horizontal (X) axis, with the leftmost side being U=0 and the rightmost side being U=255. The V component is displayed on the vertical (Y) axis, with the top representing V=0 and the bottom representing V=255.

The position of a point on the scope corresponds to a chroma value from the input clip. So the graph can be used to read of the hue (shown as angular position, with 0 degrees at 3 o'clock) and the saturation (shown as distance from the center). As the hue of a color changes, it moves around the center of the scope. The center is where U and V equal 128, which means that the saturation is zero and the corresponding pixel has no color. If you increase the amount of a specific color, while leaving the other colors unchanged, the saturation increases, and you move towards the edge of the scope.

At U=255, V=128 the hue is zero (blue, approximately) and the saturation is at maximum, that is,

saturation = sqrt( (U-128)² + (V-128)² ) or 127

When turning hue clockwise 90 degrees, the chroma is given by U=128, V=255 (red, approximately). Keeping the hue constant and decreasing the saturation, means that we move from the circle to the center of the vectorscope. Thus the color flavor remains the same, only it fades slowly to greyscale.

Color2 mode

Histogram("color2")

Available in all planar modes except Y8. This mode will display the pixels in a two dimensional graph (called a vectorscope) on the right side of the video frame, increasing clip.Width by 256. It can be used to read of the hue and saturation of a clip.

The U component is displayed on the horizontal (X) axis, with the leftmost side being U=0 and the rightmost side being U=255. The V component is displayed on the vertical (Y) axis, with the top representing V=0 and the bottom representing V=255. The white square denotes the valid CCIR-601 range.

Histogram("color2") output with added labels

As in the previous vectorscope image, labels have been added. The position of a point on the scope corresponds to a chroma value from the input clip, exactly as with Histogram("color"). A color wheel is shown around the circumference of the scope and divided into six hues (red, yellow, green, cyan, blue and magenta), with white tick marks at 15 degree intervals, to help you reading of the hue values.

Luma mode

Histogram("luma")

Available in planar and YUY2 modes. This mode will amplify luminance, and display very small luminance variations. This is good for detecting blocking and noise, and can be helpful at adjusting filter parameters. In this mode a 1 pixel luminance difference will show as a 16 pixel luminance pixel, thus seriously enhancing small flaws.

Audiolevels mode

Histogram("audiolevels")

Planar video is required. Audio is converted to 16 bit. Shows the audio levels in decibels for each channel present. For example, if the source has six channels of audio, six vertical bars will be shown.

The green bars show the RMS ([wikipedia:Root_mean_square|Root Mean Square]]) level of the audio in each video frame (let's say n samples) using the following formula:

$<math> RMS = 20 \cdot log_{10}( 1/32768 \cdot \sqrt{ 1/n \cdot \sum_{j=1}^{n} sample(j)^{2}} ) </math>$

The blue bars show the max (peak) level of the audio in each video frame using the following formula:

$<math> max = 20 \cdot log_{10}(max_{j} (sample(j)) / 32768) </math>$

The maximum possible level without clipping is 0 dB by definition. The minimum level for 16 bit audio is therefore

$<math> 20 \cdot log_{10}(1/32768) = - 90.31 \ dB </math>$ (since 2¹⁶ / 2 = 32768)

Stereo, StereoY8 and StereoOverlay mode

Histogram("stereo")

Requires a source clip with stereo audio; StereoOverlay also requires a source clip with a planar color format. These modes show a classic stereo graph (or Lissajous pattern) from the clip audio, often seen in recording studios. They are used to view the left-right phase distribution of the input signal. In-phase stereo appears predominantly vertical (as shown), but incorrectly phased stereo appears predominantly horizontal. Two-channel Mono appears as a vertical line.

StereoOverlay will overlay the graph on top of the original. Each frame will contain only information from the current frame to the beginning of the next frame. The signal is linearly upsampled 8x, to provide clearer visuals. Stereo and StereoY8 won't overlay the graph on the video, but will just return the graph alone as a 512×512 video clip (in YV12 or Y8 format respectively).

Changes

v2.60	Added StereoY8 mode. Added factor option.
v2.58	Added planar support. Color2 and Audiolevels modes added.
v2.56	Added invalid colors in YUY2 mode.
v2.56	Added dots to mode = "stereo" to show bias/offsets.
v2.53	Added different modes.

Histogram

Classic mode

Levels mode

Color mode

Color2 mode

Luma mode

Audiolevels mode

Stereo, StereoY8 and StereoOverlay mode

Changes

Views

Personal tools

Navigation

community

in other languages

Search

Tools