class pyqtgraph.HistogramLUTItem(image=None, fillHistogram=True, levelMode='mono', gradientPosition='right', orientation='vertical')[source]

GraphicsWidget with controls for adjusting the display of an ImageItem.


  • Image histogram

  • Movable region over the histogram to select black/white levels

  • Gradient editor to define color lookup table for single-channel images

  • image (pyqtgraph.ImageItem, optional) – If provided, control will be automatically linked to the image and changes to the control will be reflected in the image’s appearance. This may also be set via setImageItem().

  • fillHistogram (bool, optional) – By default, the histogram is rendered with a fill. Performance may be improved by disabling the fill. Additional control over the fill is provided by fillHistogram().

  • levelMode (str, optional) –

    ‘mono’ (default)

    One histogram with a LinearRegionItem is displayed to control the black/white levels of the image. This option may be used for color images, in which case the histogram and levels correspond to all channels of the image.


    A histogram and level control pair is provided for each image channel. The alpha channel histogram and level control are only shown if the image contains an alpha channel.

  • gradientPosition (str, optional) – Position of the gradient editor relative to the histogram. Must be one of {‘right’, ‘left’, ‘top’, ‘bottom’}. ‘right’ and ‘left’ options should be used with a ‘vertical’ orientation; ‘top’ and ‘bottom’ options are for ‘horizontal’ orientation.

  • orientation (str, optional) – The orientation of the axis along which the histogram is displayed. Either ‘vertical’ (default) or ‘horizontal’.


Emits the HistogramLUTItem itself when the gradient changes




Emits the HistogramLUTItem itself while the movable region is changing




Emits the HistogramLUTItem itself when the movable region is finished changing



See also


HistogramLUTItem is most useful when paired with an ImageItem.


Widget containing a paired ImageItem and HistogramLUTItem.


QWidget containing a HistogramLUTItem for widget-based layouts.

__init__(image=None, fillHistogram=True, levelMode='mono', gradientPosition='right', orientation='vertical')[source]

Enable auto-scaling on the histogram plot.


Disable auto-scaling on the histogram plot.

fillHistogram(fill=True, level=0.0, color=(100, 100, 200))[source]

Control fill of the histogram curve(s).

  • fill (bool, optional) – Set whether or not the histogram should be filled.

  • level (float, optional) – Set the fill level. See PlotCurveItem.setFillLevel. Only used if fill is True.

  • color (color, optional) – Color to use for the fill when the histogram levelMode == "mono". See PlotCurveItem.setBrush.


Return the min and max levels.

For rgba mode, this returns a list of the levels for each channel.

getLookupTable(img=None, n=None, alpha=None)[source]

Return a lookup table from the color gradient defined by this HistogramLUTItem.

setHistogramRange(mn, mx, padding=0.1)[source]

Set the Y range on the histogram plot. This disables auto-scaling.


Set an ImageItem to have its levels and LUT automatically controlled by this HistogramLUTItem.


Set the method of controlling the image levels offered to the user.

Options are ‘mono’ or ‘rgba’.

setLevels(min=None, max=None, rgba=None)[source]

Set the min/max (bright and dark) levels.

  • min (float, optional) – Minimum level.

  • max (float, optional) – Maximum level.

  • rgba (list, optional) – Sequence of (min, max) pairs for each channel for ‘rgba’ mode.