Implementation:Kornia Kornia Guided Filter

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

Overview

Implements the guided image filter for edge-preserving smoothing, supporting both grayscale and multi-channel guidance images with optional fast subsampled filtering.

Description

This module is part of the Kornia library's filters subpackage. It implements the guided filter as described by He et al. (2010, 2015) via the guided_blur function and GuidedBlur nn.Module class. The guided filter uses a guidance image to determine edges that should be preserved during smoothing. It supports arbitrary channel counts: guidance and input can have different numbers of channels. Internally, the module dispatches between a grayscale guidance path (_guided_blur_grayscale_guidance) using scalar linear models and a multi-channel guidance path (_guided_blur_multichannel_guidance) using matrix-based linear models solved via torch.linalg.solve. Fast guided filtering with subsampling is supported via the subsample parameter.

Usage

Import this function or class when you need edge-preserving filtering guided by a reference image, such as for depth map upsampling, image matting, HDR compression, or detail enhancement where a guidance image provides structural information.

Code Reference

Source Location

• Repository: Kornia
• File: kornia/filters/guided.py
• Lines: 1-232

Signature

def guided_blur(
    guidance: torch.Tensor,
    input: torch.Tensor,
    kernel_size: tuple[int, int] | int,
    eps: float | torch.Tensor,
    border_type: str = "reflect",
    subsample: int = 1,
) -> torch.Tensor: ...

class GuidedBlur(nn.Module):
    def __init__(self, kernel_size: tuple[int, int] | int,
                 eps: float, border_type: str = "reflect",
                 subsample: int = 1) -> None: ...
    def forward(self, guidance: torch.Tensor, input: torch.Tensor) -> torch.Tensor: ...

Import

from kornia.filters import guided_blur, GuidedBlur

I/O Contract

Inputs

Name	Type	Required	Description
guidance	torch.Tensor (B, C, H, W)	Yes	The guidance image providing structural information for edge preservation.
input	torch.Tensor (B, C, H, W)	Yes	The input image to filter. Can have different channel count from guidance but must share batch size and spatial dimensions.
kernel_size	tuple[int, int] or int	Yes	Size of the box filter kernel used internally.
eps	float or torch.Tensor (N,)	Yes	Regularization parameter controlling smoothness. Smaller values preserve more edges.
border_type	str	No (default "reflect")	Padding mode: constant, reflect, replicate, or circular.
subsample	int	No (default 1)	Subsampling factor for fast guided filtering. Values greater than 1 reduce computation.

Outputs

Name	Type	Description
output	torch.Tensor (B, C, H, W)	The filtered image, same shape as input.

Usage Examples

import torch
from kornia.filters import guided_blur, GuidedBlur

# Functional guided blur
guidance = torch.rand(2, 3, 5, 5)
input = torch.rand(2, 4, 5, 5)
output = guided_blur(guidance, input, kernel_size=3, eps=0.1)
print(output.shape)  # torch.Size([2, 4, 5, 5])

# Self-guided filtering (guidance == input)
output_self = guided_blur(input, input, kernel_size=5, eps=0.01)

# Module-based guided blur with fast subsampling
blur = GuidedBlur(kernel_size=9, eps=0.1, subsample=4)
output = blur(guidance, input)

Related Pages

• Principle:Kornia_Kornia_Guided_Filtering