Kornia：面向空间 AI 的可微分计算机视觉库

Kornia 是一个可微分计算机视觉库，提供丰富的可微分图像处理与几何视觉算法。它构建在 PyTorch 之上，可无缝集成到现有的 AI 工作流中，让你利用强大的批处理变换、自动微分和 GPU 加速。无论你是在做图像变换、数据增强，还是 AI 驱动的图像处理，Kornia 都能提供把想法变成现实所需的工具。

📢 方向：Kornia 正在成为 PyTorch 生态中可微分计算机视觉与几何的参考实现和可执行规范——强调明确的约定、一致性测试和诚实的基准，而不是单纯扩充 API。请阅读路线图（Roadmap）。

何时使用 Kornia#

当手写版本变得冗长或脆弱，或者替代方案会让你离开 GPU 时，Kornia 就能发挥作用：

• 广度。1,200+ 个公共算子，大多数在 torchvision 中没有对应实现：相机模型与对极几何、最小求解器与 RANSAC、特征检测、描述与匹配、边缘检测、形态学、Lab 与 Bayer 颜色、图像损失与指标。torchvision 主要重叠在缩放、裁剪、翻转、颜色抖动和模糊上。

• 一次批处理调用中使用逐样本参数。 gaussian_blur2d(x, (9, 9), sigma) 接受 (B, 2) 的 sigma；rotate 接受 (B,) 的角度，warp_affine / warp_perspective 接受 (B, 2, 3) / (B, 3, 3) 矩阵，adjust_brightness 接受 (B,) 的系数。torchvision 的函数式算子每次调用只应用一个参数。从 Kornia 0.9.1 起，sigma 张量和增强值的检查（gamma、contrast、solarize）会在设备上验证，因此 CUDA 调用（或在 PyTorch ≥ 2.13 上的 MPS 调用）无需为它们进行主机同步。

• 批量最小求解器与稳健估计。 find_fundamental(x1, x2, method="7POINT") 求解 (B, 7, 2) 的样本，并返回 (B, 3, 3, 3) 中的所有实数解，未使用的槽位填充零矩阵；8 点、5 点本质矩阵（find_essential）、DLT 单应性和 PnP（solve_pnp_dlt）求解器也都有。RANSAC（单应、基础矩阵和本质矩阵模型）在设备上采样并评分假设；默认情况下，其精化和最终选择在主机上以 float64 运行，而 compile=True（PyTorch ≥ 2.14，CPU 和 CUDA）会将整个估计过程作为一张编译图在设备上运行。

• 可微分几何。 深度到 3D 及反向转换（depth_to_3d_v2、unproject_points、project_points）、warp_frame_depth、remap、带 Brown–Conrady 和 Kannala–Brandt 畸变的相机模型，以及李群（So3、Se3）都保留对深度、位姿和相机参数的梯度。

• 带标注的增强。 AugmentationSequential 在 2D 中对图像、掩码、框和关键点一起应用同一个采样变换，并且可以反变换；3D 增强变换体数据，不带标注或反变换。在 CUDA 上，增强会将采样参数移到 GPU 而不阻塞它，并且有一个同步守卫测试确保每个公共增强都不含可避免的主机同步。

• GPU 上的局部特征。 SIFT 和 HardNet、DISK、ALIKED、XFeat、DeDoDe、LoFTR 和 LightGlue，以及互为最近邻和比值检验匹配器。

• 在批处理张量上使用任意结构元素的形态学。

• 编译与导出。 几乎所有探测过的算子配置都能在 torch.compile 下运行并与 eager 匹配，超过 1,000 个可导出到 ONNX；每个算子的结果都在导出支持页面上。

• 在它设计的目标上很快：GPU 上的批处理张量。 在已发布的 0.9.0 旗舰基准中（RTX 4090，批大小 32），许多滤波器、warp、特征匹配步骤和图像指标在 eager 模式下比 CPU 上逐图像的 OpenCV 或 scikit-image 快约 10× 到 70×，torch.compile 让其中一些超过 100×。在相同 GPU 上与 torchvision 的小范围重叠中，eager Kornia 更慢；编译后的 Kornia 在色相、颜色抖动和高斯模糊上更快，在翻转、裁剪和亮度上仍然更慢。OpenCV 在单张 uint8 图像的 CPU 工作负载上胜出。结果随硬件和工作负载而异；每一个数字、胜与负都发布在性能页面上。

这些算子在输入所在设备上运行，无需 NumPy 往返，且大多数是可微分的；稳健估计（RANSAC）和 DeDoDe、XFeat 等学习特征的提取方法在不带梯度的情况下运行。对于单个固定参数操作，例如一次模糊或一次缩放，几行 PyTorch 或 torchvision 同样够用。

关键组件#

可微分图像处理#

Kornia 提供了一套全面的图像处理算子，全部可微分，可直接集成到深度学习流水线中。

• 滤波器：高斯、Sobel、中值、盒式模糊等。
• 变换：仿射、单应、透视等。
• 增强：直方图均衡、CLAHE、伽马校正等。
• 边缘检测：Canny、Laplacian、Sobel 等。

