How to Show a 3D Color Histogram in FFmpeg

This guide explains how to visualize three-channel color distributions in a video using FFmpeg's histogram filter. You will learn how to configure the filter to display all three color components (Red, Green, Blue or Y, U, V) simultaneously in parade and stack layouts, colorize the graphs, and overlay or place the scope side-by-side with your original footage.

Basic 3-Channel Histogram Command

FFmpeg’s histogram filter visualizes the color spectrum across three dimensions of color space (such as R, G, and B or Y, U, and V). To view the 3-channel histogram directly using ffplay, run:

ffplay -i input.mp4 -vf "format=gbrp,histogram=display_mode=parade:components=7"

Key Parameters Explained

  • format=gbrp: Converts the pixel format to planar RGB before it enters the filter. This ensures the three displayed channels correspond to Green, Blue, and Red rather than luminance and chrominance (YUV).
  • display_mode=parade: Displays the three color channels side by side. You can also set this to stack to position the three channels vertically on top of one another.
  • components=7: A bitmask setting which channels to display. The value 7 corresponds to binary 111, instructing FFmpeg to render all three channels.
  • levels_mode=linear (or logarithmic): Defines the amplitude scaling of the values. Logarithmic mode helps expose low-density color values that might otherwise be invisible.

Displaying the Histogram Side-by-Side with the Video

To view the source video next to its color histogram, use a complex filtergraph with split and hstack:

ffmpeg -i input.mp4 -filter_complex \
"[0:v]split=2[orig][temp]; \
 [temp]format=gbrp,histogram=display_mode=parade:components=7[hist]; \
 [orig][hist]hstack" \
-c:v libx264 -crf 18 -preset fast output.mp4

For real-time previewing via ffplay, the same filtergraph applies:

ffplay -i input.mp4 -vf "split=2[orig][temp],[temp]format=gbrp,histogram=display_mode=parade:components=7[hist],[orig][hist]hstack"

Overlaying the Histogram on Top of the Video

If you prefer a picture-in-picture style scope, scale the histogram and overlay it onto a corner of the source footage:

ffplay -i input.mp4 -vf \
"split=2[base][scope]; \
 [scope]format=gbrp,histogram=display_mode=stack:components=7,scale=320:-1[pip]; \
 [base][pip]overlay=W-w-10:10"
  • scale=320:-1: Reduces the histogram width to 320 pixels while preserving aspect ratio.
  • overlay=W-w-10:10: Pins the scope to the top-right corner with a 10-pixel margin.

Alternative: Color Plane Mapping with Vectorscope

While the histogram filter separates the three color channels into discrete waveforms or bars, plotting color chrominance as a 2D/3D planar distribution can also be done using FFmpeg's vectorscope filter:

ffplay -i input.mp4 -vf "vectorscope=mode=color3"

The vectorscope filter with mode=color3 plots U and V color difference components against each other in real-time, providing an alternative multidimensional representation of your video's color gamut.