Implementation:Kornia Kornia Histogram Matching
| Knowledge Sources | |
|---|---|
| Domains | Vision, Image_Enhancement, Color_Transfer |
| Last Updated | 2026-02-09 15:00 GMT |
Overview
Adjusts the pixel value distribution of a source image to match the histogram of a template image using cumulative distribution function mapping.
Description
The histogram_matching module in the Kornia contrib package implements histogram matching (also known as histogram specification). It transforms a source image so that its histogram matches that of a given template image. The algorithm computes empirical cumulative distribution functions (CDFs) for both images, then uses linear interpolation to map source pixel values to the corresponding template quantiles. The module also includes a helper function interp that provides one-dimensional linear interpolation for monotonically increasing sample points (similar to numpy.interp). Note that for batched tensors, the histograms are computed over the entire flattened tensor, not element-wise per batch item.
Usage
Import this module when you need to perform color transfer or normalize the intensity distribution of images to match a reference, for example when stitching images from different sources, for domain adaptation, or for consistent visual appearance across a dataset.
Code Reference
Source Location
- Repository: Kornia
- File: kornia/contrib/histogram_matching.py
- Lines: 1-85
Signature
def histogram_matching(source: torch.Tensor, template: torch.Tensor) -> torch.Tensor: ...
def interp(x: torch.Tensor, xp: torch.Tensor, fp: torch.Tensor) -> torch.Tensor: ...
Import
from kornia.contrib import histogram_matching
I/O Contract
Inputs (histogram_matching)
| Name | Type | Required | Description |
|---|---|---|---|
| source | torch.Tensor | Yes | Image tensor to transform (any shape, will be flattened internally) |
| template | torch.Tensor | Yes | Template image whose histogram the source should match (can have different dimensions) |
Inputs (interp)
| Name | Type | Required | Description |
|---|---|---|---|
| x | torch.Tensor | Yes | x-coordinates at which to evaluate the interpolation |
| xp | torch.Tensor | Yes | x-coordinates of the data points (must be increasing) |
| fp | torch.Tensor | Yes | y-coordinates of the data points (same length as xp) |
Outputs
| Name | Type | Description |
|---|---|---|
| matched (from histogram_matching) | torch.Tensor | Transformed image with same shape as source, pixel values adjusted to match template histogram |
| interpolated (from interp) | torch.Tensor | Interpolated values, same size as x |
Usage Examples
import torch
from kornia.contrib import histogram_matching
# Create a source and template image
source = torch.rand(1, 3, 256, 256) # source image
template = torch.rand(1, 3, 128, 128) # template (can be different size)
# Match the histogram of source to the template
matched = histogram_matching(source, template)
print(matched.shape) # torch.Size([1, 3, 256, 256]) - same shape as source
# Per-channel histogram matching
matched_channels = []
for c in range(3):
matched_c = histogram_matching(source[:, c], template[:, c])
matched_channels.append(matched_c)
matched_per_channel = torch.stack(matched_channels, dim=1)