……更多内容请查看文档。

高级增强#

使用 Kornia 的内置函数进行强大的数据增强，非常适合用复杂的增强流水线训练 AI 模型。

• 增强流水线：AugmentationSequential、PatchSequential、VideoSequential 等。
• 自动增强：AutoAugment、RandAugment、TrivialAugment。

AI 模型#

利用针对各种视觉任务优化的预训练 AI 模型，全部位于 Kornia 生态中。

• 人脸检测：YuNet
• 特征匹配：LoFTR、LightGlue
• 特征描述子：DISK、DeDoDe、SOLD2
• 分割：SAM
• 分类：MobileViT、VisionTransformer。

查看此处了解我们支持的部分方法！（总计 500+ 个算子！）

CUDA 与半精度支持#

下表中的模块表统计的是 Linux CPU 已知失败清单（cpu_float16.txt、cpu_bfloat16.txt）中的条目，固定使用 Python 3.11 和 PyTorch 2.15.0。共记录了 243 个 float16 和 256 个 bfloat16 失败。这些是参数化测试用例，而不是不支持函数的数量。剩余工作追踪于 #4153。没有任何 CI 任务覆盖 CUDA 或 MPS 半精度；CPU 结果不能证明这些后端上的支持情况。

✅ CPU 已知失败清单中没有条目。⚠️ 有已记录的 CPU 失败。这两个符号都不承诺完整的 dtype 支持：跳过、预期异常和源码级 xfail 不在这些统计中。某些算子在内部以 float32 或 float64 计算，然后返回输入 dtype。

观察到的 CPU CI 结果：

2026-10-21 在 93f1376e 上的定时运行使用 Linux x86_64、Python 3.11 和 PyTorch 2.14.0，不含慢速或编译测试：

每个任务还取消了 3 个 ONNX 一致性测试的选择。XFAIL 总数包括严格清单条目和源码级预期失败。每个成功任务中的 4 个 XPASS 是已通过的非严格预期失败；通过清单条目会使验证失败，异常发生变化、条目被跳过或 node ID 过期也会如此。因此，绿色任务意味着记录的基线被复现了，即使已知失败和跳过仍然存在。这些总数描述的是所链接的修订版本；模块表描述的是已检入的清单。

在固定环境中用以下命令验证完整的 CPU 配置：

KORNIA_TEST_OPTIMIZER= pixi run test-module tests/ --verify-known-failures --known-failure-profile=cpu-float16
KORNIA_TEST_OPTIMIZER= pixi run test-module tests/ --verify-known-failures --known-failure-profile=cpu-bfloat16

pixi run test-half 是一次不带固定配置基线的非种子 CPU 扫描。聚焦检查和基线维护请参见 TESTING.md。

CUDA 支持与测量限制：

Kornia 接受 CUDA 张量进行 GPU 加速，但受每个算子的 dtype 和后端限制约束。没有阻塞性的 CUDA CI 任务，也没有检入的 CUDA 已知失败清单，因此上面的 CPU xfail 统计不能提供当前的 CUDA 通过率。先前的本地测量仅作为历史证据保留在这里：

这些数据使用 RTX 4090、Python 3.11 和 PyTorch 2.14.0+cu130。源码标记的 xfail 被排除。半精度测试在进程中运行，设置 KORNIA_TEST_IN_SUBPROCESS=1，随后对失败进行隔离重试；两个单应性测试被取消选择。它们不代表当前分支的测量结果。这两个测试（TestFindHomographyDLT::test_nocrash 和 test_nocrash_lu）现在在 649b3f86d 上以三种 CUDA dtype 在本地均通过；在引用新的总数之前，需要进行一次全新的完整 CUDA 扫描。

对于 CUDA 半精度测试，使用 --isolate-half-precision，让每个测试获得一个新进程。没有该参数时它们默认被跳过；仅选择半精度 dtype 并不会实际检验 CUDA 半精度支持：

pixi run test-module tests/color/ --device=cuda --dtype=float16,bfloat16 --isolate-half-precision

详见完整的精度指南。

赞助#

Kornia 是一个由志愿者开发和维护的开源项目。无论你将其用于研究还是商业目的，都请考虑赞助我们或与我们合作。你的支持将有助于确保 Kornia 的成长和持续创新。今天就联系我们，参与塑造这个激动人心的倡议的未来！

安装#

从 pip 安装

pip install kornia

某些功能（ONNX、Stable Diffusion dissolving）需要额外的包；参见可选附加项。

其他安装选项

从源码以可编辑模式安装

pip install -e .

使用 Pixi 进行开发（推荐）

开发时，Kornia 使用 pixi 进行快速的 Python 包管理和环境管理。项目包含 pixi.toml 配置文件，用于可复现的依赖管理。

# Install pixi (if not already installed)
curl -fsSL https://pixi.sh/install.sh | bash

# Create the Pixi environment and install development dependencies
pixi install
pixi run -e default install

# Run tests
pixi run test

