Implementation:Kornia Kornia Histogram

Knowledge Sources	Kornia
Domains	Vision, Image_Enhancement
Last Updated	2026-02-09 15:00 GMT

Overview

This module provides differentiable histogram estimation functions using kernel density estimation (KDE), including 1D histograms, 2D joint histograms, and image-specific histogram computation with multiple kernel options.

Description

histogram.py is part of the kornia.enhance module in the Kornia computer vision library. It implements smooth, differentiable histogram computation that enables gradient flow through histogram-based operations. The module contains:

• marginal_pdf -- computes the marginal probability distribution function using Gaussian kernel density estimation. Returns both the normalized PDF and the raw kernel values.
• joint_pdf -- computes the joint probability distribution function from two sets of kernel values, used for 2D histogram estimation.
• histogram -- estimates a 1D histogram from flattened input using Gaussian KDE with a specified bandwidth (smoothing parameter).
• histogram2d -- estimates a 2D joint histogram from two input tensors.
• image_histogram2d -- computes histograms directly from image tensors of shape (H, W), (C, H, W), or (B, C, H, W). Supports multiple kernel types: triangular, gaussian, uniform, and epanechnikov. Can optionally return probability density functions.

These differentiable histogram functions are used internally by the CLAHE equalization module and can be used for mutual information computation, histogram matching, and other histogram-based image processing tasks.

Usage

Users should import from this module when they need differentiable histogram computation for training pipelines, such as for histogram-based loss functions, mutual information registration, or soft histogram equalization.

Code Reference

Source Location

• Repository: Kornia
• File: kornia/enhance/histogram.py
• Lines: 1-274

Signature

def marginal_pdf(
    values: torch.Tensor,
    bins: torch.Tensor,
    sigma: torch.Tensor,
    epsilon: float = 1e-10,
) -> Tuple[torch.Tensor, torch.Tensor]

def joint_pdf(
    kernel_values1: torch.Tensor,
    kernel_values2: torch.Tensor,
    epsilon: float = 1e-10,
) -> torch.Tensor

def histogram(
    x: torch.Tensor,
    bins: torch.Tensor,
    bandwidth: torch.Tensor,
    epsilon: float = 1e-10,
) -> torch.Tensor

def histogram2d(
    x1: torch.Tensor,
    x2: torch.Tensor,
    bins: torch.Tensor,
    bandwidth: torch.Tensor,
    epsilon: float = 1e-10,
) -> torch.Tensor

def image_histogram2d(
    image: torch.Tensor,
    min: float = 0.0,
    max: float = 255.0,
    n_bins: int = 256,
    bandwidth: Optional[float] = None,
    centers: Optional[torch.Tensor] = None,
    return_pdf: bool = False,
    kernel: str = "triangular",
    eps: float = 1e-10,
) -> Tuple[torch.Tensor, torch.Tensor]

Import

from kornia.enhance import histogram, histogram2d, image_histogram2d
from kornia.enhance.histogram import marginal_pdf, joint_pdf

I/O Contract

Inputs (histogram)

Name	Type	Required	Description
x	torch.Tensor	Yes	Input tensor of shape (B, D) to compute the histogram from
bins	torch.Tensor	Yes	Bin centers tensor of shape (N_bins,)
bandwidth	torch.Tensor	Yes	Gaussian smoothing factor, scalar tensor
epsilon	float	No	Numerical stability constant. Default: 1e-10

Inputs (image_histogram2d)

Name	Type	Required	Description
image	torch.Tensor	Yes	Image tensor of shape (H, W), (C, H, W), or (B, C, H, W)
min	float	No	Lower end of the interval (inclusive). Default: 0.0
max	float	No	Upper end of the interval (inclusive). Default: 255.0
n_bins	int	No	Number of histogram bins. Default: 256
bandwidth	Optional[float]	No	Smoothing factor. Default: (max - min) / n_bins
centers	Optional[torch.Tensor]	No	Custom bin centers of shape (n_bins,). Default: None
return_pdf	bool	No	Whether to also return probability densities. Default: False
kernel	str	No	Kernel type: "triangular", "gaussian", "uniform", "epanechnikov". Default: "triangular"
eps	float	No	Numerical stability constant. Default: 1e-10

Outputs (histogram)

Name	Type	Description
pdf	torch.Tensor	Computed histogram of shape (B, N_bins)

Outputs (image_histogram2d)

Name	Type	Description
hist	torch.Tensor	Histogram of shape (bins), (C, bins), or (B, C, bins)
pdf	torch.Tensor	Probability densities (same shape as hist) if return_pdf=True, zeros otherwise

Usage Examples

import torch
from kornia.enhance import histogram, histogram2d, image_histogram2d

# 1D histogram estimation
x = torch.rand(1, 10)
bins = torch.linspace(0, 255, 128)
hist = histogram(x, bins, bandwidth=torch.tensor(0.9))
# hist.shape == torch.Size([1, 128])

# 2D joint histogram
x1 = torch.rand(2, 32)
x2 = torch.rand(2, 32)
bins = torch.linspace(0, 255, 128)
hist2d = histogram2d(x1, x2, bins, bandwidth=torch.tensor(0.9))
# hist2d.shape == torch.Size([2, 128, 128])

# Image histogram with triangular kernel
image = torch.rand(1, 3, 64, 64)
hist, pdf = image_histogram2d(image, min=0.0, max=1.0, n_bins=256, return_pdf=True)
# hist.shape == torch.Size([1, 3, 256])

# Image histogram with Gaussian kernel
hist, _ = image_histogram2d(image, min=0.0, max=1.0, n_bins=64, kernel="gaussian")

Related Pages

• Principle:Kornia_Kornia_Differentiable_Histogram