🐍 Geometric Computer Vision Library for Spatial AI
Python artificial-intelligencecomputer-visiondeep-learninghacktoberfestimage-processingmachine-learningneural-networkpythonpytorchroboticsspatial-ai
# Kornia
> Kornia is a differentiable computer vision library for PyTorch: classic CV operations (color conversion, filtering, geometric transforms, camera/epipolar geometry, augmentation) implemented as batched, GPU-ready, autograd-friendly tensor ops, plus curated local-feature and vision models. Every op is `torch.Tensor` in, `torch.Tensor` out; OpenCV is not a dependency. Kornia 0.9.0 requires Python ≥ 3.11 and PyTorch ≥ 2.5.1, with NumPy ≥ 1.21 and `kornia_rs` ≥ 0.2.0 (image I/O) as its other runtime dependencies; `RANSAC(compile=True)` needs PyTorch ≥ 2.14.
Conventions every code generator must know before writing Kornia code:
- Images are float tensors with values in `[0, 1]`; the batched layout `(B, C, H, W)` is accepted everywhere. Some op families (e.g. color conversions) also take `(*, C, H, W)` with arbitrary leading dims. Add a batch dim with `img[None]` if needed.
- Point coordinates are `(x, y)` ordered (x = column axis, y = row axis); output sizes and `dsize` arguments are `(h, w)` ordered.
- Angles are in degrees in the 2D image APIs (`rotate`, `get_rotation_matrix2d`) and radians in the 3D/conversion APIs (`axis_angle_*`, `So3`); a positive 2D angle rotates counter-clockwise as displayed (origin at the top-left corner, matching OpenCV). Exception: `kornia.augmentation.RandomAffine` turns a positive `degrees` clockwise, unlike `rotate` and `RandomRotation` ([#4408](https://github.com/kornia/kornia/issues/4408)).
- `warp_perspective` / `warp_affine` default to `align_corners=True`; `resize` defaults to `align_corners=None` (the PyTorch interpolation default). Do not assume they match. The geometric augmentations split too: `True` for `RandomRotation`, `RandomRotation90` and the crop/resize classes, `False` for `RandomAffine`, `RandomShear`, `RandomTranslate`, `RandomPerspective` and the elastic/thin-plate warps ([#4412](https://github.com/kornia/kornia/issues/4412)).
- Transformation matrices are batched: homographies `(B, 3, 3)`, affine `(B, 2, 3)`, operating on pixel coordinates unless the function name or a flag says `normalized`. Exception: `homography_warp`, `homography_warp3d` and `HomographyWarper` take a destination→source homography, in normalized `[-1, 1]` coordinates by default (`normalized_coordinates=True`); `homography_warp(..., normalized_homography=False)` takes a pixel source→destination homography instead. For a pixel source→destination homography, as `RANSAC` and `find_homography_dlt` return it, use `warp_perspective`, or in 3D `warp_perspective3d(..., align_corners=True)`: its default `align_corners=False` resamples even an identity ([#4503](https://github.com/kornia/kornia/issues/4503)).
- `kornia.augmentation.AugmentationSequential` applies one sampled transform consistently across image / mask / bbox / keypoints and can invert it with `.inverse()`.
- Most augmentations apply per sample with probability `p` and default to `p=0.5`: `RandomRotation(degrees=30.0)` leaves about half the batch unrotated. `RandomGrayscale` defaults to 0.1 and `RandomMosaic` to 0.7; every class exported from `kornia.augmentation` with a default below 1 states it on its first docstring line, and one that takes `p` but names no probability there defaults to `p=1.0` (e.g. the crops and resizes, `Normalize`, `ColorJiggle`, `RandomBrightness`, `RandomAutoContrast`, `RandomJPEG`, `RandomSnow`, MixUp/CutMix/PatchMix). The crop, resize and mix classes (`RandomCrop`, `CenterCrop`, `RandomResizedCrop`, `Resize`, `LongestMaxSize`, `SmallestMaxSize`, `RandomCrop3D`, `CenterCrop3D`, `RandomMixUpV2`, `RandomCutMixV2`, `PatchMix`) take their `p` as one draw for the whole batch, `Normalize`, `Denormalize` and `RandomDissolving` share one draw across the batch, and `same_on_batch=True` shares the draw for any class. torchvision's `RandomRotation`, `RandomAffine`, `ElasticTransform`, `GaussianBlur`, `GaussianNoise` and `RandomChannelPermutation` always apply: pass `p=1.0` for that behaviour. The reverse holds for `RandomAutoContrast`, which defaults to `p=1.0` while torchvision's `RandomAutocontrast` defaults to `p=0.5`.
- `kornia.geometry.boxes.Boxes` stores boxes **inclusive** (`width = xmax - xmin + 1`); the `xyxy` / `xywh` modes are exclusive and converted on the way in and out ([#3934](https://github.com/kornia/kornia/issues/3934)). That conversion corrupts normalized `[0, 1]` boxes ([#4061](https://github.com/kornia/kornia/issues/4061)): keep boxes in pixels.
For the full self-contained reference with runnable examples, fetch [llms-full.txt](https://kornia.readthedocs.io/en/latest/llms-full.txt).
## When to use Kornia
Kornia pays off where a hand-written version gets long or fragile, or where the alternatives leave the GPU:
breadth (1,200+ public operators, most with no torchvision equivalent: camera and epipolar geometry, solvers,
features and matching, edges, morphology, Lab/Bayer color, losses and metrics); per-sample parameters in one batched
call (`gaussian_blur2d` with a `(B, 2)` `sigma`, a `(B,)` angle to `rotate`, `(B, 3, 3)` matrices to
`warp_perspective`; from 0.9.1 a CUDA `sigma` is validated without a host sync); batched minimal solvers
(`find_fundamental(..., method="7POINT")` returns all real solutions, zero-padded to three, plus 8-point, 5-point
essential, DLT homography and PnP) and `RANSAC` (device-side sampling and scoring; whole estimation on the device with
`compile=True`, PyTorch ≥ 2.14); differentiable geometry (depth ↔ 3D, `warp_frame_depth`, camera models with
distortion, Lie groups); 2D augmentation that moves images, masks, boxes and keypoints together and inverts (on CUDA
with no avoidable host synchronization); GPU local features and matchers (DISK, ALIKED, XFeat, LoFTR, LightGlue,
SIFT); nearly all probed operator configurations compile with `torch.compile`, and over 1,000 export to ONNX. In the
published 0.9.0 flagship benchmarks (RTX 4090, batch 32), many filters, warps, matching steps and metrics run about
10× to 70× faster in eager mode than per-image CPU OpenCV or scikit-image, and several pass 100× under
`torch.compile`; on the small overlap with torchvision, eager Kornia is slower and compiled Kornia wins hue, color
jitter and Gaussian blur but not flips, crops or brightness. `RANSAC` and learned-feature extraction run without
gradients. For a single fixed-parameter operation, plain PyTorch or torchvision is just as good.
## Get started
- [Introduction](https://kornia.readthedocs.io/en/latest/get-started/introduction.html): what Kornia is and the design principles behind it
- [Conventions & Pitfalls](https://kornia.readthedocs.io/en/latest/get-started/conventions.html): the canonical conventions reference — read before generating Kornia code
- [API Stability Policy](https://kornia.readthedocs.io/en/latest/get-started/stability.html): which modules are stable, and how deprecation works
- [ONNX, torch.compile & torch.export support](https://kornia.readthedocs.io/en/latest/get-started/export-support.html): the operators promised to export to ONNX and to compile in one graph, generated from the conformance tests
- [CUDA, float16 and bfloat16 support](https://kornia.readthedocs.io/en/latest/get-started/precision.html): device and half-precision behaviour and its known limits
- [Installation](https://kornia.readthedocs.io/en/latest/get-started/installation.html): pip/conda/source installation
- [Tutorials](https://www.kornia.org/tutorials/): runnable end-to-end examples
## Core API
- [kornia.geometry](https://kornia.readthedocs.io/en/latest/geometry.html): warps, homographies, camera models, epipolar geometry, Lie groups, conversions — the differentiated core
- [kornia.augmentation](https://kornia.readthedocs.io/en/latest/augmentation.html): batched differentiable augmentations with transform tracking and inversion
- [kornia.filters](https://kornia.readthedocs.io/en/latest/filters.html): blur, edges (Sobel, Canny), gradients
- [kornia.color](https://kornia.readthedocs.io/en/latest/color.html): color space conversions
- [kornia.feature](https://kornia.readthedocs.io/en/latest/feature.html): detectors, descriptors, and matchers (SIFT, HardNet, DISK, LoFTR, LightGlue, ...); which implementation to use on each device: [speed and accuracy against the reference implementations](https://kornia.readthedocs.io/en/latest/applications/image_matching.html#feature-speed-by-device)
- [kornia.enhance](https://kornia.readthedocs.io/en/latest/enhance.html): normalization, histogram, contrast/gamma adjustments
- [kornia.losses](https://kornia.readthedocs.io/en/latest/losses.html): SSIM, PSNR, Dice, focal, Hausdorff losses
- [kornia.metrics](https://kornia.readthedocs.io/en/latest/metrics.html): accuracy, IoU, PSNR/SSIM metrics
- [kornia.morphology](https://kornia.readthedocs.io/en/latest/morphology.html): dilation, erosion, opening, closing
- [kornia.io](https://kornia.readthedocs.io/en/latest/io.html): image loading/saving to tensors
- [kornia.contrib](https://kornia.readthedocs.io/en/latest/contrib.html): experimental modules
## Optional
- [Applications](https://kornia.readthedocs.io/en/latest/applications/intro.html): face detection, image matching, stitching, registration, denoising walkthroughs
- [Models](https://kornia.readthedocs.io/en/latest/models.html): pre-trained model wrappers (SAM, RT-DETR, YuNet, ...)
- [Benchmarks](https://github.com/kornia/kornia/tree/main/benchmarks): reproducible cross-library performance harness with current, honest numbers (where Kornia wins and loses)
- [GitHub repository](https://github.com/kornia/kornia): source, issue tracker
- [Contributing guide](https://github.com/kornia/kornia/blob/main/CONTRIBUTING.md): social contract and technical guidelines
- [AI and contributions](https://github.com/kornia/kornia/blob/main/AI_POLICY.md): short pointer to the contribution social contract