Thumbor 高斯模糊滤镜（blur）完整指南：参数、URL 用法与底层卷积实现-平芜编程栈

后端
图像处理

【免费下载链接】thumbor

thumbor is an open-source photo thumbnail service by globo.com

项目地址：https://gitcode.com/gh_mirrors/th/thumbor

Thumbor 内置的blur滤镜用于对图片施加高斯模糊（Gaussian blur），是处理隐私遮挡、背景虚化、圆角过渡等场景最常用的图像操作之一。本文以 docs/blur.rst 为骨架，结合 blur.py 源码、C 卷积扩展与测试用例，完整讲解该滤镜的用法、参数语义、URL 拼写规则以及底层的两阶段卷积实现原理，读完即可在真实 Thumbor 服务中正确拼写并调优模糊效果。

一、滤镜用法与参数说明

blur滤镜的调用语法为：

blur(radius [, sigma])

它通过 URL 中的filters:段落传入，例如对任意一张图片执行半径为 7 的高斯模糊：

http://localhost:8888/unsafe/filters:blur(7)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg

参数语义如下：

参数	是否必填	说明
`radius`	必填	高斯函数生成卷积矩阵所用的半径，最大值为 150。半径越大，图片越模糊
`sigma`	可选	高斯函数中的标准差（σ）。默认与`radius`取相同值，即省略时`sigma = radius`

从源码可以看出，滤镜类内部显式定义了半径上限常量，并对超出上限的输入做了截断处理：

# thumbor/filters/blur.py MAX_RADIUS = 150 def apply_blur(mode, data, size, radius, sigma=0): if sigma == 0: sigma = radius radius = min(radius, MAX_RADIUS)

这意味着即便请求blur(500)，实际生效的半径也会被限制为 150，避免生成过大的卷积核拖垮性能。

二、参数解析与校验：从 URL 字符串到数值

blur的参数解析依赖filter_method装饰器声明的类型约束（见 thumbor/filters/init.py）：

@filter_method(BaseFilter.PositiveNonZeroNumber, BaseFilter.DecimalNumber) async def blur(self, radius, sigma=0): mode, imgdata = self.engine.image_data_as_rgb() imgdata = apply_blur(mode, imgdata, self.engine.size, radius, sigma) self.engine.set_image_data(imgdata)

其中：

radius使用PositiveNonZeroNumber类型（正则[\d]*[1-9][\d]*，解析为int），因此 URL 中的半径必须是大于 0 的整数；
sigma使用DecimalNumber类型（解析为float），支持小数，如blur(4, 1.5)；
sigma带默认值0，省略时由apply_blur内部将其重置为radius。

BaseFilter会在类加载阶段根据装饰器元数据编译出匹配正则（compile_regex），把blur(7)、blur(4,2)这类 URL 片段解析成 Python 数值，再交给blur方法执行。解析失败（例如 radius 为 0 或负值）时init_if_valid会返回None，该滤镜将被静默跳过，不会中断整条处理管线。

三、底层原理：一维高斯核与两次分离卷积

blur并非直接在像素级做简单的均值模糊，而是严格按高斯模糊算法实现。核心分两步：

1. 生成一维高斯核

generate_1d_matrix 依据高斯分布公式生成一维权重矩阵：

def generate_1d_matrix(sigma, radius): matrix_size = (radius * 2) + 1 matrix = [] two_sigma_squared = float(2 * sigma * sigma) for column in range(matrix_size): adj_x = column - radius exp = math.e ** -(((adj_x * adj_x)) / two_sigma_squared) matrix.append(exp / math.sqrt(two_sigma_squared * math.pi)) return tuple(matrix), matrix_size

以radius=1为例，矩阵大小为2*1+1 = 3，生成 3 个权重系数；sigma控制曲线的"胖瘦"，sigma越大权重分布越平缓，模糊范围越广。这就是文档所述"sigma 默认等于 radius"的实际作用点——它直接决定了高斯函数的形状。

2. 水平 + 垂直两次分离卷积

直接对二维高斯核做一次卷积计算量很大，因此apply_blur采用了**分离卷积（separable convolution）**优化：先沿水平方向卷积一次，再沿垂直方向卷积一次，两者叠加等效于一次完整二维高斯模糊：

def apply_blur(mode, data, size, radius, sigma=0): if sigma == 0: sigma = radius radius = min(radius, MAX_RADIUS) matrix, matrix_size = generate_1d_matrix(sigma, radius) data = _convolution.apply( mode, data, size[0], size[1], matrix, matrix_size, True ) return _convolution.apply(mode, data, size[0], size[1], matrix, 1, True)

这里的_convolution是 C 语言实现的性能关键路径（thumbor/ext/filters/_convolution.c）。从 C 源码看，卷积过程对每个像素遍历核内邻域、按权重累加 RGB（以及存在时的 Alpha）通道，并使用MINMAX宏对越界采样做钳制、对核做归一化（normalize_kernel，should_normalize=True）。两次调用分别以matrix_size（水平核宽）和1（垂直核高为 1）作为columns_count，正是"先水平后垂直"的分离卷积实现。模糊后的数据通过engine.set_image_data(imgdata)写回图片引擎，最终输出到响应流。

四、滤镜管道：与其他滤镜组合使用

Thumbor 的滤镜以管道（pipeline）方式按书写顺序依次执行（参见 docs/filters.rst）。例如：

http://localhost:8888/fit-in/100x100/filters:watermark(..):blur(..):fill(red,1):upscale()/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg

会先加水印、再对整个图片（包括水印）做模糊、然后填充红色背景、最后尝试放大。因此执行顺序会影响最终效果：若把blur放在watermark之前，水印就不会被模糊；反之则整张图（含水印）一起虚化。设计 URL 时需根据"是要模糊全图还是只模糊原图"来调整滤镜顺序。

blur在内置滤镜清单中以thumbor.filters.blur注册，位于PHASE_POST_TRANSFORM（后变换）阶段，即缩略图尺寸变换完成后才执行，属于默认的"结果加工"型滤镜。

五、边界行为与工程实践建议

从 tests/filters/test_blur.py 可以确认以下边界行为，实际使用时可作为预期参考：

场景	行为	测试依据
`blur(4,2)`指定 sigma	结果与基准图 SSIM > 0.99	`test_blur_filter_with_sigma`
`blur(0)`半径为 0	图片几乎无变化，与原图 SSIM = 1	`test_blur_filter_with_zero_radius`
`blur(8)`省略 sigma	与基准图 SSIM > 0.99	`test_blur_filter_without_sigma`
`blur(500)`超出上限	按 150 截断执行，结果稳定	`test_blur_filter_with_max_radius`
调色板 PNG（P 模式）	正常模糊，SSIM > 0.99	`test_blur_filter_for_png_palette_mode`
带透明通道 PNG（RGBA / LA 模式）	透明区域与颜色一并处理，SSIM > 0.99	`test_blur_filter_png_with_transparency_*`

工程建议：

半径按需取小：radius是卷积核半宽，核宽为2*radius+1，半径翻倍意味着每像素参与计算的邻域像素数量大幅增加。文档允许的最大值 150 意味着极端模糊，日常遮挡/虚化场景blur(4)~blur(10)通常已足够；
善用 sigma 微调：当需要"同样的模糊范围、更柔和的过渡"时，可给sigma传大于radius的小数（如blur(6, 9)），反之传更小的值可让边界更锐利；
结合其他滤镜使用：blur常与round_corner、fill搭配做圆角虚化背景，或与watermark组合实现水印下压效果，注意按上面介绍的管道顺序规划。