Kornia 2D 强度变换（Intensity Transforms）完全指南：像素级增强算子、参数与源码解析

计算机视觉人工智能深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/gh_mirrors/ko/kornia点击查看免费下载本指南聚焦于 Kornia 计算机视觉库中的 **2D 强度变换2D intensity transforms**——这是数据增强流水线的核心组成部分。强度变换只改变图像像素值不改变像素的空间位置因此掩码mask、边界框box与关键点keypoint可以原样透传。你将了解完整算子清单、参数语义、底层实现原理与实战用法。该 API 页面位于 docs/source/augmentation.intensity.rst对应的全部实现位于 kornia/augmentation/_2d/intensity/ 目录。一、什么是 2D 强度变换Kornia 的强度变换intensity transforms是一类只改变像素值、不移动任何像素位置的增广算子。与之相对的是几何变换geometric transforms如旋转、缩放、仿射变换后者会改变像素的空间坐标。强度变换的关键特性像素位置不变输入图像的每个像素都留在原地只有数值被修改元数据透传由于不移动像素掩码mask、边界框box和关键点keypoint等标注数据可以直接“原样穿过”而不需要任何重投影或插值处理可批量可随机所有随机强度变换都支持p应用概率、same_on_batch整批相同、keepdim输出维度保持等通用参数。这一特性使强度变换非常适合与几何变换混合使用先做几何变换同步更新 box/keypoint再做强度变换标注无需变动从而构成完整的增广流水线。统一的基类IntensityAugmentationBase2D所有 2D 强度变换都继承自IntensityAugmentationBase2D该类定义在 kornia/augmentation/_2d/intensity/base.pyclass IntensityAugmentationBase2D(RigidAffineAugmentationBase2D): _compute_matrix_lazily True _input_metadata_only def compute_transformation(self, input, params, flags): return self.identity_matrix(input)从源码结构可以看出其设计要点恒等变换矩阵compute_transformation返回恒等矩阵。由于强度变换不移动像素其变换矩阵恒为单位阵掩码/框/关键点的处理函数apply_transform_mask、apply_transform_box、apply_transform_keypoint全部直接返回输入矩阵惰性构建_compute_matrix_lazily True变换矩阵直到.transform_matrix被真正读取时才构建节省了每次前向传播中不必要的矩阵计算开销无inverse实现基类不提供逆变换。当AugmentationSequential执行inverse时会跳过 2D 强度子变换仅反转支持的几何子变换。基类约定中特别强调这些类假定全库统一的[0, 1]浮点图像值范围详见 get-started/conventions。超出该范围时不同类有各自的策略有的 clamp、有的重缩放、有的执行uint8转换、有的不 clampRandomEqualize甚至会对越界图像抛出RuntimeError。基类参数p、p_batch、same_on_batch、keepdim的语义如下参数作用p逐样本控制增广应用概率element-wisep_batch逐批次控制增广应用概率batch-wisesame_on_batch整批应用同一个变换参数keepdimTrue时保持输入形状False时广播为批形式(B, C, H, W)注意基类并未在入口对[0,1]范围做校验这是一个前置条件而非强制契约。此外在p 1时变换仍会对每个样本计算再通过门控选择因此一个越界输入即使被跳过也可能在计算阶段触发报错。二、完整算子清单Kornia 2D 强度变换模块共提供36 个随机/确定性算子全部从 kornia/augmentation/_2d/intensity/init.py 导出。按功能类别划分如下1. 颜色调整类Color Adjustment类名功能默认参数ColorJiggle亮度/对比度/饱和度/色相联合抖动推荐四个因子默认0.0ColorJitter同上但实现对 PIL/TorchVision 对齐兼容用四个因子默认0.0RandomBrightness随机亮度调整brightness0.0RandomContrast随机对比度调整contrast0.0RandomSaturation随机饱和度调整saturation0.0RandomHue随机色相调整hue0.0RandomGrayscale随机转灰度概率pRandomRGBShiftRGB 通道随机偏移—RandomChannelShuffle通道随机重排—RandomChannelDropout随机丢弃通道num_drop_channels2. 噪声与退化类Noise Degradation类名功能RandomGaussianNoise添加高斯噪声mean/stdRandomSaltAndPepperNoise椒盐噪声amount/salt_vs_pepperRandomBoxBlur盒式模糊RandomGaussianBlur高斯模糊RandomMedianBlur中值模糊RandomMotionBlur运动模糊核大小/角度/方向RandomJPEG模拟 JPEG 压缩伪影可选依赖RandomDissolving溶解效果需要diffusers且冷启动会下载 Stable Diffusion checkpointRandomSharpness锐化RandomRain雨天效果RandomSnow雪天效果3. 光照类Illumination类名功能RandomGaussianIllumination高斯光照扰动RandomLinearIllumination线性光照RandomLinearCornerIllumination角落线性光照RandomPlanckianJitter基于普朗克黑体辐射曲线的色温抖动RandomPlasmaBrightness等离子体亮度场RandomPlasmaContrast等离子体对比度场RandomPlasmaShadow等离子体阴影场4. 色调映射与后处理类Tone Post-processing类名功能RandomAutoContrast自动对比度RandomEqualize直方图均衡化RandomClahe自适应直方图均衡CLAHE不在__all__中RandomGammaGamma 校正RandomInvert反色RandomPosterize色调分离posterizeRandomSolarize曝光过度solarize注意RandomClahe和RandomJPEG未包含在kornia.augmentation.__all__中需从kornia.augmentation._2d.intensity子模块直接导入。5. 归一化类Normalization确定性类名功能Denormalize反归一化input * std meanNormalize归一化(input - mean) / std三、核心算子的参数详解与源码剖析3.1ColorJiggle与ColorJitter颜色抖动的两套实现这两个类是 2D 强度变换中最常用的颜色增强算子均继承自IntensityAugmentationBase2D。它们的构造签名完全一致ColorJiggle( brightness0.0, contrast0.0, saturation0.0, hue0.0, same_on_batchFalse, p1.0, keepdimFalse, orderNone, # 固定应用顺序0亮度, 1对比度, 2饱和度, 3色相 )brightness/contrast/saturation可传入标量表示以 1.0 为中心的偏移量[1 - x, 1 x]或(min, max)元组hue色相因子范围限制在(-0.5, 0.5)之间见 color_jitter.py 中_range_bound(self.hue, hue, bounds(-0.5, 0.5))order默认None表示每次调用随机抽取应用顺序torch.randperm(4)传入固定顺序如[0, 1, 2, 3]或[1, 3]子集则按固定顺序执行并使得变换在torch.compile下可进行 fullgraph 编译。两类的核心区别源码 docstring 与实现均明确说明底层 primitive 不同ColorJitter使用kornia.enhance.adjust_brightness_accumulative、adjust_contrast_with_mean_subtraction、adjust_saturation_with_gray_subtraction对齐 PIL/TorchVisionColorJiggle使用kornia.enhance.adjust_brightness、adjust_contrast、adjust_saturation更符合色彩理论推荐使用二者都调用adjust_hue。brightness 的重新基准ColorJitter将抽到的亮度因子直接传给 primitive不做-1处理而ColorJiggle与RandomBrightness一样先执行factor - 1。边界检查ColorJiggle的 brightness 边界是[0, 2]因此brightness1.5或(0.0, 3.0)都会在构造时抛出brightness out of bounds. Expected inside (0, 2)ColorJitter则接受任何值。随机性来源ColorJiggle在采样设备上抽取orderColorJitter始终在 CPU 上抽取因此二者在 GPU 上生成的顺序可能不同。中性因子处理ColorJiggle对中性因子如contrast 1直接跳过该步骤不计算ColorJitter则在torch.where下计算后选择因此ColorJiggle(0,0,0,0)是恒等变换且接受任意通道数包括 1 通道和 4 通道而ColorJitter的饱和度/色相步骤要求 3 通道。参数生成器二者分别使用ColorJiggleGeneratorcolor_jiggle.py和ColorJitterGeneratorcolor_jitter.py。以ColorJitterGenerator为例其make_samplers用UniformDistribution构造四个因子的均匀分布采样器forward返回brightness_factor、contrast_factor、hue_factor、saturation_factor形状(B,)以及order形状(4,)的随机排列0亮度、1对比度、2饱和度、3色相。使用示例来自源码 docstring可复现import torch from kornia.augmentation import ColorJiggle rng torch.manual_seed(0) inputs torch.ones(1, 3, 3, 3) aug ColorJiggle(0.1, 0.1, 0.1, 0.1, p1.0) aug(inputs) # tensor([[[[0.9993, 0.9993, ...]]]]) —— 全部通道被轻微扰动精确重放replayKornia 的强度变换支持参数状态重放即用上一次调用保存的_params精确复现同样的变换input torch.randn(1, 3, 32, 32) aug ColorJiggle(0.1, 0.1, 0.1, 0.1, p1.0) (aug(input) aug(input, paramsaug._params)).all() # tensor(True)这一机制在测试与可复现实验如对比同一次随机增广下不同模型的行为中非常有用。3.2RandomGaussianNoise高斯噪声源码位于 gaussian_noise.pyRandomGaussianNoise(mean0.0, std1.0, same_on_batchFalse, p0.5, keepdimFalse)噪声是加性的输出 输入 _params[gaussian_noise]噪声张量形状与输入(B, C, H, W)一致mean直接偏移图像不进行任何 clamp因此原本在[0,1]内的输入可能在任一方向越界same_on_batchTrue时噪声张量以(1, C, H, W)存储在应用时expand_as(input)扩展到整个批次。3.3RandomMotionBlur运动模糊源码位于 motion_blur.py是参数最丰富的算子之一RandomMotionBlur( kernel_size, # int 固定核大小或 (min, max) 随机取范围内奇数闭区间等概率 angle, # 运动方向角度度逆时针float 表示从 (-angle, angle) 采样 direction, # 前后方向-1.0 向后、1.0 向前、0.0 均匀float 表示从 (-direction, direction) 采样 border_typeBorderType.CONSTANT.name, # CONSTANT0, REFLECT1, REPLICATE2, CIRCULAR3 resampleResample.NEAREST.name, # 插值方式 same_on_batchFalse, p0.5, keepdimFalse, )关键实现细节核大小整批共享kernel_size为元组时每次调用只抽一个奇数并重复到_params[ksize_factor]形状(B,)即使same_on_batchFalse所有样本也共用同一个核大小angle和direction则逐样本采样除非same_on_batchTrue。范围行为(3, 5)等概率抽取 3 和 5(4, 4)因范围内无奇数会被向上取整抽到 5(20, 3)这种倒置范围在构造时直接报错。方向语义direction0沿模糊线均匀分布权重-1/1将权重堆到两端旋转使用resample重采样nearest可能丢/重复抽头bilinear/bicubic会把权重扩散到线外。越界行为默认border_typeconstant时填充为 0边界像素会被拉向 0reflect时结果保持在输入极值之间bicubic旋转可能过冲默认resamplenearest。可微性如需更有意义的梯度建议设置resamplebilinear。底层调用kornia.filters.motion_blur输入需为 float 且归一化到[0,1]以获得最佳可微性支持该函数还接受额外的(B, 3, 3)变换张量并与之合并返回。3.4Normalize与Denormalize确定性归一化/反归一化这两个是确定性算子无随机参数对 2D 和 3D 张量形状无关shape-agnostic。源码位于 normalize.py 与 denormalize.pyNormalize(mean, std, p1.0, keepdimFalse) # (input - mean) / std Denormalize(mean, std, p1.0, keepdimFalse) # input * std meanmean/std可接受单个 float、逐通道序列/张量、或逐样本(B, C)张量长度既不是 1 也不是通道数时会报错p以整批为单位门控构造函数硬编码same_on_batchTrue不提供same_on_batch参数统计量存放在flags而非 buffer 中因此state_dict()为空、Module.to(...)不会改变其 device 和 dtype便于 ONNX 导出时按需 reshape结果不做 clamp将图像移出[0,1]正是归一化的目的用相同的mean/std构造的Denormalize与Normalize互为逆运算存在浮点舍入误差这一点在 Normalize 的 docstring 中有明确说明。例如from kornia.augmentation import Normalize, Denormalize import torch norm Normalize(meantorch.zeros(4), stdtorch.ones(4)) x torch.rand(1, 4, 3, 3) out norm(x) # torch.Size([1, 4, 3, 3]) denorm Denormalize(meantorch.zeros(1, 4), stdtorch.ones(1, 4)) denorm(out) # 恢复 x浮点舍入内四、实战用法构建强度变换增广流水线4.1 单独使用每个强度变换都可以当作一个独立的nn.Module使用import torch from kornia.augmentation import ( RandomGaussianNoise, RandomMotionBlur, RandomGrayscale, RandomPosterize, RandomGamma, ) x torch.randn(2, 3, 64, 64) # (B, C, H, W) # 依次施加多个强度变换 x RandomGaussianNoise(mean0.0, std0.05, p0.8)(x) x RandomMotionBlur(kernel_size(3, 7), angle(0.0, 360.0), direction0.0, p0.5)(x) x RandomGrayscale(p0.2)(x) x RandomPosterize(bits3, p0.3)(x) x RandomGamma(gamma(0.5, 1.5), gain(0.8, 1.2), p0.5)(x)4.2 与几何变换、标注数据混合使用强度变换不移动像素的特性使得它可以安全地与几何变换、mask/box/keypoint 标注共存——无需重新投影标注from kornia.augmentation import ( RandomAffine, RandomHorizontalFlip, RandomGaussianNoise, ColorJiggle, ) from kornia.augmentation.container import AugmentationSequential augment AugmentationSequential( RandomAffine(degrees15, p0.5), # 几何变换会同步更新 box/keypoint RandomHorizontalFlip(p0.5), # 几何变换 ColorJiggle(0.1, 0.1, 0.1, 0.05, p0.5), # 强度变换标注透传 RandomGaussianNoise(mean0.0, std0.03, p0.5), # 强度变换标注透传 )当AugmentationSequential执行inverse()时2D 强度子变换会被跳过基类不提供逆变换仅反转几何子变换。4.3 精确重放与可复现性Kornia 的强度变换都支持参数重放aug RandomMotionBlur(3, 35.0, 0.5, p1.0) out1 aug(input) out2 aug(input, paramsaug._params) # 与 out1 完全一致这在需要“同一增广两次不同前向”或需要保存增广参数以便推理时复现的场景中很有价值。4.4 注意事项与边界行为阅读 base.py 的 Convention 块可以总结出以下实战要点全负值输入风险基类明确警告多个强度变换对“全负值”输入可能返回全零图像且无警告已跟踪 issue#4430。例如Denormalize(mean0.5, std0.5)会将-1映射到恰好 0RandomAutoContrast对任意常数图像返回零。若训练数据包含负值请谨慎。p 门控的副作用即使p0.0变换仍会对每个样本计算再做选择因此RandomEqualize、RandomClahe对越界图像即使p0.0也会抛错某些变换在跳过样本上可能出现 NaN 梯度issue#4576。参数边界检查多数类在构造时校验显式范围如ColorJiggle的 brightness ∈[0,2]、RandomPlanckianJitter的select_from索引、RandomChannelDropout的num_drop_channelsvs 通道数但RandomGamma的非负性、RandomGaussianBlur的sigma0、RandomMedianBlur的偶数核、RandomMotionBlur的奇数核下限等检查发生在前向时。依赖与下载RandomDissolving需要可选的diffusers包且在冷缓存下会下载 Stable Diffusion checkpointRandomClahe、RandomJPEG有独立的文档页面且后者不在__all__中。五、源码级验证与测试Kornia 为强度变换提供了详尽的测试与约定校验tests/augmentation/test_conventions_intensity_ops.py验证强度变换的操作约定恒等矩阵、mask/box/keypoint 透传等tests/augmentation/test_conventions_intensity_values.py验证各类变换对[0,1]内外输入的值域行为tests/augmentation/test_motionblur.py专项测试RandomMotionBlur的核大小/角度/方向行为tests/augmentation/test_backward.py 与 test_onnx_export.py验证变换的可微性与 ONNX 导出支持tests/augmentation/test_param_validation.py参数边界校验测试。如果你在 docs/source/augmentation.auto.rst 中看到“Convention”段落那是强度变换与几何变换共享的完整约定文档每个具体类的 docstring 中也包含自身的 Convention 块是理解边界行为的第一手资料。六、总结Kornia 的 2D 强度变换模块提供了从颜色抖动、噪声注入、光照模拟到色调映射的 36 个算子全部基于统一的IntensityAugmentationBase2D基类保证像素位置不变 → 掩码/边界框/关键点自动透传统一的p/same_on_batch/keepdim参数约定参数状态可保存、可精确重放与几何变换、AugmentationSequential容器无缝组合全部算子可微支持梯度回传与 ONNX 导出。选择ColorJiggle而非ColorJitter作为默认颜色增强后者仅用于 TorchVision 兼容结合RandomMotionBlur、RandomGaussianNoise、等离子体光照等算子即可构建覆盖真实世界退化光照变化、运动模糊、传感器噪声、压缩伪影的鲁棒性训练流水线。相关阅读[2D 几何变换](https://link.gitcode.com/i/1a9dfd22d45cfd5aec37ff1a39b1d862) · [3D 变换](https://link.gitcode.com/i/08a604b23eb0ce2cca82d4041fb3006d) · [增广容器 AugmentationSequential](https://link.gitcode.com/i/4b2253b413c1b858d774ca5dbb2becdd) · [随机参数生成器](https://link.gitcode.com/i/3b517bbc55c663c4576723f3dfe626cb) · [增强 API 总览](https://link.gitcode.com/i/0e1d18d413014d8175972b0e9c1e6b15)