# For CUDA development
pixi run -e cuda install
pixi run -e cuda test-cuda

这些命令会建立一个包含所有依赖的完整开发环境。关于依赖管理和可用任务的更多细节，请参见 CONTRIBUTING.md。

从 GitHub URL 安装（最新版本）

pip install git+https://github.com/kornia/kornia

快速开始#

Kornia 不只是另一个计算机视觉库——它是你通往轻松实现计算机视觉与 AI 的入口。

从 Kornia 的图像变换和增强开始吧！

import numpy as np
import kornia_rs as kr

from kornia.augmentation import AugmentationSequential, RandomAffine, RandomBrightness
from kornia.filters import StableDiffusionDissolving

# Load and prepare your image
img: np.ndarray = kr.read_image_any("img.jpeg")
img = kr.resize(img, (256, 256), interpolation="bilinear")

# alternatively, load image with PIL
# img = Image.open("img.jpeg").resize((256, 256))
# img = np.array(img)

img = np.stack([img] * 2)  # batch images

# Define an augmentation pipeline
augmentation_pipeline = AugmentationSequential(RandomAffine((-45.0, 45.0), p=1.0), RandomBrightness((0.0, 1.0), p=1.0))

# Leveraging StableDiffusion models
dslv_op = StableDiffusionDissolving()

img = augmentation_pipeline(img)
dslv_op(img, step_number=500)

dslv_op.save("Kornia-enhanced.jpg")

使用 ONNXSequential 了解 Kornia ONNX 模型！

import numpy as np
from kornia.onnx import ONNXSequential

# Chain ONNX models from HuggingFace repo and your own local model together
onnx_seq = ONNXSequential(
    "hf://operators/kornia.geometry.transform.flips.Hflip",
    "hf://models/kornia.models.detection.rtdetr_r18vd_640x640", # Or you may use "YOUR_OWN_MODEL.onnx"
)
# Prepare some input data
input_data = np.random.randn(1, 3, 384, 512).astype(np.float32)
# Perform inference
outputs = onnx_seq(input_data)
# Print the model outputs
print(outputs)

# Export a new ONNX model that chains up all three models together!
onnx_seq.export("chained_model.onnx")

征集贡献者#

如果 kornia 对你有用，并且你愿意提供帮助，我们欢迎各种形式的贡献：代码、bug 报告、基准、文档、问题、回答和示例。维护者的时间有限，因此我们无法保证每个提案或 pull request 都会被审阅或合并。

强化核心（优先）

Kornia 的差异化价值在于其几何核心：warp 与采样、单应性、相机、对极几何、旋转与李群，以及几何一致的增强。影响力最高的贡献是让这一核心更值得信赖——完整图景请参见路线图。很好的切入点：

• 来自你硬件的基准结果：用 --contribute 运行基准套件并发送 JSON——来自不同 GPU 的 CUDA 数据尤其有用。
• 为核心几何操作固定约定的测试和一致性向量。
• 纠正性错误消息：把裸的形状断言升级为能说明哪里错了、预期是什么、适用哪条约定的错误。
• 核心领域中的经典视觉：相机内参标定、基准标记（ArUco/ChArUco）、经典跟踪、稠密立体和 Hough 变换。对于这种规模的工作，早期的设计讨论会很有用。

更多项目背景请参见路线图的贡献者领域。

AI 模型

在维护者带宽集中于核心期间，模型库目前冻结扩张。已发布的模型（LoFTR、LightGlue、DISK、DeDoDe、SAM 等）继续可用并维护，冻结前已批准的模型工作（Efficient LoFTR、SANDesc）将在其既有范围内完成。新的集成——包括 VLM/VLA 模型——需要一位具名维护者赞助人，接受对该集成的持续所有权；仅靠贡献者实现无法重新开放这一领域。理由和重新开放条件请参见路线图。

文档与教程优化#

Kornia 的基础在于其广泛的经典计算机视觉算子集合，为图像处理、特征提取和几何变换提供稳健工具。我们持续寻找贡献者，帮助我们改进文档，并为用户提供优秀的教程。

引用#

如果你在研究相关文档中使用 kornia，建议引用这篇论文。更多信息请参见 CITATION。

@inproceedings{eriba2019kornia,
  author    = {E. Riba, D. Mishkin, D. Ponsa, E. Rublee and G. Bradski},
  title     = {Kornia: an Open Source Differentiable Computer Vision Library for PyTorch},
  booktitle = {Winter Conference on Applications of Computer Vision},
  year      = {2020},
  url       = {https://arxiv.org/pdf/1910.02190.pdf}
}

贡献#

关于我们的社会契约、开发环境搭建和技术准则，请参见 CONTRIBUTING.md。参与须遵守行为准则。

社区#

• Discord：与使用和开发 kornia 的人交流。加入服务器。
• GitHub Issues：报告 bug 并提出具体变更。提交 issue。
• GitHub Discussions：提问并讨论实现、研究和想法。加入讨论。

Made with contrib.rocks。

许可证#

Kornia 基于 Apache 2.0 许可证发布。详见 LICENSE 文件。