🐍 Geometric Computer Vision Library for Spatial AI
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Pending changes live in changelog.d.
Run pixi run changelog-preview to read the assembled notes.
[0.9.0] - 2026-10-23
Added
kornia.metrics.kitti_d1_error, the outlier ratio reported by the KITTI 2015 stereo benchmark. A pixel counts as an outlier only when its absolute disparity error exceedsabs_thresholdand its relative error exceedsrel_threshold, both strictly, with the ground truth as the relative denominator. That conjunction is what separates it frommean_bad_pixel_error, which applies the absolute criterion alone and so penalises large disparities for errors that are small next to their magnitude. A batch is pooled over every valid pixel, as the devkit accumulates it, rather than averaged per image. Closes #3758. (#3931)PadTotakescrop_if_exceeds. The defaultTruekeeps the existing behavior: an input larger thansizeon an axis is cropped tosizethere. Withcrop_if_exceeds=Falsethat axis passes through unchanged, so the output is at leastsizeon each axis and boxes and keypoints stay inside the image. Closes #3518. (#3964)Added opt-in
kornia.contrib.augmentation_auditreports with executed geometric provenance, native parameter snapshots, out-of-frame diagnostics and actual keypoint/box round-trip measurements, including explicit unsupported transforms and JSON export. (#4465)Relevant camera and image-coordinate API docstrings now link directly to the camera and general conventions guides. (#4501)
Document per-class coordinate, sampling, crop, resize, padding, and non-rigid warp conventions for 2D geometric augmentations, with executable tests for current behavior and known limitations. Clarify sampler migration after module and container moves. (#4538)
Document per-class value-range, parameter-meaning, filter, noise, weather, illumination and normalization conventions for the 2D intensity augmentations, with executable tests for current behavior and issue-linked pins for the known limitations. Rewrite the stale sampler-migration citations in the 2D augmentation bases. (#4566)
Document the conventions of mix and 3D augmentations and automatic augmentation policies, with executable tests for their sampling, coordinate, label, and output contracts. (#4634)
SIFTFeatureandSIFTFeatureScaleSpacenow acceptdescriptor_backend="pyramid"for fast extraction at their sparse detections.SIFTDescriptorFromPyramiddescribes supplied LAFs and can share an extraction pyramid between orientation assignment and description.The scale-space preset has a dedicated backend that reuses the detector Gaussian pyramid and retained octave/layer assignments, computing gradients once per used level. It preserves sparse detections and integrates rotated SIFT histograms directly from gradient fields.
The optimized scale-space path also specializes DoG detection: sparse refinement, exact octave coordinates, and top-K response ranking without contrast or edge rejection. The default patch backend remains available.
CPU Gaussian filtering avoids convolution work buffers; sparse neighbourhood gathers, two-bin angular voting, and device-specific descriptor chunks reduce extraction time without reducing integration support or the requested feature budget. Compiled and eager pyramid backends share checkpoint keys and support full-module serialization.
CPU inference builds Gaussian volumes directly in their final storage and reuses sampling coordinates; gradient atlases also avoid a full transpose copy. Spatial ties are rejected before bounded sparse gathers. Empty detections and descriptors retain zero gradients, and half-precision masks preserve their suppression semantics.
CUDA uses packed sparse refinement and separable descriptor histogram pooling to reduce kernel launches and extraction time while retaining bounded descriptor chunks. CPU and MPS keep their existing refinement paths.
Shared
conv_quad_interp3danditerative_quad_interp3dnow group finite differences and Cramer determinants on CUDA float32/float64, also accelerating the default patch-basedSIFTFeatureScaleSpacepipeline. CPU, MPS and reduced-precision inputs retain their scalar paths. (#4638)depth_from_disparityaccepts a per-batch-element(B,)baselineandfocal, so a batch of stereo pairs from rigs with different baselines or focal lengths no longer has to be split and processed one sample at a time. Elementbpairs withdisparity[b], which needs a disparity of rank 3 or more with a leading size ofB; a mismatched size still raisesShapeError. The shared forms, a Python number, a scalar tensor or a(1,)tensor, behave exactly as before, and the two may be mixed. (#4648)Added
kornia.contrib.connected_components_union_find, an exact, pure PyTorch 8-connected component labeling alternative using 2x2 block union-find. It converges without a user-selected iteration budget and returns integer labels for boolean, integer and floating-point masks, including half precision. (#4666)Document the conventions of
RandomTransplantationandRandomTransplantation3D— mask-driven donor selection, the(i - 1) mod Bdonor rule, label sampling andexcluded_labels, the replay contract, and the data-key and dtype rules — with executable tests, and export both names fromkornia.augmentation.__all__. (#4695)Add opt-in numerical reconstruction masks to both stereo disparity reprojection entry points with
return_mask=True, preserving existing coordinates, precision and gradients. The mask checks finite homogeneous components, the existing absolute W cutoff and finite returned XYZ; it does not certify matches, front-of-camera eligibility or visibility. (#4701)ColorJigglenow accepts a fixedorderfor deterministic application and full-graph compilation on RGB inputs. (#4717)kornia.morphologygainsengine="shift": a running max or min over the shifted views of the padded image. For finite inputs its output equalsengine="unfold"(torch.equal; only the sign of a zero can differ),torch.compilefuses it into a single kernel, and forward-only its peak memory is flat in the kernel area instead of growing with it (69 MiB of peak RSS growth against 1380 MiB for"unfold"with a 15x15 kernel on 8x3x256x256 float32 on CPU). Under autograd it saves two output-sized intermediates per kernel position, soengine="auto"keeps"unfold"for the float32/float64 CPU backward path. (#4728, #4996)Document the conventions of
kornia.morphology— the kernel reflection indilationand its absence inerosion, the membership-maskkerneland additivestructuring_element, the[row, col]originand its even-size default, and the fiveborder_typevalues with their scipy / scikit-image names (and OpenCV's forgeodesicandreflect) — as Convention blocks on the seven public functions and a new section on the Conventions & Pitfalls page, with executable tests for the kornia-side claims and for themax_valsentinel, non-float operand and convolution-engine dtype warts. (#4743)The
kornia.coreAPI page documents the six exception classes inkornia.core.exceptions(BaseError,ShapeError,TypeCheckError,ValueCheckError,DeviceError,ImageError), so references to them from other pages now link. (#4798)camtoworld_to_worldtocam_Rtandworldtocam_to_camtoworld_Rtacceptcheck_rotation=True, which raisesValueErrorwhenRis not a rotation matrix instead of silently returning a wrong pose. (#4817)rotation_matrix_to_axis_angle,rotation_matrix_to_quaternion,Quaternion.from_matrix,So3.from_matrixandSe3.from_matrixtakecheck_rotation(defaultFalse). Withcheck_rotation=Truethey raise aValueErrorunless every input is a rotation:max|R @ R^T - I|within 100 eps of the input dtype (16 eps for float16 and bfloat16) anddet(R) > 0. Without it the behaviour is unchanged, so a reflection such asdiag(-1, 1, 1)is still reported as the identity rotation[0., 0., 0.], andSe3.from_matrixstill accepts a reflection block. (#4773) (#4840)Convention blocks for the two-view F/E contract (
find_fundamental,find_essential, the epipolar metrics,decompose_essential_matrixand their siblings), a "Two-view geometry" section on the Conventions & Pitfalls page with the OpenCV mapping, and 28 convention and wart pins; the warts are documented and linked (#2198, #4831, #4855, #4862, #4874–#4881, #4883, #4884), not fixed. (#4887)Convention blocks for the projection and structure functions of
kornia.geometry.epipolar(projection_from_KRt,KRt_from_projection,projections_from_fundamental,depth_from_point,scale_intrinsics,intrinsics_like,random_intrinsics,triangulate_points,generate_scene), three functions added to the rendered API reference, and 16 convention and wart pins; the #4263 wart is documented and linked, not fixed; #4863, #4864, #4865 and #4900 are fixed by #4901. (#4889)Convention blocks for homography estimation (
find_homography_dltand its iterated and line-segment variants, the transfer errors),RANSACand the polynomial and homogeneous solvers (solve_quadratic,solve_cubic,solve_quartic,determinant_to_polynomial,null_vector_3x4), with convention and wart pins;solve_quarticis added to the rendered API reference. The documented defects are linked to their issues (#4833, #4866–#4870, #4872–#4874, #4881, #4890, #4905) and not fixed here. (#4892)RANSAC(prosac_sampling=True)now draws progressive samples from correspondences sorted best-first, following Chum and Matas (CVPR 2005); the flag used to be accepted and ignored. The schedule advances per sampled set inside each batch, and the sampler runs the fullbatch_size * max_iterbudget.RANSACalso acceptslo_sample_size, which fitsmax_lo_itersrandom inlier subsets of that size in one solver batch before a final full-inlier refit. (#4902)normalize_pointsaccepts optional per-pointweightsof shape(B, N): the centroid and the mean radius are weighted, negative weights count as zero, and a batch element whose weights are all zero uses the unweighted statistics. (#4908)Convention blocks for
Quaternion,average_quaternionsandSo3(storage, product order, principallog, Jacobian sides), a "Rotations and rigid motions" section on the Conventions & Pitfalls page with the scipy / Sophus / Eigen mapping, and 19 convention and wart pins; the warts are documented and linked (#3950, #3953, #4923, #4942), not fixed. (#4976)Convention blocks for
So2,Se2andSe3(tangent order, direction,logrange, adjoint and matrix layouts, composition order) and 25 convention and wart pins; the warts are documented and linked (#4923, #4929, #4931, #4932, #4942), not fixed. (#4977)Convention blocks for
relative_transformationand its linalg siblings (frame naming, rigid-only inputs, the contrast withrelative_camera_motion) and forNamedPose, an API page forkornia.geometry.pose, and 12 convention and wart pins; the warts are documented and linked (#4881, #4937), not fixed. (#4978)RANSACgainslocal_optimization("lm"or"dlt"),refine_itersfor the final Levenberg-Marquardt refinement, the"fundamental_8pt"model type, and anoffsetargument toRANSAC.samplethat continues the PROSAC schedule across batches of different sizes. The new pipeline normalizes the correspondences once per call, solves minimal samples through a batched LU null space and scores them with one matrix product per batch; on PhotoTourism fundamental matrices and HEB homographies it is more accurate than the previous defaults and several times faster on CUDA.sample_is_valid_for_homographyno longer copies index tensors to the device on every call. The minimal solvers share their LU null space with the public estimators:find_fundamental(method="7POINT"), the eight-correspondence unweighted case offind_fundamental, and the four-correspondencefind_homography_dlt(solver="lu")replaceeigh, QR or SVD with one batched LU factorization, which is several times faster on CPU and now runs in float16 and bfloat16; the seven-point cubic is expanded without inverting the null-space basis.sampson_epipolar_distanceandoneway_transfer_error(and sosymmetric_transfer_error) score several matrices on one set of correspondences with one or two matrix products, faster on CPU and CUDA for RANSAC-sized batches, andfind_fundamental's eight-point solver removes the smallest singular value in closed form instead of with an SVD for batches of 128 or more on CPU and 512 or more on other devices, about twice as fast for 2048 samples. (#5031)ImageRegistrator.warp_dst_into_src, the correctly spelled inverse ofwarp_src_into_dst; its docstring now names the argument it warps,dst_img. The misspelledwarp_dst_inro_srcstill works as a deprecated alias that emits aDeprecationWarning. (#5049)Convention blocks for
create_meshgrid,create_meshgrid3dandkornia.geometry.subpix(the(x, y)/(d, x, y)coordinate orders, corner-aligned normalization, thegrid_samplereorder for 3D grids, the conv soft-argmax windows, the quadratic refiners' rejection rules and strict NMS), the matching additions to the Conventions & Pitfalls page, and 14 convention and wart pins; the warts are documented and linked (#4503, #5020, #5065, #5066), not fixed. (#5068)Convention blocks for
Keypoints,Vector3and the PLY writers ((x, y)pixel coordinates, homogeneous transformation, copy / in-place / write-through aliasing, thedoublex y zPLY layout), an API page forkornia.geometry.vector, and 13 convention and wart pins; the warts are documented and linked (#5022, #5023), not fixed. (#5069)Convention blocks for
ParametrizedLine,fit_line,Hyperplane,fit_planeandImageRegistrator(unnormalized line directions, then . x + d = 0plane and the orientation ofthrough, the built-in destination-to-source registration models in normalized coordinates),fit_planeand theHyperplanemethods on the line API page, and 13 convention and wart pins; the wart is documented and linked (#4923), not fixed. (#5070)kornia.image.draw_rectanglenow acceptsline_widthto draw outlines thicker than one pixel. The outline grows inward from each edge, so it stays inside the rectangle, and the part of it outside the image is not drawn. (#5093)RANSACgains opt-indegensac=True(off by default), DEGENSAC's dominant-plane recovery for seven-point fundamental matrices (Chum, Werner and Matas, CVPR 2005), following Chum's implementation in pydegensac: record-setting seven-point models are tested for five or more correspondences related by one homography, and a degenerate one hands that homography to a plane-and-parallax search over the correspondences off the plane. The newkornia.geometry.homography.sampson_homography_distancereturns the Sampson distance of correspondences to homographies, the first-order geometric error over both images (Hartley and Zisserman, section 4.2.6): unlikeoneway_transfer_error, it accounts for noise in both images and does not depend on the scale ofH, and an exact correspondence scores 0. (#5099)RANSAC(compile=True)runs the wholelocal_optimization="lm"estimation (homography, fundamental and essential matrices) as onetorch.compilegraph on CPU and CUDA with torch 2.14 or later. The graph is traced once per configuration and does not depend on the number of correspondences, the threshold, the confidence or the sample budget; it is saved next to inductor's cache, so a later process loads it instead of compiling. Seeded compiled calls are reproducible but use their own random stream without changing the global CPU or CUDA generators. Ordinary and inference-mode calls share the compiled artifact. Eager results are unchanged.Compiled calls normalize autocast, distinguish thread/default-dtype/default-device settings in the artifact cache, and draw their samples from a counter-based hash of the seed, so concurrent seeded calls preserve the global RNG. Large explicit CPU batches split to bound scoring memory while retaining the sample budget. Zero-weight singular correspondences no longer prevent LM refinement; artifact writes are atomic. (#5117)
convert_sift_descriptor_layoutreorders SIFT descriptors between kornia's layout and OpenCV's, andSIFTFeatureandSIFTFeatureScaleSpacetakedescriptor_layout="opencv"to return OpenCV's layout directly.LightGlueMatcher("sift")expects OpenCV's layout, which kornia's SIFT descriptors do not use by default, so request it or convert before matching: on Oxford Graf 1→4,SIFTFeaturedescriptors matched in kornia's layout gave 2 correct matches, and 497 in OpenCV's. (#5145)Convention blocks for
filter2d,filter2d_separable,filter3d,fft_convand the kernel builders: correlation vsbehaviour='conv', theborder_typevocabulary, the(k - 1) // 2anchor of an even kernel, kernel batch and normalisation rules, the Rodrigues axis-angle vector used byget_motion_kernel3d, and the orientation, sign and normalisation of every derivative kernel. A new Filtering section on the Conventions page maps the border modes, the correlation rule and the even-kernel anchor to scipy and OpenCV.fft_convand ten kernel builders are added to the API reference. (#5230)correlate2d,convolve2d,correlate3dandconvolve3dare now listed inkornia.filters.__all__, sofrom kornia.filters import *brings them, and appear on the Filtering API page and in the API-surface inventory. They were already importable fromkornia.filtersby name, and equalfilter2d/filter3dwithbehaviour='corr'/'conv'. The two 2-D docstrings now state the output shape forpadding='valid', and each of the four has an example that shows how correlation and convolution differ. (#5249)kornia.morphology.reconstruction: grayscale morphological reconstruction by dilation or erosion, matchingskimage.morphology.reconstruction. (#5257)Document color-space and enhancement conventions, correct channel units and API contracts, and add executable convention and known-defect tests. (#5319)
Convention blocks for
spatial_gradient,spatial_gradient3d,sobel,laplacian,canny,in_rangeandotsu_threshold: the(dx, dy)output layout and default normalisation of the derivative filters, the Laplacian kernel's sign and scale, the unnormalized Sobel magnitude thatcanny's thresholds are compared with and its tie rule,in_range's inclusive bounds and accepted bound shapes, and the per-plane Otsu threshold read from the upper edge of the split bin. The Filtering section of the Conventions page maps the derivative scales andcanny's thresholds to OpenCV and scikit-image. (#5427)Convention blocks for the blurring operators of
kornia.filters(gaussian_blur2d,box_blur,median_blur,bilateral_blur,joint_bilateral_blur,guided_blur,motion_blur,motion_blur3d,unsharp_mask,blur_pool2d,max_blur_pool2d,edge_aware_blur_pool2dand their module classes):kernel_sizeandsigmagiven rows first, per-sample tensor sigmas, the bilateral and guided filters' parameter units and argument order, the motion-blur angle and streak weighting, the blur pools' sampling grid and padding. The Filtering section of the Conventions page relates them to OpenCV, scipy, scikit-image and the antialiased-cnnsBlurPool.edge_aware_blur_pool2d,motion_blur3d,EdgeAwareBlurPool2D,MotionBlur3DandStableDiffusionDissolvingare added to the API reference. (#5433)kornia.feature.match_smnn_batchedmatches independent descriptor pairs with batched distance computation, packed match indices, and optional validity masks for padded inputs. (#5558)Convention blocks for the image-quality and regression losses and metrics (
ssim,ssim3d,psnr, the SSIM / MS-SSIM / PSNR losses, the Charbonnier / Cauchy / Geman–McClure / Welsch losses, total variation, inverse-depth smoothness and the KL / JS divergences), withtest_convention_*pins and a new "Losses and metrics" section on the conventions page. (#5566)Convention blocks for the mutual-information losses (
mutual_information_loss, its normalized, 2-D, 3-D andFromRefmodule forms, andMIKernel), withtest_convention_*pins and a new Registration API page that lists all 13 mutual-information exports. (#5632)Convention blocks for the dense-prediction losses (
focal_loss,binary_focal_loss_with_logits,dice_loss,tversky_loss, the Lovász and Hausdorff losses andone_hot), withtest_convention_*pins and a "Dense-prediction losses" sub-section on the conventions page. (#5634)Convention blocks for the task metrics (classification, segmentation, detection, optical flow, disparity and pose), with
test_convention_*pins and a "Task metrics" sub-section on the conventions page that tabulates each metric's output, pooling and scale. (#5635)The docstrings of
shear,Shear,Affine,get_affine_matrix2d,get_shear_matrix2dandRandomAffinenow say what their shear arguments mean: raw factors about pixel (0, 0) forshearandShear, and angles in radians about the centre, sheared by their negative tangent, forAffine, the two matrix helpers andRandomAffine(in degrees there). That two entry points readsheardifferently is a known defect (#5661). (#5682)DoGHardNetandDoGAffNetHardNetreturn LAFs and HardNet descriptors thatLightGlueMatcher("doghardnet")andLightGlueMatcher("dog_affnet_hardnet")take without rescaling. They detect with the DoG detector of the default"patch"backend ofSIFTFeatureScaleSpace,DoGAffNetHardNetadding AffNet shapes, estimate the orientation at the detection scale, and return and describe LAFs twice the detection frames: 12 sigma, the scale those LightGlue weights were trained with. TheLightGlueMatcherdocumentation states that scale. (#5727)Document an explicit scale-space pyramid SIFT recipe, distinguish multiresolution detection from scale-space detection, and explain the patch, dense and supplied-frame descriptor interfaces. Document the repaired multiresolution pyramid orientation and its remaining validation and possible-deprecation criteria without changing defaults, adding runtime warnings or removing APIs. (#5750)
kornia.image.ColorSpaceis exported, so aPixelFormator a colour space forImage.from_numpyno longer needs an import fromkornia.image.base.draw_point2danddraw_lineaccept a single-value colour, of shape(1,)or 0-d, and write it to every channel, asdraw_rectangleanddraw_convex_polygonalready did; they used to raise for it on an image with more than one channel. OpenCV's and Pillow's scalar colours fill only the first channel. (#5813)The ONNX guide and the landing page now export with the
torch.export-based exporter (dynamo=True, withdynamic_shapes) instead of the deprecated TorchScript-based one at opset 17, and show theauto_ir_version_conversion=Trueflag thatONNXSequentialneeds to chain such an export with the pre-exported Hub operators. (#5818)The ONNX, torch.compile and torch.export page is now presented as a dated survey rather than a support statement: it is titled a survey, opens with a note that it records one measurement that Kornia's tests check only in part, and reports passed / probed instead of supported / probed. The ONNX guide no longer quotes the share of operators that export. (#5820)
The
kornia.ioandkornia.imageAPI documentation states their conventions: the channels, dtype and range of eachload_imagetype, the dtypes and channel counts eachwrite_imageformat stores, when the NumPy converters share memory, the pixel frame, rounding and clipping of the drawing functions, the value ranges of the terminal printers, and the supported dtypes forImage.to_gray(). The conventions page gains a Files and arrays section, with the load types and a table mapping OpenCV's, Pillow's and torchvision's readers, writers and converters onto kornia's, and a Drawing section. One known defect is documented:write_imageraises a bareExceptionand leaves an empty or truncated file for an image with zero height or width (#5770). (#5823)Document the conventions of the local affine frame (LAF) and patch-extraction API (
kornia.feature.laf,get_laf_descriptors,LAFDescriptorandKORNIA_CHECK_LAF) as Convention blocks and pointers, and add a "Local features" section to the Conventions & Pitfalls page: the[A | c]frame in pixels, scale and orientation, the patch a LAF samples, detector padding, and the conversion from OpenCV keypoints. (#5827)Document the conventions of the
kornia.featureresponse functions, detectors, orientation and affine-shape estimators as Convention blocks and pointers: the sign and intensity scaling of each response, the candidates, frame and padding ofScaleSpaceDetector, the level-pixel frame ofMultiResolutionDetector, the input range ofKeyNet, the orientation sign, and the layout of thePatchAffineShapeEstimatoroutput. (#5835)Document the conventions of the
kornia.featurepatch descriptors (SIFTDescriptor,DenseSIFTDescriptor,SIFTDescriptorFromPyramid,HardNet,HardNet8,SOSNet,TFeat,HyNet,FilterResponseNorm2d,TLUandMKDDescriptor) as Convention blocks and pointers: the patch shape and sampling, which intensity changes leave a descriptor unchanged, the output norm and width, SIFT clipping and RootSIFT, and the dense and pyramid SIFT cell geometry. (#5836)Document the conventions of the
kornia.featurematchers (match_nn,match_mnn,match_snn,match_smnn,match_smnn_batched,match_fginn,match_adalam,DescriptorMatcher,GeometryAwareDescriptorMatcher,LocalFeatureMatcher,LightGlueMatcher,LightGlue,OnnxLightGlueandLoFTR) as Convention blocks and pointers: what the returned values and index pairs hold for each matcher, the inclusive ratio thresholds and a given distance matrix, the keypoints, image size and extra inputs each LightGlue feature type takes, the dtype of LightGlue's matching scores, the LoFTR keypoint frame, and the known defects ofmatch_adalam,LightGlueandOnnxLightGlue. (#5856)LoFTR.extract_features(image)returns the features of an image that do not depend on the image it is matched with (the backbone's coarse and fine maps, the coarse one position-encoded), andLoFTR.forwardaccepts them asfeatures0/features1instead ofimage0/image1, on either side or both. Matching one image against many no longer runs the backbone for every pair. For images of different sizes the matches are bitwise the same as when passing the images;forwardstill runs two images of the same size through the backbone together. All image and feature input combinations reject unequal batch sizes withValueError. (#5880)Document the conventions of the
kornia.featurelocal-feature presets and learned models (LocalFeature,SIFTFeature,SIFTFeatureScaleSpace, the AffNet/HardNet/KeyNet presets,DISK,ALIKED,XFeat,XFeatModel,InterpolateSparse2d,DeDoDe,SOLD2,SOLD2_detectorandDeFMO) as Convention blocks and pointers: the input range and layout each model reads, the keypoint frame, order and dtype each returns, how DISK'snand ALIKED's top-k and threshold modes select keypoints and where that departs from the reference implementations, which dense descriptors are normalised, the padded slots ofLocalFeatureand why they must be dropped before matching, and the known defects ofSIFTFeature,ALIKED,SOLD2andInterpolateSparse2d. (#5899)kornia.geometry.conversions.denormalize_homography3d, the inverse ofnormalize_homography3d, andkornia.geometry.conversions.ColmapQTVecs_to_ARKitQTVecs, the reverse ofARKitQTVecs_to_ColmapQTVecs, so both conversions can now be round-tripped through the public API. (#5938)Add weighted
kornia.geometry.find_affineestimation andRANSAC(model_type="affine")for full 2D affine transforms. AdaLAM shares the linear solver while retaining its seed-constrained neighborhood RANSAC. Affine fitting and scoring retain at least float32 arithmetic under autocast. (#5940)kornia.trackingand the numeric and tooling exports ofkornia.contribdocument their conventions in Convention blocks, the contrib page listshistogram_matchingandinterpand maps the connected-component connectivity onto SciPy, OpenCV and scikit-image, and the known defect links its issue (#5956). (#5978)kornia.augmentation.CenterCrop,RandomCropandRandomResizedCropsupportinversein their defaultcropping_mode="slice": images and masks, and forRandomCropalso boxes and keypoints, are warped back onto the input canvas with the inverse of the recordedtransform_matrix, as in resample mode. Cropped-away content is not restored. These calls used to raiseNotImplementedError, except thatCenterCropandRandomResizedCropreturned a tensor for an empty batch or one the crop was not applied to. (#5984)kornia.models.qwen25.Qwen25VisionTransformerandQwen25VisionConfig, the Qwen2.5-VL vision tower: a temporal patch embedding, a 2D rotary position embedding, RMS-normalized blocks with gated MLPs, windowed attention with full attention in selected blocks, and the 2 x 2 patch merger.from_pretrainedstrictly loads thevisual.*tensors of a Qwen2.5-VL checkpoint from a local file or directory. On the released 3B weights it matches Hugging Facetransformersv4.51.0 on the same preprocessed patches.kornia.core.load_safetensorsgains anincludepredicate that copies only the selected tensors out of the file, so a vision tower can be read from a shard it shares with a language model. Closes #6003. (#6025)SigLip2Model.forwardtakes apixel_attention_maskfor the vision tower, as transformers'Siglip2Model.forwarddoes: it reachesget_image_features, so the image embeddings, the logits and thereturn_lossloss leave out the masked patches. (#6051)KORNIA_CHECK_SAME_SIZEchecks that two tensors have the same size along a dimension, optionally accepting a size of 1 for the first, andKORNIA_CHECK_SIZESchecks a tensor against sizes computed at run time, withNonefor a dimension of any size. Both build their error message only on failure. Themsgof everyKORNIA_CHECK*helper can also be a function without arguments, called only when the check fails:KORNIA_CHECK(condition, lambda: f"..."). (#6063)kornia.filters.dexined.DexiNedis now the same class askornia.models.dexined.DexiNed, which that module re-exports with its building blocks, so it gainsto_onnxand its ONNX declarations. A whole model pickled fromkornia.filters.dexinedstill loads, and a newly pickled one is stored underkornia.models.dexined. (#6107)Added
force_download=TruetoCachedDownloaderand the ONNX loaders, including the Hugging Face community loader andDepthAnythingONNXBuilder, to refresh cached models, external weights, and preprocessing configs. Failed downloads preserve the previous cached file. Errors when loading cached models or parsing configs now suggest the option. (#6139)The ONNX, torch.compile and torch.export page now opens with "What Kornia promises": the stable-core configurations that export with the dynamo ONNX exporter at opset 18 and match eager in onnxruntime, and the ones that compile with
torch.compile(..., fullgraph=True)and match eager, for inference at static shapes, checked in CI on torch 2.9 and 2.14, with the configurations left out, the known failures and their tracking issues; the survey tables mark every promised configuration.nmsanddraw_rectangledocument howtorch.compilehandles them, and are left out of the compile promise (#6194). (#6233)API reference entries now carry a Try in browser badge that links a function, its
nn.Modulecounterpart or a browser model to its interactive page on the kornia.org playground, so readers can run the operator on a sample image without installing anything. The set of linked APIs is a snapshot of the playground indocs/source/_playground_links.json, refreshed bydocs/generate_playground_links.py. (#4333)An Adoption page (
community/adoption) listing the most-starred GitHub repositories and packages that depend on kornia, rendered at build time fromdocs/source/_data/dependents.json;docs/fetch_dependents.pyrefreshes that snapshot from GitHub's dependency graph. (#4155)An ONNX, torch.compile and torch.export support page under Resources (
get-started/export-support) lists every surveyed public operator, grouped by package and section, with its dynamo ONNX export,torch.exportandtorch.compileoutcome, the cause of each failure and a search box with result filters. It is rendered at build time from the committed snapshotdocs/source/_data/export_support.json;docs/export_support/run.pyreruns the survey to refresh it. (#4182)Documentation pages now provide search-specific titles and descriptions, canonical tutorial links, and a canonicalized redirect from the retired highlighted-features page. (#4226)
Documented bbox/Boxes geometry-operation conventions and added executable pins for transforms, NMS, padding, clipping, and area filtering, including known unbatched-input limitations. (#4245)
Documented camera distortion and calibration conventions (normalized versus pixel inputs, the coefficient layout, the
new_K/Kroles, the iterative inverses) and added executable pins forkornia.geometry.camera's distortion models andkornia.geometry.calibration, with the tilt-projection, Kannala-Brandt Jacobian and float16 defects tracked in dedicated issues. (#4312)Documented camera projection-core conventions (
PinholeCameraframes, integer pixel centres, the two meanings of depth, thez = 0policies) and added executable pins forkornia.geometry.camera's projection core, with the known scale-rule, aliasing, guard and legacy-API limitations tracked in dedicated issues. (#4294)Documented depth and stereo conventions (the two meanings of depth, the
(B, 3, H, W)versus(B, H, W, 3)layouts, the opposite source/destination naming ofwarp_frame_depthandDepthWarper, the rectified stereoQmatrix) and added executable pins forkornia.geometry.depthandStereoCamera, including dtype promotion, extra-axis broadcasting, subpixel border sampling, and singular stereo reprojection. Remaining defects are tracked in dedicated issues. (#4317)Documented the
kornia.sensors.cameraconventions (Vector-typed inputs, the per-modelparamslayout, the shared half-pixelscalerule, and the pinhole mapping shared withkornia.geometry.camera, including its camera-axis broadcasting, projection rounding and zero/near-zero depth differences) and added executable pins, with the unimplemented models tracked in a dedicated issue; the three non-pinhole models now appear on the sensors documentation page. (#4318)Documented the shared 2D contract of
kornia.augmentation— the(B, C, H, W)float working layout andkeepdim,p/p_batch/same_on_batch, where random parameters are drawn and howtorch.manual_seedandparams=replay them, what a module serializes, and whatAugmentationSequentialdoes with each data key (layouts, the inclusivexyxy_plusboxes and integer-centre flips, nearest masks,extra_args,inverse) — as Convention blocks on the base classes and containers, with the canonical randomness and serialization statements on the Conventions & Pitfalls page and executable pins. The contracts distinguish sampler and returned-parameter placement, trainable range parameters, application-time replay exceptions, padding labels, information lost by rotated tensor boxes, mask-list gates, mixed mask dtypes, dictionary-key exceptions, and the transplantation constructors. Scope corrections and regression tests cover mix-specific contracts, inverse support, mask erasing/filtering/precision, nested matrices, serialization and sampler limitations; the container,p_batch,set_rng_device_and_dtype,state_dictandB = 0defects are tracked in dedicated issues. (#4452)Dynamo ONNX export (
torch.onnx.export(..., dynamo=True)) now covers a much larger part of the library: about 140 additional operator cases in the export survey capture, pass the ONNX checker and match eager execution under onnxruntime. Operators that failed graph capture or had no ONNX lowering gained an export-time path that returns the same values eagerly: matrix inverses up to 4x4 use a closed-form adjugate instead ofaten::linalg_inv(warp_perspective3d,warp_affine3d,rotate3d,affine3d,get_projective_transform,invert_affine_transform,denormalize_homography,symmetric_transfer_error,safe_inverse_with_mask,DepthWarper,PinholeCamera,StereoCamera,NamedPose,ImageRegistrator,ParametrizedLine.intersectand theSe2/Se3/So2groups);MedianBlur/median_blurselect the median throughsort;HausdorffERLoss/HausdorffERLoss3Dpool throughamax(which also makes the 3D loss run on MPS);distance_transformavoidshypot;match_nn/match_mnn/DescriptorMatcheravoidcdist; the mutual-information losses, the Bessel kernels,solve_quadratic,matrix_cofactor_tensor,decompose_essential_matrix_no_svd,distort_points/undistort_points/undistort_image,Boxes/Boxes3D(from_tensor,to_mask),bbox_to_mask3d,mean_iou_bbox,conv_soft_argmax2dwith a tensor temperature,JPEGCodecDifferentiable,ZCAWhitening(transform/inverse_transform),BoxFiltering,MotionBlur3D,center_crop/crop_and_resize/crop_by_transform_mat3dand theOriNet/LAFOrienter/LAFAffNetShapeEstimator/HardNet/HardNet8/SIFTFeature/LAFDescriptor/DeDoDefeature stack are branch-free or guard their data-dependent checks withkornia.core.utils.is_exporting(). Among augmentations,LongestMaxSize,SmallestMaxSize,RandomCrop,RandomResizedCrop,RandomAffine3D,RandomRotation3D,RandomMotionBlur3D,RandomJPEG,RandomMedianBlur,RandomPlanckianJitterandAugmentationSequentialwith crops or boxes now export, andLightGlueexports oncedepth_confidence/width_confidencepruning is disabled. Behavior notes:Se2/Se3/So2/ParametrizedLinebuilt from a tensor that already carries autograd history (Se2.exp(v),ParametrizedLine.through(p0, p1)) keep that history: the tensor is registered as a buffer instead of being re-rooted as annn.Parameter, so.to(),state_dict()andload_state_dict()still reach it under the same key but it no longer appears inparameters();kornia.core.utils.is_exporting()falls back tois_compiling()on torch < 2.6, which has no export flag (inside a Dynamo trace newer torch folds its flag toTruefortorch.compileas well, so the export-safe paths are what a compiled graph contains on every supported version); under exportcrop_by_indiceswith asizeresamples the crop and without one keeps the eager path,distort_points/undistort_pointsalways apply the tilt term (a no-op when the coefficients are zero) andnormalize/denormalizeaccept a 1-D(C,)mean/std;matrix_cofactor_tensorreturns exact cofactors for singular matrices instead of raising when every matrix in the batch is singular. (#4182)Every page in the Models section of the docs now opens with the shortest script that runs the model and a figure of its output on a real input, with the paper card moved to the bottom. The figures are rendered by
docs/generate_model_examples.pyand committed underdocs/source/_static/img/models/, so the docs build needs neither the weights nor the sample images. (#4178)Implemented the exported Brown-Conrady, Kannala-Brandt K3, and Orthographic sensor camera models, including distortion/projection plumbing, intrinsic matrices, and batched project/unproject support. (#4284, #4377)
KimiVL and SigLIP2 builders load their safetensors checkpoints with kornia's own downloader (
kornia.core.download_hf_file/download_file_from_url, which share the retrying, rate-limit-aware cache every other checkpoint uses) and a pure-torch reader (kornia.core.load_safetensors);huggingface_hubandsafetensorsare no longer needed. Both were imported without ever being declared as dependencies, soKimiVLBuilder.from_pretrained_hf()andSigLip2Builder.from_pretrained_hf()used to raiseImportErroron a plainpip install kornia. The checkpoints move to torch's hub cache as a result; see Breaking changes. (#4293)Linux CPU half-precision CI now uses explicit reproducible profiles, exact phase/exception manifests, complete lifecycle verification, and guarded candidate-only baseline regeneration. (#4154)
New "Camera and world conventions across the ecosystem" page cataloguing the pixel-centre, axis and extrinsics conventions of OpenCV, COLMAP, OpenGL, ARKit, ARCore, PyTorch3D and Direct3D with the kornia converter for each, plus the baked
align_cornersrows for the depth and undistortion warps on the Conventions & Pitfalls page. (#4315)Optional-dependency extra
kornia[image]installs Pillow for PIL-backed image input/output, display helpers andkornia.io.sample; missing-Pillow errors now name the extra to install, and the unusedDinoVisionTransformer.forward_features_listlist path has been removed. (#4464)Optional-dependency extras
kornia[onnx]andkornia[sd]declare the third-party packages that the ONNX and Stable-Diffusion-dissolving wrappers lazily import, and are documented on the installation page. Missing-dependency errors now name the extra to install, anddevno longer pullsdiffusersandtransformers. (#4301)Repeatable Oxford affine local-feature benchmarks for SIFT, SIFT-AffNet-HardNet, and KeyNet-HardNet, with eager/compiled median/IQR speed, homography corner error, and JSON output; historical scale-space SIFT CPU/CUDA batch-runtime comparisons and plotting. (#4254)
The blocking MPS CI gate now runs on torch 2.14.0 instead of 2.9.1, on the
macos-15image instead ofmacos-latest, and its recorded failure baseline drops from 200 entries to 14. torch 2.14.0 adds MPS kernels forgrid_sample's 2-D and 3-D backward passes, forpadding_mode="border"and 5-Dmode="nearest"sampling, and for the eigen/QR/LU/SVD family (eigh,svd,svdvals,qr,lu_solve,lstsq,cholesky_solve,matrix_exp), so most of what used to fail on Apple silicon now runs there natively. What is still pinned in the baseline:torch.linalg.eigvals, which has no MPS kernel and keeps the 5-point essential-matrix solver off the device, and theyuv420/yuv422empty-input reshape defect. Separately,tests/geometry/test_ransac.pyis skipped rather than pinned — it aborts the process on the runners' paravirtualized GPU, and aSIGABRThas no exception type to record (#4204); the skip costs 9 tests that pass on real Apple hardware, and--run-mps-process-abortruns them locally. The underlying limit is thattorch.linalg.svd/svdvals/lstsqfails to build a Metal pipeline once its input holds 8192 elements or more, which used to keepRANSAC's batched minimal solvers off the device (#4201);_torch_svd_castand_torch_linalg_svdvalsnow route such inputs through the CPU, so the fundamental and homography solvers reach it, whilefind_essentialstill raises ontorch.linalg.eigvals, which has no MPS kernel. The image stays onmacos-15: onmacos-latest(macOS 26) the runner's virtual GPU cannot compile the Metal 4 cooperative-tensor shaders torch 2.14 emits, which fails 664 tests — a physical M1 on macOS 26 compiles them fine. kornia still supports torch 2.5.1, so the in-tree MPS workarounds stay. (#4202)The documentation site was rebuilt on
pydata-sphinx-themewith a top navigation bar (Learn / API / Models plus Ecosystem, About and Support menus), a redesigned landing page, a restructured API reference with per-topic subpages, and a long list of fixed doc examples and removed dead interactive demos. Old deep links into the split module pages (e.g.augmentation.module.html#kornia.augmentation.RandomAffine) are forwarded to the subpage that now documents the object, so existing links keep resolving. The furo layout stayed available behindKORNIA_DOCS_THEME=furountil #4304 removed that fallback. (#4155)benchmarks/feature/laf_ops.pymicrobenchmarks seven public LAF operations (laf_from_center_scale_ori,make_upright,ellipse_to_laf,laf_to_boundary_points,laf_is_inside_image,extract_patches_simple,extract_patches_from_pyramid) as kornia eager vstorch.compile, and its CPU and CUDA runs are the first committed non-Apple result set, so the docs performance page now shows CUDA numbers. The page labels its throughput column from a new optionalunitsmetadata key (LAFs/shere,items/swhen absent) and identifies a row by every config field that varies within a result file rather than by(op, batch)alone, which a suite sweeping a second axis at a fixed batch would otherwise collapse onto one row.run_batch_sweepgainedlabel_fn,items_fnandunitsso such a suite can use the shared sweep; the existing callers are unchanged. (#4119)kornia.feature.laf_is_filled(laf)returns the(B, N)mask of the slots a detection filled, the complement of a detector's zero-LAF padding. Fixed-shape detectors pad the slots no detection filled with an all-zero LAF, and those slots must be dropped before matching -- their descriptors are identical to one another, so they match each other at zero distance and a mutual nearest-neighbour test does not reject them.LocalFeature.forward's docstring already required callers of a hand-rolled pipeline to do this and gave them the expression to copy; they can now call the function instead. It replaces the same expression at four internal sites inkornia/feature. (#4223)kornia.models.RRDBNet, a vendored Real-ESRGAN generator;RRDBNetBuilderno longer needsbasicsr. (#4292)
Bug fixes
The
kornia.metricsdisparity reductions accumulate infloat32forfloat16andbfloat16inputs, somean_absolute_disparity_error,root_mean_squared_disparity_errorandmean_bad_pixel_errorno longer returninfon an image-sized map. Afloat16sum saturates at 65504, and abfloat16sum lost roughly 0.5% over 100k terms.root_mean_squared_disparity_erroradditionally squared in the input dtype, so a 300 px error saturated before any reduction ran; it now squares in the accumulator dtype. A mixed-dtype pair now returns the promoted dtype from every metric in the module rather than the dtype ofinput, matching whatmean_absolute_disparity_erroralready did. (#3931)warp_perspective,warp_affine,homography_warp,HomographyWarperandwarp_image_tpsnow build their sampling grid and homography normalization under the samealign_cornersconvention they pass togrid_sample. Previously the grid was always corner-aligned, so withalign_corners=Falsean identity homography did not reproduce its input (max deviation11.25on a 4x4arangeimage) and a whole-pixel translation resampled at fractional offsets;warp_image_tpswas affected on its default path.create_meshgrid,normal_transform_pixel,normalize_homographyanddenormalize_homographygain analign_cornersparameter (last, defaultTrue, so existing calls are unchanged).crop_by_transform_matdrops the #3650 correction matrix and the 1-pixelwarp_affinefallback that worked around the mismatch, so 1-pixel outputs are exact under both settings.normal_transform_pixelalso writes thealign_corners=Falseoffset as a single division, so eager and graph capture agree bit for bit at every size rather than differing by onefloat32step at 5 of the first 4999. Fixes #3904, #3928, #3929, #4411. (#3945)Align Kimi-VL positional embeddings, rotary embeddings, and projector ordering with Moonshot. (#3968)
build_laplacian_pyramid()now pads mixed image sizes when needed to keep adjacent pyramid levels aligned, while preserving the output shapes of sizes that already worked. (#3971)normal_transform_pixelandnormal_transform_pixel3dnow raiseValueErrorfor an integerdtypeinstead of returning a rank-deficient matrix. The scale2 / (size - 1)truncated to0, sonormal_transform_pixel(4, 5, dtype=torch.int64)returned[[0, 0, -1], [0, 0, -1], [0, 0, 1]]and mapped every pixel to(-1, -1), with no error or warning. Floating point dtypes, including thefloat8formats, and complex dtypes are unaffected. (#3974)Homography normalization now builds matrices with float64-native constants for float64 inputs, preserving full precision (#3958).
normal_transform_pixelandnormal_transform_pixel3dalso keep float64 constants exact under TorchScript, where they were previously rounded through float32. (#3979)rotation_matrix_to_quaternionno longer addsepsinside the square root of the dominant component, which inflated everyfloat64result: the identity used to return[1.0000000012499999, 0, 0, 0]and now returns exactly[1, 0, 0, 0], and the unit-norm error of random rotations drops from about2.5e-9to about7e-16.epsis now only a floor on the radicands of the discarded branches; the selected branch's radicand is at least1for any real 3x3 matrix, so it never reaches the floor.ARKitQTVecs_to_ColmapQTVecsinherits the fix.float32,float16andbfloat16outputs are unchanged. (#3981)RANSAC's local-optimization step now keeps the polished model thatverify()scores best, instead of always taking the first candidate the polisher returns, so the returned model agrees with the returned inliers. Every built-in polisher returns a single candidate, so results are unchanged for them; the fix matters for custompolisher_solvers that return several candidates. (#3991)Slicing or masking list-backed
Boxesnow preserves each batch element's padding metadata, soto_tensor()returns the original number of boxes per element. (#4194)kornia.feature.loftr'sCoarseMatchingno longer crashes in training mode. Its gt-padding branch calledzip()with four separate 2-element lists instead of two 4-element lists, so every resulting tuple failed to unpack (ValueError: too many values to unpack) on every call; no existing test exercised this path. Restructured thezip()to pair each real tensor with its ground-truth counterpart. Once reachable, a second bug surfaced: the padding tensormconf_gtwas built withoutdtype=, defaulting to float32 regardless ofmconf's own dtype (which can be float16/bfloat16 under autocast) and silently promoting the concatenated result. Fixed by buildingmconf_gtinmconf.dtype. (#4359)kornia.enhance.image_histogram2dno longer collapses distinct bins together on afloat16orbfloat16image. The auto-built bin centers were created at the image dtype, which cannot represent the bin indices exactly:bfloat16lost 63 of 256 centers at the defaultn_bins, andfloat16lost 511 of 2048, so those bins came back numerically identical. The centers are now built atfloat32for half-precision images (afloat64image keepsfloat64), and a floating-point image still gets its own dtype back. Integer images and explicitly passedcentersbehave exactly as before. (#4360)kornia.geometry.subpix.render_gaussian2dno longer distorts the rendered Gaussian's peak location on large grids forfloat16andbfloat16inputs. The pixel-coordinate linspace was built at the input dtype, so distinct coordinates collapsed together oncewidth/heightexceeded what the dtype represents exactly: about 2048 forfloat16and about 256 forbfloat16. The coordinate vectors are now built atfloat32for half-precision inputs, and the result is returned in the original dtype. Half-precision outputs of this function change bitwise (in a random-input check against the previous code every grid from 5x7 up differed, and a 1x1 grid did not), so stored regression baselines for half-precision inputs need regenerating. (#4361)PinholeCamera.scale_now promotes an integerheight/widthwith a floating-point scale factor to floating point, matchingscale, instead of raisingRuntimeError. (#4371)Boxes,Boxes3D, theirfrom_tensorhelpers and_transform_boxesnow cast integer input totorch.get_default_dtype()instead of a hardcodedfloat32. Under a caller that setstorch.set_default_dtype(torch.float64)— as NPU and other backends commonly do — the old.float()silently forced every box and transformation matrix down to single precision, losing precision end to end. The mask, shape and transform results now follow the configured default dtype. (#4379)Fixed TorchScript compilation of
unproject_meshgrid,depth_to_3d_v2andwarp_frame_depthby passing a floating-point norm order. (#4389)SVD no longer fails on MPS at 8192 elements or more. torch 2.14's MPS
linalg.svdandlinalg.svdvalsfail to build their Metal pipeline state object once an input holds 8192 elements or more, whatever the per-matrix shape. At realistic batch sizesfind_fundamentalandsolve_pnp_dltraised that "Failed to created pipeline state object" exception;find_homography_dlt(..., solver="svd")instead caught it, emitted a "SVD did not converge" warning, and returned an uninitialized (invalid) tensor. Such inputs are now decomposed on the CPU and moved back.find_essentialstill raises on MPS at any batch size, becauserun_5pointcallstorch.linalg.eigvals, which has no MPS kernel. (#4455)AutoAugment,RandAugmentandTrivialAugmentnow raise aRuntimeErrorfrominversewhen the drawn sub-policy applied a non-geometric operation, instead of silently returning a tensor that still carries it -- for a draw with no geometry at all, the input unchanged. Only geometric operations are invertible, and the sub-policy is redrawn on every forward pass. An operation whose probability gate skipped every sample does not count. (#4456)Add bfloat16 support to mix augmentations and preserve input half-precision dtypes in MixUp and CutMix. (#4471)
Built-in 2D augmentations with lazy transformation matrices retain input metadata instead of the last image batch, preventing unnecessary tensor lifetime extension and image-sized pickle, deepcopy and torch.save payloads. Custom matrix implementations that read pixels retain their existing lazy behavior. Cached metadata remains compatible with non-strict torch.export and ONNX export after an eager forward. (#4484)
RandomCropwithpaddingorpad_if_neededno longer shifts keypoints and bounding boxes by the left/top padding when the crop is skipped; they previously moved while the image and mask stayed unchanged. (#4473) (#4485)transform_pointsreturns an empty result for an empty transform batch whose points carry a non-empty point axis, such as(0, 4, 4)transforms with(0, 5, 3)points. It used to raiseZeroDivisionErrorexpanding the transforms (0 // 0), andPinholeCamera.projectinherited the crash for an empty camera batch on(0, N, 3)points. (#4466) (#4487)Rotate,ShearX,ShearY,TranslateXandTranslateYnow draw negative magnitudes undersymmetric_megnitude, which is their default. The sampled magnitude was multiplied by a boolean mask rather than a sign, so these ops never drew a negative magnitude: rows meant to get-mgot0, a silent no-op on roughly half of their draws. This reaches the five ops used directly andRandAugment.AutoAugmentbuilds them withsymmetric_megnitude=Falseand is unaffected;TrivialAugmentskipped the sign altogether and is covered by #4761 instead (#4441). For a seeded pipeline the random stream, the ops picked and the rows that already drew+mare unchanged; only the rows that drew0now draw-m. (#4440, #4494) (#4495)AugmentationSequentialdispatchesmask, box andkeypointskeys through a mix child's own handlers instead of silently returning them unchanged next to a mixed image. Unsupported keys raiseNotImplementedErroras a direct call does;RandomMosaicboxes are transformed. (#4493) (#4505)RandomCutMixV2now documents itsdata_keysconstructor argument. (#4506)A
resampleentry inAugmentationSequential(extra_args={DataKey.MASK: {...}})now reaches the mask sampler on 2D geometric augmentations that use the base mask path (RandomAffine,RandomRotation,RandomPerspective,Resize, the crops and the rest). It used to be merged and then overwritten with nearest on the forward path, thoughinversealready honoured it. Masks still default to nearest when noresampleis given, including when a user dict leaves it out. (#4419) (#4509)RandomElasticTransformdocumentsalphain the order the code applies it,(x, y); it said(y, x), the orderkernel_sizeandsigmause, so an anisotropicalphawarped the other axis from the one documented. (#4418) (#4510)RandomAutoContrastdocumentsclip_outputas having no effect:normalize_min_maxalready maps each channel onto[0, 1], so the clamp cannot change a value, including for inputs outside that range. It was described as "if true clip output". A constant channel is documented to come back as zeros. (#4436) (#4511)RandomCrop(4)andRandomResizedCrop(4)raise errors that namesize, the(height, width)form it needs and the value passed, instead of anAssertionErrorabout atorch.Tensorshape and a bareTypeError: object of type 'int' has no len(). The exception types are unchanged, and both classes still reject anint. (#4417) (#4512)warp_perspective3dandhomography_warp3dreproduce an identity warp.homography_warp3dhanded the(d, x, y)grid thatcreate_meshgrid3dproduces straight towarp_grid3dandtorch.nn.functional.grid_sample, both of which read the last axis as(x, y, z), so every voxel was sampled from the wrong place: an identity homography on a 4x4x4arangevolume deviated by 45.0 atalign_corners=Trueand 55.125 atFalse, and a +1 translation alongxmoved slices instead of columns. The grid is reordered at that call site;create_meshgrid3d,normalize_pixel_coordinates3dandconv_soft_argmax3dkeep their documented(d, x, y)order andwarp_affine3d, which builds its grid withF.affine_grid, was never affected. Thealign_corners=Falseidentity still deviates after this change; that remaining residual is the 3D normalization convention tracked in #4503. Fixes #4502. (#4514)RandomAffineandRandomPerspectivenow compile on CUDA with CPU-generated geometry parameters, including numeric and CPU tensor constructor ranges, with or without moving the augmentation. Their parameter placement, returned dtype, and RNG consumption are preserved. This compiler workaround covers these two transforms; other augmentations, includingRandomShear,RandomThinPlateSpline,RandomErasing, andCenterCrop, may still encounter the upstream CPU-constant transfer defect.Augmentations and random generators now use standard module migration: dtype-only
.to()calls preserve the sampler device, device-only calls preserve its dtype, and invalid integer-dtype requests raise before changing samplers. Generator.to(),.cuda(),.cpu(),.double(), and parent-module moves now update registered buffers and samplers together. Plain tensor constructor attributes retain their existing placement precedence. (#4517)The unimplemented tuple-bound
Boxes.clamp,Boxes.trim, andBoxes.translate(method="fast")paths now raiseNotImplementedErrorwith actionable messages, including the supported tensor bounds andwarpalternatives where applicable. (#4518)Extend the CUDA
torch.compileconstant-transfer workaround to shear, thin-plate spline, erasing, crop, resize, 3D affine/perspective, and illumination/mix parameter generators. Eager execution,torch.compile, andmake_fxbuild these constants with the same scalar factories, without a host-device copy. Crop operations retain their existing graph breaks.Fix
RandomShearandRandomAffinesampler migration so scalar and tuple shear ranges honor the requested device and dtype; movingRandomAffinewith a scalar or two-elementshearto CUDA used to raise a device-mismatch error. Fix mixed-device sign generation in both linear-illumination generators after moving their samplers.CenterCrop3Dparameters for an empty batch are nowlongtensors on the requested device, matching non-empty batches, instead of CPUfloat32tensors. (#4523)RandomPerspective3D's docstring example printed the output of the 3D sampling-grid defect fixed in #4514, so its values were a permutation of the correct ones. The example now shows what the class returns. Only the docstring changes; no behaviour does. (#4539)Resize(antialias=True)no longer antialiases masks, so their label set is preserved; passantialias=Trueinextra_args[DataKey.MASK](or totransform_masks) to filter soft masks explicitly. (#4540)kornia.morphology.dilation/erosion(andopening,closing,gradient,top_hat,bottom_hat) no longer crash withengine="convolution"when the input tensor's dtype differs from the kernel's dtype; the result now preserves the input tensor's dtype. (#4544)KMeans.fitno longer synchronises with the device once per cluster per iteration to update centroids; the update is now vectorised. This mainly benefits GPU backends where the per-cluster host syncs were expensive (e.g. MPS); on CPU the win is smaller and shrinks further at larger problem sizes, where the O(N·K·D) distance computation dominates. A fit that hits an empty cluster may now produce different (but equally valid) centers for the same seed, since the random reseed draws differ from before. Two more observable side effects of the old in-place update are also gone:fitno longer mutates acluster_centerstensor passed in at construction, and callingfita second time no longer warm-starts from the first call's result - neither was documented behavior, but code relying on either will now see a difference. (#4545)RandomLinearIlluminationandRandomLinearCornerIlluminationbuild theirgradientparameter on the device and dtype their samplers were moved to, matchingRandomGaussianIllumination. Moving either augmentation to CUDA or MPS, or callingset_rng_device_and_dtypeon its generator as the class docstring describes, used to return a CPU tensor of the default dtype, so afloat64pipeline silently gotfloat32parameters and every call copied the gradient across devices. (#4536) (#4546)kornia.losses.total_variationreduces over one flattened dimension instead ofdim=(-2, -1), which returns identical values and avoids a slow reduction path on MPS. (#4547)kornia.color.rgb_to_yuv420subsamples chroma withavg_pool2dinstead of a mean over two unfolded window dimensions: same values, several times faster on CPU and MPS. (#4548)Calling
transform_boxesdirectly on a 2D intensity augmentation returns the boxes unchanged instead of raisingNotImplementedError:IntensityAugmentationBase2Dnow defines its box pass-through handlers under the names the dispatcher calls. (#4549)RandomMosaicplaces bounding boxes on the tile that holds their image on non-square inputs: the x and y tile offsets of the box composition were swapped, which only agreed with the composed image when height equals width. (#4550)SOLD2's line matcher now samples line descriptors at the positions the reference implementation uses.
keypoints_to_gridnormalized keypoints with the corner-aligned mapping and fed them togrid_sample(align_corners=False), so every sample drifted byp / (size - 1)image pixels toward the far edge relative to the grid the pretrained weights were trained with, up to one image pixel and one eighth of a descriptor pixel on a 480x640 image. It now uses the reference formulakeypoints * 2 / img_size - 1, under which image pixelpreads descriptor coordinatep / grid_size - 0.5. Match decisions can change anywhere except at the top-left origin; the shift grows from zero there to one image pixel at the far edge. Fixes #4554. (#4558)rgb_to_hsvand hue-based color augmentation now keep black pixels and their gradients finite in float16. (#4561)Fix float16 NaNs in thin-plate-spline transforms by handling zero kernel distances safely. (#4565)
RandomRainnow drawsnumber_of_drops,drop_heightanddrop_widthuniformly over their closed integer ranges. The upper bound used to be practically unreachable (drop_height=(5, 20)gave 5 to 19) and a signeddrop_widthdrew0twice as often as any other value (#4567). Seeded draws therefore differ from earlier releases, and because the upper bounds are drawn now, an image that only cleared the old effective maximum can raise the documented drop-size check: on the defaults, a 20-row or 5-column image raises on some seeds where it never did before. A range that is reversed, fractional or non-finite is rejected at construction instead of reaching the sampler. (#4568)RandomPlanckianJitternow preserves the input dtype. The illuminant table was moved to the input's device but left atfloat32, so multiplying the red and blue channels by it promoted afloat16orbfloat16input to afloat32output; the table now follows the input's dtype as well.float32andfloat64outputs are bit-identical. Fixes #4574. (#4578)normalizeandnormalize_min_maxnow accept non-contiguous images, including through theNormalizeandRandomAutoContrastaugmentations. (#4580)Fixes
augmentation.Denormalizeso integermeanandstdvalues are accepted alongside floating-point, list, tuple, and tensor statistics. (#4581)RandomClahenow applies each sampled clip limit to its corresponding image in a batch. (#4582)Use safe denominators in
rgb_to_hlsfor achromatic inputs and out-of-range colors with lightness zero or one. For achromatic inputs in every supported float dtype, hue-gradient magnitudes now scale aspi / 3instead ofpi / (3 * eps), reducing them from about1e8to about1with the defaulteps; infloat16they werenan/infand are now finite. (#4583)RandomPlasmaBrightness,RandomPlasmaContrast, andRandomPlasmaShadownow share one sampled map whensame_on_batch=True(#4570). Seeded outputs and the subsequent RNG stream therefore differ from earlier releases for batches with multiple samples;same_on_batch=Falseis unchanged. (#4584)kornia.enhance.equalize_claheandkornia.augmentation.RandomClahenow raise aRuntimeErrornaming the[0, 1]input range for values the 256-bin tile lookup cannot index, instead of a rawindex ... is out of bounds for dimension 5 with size 256from the gather — the same named-range treatmentequalizegot in #4489. The check usestorch._assert_async, so it adds no device sync andtorch.compilefullgraph still works; inputs the lookup can index (including values a hair above 1) are unchanged. (#4585)RectangleEraseGenerator now keeps position sampling in safe floating-point precision and preserves nonnegative erase positions for half and bfloat16 parameters. (#4553) (#4587)
RandomCrop now uses the effective pre-crop canvas for oversized requests. With
RandomCrop((10, 10), padding=1)on a 3-by-3 input, the scale changes from10/3to10/5; the no-padding behavior tracked in #4414 is unchanged. (#4588)RandomBoxBluraccepts the sameborder_typespellings asRandomGaussianBlurandRandomMotionBlur: aBorderType, its integer value or an upper-case name no longer raises, and an unknown name is rejected when the augmentation is constructed.RandomBoxBlur.flags["border_type"]now holds aBorderTyperather than the string that was passed in. (#4591)kornia.filters.kernels.gaussianno longer returns NaN when every sample underflows, which a smallsigma(orsigma = 0) on a short window caused. It returns the unit-impulse limit instead, soRandomGaussianIlluminationproduces a finite image for everysigmaits constructor accepts. Kernels with an odd window are bit-identical to before; an even window can differ in the last bit (half a float32 epsilon at worst over window sizes 1 to 31), because the nearest sample now sits a quarter-pixel away and that subtraction rounds. The impulse limit is differentiable: the gradient with respect to a tensorsigmais 0 there, the value of the continuoussigma -> 0limit, rather than NaN. An empty window still returns an empty kernel. (#4592)draw_linenow always draws both endpoints: it could stop one pixel short ofp2, or pass a row or column off a pixel centre the line runs exactly through, because the minor coordinate was stepped in floating point. It is now placed atceil(t * minor / major)in integers, one pixel per step along the major axis.draw_linealso builds every line's pixels on the image's device instead of in Python loops over 0-d tensors, accepts an empty(0, 2)batch, and rejects ap1andp2of different shapes instead of broadcasting a(2,)point against a(B, 2)batch. (#4596)MKDDescriptor'sExplicitSpacialEncodingcomputes the spatial encoding with one matrix multiply instead of building a(B, in_dims * d_emb, H, W)product and summing it over the spatial dimensions. Descriptor values are unchanged and existing state dicts still load.ExplicitSpacialEncodingnow raisesValueErrorfor an input whose channel count differs fromin_dims, as documented; its shape check could never fire. (#4598)Fixed
RandomDissolvingandStableDiffusionDissolvingdocstring figure tables to render images instead of literal text, and updated the SD XL column to show a pending asset note instead of a mismatched SD 2.1 image. (#4603)RandomChannelDropoutaccepts anintfill_valuesuch as0or1, asRandomErasingdoes forvalue, instead of raisingTypeCheckError. The value is stored as a float buffer, so the output is identical to passing the float. (#4607)kornia.enhance.solarizeacceptsadditionsof exactly-0.5and0.5, the closed rangeRandomSolarizealready admits at construction.RandomSolarize(additions=(-0.5, 0.5))no longer raisesThe addition must be in the open range (-0.5, 0.5)on the forward pass when it draws an endpoint, or on every call for an endpoint-only range. (#4608)RandomMotionBlurnow draws every odd size in akernel_sizerange with equal probability, the upper bound included. Previously the upper bound was practically never drawn (only when a float32 draw rounded onto it), sokernel_size=(3, 5)practically always blurred with3and(3, 7)drew practically only3and5. An even upper bound caps at the largest odd size below it, and a range holding no odd size still rounds up, so(4, 4)draws5as before. Because the larger sizes are now drawn,kernel_size=(3, 5)withborder_type="reflect"on a2 x 2image raises for roughly half the draws, where the constant3always fit. A two-element list such askernel_size=[3, 9]is now accepted as a range, like a tuple, instead of raisingTypeError. (#4610)equalize_clahe, and soRandomClahe, builds every tile histogram with onescatter_add_instead of onetorch.histccall per tile, which is 192 kernel launches for a 256x256 RGB image on the default 8x8 grid. The histograms and the output are bit-identical to before on CPU. On MPS the tile histogram now matches the CPU one for inputs marginally outside[0, 1](for example1.0000001or-1e-7), whichtorch.histcon MPS counted and the CPU kernel skips. (#4611)RandomRainnow places drops uniformly over every start position that keeps the drop inside the image, so the last row and column can be painted. (#4612)axis_angle_to_rotation_matrixreturns finite gradients near the identity infloat16; the discarded Rodrigues branch no longer differentiatessqrt(0)behind a1e-12floor that underflows to zero. (#4613)LoFTRfine matching returns finite gradients throughexpec_finfloat16on torch older than 2.14. The1e-10floor undersqrtunderflows to zero infloat16, so a peaked heatmap -- what a confident match produces, not a degenerate corner -- sentsqrt'(0) = infback into the features; sincestdis summed into the loss, one such match is enough to make the whole gradientnan. (#4614)in_range,normalize_min_max,posterize,sharpness,equalize,equalize_clahe,jpeg_codec_differentiableandequalize3dnow accept non-contiguous inputs of more than 4 (resp. 5) dimensions instead of raising a rawview size is not compatibleerror. (#4615)Fixed the mixed-precision (
autocast) guard inkornia.feature.lightglueto resolve the accelerator type from the input tensor instead of a hardcoded"cuda". This makesLightGlue/LighterGlueusable under autocast on any accelerator (Ascend NPU, XPU, MPS) and on CPU-only builds wheretorch.accelerator.current_accelerator()returnsNone. (#4624) (#4624)Fixed non-finite gradients in
rotation_matrix_to_quaternionandrotation_matrix_to_axis_anglenear singular points (identity and 180° rotations) acrossfloat16,bfloat16, andfloat32by applying safe square-root gradient substitution matching #4613. Fixednormalize_quaterniongradient NaN leakage for exact zero-norm inputs andeps=0.0(note: subnormal-but-nonzero norms infloat16remain out-of-scope pre-existing behavior). (#4627)equalize_claheandRandomClaheaccept agrid_sizewhose two entries differ. Such a grid used to raiseIndexError: shape mismatch: indexing tensors could not be broadcast togetheron every image (#2531). Output for square grids is unchanged. (#4628)Fix
equalize_clahetranspose equivariance in the slow differentiable path when histogram clipping is enabled. The fast histogram path preserves its existing redistribution behavior, including for marginally out-of-range input values. (#4637)Setup documentation (
CONTRIBUTING.md,README.md,README_zh-CN.md,AGENTS.md,docs/export_support/README.md) now qualifies the ambiguous Pixi tasks with-e default, sopixi run install,pixi run install-docsandpixi run build-docswork as documented instead of stopping with a "task is ambiguous" error or an environment picker. (#4639)Speed up large float32/float64 CPU Gaussian blurs and scale pyramids on builds without oneDNN while preserving tensor sigma gradients and existing autocast/export behavior. (#4641)
equalize_clahe(..., slow_and_differentiable=True)no longer raisesIndexErrorforgrid_size=(1, 1), which is global histogram equalization with the clip limit applied. Grids with more than one tile are unchanged. (#4642)RandomBoxBlur,RandomGaussianBlurandRandomSharpnessnow raise aValueErrornaming the class, the kernel, the border type and the input shape when the image is too small for the filter, instead of letting a raw torch padding error out. The sizes they accept are unchanged: the minimum is derived from the wider offilter2d's two pads, which for an even kernel extent is the rear one, soRandomBoxBlur((4, 4), border_type="reflect")reports the 3 pixels it needs rather than 2. (#4645)Speed up median blur inference for 3×3 and 5×5 kernels using selection networks on CPU, and on CUDA for 3×3 kernels or under
torch.compile. Speed up CPU float32/float64 Laplacian filtering using separable neighborhood sums (with oneDNN, below 2^22 input elements), also on CUDA undertorch.compile. Preserve median gradient tie behavior with the original autograd path. Replace dense and separable box convolutions with average pooling for floating-point inputs outside autocast, except where oneDNN's CPU convolution is faster: eager inputs below 2^22 elements, larger windows, and compiled windows wider than 5 (separable) or 3 (dense). Construct fixed first-order Sobel kernels directly without transposing, stacking, or normalizing them. Benchmark timing now honors the configured PyTorch thread count, and the filters flagship warms the CPU thread pool with sustained load so hybrid CPUs are measured on their performance cores. Use the large-image Gaussian slice shortcut in eager mode on CPUs with oneDNN, undertorch.compileon CPUs without oneDNN, and undertorch.compileon CUDA. Avoid padded-image copies for odd constant-border box windows, and redundant identity passes for one-dimensional box windows. Reuse Gaussian CPU accumulation buffers during eager execution (also accelerating unsharp masking), keep bilateral patch axes as views to avoid materialized patch copies, fuse guided-filter multiply/add operations, and vectorize 2D motion-kernel construction. Ordinary eager CPU box/Laplacian filtering uses a range check and convolution fallback for extreme values, preserving the optimized path for practical image ranges; captured graphs and function transforms keep their native arithmetic. (#4647)Augmentation classes no longer exhaust a shared
torch.compilecache. CompiledRandomResizedCropandRandomCropslice modes keep sampled crop coordinates in tensors, avoiding recompilation as crop boxes change while preserving interpolation and input gradients. Nearest-neighbor upsampling accumulates half-precision input gradients in float32 to avoid saturation. CompiledRandomClahealso keeps per-image clip limits in tensors so varying sampled limits reuse the graph.RandomClahebatches clip limits in eager execution as well. Compiled crop interpolation matches eager to floating-point tolerance rather than bitwise. Avoiding recompilation does not guarantee faster steady-state execution: compiled CPURandomCropcan remain slower than eager or the previous post-fallback path. (#4659)RandomMixUpV2 and RandomCutMixV2 preserve class-label precision when the input image uses float16 or bfloat16. (#4661)
Fix
RandomMotionBlur3Dranged kernel sizes for batched inputs. (#4662)equalize,equalize_clahe,RandomEqualizeandRandomClahenow raise the sameRuntimeErrornaming the[0, 1]input range on MPS as on the CPU, instead of torch's rawgather: index ... is out of boundserror. On MPS the check is the same asynchronoustorch._assert_asyncfrom torch 2.13; older releases have no MPS kernel for it, so there the condition is read on the host at one device sync per call and is skipped undertorch.compile. (#4663)AugmentationSequentialreturns each mask in the dtype of its own argument. It used to cast every mask output to the dtype of the last mask argument, so an integer semantic mask followed by a boolean one came back boolean and lost its labels. An empty batch with a mask no longer raisesIndexError, and a mask placed before the image in dictionary insertion order is now converted with that call's image dtype instead of the previous call's, so a float64 mask keeps its precision. The same holds undertorch.export, which used to convert masks throughfloat32or a dtype left behind by an earlier eager call and bake the rounding into the exported graph. (#4665)RandomCrop3Dnow preserves the input when the transformation is skipped, including whenpaddingorpad_if_neededis enabled. (#4667)solve_quarticno longer returns values that do not satisfy the quartic it was given. When the resolvent cubic has a near-double root,solve_cubiccan lose it, and Ferrari then factored a different polynomial and reported its roots:(x^2 + 2x + 5)(x^2 + 2x + 5.01), which has no real roots, came back as[1.0012, -3.0012, 1.0012, -3.0012]with a residual of 64. Each candidate is now Newton-polished and checked against the quartic with asqrt(eps) / 4tolerance for its dtype. A zero that stood for a complex pair is polished too, but kept only where Newton converged at a simple root, and a root reached by two candidates is reported once, from Ferrari's own candidate. Over 50k-row families built from known roots, rows returning a non-root on the near-square family fall from 23,488 to 0 in float32 and from 10,727 to 0 in float64, no family gains a row with a value off its root, and the small root of a mixed-scale quartic thatmainmisses is recovered (rows missing a root fall from 18,495 to 1,851 in float32). The residual is measured against the size of the quartic's terms with a floor of 1, as elsewhere insolve_quartic, so the check does not reach a quartic whose roots are all small: the near-square family scaled to roots of about 0.04 still returns non-roots in float32, and scaled to about 0.004 in float64. Affects float64 as well as float32. Fixes #4474. (#4669)RandomMotionBlur3Dkeeps a tuplekernel_sizeinside the range it was given. An even upper bound used to admit the odd size above it -- the+ 1was taken offkernel_size[1] // 2rather than off the largest odd size in the range -- so(3, 4)drew5and(3, 20)drew21. The upper bound is now the largest odd size not abovekernel_size[1]. Afloat32draw landing on the sampler's open upper end is clamped back onto the range, where(3, 5)could otherwise draw7. A reversed range such as(20, 3)now raises aValueErrorat construction; it used to be accepted and drew a constant9, outside both of its own bounds. A range holding no odd size still rounds up out of the range, so(4, 4)draws5as before, matching the 2D generator. (#4674) (#4674)RandomRainnow rasterises every drop of every sample in a single indexed write instead of oneindex_put_per step of each drop per sample, removing the per-sample host-to-device copies and.item()syncs as well. Output is unchanged: verified bit-identical (torch.equal) against the previous implementation over 12,482 configurations across four device/dtype combinations (cpu float32 and float64, mps float32 and float16). On MPS at batch 32 (128 x 128) this is 45.0 ms to 5.1 ms, and at batch 8 (256 x 256) 12.0 ms to 3.6 ms; CPU is faster at every shape measured. Fixes #4530. (#4675)Mix augmentations now reject unsupported data keys even when no samples are selected. RandomJigsaw validates that image dimensions are divisible by its grid regardless of the probability gate. (#4676)
Fix RandAugment posterize and translation magnitudes. Posterize now uses the 4–8 bit range, preventing low magnitudes from producing black images, and translation magnitudes are converted from image-relative fractions to pixel values before being applied. (#4677)
OperationBasecan now be deep-copied after augmentation operations have been used without retaining stale probability sampler state. (#4678)RandomMosaicnow respectsoutput_sizewhen transforming bounding boxes and no longer crashes withcropping_mode="resample"whenoutput_size=None. With an explicitoutput_size, both cropping modes now take an unscaledoutput_sizewindow of the composed canvas, so the boxes stay on their tiles; before,"slice"rescaled an input-sized crop whenever every sample drew the same corner and zero-padded it otherwise. When the gate selects only part of the batch, an unselected sample's boxes are now returned unchanged; before, they were clipped to the input extent and a box belowmin_bbox_sizewas replaced by[0, 0, 1, 1]. For a tensor box input the unselected row is still padded to the mosaic box count, now with all-zero (zero-area) rows instead of the[0, 0, 1, 1]placeholder that looked like a real box (insideAugmentationSequential,"bbox_xyxy"padding was already all-zero). A list box input still comes back as a list with one tensor per sample, and an unselected sample's tensor now holds only its own boxes instead of being padded with placeholder rows. Fixes #4652. (#4679)PatchMixrejects apatch_sizelarger than the input instead of drawing negative corners. The corner range washeight - patch_sizewith nothing checking that the patch fits, so a larger patch made it negative and the negative slice that followed copied an arbitrary rectangle: the defaultpatch_size=16on an 8x10 input changed a 7x5 region, andpatch_size=9changed a non-square 8x9 one, neither raising.same_on_batch=Truealso returned its input unchanged, because the pairing is an argsort of drawn values and sharing that draw made every value equal, so the permutation was the identity and each image was patched with itself. The pairing draw is no longer shared; the patch location still is. (#4680)kornia.enhance.normalizeand theNormalizeaugmentation now preserve empty batches instead of raising a reshape error forB=0. Existingmeanandstdvalidation remains unchanged. (#4681)kornia.geometry.cart2polnow returns the exact Euclidean radius without perturbing the forward value, while keeping the gradient finite at the origin. (#4682)Fix double application of probability
pinRandomMixUpV2andRandomCutMixV2. (#4685)RandomMotionBlurnow draws a ranged kernel size once per call and repeats it acrossksize_factor, so the stored sizes match the shared size applied to the batch. Previously it drew a size per sample and used only one randomly selected entry. Angle and direction still followsame_on_batch. Fixed integer kernel sizes and replay of previously saved parameters are unchanged; seeded ranged calls withsame_on_batch=Falsecan produce different sizes and advance the random generator differently. (#4687)RandomCrop3Dno longer accepts a crop exactly one voxel larger than the (padded) input along an axis. It used to pass the size guard, crop past the edge and return a volume with an empty slab; it now raises the sameValueErrorthat a larger crop already did.RandomCropandRandomCrop3Dalso honour afillsequence holding one value per channel, which both have always documented but which raisedTypeError: pad(): argument 'value' must be float, not tuple; a sequence must match the channel count and requirespadding_mode="constant". InAugmentationSequential, a per-channel image fill defaults mask padding to zero unlessextra_args[DataKey.MASK]["fill"]overrides it, so masks with a different channel count remain supported. (#4691)RandomTransplantationno longer misaligns donor labels when one donor's labels are all excluded. The label list was built only for donors that had an eligible label and then zipped positionally against the donors, so a single fully excluded donor shifted every later label onto the wrong donor and dropped the last acceptor — at a batch size of two the whole call became a silent no-op, and at three an acceptor could receive the region chosen for a different donor. An acceptor whose donor has no eligible label is now dropped fromacceptor_indicesanddonor_indicesand itsbatch_probentry is cleared, so the remaining labels stay aligned with their own donors for every mask dtype, and an emptyselected_labelsfollows the mask's dtype and device instead of defaulting to float32 on CPU. Labels are no longer drawn, and the RNG no longer consumed, when the caller supplies aselection. The length-check message no longer reads "than images torch.where this augmentation should be applied". (#4695)AugmentationSequentialnow rejects 4D image batches when used with a 3D augmentation instead of silently treating the batch as a single 3D sample. (#4697)Fixed
AugmentationSequential.inverse()silently ignoring unsupported mix augmentations. (#4698)RandomJigsaw(ensure_perm=True)now rejects the permutation that reproduces the image. It used to reject[0, ..., N - 1], which is the no-op only for a single-row or single-column grid: on a2 x 2grid it is a transpose of the patch grid, while the no-op[0, 2, 1, 3]was still drawn, so about 1 call in 23 returned its input unchanged. The rejected permutation is nowarange(N).view(rows, columns).T.flatten(). A1 x 1grid withensure_perm=True, which used to hang in the rejection loop, now raisesValueErrorin the constructor. Fixes #4703. (#4708)ColorJiggleandadjust_saturationnow avoid a redundant RGB-to-HSV round trip in float32 and float64, improving eager and compiled performance. At tied RGB extrema, the direct formula uses PyTorch's symmetric max/min subgradient instead of the arbitrary first-channel subgradient from the HSV branch. (#4717)adjust_brightness,adjust_contrast,adjust_saturation,adjust_hueand their variants now raiseValueErrorfor afactorwith more dimensions than the image, instead of hanging forever (#4718). (#4720)RandomCutMixV2now draws the cut placement per row and mix whensame_on_batch=False; one uniform draw per axis used to place every cut of the batch, so all cuts sat at the same relative position. The random stream for a fixed seed changes whenB * num_mix > 1. (#4721)ColorJiggle(order=...)no longer turns offtorch.distributionsargument validation for the rest of the process. Its eagertorch.conddispatch entered Dynamo, whose one-time setup disables that validation globally; the caller's setting is now restored. A fixedorderalso no longer raisestorch.cond requires dynamo supportwhere Dynamo is unavailable (torch 2.5.1 on Python 3.13); it uses the Python dispatch there. (#4725)RandomMixUpV2andRandomCutMixV2now replay aforward_parameters()dictionary with the"class"key; the image dtype that the label handlers need is taken from the input, instead of raisingKeyError: 'dtype'. A replayed dictionary with an unsupported image dtype still raisesTypeError. (#4726)RandomAffine3DandAffineGenerator3Dnow draw a two-valuescale=(a, b)once per sample and apply it to all three axes, as the docstring says and as the 2DRandomAffinedoes; each axis used to be drawn independently. The three-pair form((a, b), (c, d), (e, f))is unchanged. The random stream for a fixed seed changes for the two-value form: the scale consumes one draw instead of three, so the translations and shears drawn after it move. (#4731)CenterCrop3DandRandomCrop3Dnow accept a crop with a size-1 axis. The crop matrix is built as the translation it is, instead of being solved from the box vertices, which raised_LinAlgErrorbecause those vertices are coplanar. (#4732)kornia.geometryno longer re-exportssys,struct,array,os,BinaryIO,Dict,List,NamedTupleandis_compilingfrom itspointcloudandgridsubmodules, which now declare__all__. (#4738)AugmentationSequential.inversenow inverts a list-valuedmaskelement by element, reusing each entry's forward gate, instead of raisingAttributeError: 'list' object has no attribute 'dtype'. (#4739)RandomTransplantationandRandomTransplantation3Daccept a(B, 1, *spatial)mask next to an image of the same rank and read it as the(B, *spatial)mask, soRandomTransplantationno longer raises insideAugmentationSequentialwhen another augmentation runs before it. (#4740)crop_by_indices,RandomCropandRandomResizedCropreturn an empty batch for an empty batch instead of raisingIndexError: list index out of range. (#4741)Corrected the
kornia.morphologydocstrings:origindefaults to[k_h // 2, k_w // 2]rather than "the center ... (rounding towards zero)", theReturnssection ofbottom_hatnames the bottom hat rather than the top hat, and the kernel shape is(k_h, k_w)over the image's(H, W)axes rather than(k_x, k_y). (#4743)CenterCrop,RandomCrop,center_cropandCenterCrop2Dnow accept a crop with a size-1 axis. The crop matrix is built as the translation it is, instead of being solved from the box vertices, which returned a matrix ofNaNbecause those vertices are collinear. For every other crop the matrix is now the exact translation rather than the solver's approximation of it, sotransform_matrix, transformed boxes and keypoints, and resampled pixels can differ from before in the last bits in float32, and by more in bfloat16, where the solve was inexact for coordinates above 256. (#4753)draw_point2daccepts a single[x, y]vector and an empty(0, 2)point set instead of raisingTypeError/ValueError. (#4754)RandomCutMixV2now draws each cut start uniformly over every legal position,0toside - cut_sideon each axis. Previously the draw stopped short of the far edge: with the default float32 parameters a cut smaller than the image never reached its last row or column, and a full-image cut (cut_size=(0.0, 0.0)) practically always started one pixel before the image, so the last row and column kept their original pixels while lambda reported a full-image cut. The random stream for a fixed seed changes: cut sizes, lambdas andmix_pairsare unchanged, but the cut positions differ from earlier releases. (#4757)dilation,erosion,opening,closing,gradient,top_hatandbottom_hatnow ignoreborder_valueunderborder_typereflect,replicateandcircular, as documented, instead of raisingRuntimeError: Padding mode "reflect" doesn't take in value argumentfor any value other than0.0. (#4758)dilation, erosion and the operations built on them (opening, closing, gradient, top_hat, bottom_hat) update the shift engine's running maximum/minimum in place when the call records no gradient, instead of allocating a new output-sized tensor at every kernel position. This is about 1.1-1.5x faster on CPU for a batch of eight 256 x 256 images, about neutral for a single small image, and unchanged on MPS; outputs are identical. Calls that record a backward graph, carry a forward-mode AD tangent on the image or the structuring element, run under torch.func transforms, or are traced or scripted keep the out-of-place reduction. (#4759)
find_essentialandrun_5pointno longer abort withtorch._C._LinAlgErrorwhen a correspondence set makes the 10x10 elimination matrix exactly singular, as a set of points all at the origin does. Such a sample has no solution and now returnsNaNfor all 10 candidates, like any other sample without candidates. Whether another degenerate set is exactly singular depends on the platform's LAPACK. Every other sample goes through the same solve as before and its result is unchanged bit for bit, including when a singular sample shares its batch, so a singular minimal sample insideRANSAC(model_type="essential")is dropped like any other sample without candidates instead of raising out offorward. Fixes #4765. (#4766)Fix augmentation API documentation examples for AutoAugment, RandAugment, and TrivialAugment, and correct the ManyToManyAugmentationDispather name in the augmentation container metadata. (#4769)
The conventions pages are trimmed to kornia scope: the augmentation, randomness and serialization sections are condensed with every tracked defect link kept,
RandomEqualizeandRandomClaheare documented as raising out of range on every device, the ARCore camera frame is merged into the OpenGL row whosecamtoworld_graphics_to_vision_*converters apply to it, and the Direct3D row and the upstream-quote appendix are removed. (#4786)geometry.transformdocstrings: removed the falsecrop_by_boxesnote claiming a source box smaller than the destination box raises, and documented three known defects with their issues:homography_warp(normalized_homography=False)ignoresmodeandalign_corners(#4772),remapresamples under an identity pixel map at its defaultalign_corners(#4504), andwarp_perspectiveandwarp_perspective3dwarp afloat64input through afloat32grid (#4776). (#4788)The
kornia.morphologydocstrings are trimmed to what a caller needs:dilationcarries the one convention block and lists the known defects (#4734, #4735, #4762) in one place, the other six functions refer to it, and an out-of-rangereflectorcircularpad is documented as raising an error rather than aRuntimeError, since that error comes from torch. The morphology table on the Conventions & Pitfalls page now holds the scipy, scikit-image and OpenCV mapping, including the kornia calls equal to their dilation, erosion, opening and closing and thereplicate->nearestandcircular->wrapborder names. (#4789)solve_pnp_dlt's point-count, dtype andsvd_epschecks now name the offending argument (for example "world_points must hold at least 6 points (N >= 6), got N = 5.") instead of a bare "Validation condition failed". The convention blocks ofkornia.geometry.bbox,kornia.geometry.boxes,kornia.geometry.depth,kornia.geometry.camera,kornia.geometry.calibrationandkornia.sensors.cameraare trimmed to kornia's own contract, with the pixel-centre convention stated once onPinholeCamera, and atorch.where:typo for "where:" is fixed in the docstrings ofharris_response,gftt_response,hessian_response,BinaryFocalLossWithLogits,ssim3d,SSIM3D,solve_pnp_dltandhomography_i_H_ref. (#4790)The
kornia.augmentationConvention blocks outside the 2D intensity classes are shorter and state each rule once.RandomEqualize3Dnow documents its out-of-range check as raising on every backend; the old text said MPS skipped it. Each known defect is stated with its tracking issue, including the new #4775, #4776, #4777, #4787, #4801, #4802, #4804, #4805, #4809 and #4815. (#4791)kornia.geometry.conversionsdocstrings no longer claim that the deprecated aliases break-W error::DeprecationWarning(fixed in #3956), state the float64 axis-angle round-trip accuracy correctly (roundoff, about2e-10on the low-angle branch), and document a defect:Rt_to_matrix4x4andcamtoworld_to_worldtocam_Rthandle anR/tbatch-size mismatch differently (#4774). (#4792)Corrected the 2D intensity augmentation docstrings and the
kornia.enhanceAdjustHue,AdjustContrastWithMeanSubtraction,AdjustSaturationWithGraySubtractionandAdjustBrightnessAccumulativesummaries:RandomBrightness,RandomContrastandRandomSaturationno longer claim to match PIL and torchvision (their formulas differ, andColorJitteris the class whose steps use torchvision's),RandomHue,RandomGammaand theenhancemodules state the mapping they do share with torchvision, the stale MPS and raw-error notes onRandomEqualizeandRandomClaheare gone, and the convention blocks are trimmed to kornia's own behaviour. Newly found defects are linked as known issues: #4781, #4782, #4783, #4784, #4785, #4807, #4810, #4811 and #4813. (#4793)find_homography_dltno longer hangs on CUDA when a four-point sample contains NaN or infinite values: the minimal LU path keeps non-finite entries out oftorch.linalg.qrand returns a NaN homography for the affected batch elements, as on CPU. (#4794)warp_perspective,warp_perspective3dandhomography_warp3dbuild their sampling grid in the input dtype instead offloat32. Afloat64identity warp, includingRandomPerspectiveandRandomPerspective3Dwithdistortion_scale=0, now reproduces its input tofloat64roundoff, aswarp_affinedoes.float32and half-precision grids are unchanged at the defaultfloat32default dtype; undertorch.set_default_dtype(torch.float64)they are no longer built infloat64and rounded, so they now match the result at the default. (#4795)The Conventions page and the
remapdocstring now link tokornia.geometry.grid.create_meshgridinstead of rendering its name as plain text. (#4797)solve_quarticnow takes its cubic fallback forfloat16andbfloat16inputs whose leading coefficient is below1e-6in magnitude, the tolerancefloat32uses, since half-precision quartics are solved infloat32.float16used to round the fallback tolerance to 0: a zero leading coefficient returned NaN and one below1e-6returned an infinite fourth root.bfloat16lost every root ofx^3 - 6x^2 + 11x - 6behind a leading coefficient of1e-9. Fixes #4498. (#4822)kornia.augmentation.__all__now listsRandomClaheandRandomJPEG, sofrom kornia.augmentation import *includes them. Both classes were importable by name before but had never been in__all__. (#4825)Clarify that
draw_point2danddraw_linemodify the input image in place and return it for convenience. (#4826)ColorJitterskips a step whose factors are all neutral again, as it did before v0.9.0rc1, instead of computing every step and discarding the neutral ones:ColorJitter(brightness=0.2)accepts one- and four-channel images again, and an eager call no longer pays for the neutral colour-space round trips. Outputs for inputs that were accepted before are unchanged (#4813). (#4828)depth_from_plane_equationfloors a positiveepsat float16's smallest subnormal,2**-24. The defaulteps=1e-8rounded to zero in float16, so a ray parallel to the plane returnedinf, ornanfor a plane through the camera centre; it now returnsd / 2**-24, which float16 can represent only for|d|below about3.9e-3. Larger offsets still returninfin float16 unless a largerepsis passed. (#4830)crop_by_boxesandcrop_and_resizenow accept a box with a size-1 axis. Its vertices are collinear, so solving the perspective system from them returned a matrix ofNaN; such a box now gets the matrix built from the box extents, with a plain translation on the size-1 axis. Boxes the solve already handled keep the same matrix. Resizing a size-1 axis to a larger size, or a larger axis down to size 1, still returnsNaN(zeros withmode="nearest"), because no invertible matrix maps one onto the other. (#4834)solve_cubicnow returns the real root of a cubic whose depressed form ist^3 = 2RwithR < 0(for examplex^3 + 1) instead of NaN.solve_quarticinherited the NaN through its cubic fallback and through its resolvent cubic:x^4 - 3x^2 - 0.75returned four NaNs instead of its real roots±1.798. The gradient of thatQ == 0root also used to drop the root's dependence onQ, so forx^3 - 1the derivative with respect to the linear coefficient was 0 instead of -1/3; it now matches the implicit derivative. (#4832) (#4837)PlanckianJitterGenerator keeps its index sampler in float32 when the augmentation is moved to float16 or bfloat16, so the sampled Planckian table index cannot go one past the end. On MPS, half-precision
torch.randreturns exactly 1.0 for about 1 in 4096 (float16) or 1 in 512 (bfloat16) draws, which madeRandomPlanckianJitterraise an out-of-bounds index error. float32 and float64 draws are unchanged; for the same seed, float16 and bfloat16 pipelines now draw some different indices than before. (#4553) (#4839)confusion_matrixandmean_ioureturn an empty(0, K, K)/(0, K)result for a zero-length batch instead of raisingRuntimeErroronview(0, -1). (#4845)find_essentialandrun_5pointno longer abort when a degenerate sample makes the companion matrix of the 5-point solver non-finite. That happens at float32 when the elimination system is ill-conditioned without being exactly singular and its solution overflows the determinant polynomial, or when a finite polynomial overflows on division by its leading coefficient.torch.linalg.eigvalsrejected that matrix for the whole batch: with aRuntimeErroron macOS, and by crashing the process inside MKL on Linux x86. Such a sample has no usable roots and now returnsNaNfor all 10 candidates, like a singular one. Every other sample is unchanged bit for bit, including one that shares its batch. Which inputs reach this path depends on the platform's LAPACK. (#4846)ColorJitter,RandomGaussianBlurandRandomGaussianIlluminationnow pickle and pass throughtorch.saveafter their owncompile(). Unpickling compiles the restored module again with the same arguments. (#4849) (#4849)draw_lineaccepts a 0-d scalar color for single-channel images instead of raisingIndexErroroncolor.size(0). (#4850)RandomResizedCrop(resample="nearest")no longer raises in the default slice mode. Slice mode now ignoresalign_cornersfor nearest resampling, for images and masks. (#4852) (#4852)pixi run -e cuda installnow installs the CUDA 12.1 PyTorch build into the project.venvthat the test tasks use, and CUDA tasks no longer re-sync it back to the locked PyTorch. The task used to pass the CUDA index by name, which uv does not resolve, so it installed PyPI's default build into Pixi's.pixi/envs/cudaand left.venvon the locked build. (#4858)AugmentationSequentialnow normalizes a string or intresampleinextra_argsas the augmentation constructors do. It used to raiseAttributeErrorwherever the mask was resampled. (#4859) (#4859)find_essentialandrun_5pointnow return correct input gradients for fewer than 9 points. The solver's null space comes from right singular vectors thattorch.linalg.svdgives no gradient to when there are fewer than 9 points, so the gradient to the correspondences was dropped: exactly zero for the 5-point minimal sample, and wrong for 6 to 8 points. The null space is now differentiated as a subspace, and the gradients agree with finite differences. The forward result is unchanged, and so are the gradients for 9 points or more. (#4860)warp_frame_depthnow raises whenimage_srcanddepth_dsthave different heights or widths, instead of resampling the whole image onto the depth grid. (#4861)draw_convex_polygonreturns the input image unchanged for an empty(B, 0, 2)polygon batch instead of raisingIndexErrorwhen closing the polygon loop. (#4895)Boxes.from_tensoraccepts nested numeric lists shaped like(N, 4)and an empty Python list instead of raisingAttributeError/ValueError. (#4896)solve_cubicno longer returns NaN forfloat16cubics whoseQ^3underflows to 0 whileRis 0, such asx^3 - 0.003xorx^3 + 0.003x. Half-precision cubics are now solved infloat32and the roots are cast back to the input dtype, assolve_quarticalready did for its Ferrari path. This also fixes thebfloat16reference quartic that went through the cubic fallback. (#4856) (#4898)KRt_from_projectionreturns a proper rotation and the sameK,R,tfor every nonzero scale ofP, including-Pand aPscaled below the oldeps, which is now unused (#4864).triangulate_pointsreturns NaN for a correspondence at infinity instead of a finite point at a roundoff-set distance (#4865);solver="cofactor"normalises in the compute dtype, so pixel-scale float16 input is finite (#4863), and returns thesvdpoint instead of averaging two normalised sub-system null vectors: it refines the longest of the four through the adjugate of the DLT matrix. The average was up to 3.5 units off on a noise-free rectified pair and 144 on a pair rolled by 90 degrees, 3 to 6 units off on every point of a rectified, vertical or rolled pair with 0.5 px of noise (0.1 forsvd), and a roundoff direction for zero baseline, which now gives NaN (#4900). (#4901)RANSAC(score_type="msac")accepts models again. Acceptance and confidence stopping treated the MSAC score as an inlier count, and a hypothesis was kept only when that score exceeded the minimal sample size. The old score subtracted the truncated squared residuals fromN, so with a 2-pixel threshold it usually fell below that cutoff and the estimator returned the all-zero failure matrix: eight-point fundamental estimation on 60 IMC phototourism pairs failed for 87% of SIFT and all XFeat pairs. With thresholds below 1 the score could instead exceed the inlier count and stop sampling too early. The score is nowsum(1 - min(e / inl_th**2, 1)), accumulated in at least float32, and the inlier count is tracked separately for acceptance and stopping, so those pairs no longer fail. Early stopping is checked after every batch, using the current best model's support after local optimization. Zero and nonfinite candidate matrices are rejected, since a zero fundamental matrix has zero Sampson error for every match. A model needs more inliers than its minimal sample for every score, so five-point essential estimates with six or seven inliers, fewer than the eight-point polisher needs, are kept. Local optimization keeps a full-inlier refit that ties the score instead of discarding it, so RANSAC scoring no longer returns the less precise minimal-sample model when support does not grow. The essential-matrix mask is recomputed after projection onto the essential manifold, and a projected model left with five inliers or fewer is reported as the failure result. (#4902)enhance.equalize_claheandaugmentation.RandomClahenow raise kornia'sValueErrorwhen either image axis is not larger than itsgrid_sizeentry, and the message names the smallest image the grid admits. An image exactly as large as the grid, such as8 x 8at the defaultgrid_size=(8, 8), previously passed the size check and failed inside the reflect padding with torch's rawRuntimeError. Closes #4783. (#4907)draw_convex_polygonnow draws a one-vertex polygon as that point, leaves the image of an empty polygon in a list unchanged, and accepts an empty list with a zero-batch image, instead of raising PyTorch errors. The edge slope no longer divides bydy + 1e-12: in float16 that epsilon underflowed and left the scanline through a repeated vertex (including the padding of a shorter polygon in a list) unfilled, and in float64 it dropped pixels whose centre lies exactly on a sloped edge. (#4909)draw_point2d,draw_rectangleanddraw_convex_polygonnow accept a 0-d color such astorch.tensor(9.0), likedraw_line, instead of raisingIndexErrororValueError. (#4910)solve_quadratic,solve_cubicandsolve_quarticnow solve a polynomial with a zero leading coefficient as the lower-degree polynomial it is. Before,solve_quadraticreturnednan/inffor a linear equation,solve_cubicreturned1.0for every linear equation and zeros forbx² + d, andsolve_quarticinherited both. (#4873) (#4913)decompose_essential_matrix_no_svdnow returns rotations for every element of a batch. It used to divide each rotation byb · bsummed over the whole batch, so each rotation of a batch of two or more came back scaled by its matrix's share of the batch's squared Frobenius norm: by1 / Bwhen allBmatrices have the same norm, such as the unit-norm candidates offind_essential. A batch of one is unchanged bit for bit. (#4915) (#4915)AugmentationSequential.show()and.save()now work after a forward call that returns tensors (the defaultoutput_type="pt"). The container cached the raw forward output, so.show()raisedRuntimeError: Can't call numpy() on Tensor that requires gradfor an input that requires gradients, aTypeErrorfor a CUDA or MPS one, andAttributeError: 'list' object has no attribute 'shape'for a call with several data keys. It now caches a detached view of the augmented image alone, which no longer holds the autograd graph, and.show()/.save()move it to the CPU when they render it, so the forward pass still makes no device-to-host copy. A call whose data keys carry no image caches nothing, andImageModule.save()reports an empty cache with the sameValueErroras.show()instead ofAttributeError: 'NoneType' object has no attribute 'shape'. Closes #4835. (#4918)solve_quadraticno longer loses the root of smaller magnitude to cancellation when|4ac|is much smaller thanb^2: it usesq = -(b + sign(b) sqrt(D)) / 2and returnsc / qandq / ain the previous slot order.[1e-8, 2, -6]gave[0, -2e8]in float32 and now gives[3, -2e8], and the root's gradient is correct too. (#4919)solve_quarticdecides whether a row is really a cubic relative to the row's scale: the leading-coefficient tolerance for the cubic fallback (1e-6, or1e-12in float64) is multiplied by the largest coefficient magnitude of the row, capped at 1.(x - 1)(x - 2)(x - 3)(x - 4)scaled by5e-7in float32 (or1e-13in float64) now returns1, 2, 3, 4instead of a single wrong root. Rows whose largest coefficient is 1 or more keep the previous absolute tolerance. (#4905) (#4921)So3.log,So3.right_jacobian,So3.left_jacobian,Se3.expandSe3.lognow keep their digits for small rotations (#4897).So3.logmeasures the angle withatan2instead of2 * acos(w), which in float32 returned exactly[0, 0, 0]for every rotation below 1e-4 rad and was 2% short at 1e-3 rad. The Jacobians and theSe3VandV^-1matrices evaluate(1 - cos theta) / theta**2,(theta - sin theta) / theta**3and(1 - (theta / 2) cot(theta / 2)) / theta**2from their series below 0.5 rad (0.2 rad in float64), so they are the identity instead ofnanattheta = 0andSe3.exp(v).log()returnsvfor rotations below 1e-4 rad in float32 (1e-8 rad in float64) instead of dropping the rotation-coupled part of the translation. (#4941)Quaternion.slerptakes the shorter arc between the two rotations whatever the signs of the stored quaternions (it used to go the long way round when their dot product was negative). (#4944) (#4945)compose_transformationsandrelative_transformationnow broadcast a batch of one against a batch ofNin either argument. Before, a(1, 4, 4)first argument with an(N, 4, 4)second argument raised a torchRuntimeError, while the reverse order worked. Batches of two different sizes other than one now raise aValueErrorinstead of a torchRuntimeError. Fixes #4933. (#4946)So2,Se2,Se3andParametrizedLinebuilt from a tensor that requires grad keep that tensor, so the gradient reaches it; they used to wrap it in a newnn.Parameterand leave the caller's.gradatNone. Such a tensor is now registered as a buffer: it no longer appears in the module's.parameters(), butstate_dict(),load_state_dict()and.to()still reach it. A tensor that does not require grad still becomes a parameter. (#4943) (#4947)transform_pointsnow applies an unbatched transform to point sets of any size. (#4958)ImageSequential.show()/.save()andAugmentationSequential.show()/.save()now work after a call withoutput_type="numpy"or"pil". The containers cached the converted output, so.show()raisedTypeError: Input tensor must be a PyTorch tensor.for NumPy andAttributeError: 'list' object has no attribute 'shape'for PIL. They now cache the augmented tensor before converting the output; the returned output is unchanged. Closes #4956. (#4959)Se2.expandSe2.lognow keep the translation at and neartheta = 0(#4924). Both guarded their 0/0 coefficients with a fallback of 0 where the limit is 1, soSe2.exp([1, 2, 0]).twas[0, 0], the log of every pure translation was[0, 0, 0], and just abovetheta = 0the closed forms cancelled:Se2.exp(v).log()was off by 2.0 attheta = 1e-4in float32 (2e-2 in float16, 1e-8 in float64).Se2.lognow evaluates(theta / 2) cot(theta / 2)through the cancellation-freeSo3coefficients, andSe2.expevaluatessin(theta) / thetaand(1 - cos(theta)) / thetathrough them below 0.5 rad and assin(theta) / thetaand2 sin(theta / 2)^2 / thetaabove it, which also keepsexp(v).tto a few ulps where it is nearly zero (thetanear a nonzero multiple of2 pi). The gradients at the identity are the true ones instead of 0 andnan. For avthat does not require grad,Se2.exp(v).tis now annn.ParameterlikeSe3.exp(v).t, instead of a tensor whose autograd graph led to the hiddenSo2parameter. TheSo3coefficient series are now evaluated on 0 above their switch, so the float16 gradients ofSe3.exp,So3.left_jacobianandSo3.right_jacobianare finite from 50 to 255 rad instead ofnan(#4965). (#4960)A weight of exactly 0, the documented way to drop a correspondence, now gets its derivative from above in
find_fundamental,run_8pointand the weightednormalize_points, and so in the weightedfind_homography_dltandfind_homography_lines_dlt, on every supported torch.find_fundamentalandrun_8pointused to returnNaNfor it on torch 2.5.1 and 2.9.1, and on torch 2.14clamp_min(0)masked the gradient to 0 inrun_8pointand dropped the Hartley-normalization part of it innormalize_points. (#4961)So3.exp, and with itSe3.exp, now switches to its small-angle series below a fixed 0.5 rad instead of belowfinfo(dtype).eps * 1e3, which is 7.8 rad in bfloat16 and 0.98 rad in float16 (#4928). Every bfloat16expused the two-term series0.5 - theta**2 / 48forsin(theta / 2) / theta, so attheta = 3the quaternion had norm 0.94 and the rotation matrix was off by 0.23 in an entry; the quaternion is now within about one bfloat16 ulp (at most 5.5e-3 for angles up to pi), and in float16 attheta = 0.97its error drops from 2.8e-4 to 9.1e-5. The series now runs throughtheta**10, so the float32 and float64 outputs move by at most 1.5e-8 and 2.8e-17 below 0.5 rad, a rounding difference, and do not change above it. (#4962)Se3.expandSe3.lognow have the right gradient at the identity (#4953). Both fell back tot = upsilon(upsilon = t) atomega = 0, which is the right value sinceV(0) = Ibut does not depend onomega, so autograd returnedd t / d omega = 0there instead of-0.5 [upsilon]_x, andd upsilon / d q_vec = 0forloginstead of[t]_x. The coefficients ofVandV^-1have been finite attheta = 0since #4941, soV @ upsilonis now taken for every element. The forward values are unchanged. (#4963)_so3_small_angle_coefficientsnow divides its closed forms bythetaone factor at a time instead of bytheta**2andtheta**3, which overflow float16 above 256 and 40.3 rad (#4965). From 41 rad the[omega]_x^2coefficient was 0, so the float16Se3.exp(v).twas off by 0.18 andSo3.right_jacobianandSo3.left_jacobianby 0.79 up to 250 rad; they are now within about 2 float16 ulp there. The gradient of the coefficients,nanfrom 256 rad, is finite. Above the series switch the float32 and float64 coefficients move by at most about 2 ulp; below it they are unchanged. (#4967)kornia.geometry.euclidean_distancenow returns the exact Euclidean distance. The previous form addedeps(1e-6) inside the square root, which biased every result upwards and floored it atsqrt(eps)= 1e-3: coincident points read 0.001 and a true distance of 1e-4 read 1.005e-3 (+905 %). The singular point is guarded withtorch.whereinstead, so coincident points return exactly 0 with a finite (zero) gradient, astorch.linalg.normdoes. Theepsargument is now unused and is kept for backward compatibility. (#4968)RandomClaheand the per-sample CLAHE path now compute their clip thresholds correctly when the clip tensor is on MPS (#4970). The limits were moved to the CPU in float64 with a single.to("cpu", torch.float64), which returns zeros on torch 2.14, so every tile histogram was clipped at one count (a mean error of 0.16 on a 256x256 image), and raisesTypeErroron torch 2.5.1. Parameters drawn by the default generator stay on the CPU and were not affected. (#4971)So3.expnow evaluatescos(theta / 2)andsin(theta / 2) / thetabelow the 0.5 rad switch as series intheta**2 = v . vinstead of ontheta = |v|, which has no second derivative atv = 0, so the Hessian ofexpat the identity is finite (-I / 4for the real part) instead ofnanandgradgradcheckpasses there (#4966). Above the switch the output is bitwise unchanged in every dtype; below it the quaternion moves by at most 1 ulp. (#4972)So2.randomandSe2.randomnow draw a unit rotation with a uniform angle on [-pi, pi) (#4930). They builtz = complex(rand, rand), so|z|ranged over (0, sqrt 2),matrix()was a rotation scaled by|z|withdet = |z|**2down to 3.5e-6, and every angle was in [0, pi / 2]. The random values under a fixed seed change. (#4973)point_line_distancenow divides by the weight of a homogeneous(*, N, 3)point,|ax + by + cw| / (|w| |(a, b)|), and returnsinffor a point at infinity (#4935). The weight was ignored, so a point withw != 1got the distance of(x, y)instead of(x / w, y / w), andleft_to_right_epipolar_distanceandright_to_left_epipolar_distanceinherited it for(*, N, 3)input. 2-D points andw = 1are unchanged. (#4975)RANSAC(prosac_sampling=True)always ran the wholebatch_size * max_iterbudget. It now stops with PROSAC's termination-length test (Chum and Matas, 2005): a ranked prefix certifies the incumbent when its support there is non-random and the draws it needs forconfidencefit inside the prefix's growth interval, with OpenCV USAC's guards against short or weakly supported prefixes; the whole set is always a candidate, so PROSAC never runs longer than uniform sampling would.confidence=1still runs the whole budget.find_homography_dltwith the defaultsolver="lu"computed the gauge null vector of a four-point sample withtorch.linalg.qr, which has no batched CUDA kernel and factored a batch of 2048 minimal samples one matrix at a time in about 250 ms. On CUDA it now uses the batched SVD (about 1 ms), soRANSAC("homography")batches on GPU are up to 7x faster; CPU results are unchanged.find_essentialon CUDA computed the roots of Nistér's degree-ten polynomial withtorch.linalg.eigvals, which has no batched CUDA kernel and factors the companion matrices one cusolver call at a time (about 3.6 ms each), soRANSAC("essential")spent 6.4 s per batch of 2048 samples. The eigenvalues are now computed on the host with LAPACK for CUDA inputs (about 15 ms for that batch, transfers included), which makes the solver about 150x faster on the GPU; results are unchanged to roundoff.RANSAC("homography_from_linesegments")local optimization re-weighted segments by the length-scaled residual ofline_segment_transfer_error_one_way, which down-weighted long segments (#4867); it now re-weights by the perpendicular distance in pixels that the score uses. (#4979)average_quaternionsnow normalises its members before averaging and raisesValueErrorfor a negative weight or weights that are all zero (#4974). A member's squared norm used to act as an extra weight (one stored as3 qcounted 9 times), a negative weight extrapolated past a member, and an all-zero weight divided by zero. Unit members with non-negative weights give the same rotation to rounding. (#4980)Quaternion.polar_angleis computed asatan2(|v|, w)instead ofacos(w / |q|): the same angle up to rounding (at most 2.6e-6 rad on random float32 unit quaternions; angles belowsqrt(eps), which used to come out as exactly 0, are now resolved), and its gradient at the identity and at every other quaternion with a zero vector part is zero instead ofnan. (#4927) (#4981)RandomMotionBlurnow raises aValueErrornaming the class, the drawn kernel, the border type and the input shape when the image is too small forborder_type="reflect"or"circular", asRandomBoxBlurandRandomGaussianBluralready do, instead of letting a raw torch padding error out. The sizes it accepts are unchanged. (#4982)RandomTransplantationandRandomTransplantation3Dnow raise a kornia error naming the mask when a call has to draw the parameters without one, adding the key count when the inputs do not matchdata_keys, instead of Python'sIndexErrororlist.indexValueError. (#4983)RandomRGBShiftnow accepts a(low, high)pair (a tuple, a list or a 1-D tensor) for each*_shift_limitas the sampling range, asalbumentations.RGBShiftdoes, instead of failing at construction with a rawTypeErrorfrom negating the tuple. A number is still a non-negative half-width sampled from[-limit, limit]. (#4984)RandomPerspectiveno longer returns a NaN transform matrix and output for an image with a spatial dimension of 1. That axis now gets a unit source extent and no corner offset, so its single row or column maps onto itself and only the other axis is warped; atdistortion_scale=0the warp is the identity. Images larger than one pixel along both axes draw and warp exactly as before. (#4985)crop_by_indicesjoins the per-row crops with onetorch.catwhen every row's slice already matchessize, instead of acopy_per row (#4531): one copy kernel per batch instead of one per sample, with the same values and the same default memory format.RandomCropin slice mode always takes this path; rows that needshape_compensationstill go through the per-row loop, and MPS keeps the per-row copies, which are faster there. A listsize, asRandomCrop([h, w])passes it, no longer resizes every row to its own size. (#4987)Boxes.translatewith an unknownmethodnow raisesNotImplementedErrorwith a message that names the accepted values and repeats the rejected one, instead of an empty message. The exception type is unchanged. (#4988)Quaternion.slerpnow reads a(B,)tensor ratio as one ratio per quaternion, like(B, 1). WithB == 3it scaled the components of each rotation vector instead and returned a wrong result, and otherB > 1raised (#4991). (#4993)Quaternion.__pow__takes the axisn = e_xon the negative real axis (w < 0, zero vector part), wheretheta = piand the axis is undefined, so a non-integer power there has norm|q|**tand anglet * piand(q**0.5)**2 == q.Quaternion([-2, 0, 0, 0]) ** 0.5used to be the zero quaternion. Integer powers are unchanged. (#4955) (#5003)find_fundamental(..., method="7POINT")/run_7pointnow return zero matrices for the two extra candidates when the 7-point cubic has one real root, instead of one rank-3 matrix repeated. (#5006)find_homography_lines_dltbuilds each segment's equations from its own start and end instead of from flattened points i and N + i, so line segments whose endpoints are not point correspondences give the right homography,RANSAC("homography_from_linesegments")finds a model on them, and a zero weight removes its segment (#4866). (#5008)NamedPosenow rejects a pose that is not anSe2or anSe3at construction with aTypeCheckError(anSo3,So2,Quaternionor tensor used to be accepted and fail later in.rotationwithAttributeError), andNamedPose.__mul__raises aTypeErrorthat names the offending type when the right operand is not aNamedPoseor holds the other group, instead of anAttributeErrorfrom inside the dispatch.from_rtandfrom_matrixare unaffected. (#5010) (#5010)solve_cubicevaluates the closed form on each row scaled by an exact power of two to a unit root bound and scales the roots back, takes Cardano'sA + Bas2R / (A^2 + B^2 + Q)whenQ > 0andA^2 < 4.79 Q, and drops the|R| > 1e-16floor that returned-b/3forD > 0rows with a smallR, so a tiny leading coefficient keeps its finite root in float32 and float64 and the #4833 literal solves (#4914). A row whose largest root exceeds 16 times the scale of the other two keeps that root and gets the other two from Vieta's relations andsolve_quadratic, so1e-8 x^3 + (x - 1)(x - 2)returns all three roots instead of two values that are not roots. Outside that case,D <= 0rows whoseQ^3andR^2stayed within the dtype's range keep their bits, rows whose intermediates overflowed or underflowed are now solved, andD > 0rows can move at rounding level. (#5024)motion_from_essential_choose_solutionnow selects each batch element's own best candidate pose independently. Previously, every element in a batched call silently reused the first element's chosen candidate index, which could return a wrong rotation, translation, and triangulated points for any batch (size > 1) where different elements' correct candidates differ. (#5025)fit_linenow returns the direction in the input's dtype for unweighted 2-Dfloat16andbfloat16points. Its vertical-line fallback constant had no dtype, sotorch.wherepromoted the direction tofloat32while the origin kept the input's dtype. (#5026)spatial_expectation2d, and sospatial_soft_argmax2d, now builds its normalised grid in the input dtype. float64 coordinates no longer carry float32 rounding error. float16 and bfloat16 still build it in float32. (#5027) (#5027)ParametrizedLine.squared_distanceanddistanceno longer go negative or return NaN for points on or near the line. They use the sum of squares of the perpendicular component again, row by row, instead of a cancelling identity. (#5028) (#5028)The seven-point fundamental solver keeps rank-two candidates when both null-space basis matrices have nearly vanishing determinants, and its cubic polishing no longer displaces repeated roots through a nearly zero derivative. RANSAC's Levenberg-Marquardt pipeline filters unsupported hypotheses before selecting its best candidates and recomputes the returned inlier mask after converting the model to the input dtype, returning failure if rounding removes sufficient support. (#5031)
Hyperplane.throughno longer documents a two-point 2D form. That form never worked:Hyperplane.through(p0, p1)always raised a bareValidation condition failed(a 2D normal cannot be stored in aVector3), and the unreachable code would have used the line direction as the normal. A two-point call now raises aBaseErrorsaying that three points are required. The undocumented, unexported helperkornia.geometry.plane.normalized, used only by that code, is removed. (#5034)conv_soft_argmax2dandconv_soft_argmax3dnow compile withtorch.compile(fullgraph=True)whentemperatureis a tensor. Their positivity check read the tensor under compile, becauseis_exporting()isFalseinsidetorch.compileon recent torch; the check now runs only outside graph capture, as inspatial_softmax2d. (#5035)Batched
ParametrizedLine.point_at,ParametrizedLine.projection,ParametrizedLine.intersectandHyperplane.projectionnow work row by row. Previously they broadcast a per-row step or distance against the coordinate axis: a batch ofBlines inDdimensions returned rows mixed with each other whenB == Dand raised for most other batch sizes, and a(2, 1)plane batch returned a(2, 2, 3)projection.point_atalso reads aScalarstep as its tensor and returns atorch.Tensor, as annotated (#5013). (#5046)save_pointcloud_ply(ASCII) writes every float64 coordinate with its shortest round-trip representation instead of 9 significant digits, sodoubleproperties no longer lose precision past the ninth digit (UTM-scale metres were off by millimetres). (#5048)CropGenerator, ResizedCropGenerator, CropGenerator3D and PatchMixGenerator keep their position sampler in float32 when the augmentation is moved to float16 or bfloat16, so a crop or patch start cannot land one past the last valid position. On MPS, half-precision
torch.randreturns exactly 1.0 for about 1 in 4096 (float16) or 1 in 512 (bfloat16) draws, which madeRandomCrop(cropping_mode="resample")blend a zero padding line into the crop and putRandomCrop3Dboxes andPatchMixpatches one pixel past the edge. float32 and float64 draws are unchanged; for the same seed, float16 and bfloat16 pipelines now draw some different positions than before, andRandomResizedCropalso some different crop sizes, because its scale draw comes from the same sampler. (#4553) (#5050)Keypoints.padandKeypoints.unpadaccept the unbatched(N, 2)container the class documents and constructs. Both added the(B, 1)padding column to the(N,)coordinate view in place, which broadcast to(1, N)and raisedRuntimeError: output with shape [N] doesn't match the broadcast shape [1, N], soRandomCropfailed on(N, 2)keypoints with and withoutpadding. They now shape the padding to the container, asBoxes.paddoes since #4372, and match the singleton-batch result; an unbatched container carries one image, so a padding with more than one row is rejected.padding_sizeis also moved to the keypoints' device. Batched results are unchanged (closes #5021). (#5051)Hyperplane.throughno longer returns NaN gradients whenp2 - p0andp1 - p0are orthogonal and of equal length: the SVD fallback, which runs on every row, now sees a constant matrix with distinct singular values in the rows that take the cross product, so its backward no longer divides by a zero singular-value gap (#5056). (#5058)Crop starts no longer land one past the last valid position for
CropGeneratorandCropGenerator3Dwith a float16 or bfloat16sizetensor, forRandomResizedCropwith a float16 or bfloat16scaleorratiotensor, and forRandomCrop,RandomResizedCropandRandomCrop3Dmoved to float64: the start draw is scaled and floored in the wider dtype and the integer start is cast afterwards. When the draw and the crop parameters share a dtype, the parameters are unchanged. With a float16 or bfloat16 tensor, the same seed also moves a few in-range starts, those whose draw crossed a start boundary when it was rounded to half precision, to the start of the unrounded draw (#5052). (#5061)RandomPerspective3Dnow handles singleton spatial dimensions without a singular perspective solve. These axes get unit source extents and zero corner offsets, and their single slice, row or column maps onto itself. Zero distortion gives an identity transform (output identity still needsalign_corners=Truewhile #4503 is open). Non-singleton volumes and random draws are unchanged. (#5071)ImageRegistrator.registerappliestolerancewithin each pyramid level, so every level takes at least its first optimization step. Previously the first loss of a finer level was compared with the final loss of the coarser level, and when the two differed by less thantolerancethat level stopped before any update (#5073). (#5074)nms2d,nms3d,NonMaximaSuppression2dandNonMaximaSuppression3dnow return 0 at every suppressed position, as their Returns sections state. The value output used to beinput * mask, so a suppressed±inforNaNcame back asNaN, whichtopkranks above every maximum, and a suppressed negative value came back as-0.0(now+0.0). The gradient reaching a suppressed position is 0 even when the incoming gradient there is not finite. (#5067) (#5076)find_essentialsolves in float64 whatever the input dtype, so a float32 five-point sample no longer misses the true essential matrix (#4884); MPS, which has no float64, solves on the host and copies the candidates back. It now runs on MPS, wheretorch.linalg.eigvalsraisedNotImplementedError(#4528), and on float16 and bfloat16 inputs. On 42000 exact five-point samples with random motions it misses the true matrix by more than 1e-3 12 times, where it missed it 31 times. Its roots come from the host for every device, detached, with a Newton step that supplies their gradient, sobackwardno longer raises at a multiple root (#4903) nor returns NaN gradients for samples without parallax (#4952), and repeated calls on CUDA return identical results. A five-point sample whose constraints are rank deficient, such as one with a repeated correspondence, returns ten NaN candidates and a zero gradient. At 2048 samples it takes 29 ms instead of 40 ms on CPU and 21 ms instead of 28 ms on CUDA; at 256 samples it costs about the same on CPU and 1 ms more on CUDA. (#5078)Vector3.normalizedandVector2.normalizedreturn a zero vector, not NaN, for a float16 zero input, and its gradient is zero instead of inf;ParametrizedLine.throughdoes the same for coincident points when value checks are disabled. They now sharenormalize_quaternion's arithmetic, and a non-zero input keeps itsF.normalizevalue bit for bit (#5062). (#5084)RandomPerspectiveexported with the legacy ONNX tracer now keeps a unit source extent on a size-1 axis, matching eager mode instead of returning zeros. (#5089)rgb_to_grayscaleandbgr_to_grayscaleon a uint8 image no longer wrap the weighted sum modulo 256 (white came back as 1 and pure red as 180), which also garbledload_image(..., ImageLoadType.GRAY8)of a colour file. The uint8 result now matchescv2.cvtColor(..., cv2.COLOR_RGB2GRAY)bit for bit. (#5090)kornia.color.rgb_to_yuv422,yuv422_to_rgb,RgbToYuv422andYuv422ToRgbaccept an odd height when the width is even. 4:2:2 subsamples chroma along the width only, but the shape guard also required an even height and raisedShapeError. Results for even heights are unchanged; the 4:2:0 functions still require an even height and width. (#5091)save_pointcloud_ply,save_pointcloud_ply_binary,load_pointcloud_ply, andload_pointcloud_ply_binarynow acceptpathlib.Pathand other string-backedos.PathLikefilenames, which raisedTypeErrorbefore. As for astr, the.plyextension check ignores case. (#5092)Speed up
RANSACwithlocal_optimization="lm", the default for homographies, fundamental and essential matrices. Hypothesis verification allocates fewer temporaries and, on CPU, is tiled at about a million residuals. The Levenberg–Marquardt stages, which run on the host for every input device, evaluate only the cost of their last trial instead of building an unused Jacobian, and the final refinement drops correspondences outside its inlier mask before building its equations. Five-point essential estimation evaluates its Newton correction with bounded cumulative products instead of general powers. Returned models can differ slightly, since rounding differences can change which refinement steps are accepted. (#5095)jpeg_codec_differentiable,JPEGCodecDifferentiableandRandomJPEGnow keep the DCT basis cache out oftorch.compile,torch.exportand dynamo ONNX tracing, and build eager cache entries outside inference mode. A first inference-mode call no longer breaks later image-gradient computations. Exporting the codec no longer leaves cached fake or functional tensors that break subsequent eager calls. Eager calls still reuse the basis per dtype and device. (#5098)RandomMosaicwith a list box input now gives each tile the padding count of the image it was drawn from. A selected sample used to take its box count from the wrong source images, so it could drop real boxes or return padding rows as boxes such as[7, 0, 7, 0], from a direct call and fromAugmentationSequential. Tensor box inputs are unchanged. (#4715) (#5100)AugmentationSequentialnow calls the box and keypoint handlers of a customRigidAffineAugmentationBase2Dsubclass with its recorded matrix, as it does for a geometric child. It used to return those annotations unchanged next to the moved image, whiletransform_matrixreported the move. Mask handlers of such a subclass now receive the matrix too instead oftransform=None, and a registered box or keypoint key whose handler the subclass does not implement raisesNotImplementedErrorinstead of passing through. With an annotation key listed beforeinputindata_keys, the container used to transform the annotation before the image call recorded the matrix, so a geometric child such asRandomAffineraised on the first call and warped the annotation with the previous call's matrix after it; the image is now transformed first, and the outputs keep the caller's order. (#4481) (#5105)RgbToGrayscale()withoutrgb_weightsnow leaves the weights torgb_to_grayscale, which picks them for the image dtype. A uint8 image used to come back all zeros, because the module's float32 default weights were cast to uint8 as[0, 0, 0]; it now gets the functional's uint8 result, which matchescv2.cvtColor(#5090). A float64 image used to get float32-rounded weights (up to 1.2e-8 off); outside TorchScript it now gets float64 weights. float32, float16 and bfloat16 outputs, and modules built with explicit weights, are unchanged (#5109). (#5111)JPEGCodecDifferentiableandjpeg_codec_differentiablenow build their DCT and IDCT bases withmath.piinstead of the float32 tensorkornia.constants.pi(#5107). Stricttorch.exporton torch 2.5.1 and 2.9.1 rejected the codec because its forward referenced that module-level tensor, and torch 2.5.1'storch.export.exportis strict by default. The float64 bases were only float32-accurate (the DCT basis was up to 5.65e-7 off the exact cosines), so float64 outputs change, typically by less than 1e-6 for an image in [0, 1]. float32, float16 and bfloat16 outputs are unchanged. (#5112)RandomPerspective3Dtraced withtorch.jit.traceon a volume with a size-1 axis now matches eager mode instead of raising a singular solve. The tracer passes the sizes as 0-d tensors, and both size-1 rules used to apply only to Python integers:PerspectiveGenerator3Dnow gives a traced size-1 axis the unit source extent and zero corner offset of eager mode, andRandomPerspective3Dkeeps, in the traced graph, the corner order that holds a size-1 width in place. Eager parameters and outputs are unchanged (#5110). (#5115)AugmentationSequentialnow dispatches box and keypoint data keys toIntensityAugmentationBase2Dchildren so subclass overrides ofapply_transform_boxandapply_transform_keypointare called alongsideapply_transform_mask(#5113). (#5119)The unimplemented
KeypointsandKeypoints3Dpaths now raiseNotImplementedErrorwith a message naming what is unsupported instead of a bare one: building either class from a list of tensors,to_tensor(as_padded_sequence=True)on both, andKeypoints3D.pad,unpad,transform_keypointsandtransform_keypoints_.Keypoints3D.transform_keypointspoints atkornia.geometry.linalg.transform_points(M, keypoints.data), and itsArgsblock now documentsMas :math:(4, 4)or :math:(B, 4, 4)rather than the 2D :math:(3, 3)shape. The paths remain unimplemented. (#5122)dice_lossandDiceLosssum float16 and bfloat16 inputs over the image in float32 and return the loss in the usual dtype. In float16 a sum above 65504 used to overflow, so the loss came back as 1.0 or NaN instead of its value, withaverage="micro"from 128 × 256 pixels on. (#5123)axis_angle_to_rotation_matrixis now accurate to float64 rounding for rotations below1e-3rad. Its low-angle branch used to drop thetheta**2terms of Rodrigues' coefficients, an error oftheta**3 / 6per entry (1.3e-10just below the switch), so the result jumped attheta = 1e-3and disagreed with the quaternion route by the same amount. (#5124)tversky_lossandTverskyLosssum float16 and bfloat16 inputs over the image in float32, form the ratio there and return the loss in the input dtype. In float16 a pixel count above 65504 used to overflow, so the loss came back as 1.0 from 256 × 256 pixels on, or NaN withignore_indexpixels; in bfloat16 a loss below about 4e-3 was rounded to a multiple of 2**-8. (#5129)AugmentationSequentialnow processesinputbefore annotations so nested geometric augmentations and auto-augment policies use the current call's transformation matrix, regardless of caller argument order. (#5130)PatchDominantGradientOrientation,LAFOrienter,SIFTDescriptor,DenseSIFTDescriptor,SIFTDescriptorFromPyramid,SIFTFeature,SIFTFeatureScaleSpace,LightGlueMatcher,RandomHue,ColorJiggleandColorJitternow usemath.piinstead of the float32 tensorkornia.constants.piin their forward arithmetic (#5127). Their float64 results used the float32 value of pi, 8.7e-8 above pi: orientation angles move by up to about 3e-6 rad and descriptor entries by up to about 1e-6, the orientationsLightGlueMatcherwraps into [0, 2 pi) are no longer 1.7e-7 rad too large, and a hue shift offturns is no longerf * 1.7e-7rad too large (with float64 hue factors inColorJiggleandColorJitter). float32 results are unchanged. On CPU,PatchDominantGradientOrientationused to round 2 pi to the half dtype before its bin-to-angle product: a third of its float16 angles move by up to 3.9e-3 rad and 2% of its bfloat16 angles by up to 3.1e-2 rad, and the frames oriented byLAFOrienterand by the default patch backend ofSIFTFeatureandSIFTFeatureScaleSpacemove with them. Every other float16 and bfloat16 result, and every half result on MPS, is unchanged. (#5131)ImageModule,kornia.core.ImageSequentialandkornia.augmentation.ImageSequentialno longer copy every forward output to the CPU. On CUDA and MPS that was a blocking device-to-host copy on each call, made only for.show()and.save(). The cache now holds a detached reference on the output's device, asAugmentationSequentialalready does, and.show()/.save()copy on use;disable_features=Truestill skips the cache. (#5133)The
GeometricAugmentationBase2DConvention block no longer says the 3D augmentations accept an unbounded angle range:RandomRotation3D,RandomAffine3DandRandomMotionBlur3Draise past±360like the 2D classes. (#5140)LightGlueMatcher("sift")now gives LightGlue each keypoint's scale and orientation in the convention of the COLMAP keypoints its weights were trained on: the orientation is the negated LAF orientation in (-pi, pi], and the scale is a sixth of the LAF scale, which is sigma for 6-sigma DoG frames such asSIFTFeatureScaleSpace's. It used to pass the LAF scale and kornia's orientation in [0, 2pi). With OpenCV-layout descriptors, correct matches over the eight Oxford affine sequences rise by 1–2.4% for the kornia SIFT pipelines, and by up to 28% on bark, whose pairs rotate. (#5145)ssim,ssim3d,SSIMandSSIM3D, and thessim_loss,SSIMLoss,ssim3d_lossandSSIM3DLosslosses built on them, compute float16 and bfloat16 inputs in float32 and return the map in the input dtype. In float16 the products of the local moments overflowed for pixel-range data, so withmax_val=255.0the map and the loss came back NaN (a constant image of value 24 or more compared with itself was NaN everywhere), and withmax_valof 0.75 or less an all-zero region gave NaN becauseC1 * C2underflowed to zero; bfloat16 maps were up to 0.08 off on random 32 x 32 images. The convolutions also run with autocast disabled now: undertorch.autocasta float32 input used to give a map in the autocast dtype (bfloat16 on CPU, up to 0.07 off, and NaN for pixel-range data under float16 autocast), and now gives a float32 map. (#5148)Call-time
data_keyspassed toAugmentationSequential.forwardor.inversenow apply to that call only. A call that raised, and aninversecall that succeeded, used to leave its keys as the container's default, so a later call withoutdata_keysraised on an argument-count mismatch or sent each input through another key's handler. (#5136) (#5149)focal_lossandFocalLossnow exclude ignored logits before log-softmax, so extreme finite logits (whose log-probability overflows) and infinite or NaN logits at ignored positions no longer turn the loss and its gradients into NaN. (#5153)Fix
ImageModule.show()/.save()and coreImageSequential.show()/.save()after requesting NumPy or PIL output by retaining a detached tensor cache before conversion. (#5178)otsu_threshold(x, return_mask=True)now returns the comparisonx > threshold, taken per image and channel against that plane's Otsu threshold and reshaped to the input, so a foreground pixel whose value is 0 or negative isTrue(#5173). Previously the mask wasresult > 0withresult = x * (x > threshold): on data whose upper level is 0 or below, for example values in {-1, 0} or {-2, -1}, the threshold separated the two levels but every mask pixel came outFalse. Only a negative threshold is affected: the pixels in(threshold, 0]are nowTrue, and the mask is unchanged whenever the data are non-negative. The thresholded image is unchanged. (#5182)torch.compile(fullgraph=True)now tracesRandomCropatp=1,crop_by_indiceswithsizeand bilinear, bicubic or nearest resampling, and theImageModule,ImageSequentialandAugmentationSequentialcall paths, including a fixed-orderColorJiggle. The containers no longer go throughfunctools.wrapsinside the traced call. Part of #5137. (#5183)edge_aware_blur_pool2dandEdgeAwareBlurPool2Daccept an evenkernel_sizeand keep the input shape, instead of raising aRuntimeErrorabout mismatched tensor sizes. (#5184)ImageModule,ImageSequentialand the augmentation containers no longer load a string argument as an image unless it is the first positional argument, or a keyword argument listed ininput_names_to_handle. An option such asmode="bilinear"is now passed through unchanged even when a file of that name exists in the working directory. NumPy arrays, PIL images and tensors are converted as before. (#5231)KORNIA_CHECK_IS_IMAGErange-check fixes. An empty image, such as a(0, 3, H, W)batch, passes instead of crashing insidetorch.aminmax, withraises=Falsetoo. A signed integer image whosebitsis at least the dtype's width (for exampleint8with the defaultbits=8or withbits=9, orint64withbits=64) used to fail for every value, because2 ** bits - 1was converted to the dtype, where it overflowed. It is now range-checked normally.uint16,uint32anduint64images are range-checked instead of crashing. The integer range error states[0, 2 ** bits - 1]and setsexpected_rangeto it, where it used to say[0, 1]whateverbitswas.Image.printnow moves channels-last data to channels-first before rendering it, asImage.writedoes, so an RGB image fromImage.from_numpyprints correctly instead of as a garbled picture. (#5232)otsu_threshold/OtsuThresholdno longer return a threshold of 0 for afloat16image plane of 65520 pixels or more (256 x 256 and up): the histogram counts were cast back to the image dtype, so their sum overflowed toinf, andbfloat16counts were rounded to 8 bits. The normalised histogram is no longer summed in half precision either, so the thresholds of smallerfloat16andbfloat16images now match thefloat32call (a 1024-pixel ramp of the levels k / 256 gave 0.4922 infloat16and 0.4805 inbfloat16against 0.5; all three give 0.5). The counts are now kept infloat32(float64for afloat64image).normalize_homography, and thewarp_perspectiveandwarp_affinecalls built on it, now invertfloat16andbfloat16matrices infloat32and cast the result back: thefloat16determinant of a large image's pixel-normalization matrix is subnormal, so a 3000 pxfloat16normalization was 7 % off and an 11600 px one was NaN, andbfloat16on MPS with torch 2.5.1 raised for want of acrosskernel. (#5237)get_gaussian_discrete_kernel1dcomputes the exponentially scaled Bessel termsexp(-sigma**2) I_n(sigma**2)directly, using float32 intermediates for float16 and bfloat16 inputs and returning the input dtype. This fixes NaN kernels at large sigma values and, for float16 with kernel sizes of at least 5, at ordinary positive sigma values as well. Finite float64 outputs also change for sigma values from about 7 to 19: previously inaccurate kernels now agree with the normalized reference. Forkernel_size=7, sigma=18, the maximum absolute error per tap decreases from about 0.021 to 4.9e-8. (#5238)ImageModule,ImageSequentialand the augmentation containers accept grayscale and other non-RGB PIL images (modesL,I;16,I;16B,I,F,1), which used to crashto_tensorwith apermuteor byte-order error, and convert them to one-channel tensors like a grayscale NumPy array; palette images (P,PA) are converted to RGB, or RGBA with transparency, instead of yielding their palette indices.output_type="pil"/to_pilturn a one-channel tensor into a mode"L"image instead of raisingTypeError: Cannot handle this data type, and reject multi-channel integer tensors PIL cannot store with a message naming the dtype.to_pil,show()andsave()clamp a float image to[0, 1]and round it to 8 bits on the CPU, the conversion thekornia.modelssavemethods already used: a value above 1 used to wrap modulo 256 (1.1 became 24), a negative value gave 0 or 231 depending on the method and the torch version, and auint8image was multiplied by 255 (200 became 56). A negative value now gives 0 on every torch version and auint8image keeps its values. In-range float pixels change by at most one step, from truncation to rounding (0.999 now gives 255 instead of 254).show()renders bfloat16 outputs, which used to raiseTypeError: Got unsupported ScalarType BFloat16. (#5239)kornia.core.external.LazyLoadercan be copied, deep-copied and pickled (these recursed or failed on the module object), and dunder lookups such as__wrapped__no longer import, install or ask for a module that is not loaded yet (the module metadata__version__,__file__,__path__and__all__still loads it). An installed optional module now loads when--doctest-modulesis insys.argv: theonnxruntimeanddiffusersloaders used to stay empty in any such process, for example a user's ownpytest --doctest-modulesrun, and raisedAttributeError: 'NoneType' object has no attribute ....ImageModuleand the augmentation containers no longer import PIL through the lazy loader to check an argument that is not an image (a keyword such asscale=0.5ordata_keys=[...]), so those calls work on an install without theimageextra. (#5240)torch.compilecan trace a function that builds akornia.core.TensorWrapper: on torch 2.14 and 2.5.1 it used to fail inside Dynamo withRecursionError, with or withoutfullgraph=True, becauseTensorWrapper.__getattr__looked up the wrapper's own unset slots through itself on the instance Dynamo had not initialised yet. The wrapper's own names (its slots,data,__dict__and the copy and pickle hooks) are no longer forwarded to the wrapped tensor, socopy.deepcopyof aTensorWrapper,Vector2,Vector3orScalarkeeps the class instead of returning a plainTensor, and a deep-copiedHyperplanekeeps itsVector3normal. Pickling andtorch.saveof a wrapper no longer fail after a torch function that pickle cannot store: aftertensor ** wthey raisedPicklingError, and aftertorch.unique(w)AttributeError. The copied and pickled state now keeps only theused_callsentries pickle can store, and acopy.copygets its ownused_attrsandused_callssets instead of sharing them with the original.TensorWrapperalso gains the operators it lacked: the reflected2 / wand2 // w;%,**,@,&,|,^,<<and>>in their forward and reflected forms (w % 2,2 % w); unary+,abs(w)and~w; andfloat(w),complex(w)andoperator.index(w). The unary operators and the conversions used to raiseTypeError, and so did the binary operators with a Python number or another wrapper as the other operand; with a tensor operand the binary operators already worked through__torch_function__. An operator returns what the wrapped tensor's operator returns, wrapped in the class of the left operand when that is a wrapper and otherwise in the class of the right operand. (#5243)to_onnxexports the model in eval mode and restores each submodule's training flag afterwards, also when the export fails. On torch 2.9 and later a model left in training mode exported an activeDropout, so onnxruntime zeroed about half of the outputs; the legacy exporter of older torch exported in eval mode but then reset every submodule to the model's own mode. The dummy input takes the dtype and device of the model's first floating parameter or, for a model without one, of its first floating buffer, so float64, float16 and MPS or CUDA models export with an input of their own dtype. The dummy input used to be float32 on the CPU, which failed on an input/weight mismatch or, for a model that promotes, exported a float32 input. A dynamicinput_shapewhose rank differs from the pseudo shape now raisesValueError: a longer one raisedIndexError, and a shorter one exported, sized silently from the pseudo shape's leading entries. A missing output directory raisesFileNotFoundErrorbefore the export runs rather than after it, and the export no longer passes through the deprecatedio.BytesIOdestination or, on the dynamo exporter,dynamic_axes, which warned on every call.ONNXSequentialandONNXModulenow use thesession_options=they are given instead of raisingUnboundLocalError, andkornia.onnx.utils.add_metadata(behindto_onnxand theadd_metadatamethods) overwrites a key that is already present instead of adding a duplicate thatonnx.checker.check_modelrejects. It also merges the duplicate keys of a model tagged by an earlier version into one entry with the last value, so such a model passes the check. (#5244)load_state_dict_from_url,download_file_from_urlanddownload_hf_fileno longer hang on a server that accepts the connection and then stops sending: each connection attempt and each read now times out after 30 s (timeout=overrides it per call; theKORNIA_DOWNLOAD_TIMEOUTenvironment variable, in seconds and read at each call, sets the default, which is how callers that take no timeout, such as pretrained model constructors, raise it; a number from either that is not greater than 0 and at mostthreading.TIMEOUT_MAX, or a variable that holds no number, raisesValueErrornaming its source when a download function is called, and atimeout=that is abool, astror anything else that is not anintor afloatraisesTypeError), the timeout counts as a transient failure, so it is retried and then hands over to the next source, and the call ends with the usualRuntimeErrornaming the source and the cache path. A response body shorter than theContent-Lengththat framed it is now a failed transfer too, retried like the timeout, instead of being cached as a truncated file that every later call returned; chunked and close-delimited bodies are unaffected. To apply both checks these functions now run the transfer themselves instead of callingtorch.hub.download_url_to_file, keeping its temporary-file-then-replace write, hash check and progress bar; code that patchedtorch.hub.download_url_to_fileto intercept kornia's downloads no longer does so.load_state_dict_from_urlnow rejects afile_namethat is not a bare file name with theValueErrordownload_file_from_urlalready raised; an absolute path or a../name used to make it overwrite the file it pointed at with the checkpoint and then delete the original. Calls that passed a path asfile_namenow raiseValueErrorbefore anything is read or written; apathlib.Pathholding a bare name is still accepted. Both functions also check their other arguments before touching the cache or the network: a URL whose path ends in/,/.or/..raisesValueErrorinstead of returning the cache directory or its parent (for a list of URLs, a first URL ending in/used to be cached under its directory name and now raises too), an emptyurllist raisesValueErrorinstead ofIndexError, and apathlib.PathorbytesURL, alone or in a list, raises aTypeErrorthat says what to pass instead of an unrelatedTypeErrororAttributeError. A keywordtorch.hub.load_state_dict_from_urldoes not accept raisesTypeErrorat once instead of re-downloading the checkpoint and raisingRuntimeError, and a leading~inmodel_diris expanded instead of creating a directory named~.hf_urlpercent-encodes the repository and the file name, so"a#b.pth"fetches that file rather thana; a name that was already percent-encoded ("a%20b.pth") is encoded again, so pass the plain name ("a b.pth"). The retry warnings raised throughdownload_hf_filepoint at the caller's line. (#5247)check_safetensorsandload_safetensorsnow raise the documentedValueError, naming the file, for several malformed headers that used to escape it. Previously adtypegiven as a JSON list or object raisedTypeError, a deeply nested header raisedRecursionError, and an integer too long for Python to decode, or a shape whose byte size was too large to print, raised aValueErrorthat did not name the file. A shape of many large dimensions is now rejected in linear time, where multiplying it out took about a minute for 100 000 dimensions, and error messages quote header values in shortened form.check_safetensorsnow also rejects any empty tensor shape that torch cannot build, such as[2**63, 0]or[0, 2**62, 2**62], soload_safetensorscan load, on the CPU, every file the check accepts. The header is still not validated beyond what the reader uses: the optional__metadata__entry is ignored whatever it holds, and when a key appears twice the last one wins. (#5248)kornia.core.ops.eye_likeandvec_likenow reject a non-integernwith aTypeCheckErrorthat namesn("n must be an integer. Got: 2.0 (float)"), carrying the offending type asactual_typeandintasexpected_type. Before, afloat,True, a NumPy float or bool scalar or a float tensor got past then > 0check and failed inside torch with a builtinTypeErrorabout the signature oftorch.eyeortorch.zeros; a string orNonefailed in that comparison with aTypeError;torch.tensor(True)and a multi-element tensor failed with aRuntimeError; andFalseandtorch.tensor(False)raised "n must be positive. Got: False". With NumPy 1.x, whose bool scalars still implement__index__,np.True_was read as 1 andnp.False_raised "n must be positive"; both are rejected too.TypeCheckErroris aBaseError, and since #5233 also aTypeError, so bothexcept BaseErrorandexcept TypeErroraround such a call catch it. Anint, a NumPy integer and a 0-d integer tensor are accepted as before, andn <= 0raises the same error as before. (#5251)kornia.core._compat.deprecatedno longer turns a decorated class into a plain function: the class keepsisinstance, subclassing, class attributes and classmethods, and warns when instantiated. Deprecation messages no longer carry a doubled space before the extra reason. (#5252)guided_blur(..., subsample=s)andGuidedBlur(..., subsample=s)now accept a height or width that is not a multiple ofs, or is shorter thans. They raised a broadcastRuntimeError(1-channel guidance) or aneinsumerror (multi-channel guidance) when the height or width was not a multiple ofs, because the upsampled coefficient maps came outfloor(H / s) * spixels tall and wide; an axis shorter thansfailed earlier, in a zero-sizedinterpolate. The maps are now resized to the input's own size, and an axis shorter thansis subsampled to one pixel instead of none. For a size that is not a multiple ofs, rowiof the subsampled image is the pixel nearest to(i + 0.5) * H / rows - s / 2(a tie rounds up), and likewise for columns: the subsampled grid keeps the alignment with the bilinear upsample it has on a multiple ofs, so such a size is as close to thesubsample=1result as a multiple is. Sizes that worked give bit-identical results. The box blur still runs on the subsampled grid, so its padding limit applies there: a call raises the paddingRuntimeErrorwhen the window(kernel_size - 1) // s + 1is too wide for that grid to be padded in the chosenborder_type, asbox_blurdoes on it. The default"reflect"hits this first, since it cannot pad a one-pixel axis at all, and an axis shorter thansis one pixel;"replicate"and"constant"work at every size. (#5253)bilateral_blur,joint_bilateral_blur,BilateralBlurandJointBilateralBlurnow reject an even (or non-positive)kernel_sizeup front with kornia's "Kernel size must be an odd integer bigger than 0" error; the modules raise it when they are constructed (#5163). Previously such a size was accepted and every call then failed inside the filter: usually with a raw torch shape error (The size of tensor a (7) must match the size of tensor b (8)), and on small images, where the unfolded window axis has length 1 and broadcasts, with the odd-size error ofget_gaussian_kernel2d. Odd kernel sizes are unchanged. (#5255)laplacian,Laplacian,get_laplacian_kernel2dandget_laplacian_kernel1dnow reject a kernel size of 1 (1, or(1, 1)for the 2D forms) with an error that says why. A 1x1 Laplacian kernel is[[0.0]], so the defaultnormalized=Truedivided by zero and returned an all-NaN image, andget_laplacian_kernel2d(1)andget_laplacian_kernel1d(1)returned the all-zero kernel. Sizes such as(1, 3)and(3, 1), which are a 1-D second difference, still work.Laplaciannow validateskernel_sizewhen it is constructed (odd, positive, the right length, not 1x1), so an invalid size such asLaplacian(2)raises there instead of at the firstforwardcall. (#5256)load_imagenow loads 16-bit grayscale and 16-bit RGBA PNGs asuint16withImageLoadType.UNCHANGEDinstead of raising a decoder error; the 8-bit load types, including the defaultRGB32, now raise aNotImplementedErrorthat points atUNCHANGEDfor such files. (#5258)image_to_string,print_imageandImage.printnow print one-channel (grayscale) images instead of raisingRuntimeErrororIndexError. ForImage.printthis covers channels-first data; channels-last grayscale images print once #5232 is merged. (#5259)kornia.filters.in_rangeandInRangenow check each Tensor bound on its own. A bound that does not fit the input raises aValueErrornaming it, instead of being accepted whenever the other bound was(B, C, 1, 1). A(W,)bound used to be applied per column. A bound with the wrong batch, height or width was broadcast into a wrongly shaped mask when the image's own dimension was 1, and raised aRuntimeErrorotherwise. A bound with several channels on a single-channel image was applied as extra thresholds. A Tensor bound paired with a tuple bound raises aTypeError. A 1-D bound is read per channel and needsCelements (or one), so(C,)is accepted. Any other Tensor bound of at most four dimensions is aligned with the input(B, C, H, W)from its last dimension and each dimension must be 1 or the input's. That accepts the documented(1, C, 1, 1). It keeps the shapes that already gave a correct mask next to a(B, C, 1, 1)bound, such as(C, 1, 1),(C, H, W),(B, C, H, W)and a 0-d Tensor, and accepts them for both bounds. A 1-D bound whose length equals both the channel count and the width used to be applied per column and is now applied per channel, without an error. The docstring formulas now readlower ≤ input ≤ upperwith the conjunction overc = 0 … C − 1. (#5260)Fix
image_to_string, and with itprint_imageandImage.print, printing nothing for very wide images whose resized height rounds down to zero. (#5264)kornia.io.load_imagenow raises aValueErrorthat names the file and keeps the decoder's reason, chained from the decoder's exception, when an image cannot be decoded (for example a truncated or corrupt PNG, JPEG or TIFF); it used to raise a bareExceptionthat did not name the file. A missing or unreadable file still raises the sameOSErroras before (FileNotFoundError,PermissionError). (#5267)Edge-aware blur pooling now rejects even edge-dilation kernel sizes with a clear validation error. (#5268)
Motion blur functions and modules now preserve float64 precision when angles and directions are Python numbers. (#5270)
In float16, the normalized Pascal kernels no longer overflow.
get_pascal_kernel_2dreturned an all-zero kernel forkernel_size9 to 11 and NaN from 12, andget_pascal_kernel_1d(..., norm=True)returned zeros from 17 and NaN from 20, soblur_pool2dandmax_blur_pool2don float16 input returned zero or NaN images fromkernel_size=9andedge_aware_blur_pool2dblended in the same broken blur. Each row is now normalized before it is converted to the requested dtype, and the 2-D kernel is the outer product of the normalized rows. float32 and float64 kernels are unchanged up tokernel_size=58. (#5271)kornia.onnx.download.CachedDownloaderkeeps an absolutecache_dirabsolute and caches only complete downloads, so a transfer that is cut short or interrupted is downloaded again on the next call. It used to store the file under a relative copy of the directory in the current working directory and to keep the partial file forever. A partial file already left in the cache by an earlier version is not detected: delete it once. A model cached under the misplaced relative directory is downloaded again once to the absolute one. (#5272)cannyandCannyno longer drop both pixels of an equal-magnitude pair in non-maximum suppression. A step between two flat regions puts the edge between two pixels of equal magnitude, and the strict comparison on both sides suppressed both, so a clean step gave no edge at all. As in OpenCV'scv2.Canny, a pixel now has to be strictly greater than its left (upper) neighbour and greater than or equal to its right (lower) one along a horizontal (vertical) gradient, so the step keeps its left (upper) pixel and gives a one-pixel-wide edge; diagonal comparisons stay strict. Edge maps and the returned magnitude change only at such exact ties, and at pixels of the flat magnitudesqrt(eps)whose two neighbours along the gradient both lie outside the image: every zero-gradient pixel of an image one pixel wide and, where a rounding residue in the gradient sets the direction, pixels of an image one pixel high or at an image corner. These were kept with magnitudesqrt(eps)and now are not. The neighbours are now compared exactly: on float32 the convolution used before could return a rounding residue instead of zero for a tie. The thresholds are no longer limited to(0, 1): they are compared with the unnormalised Sobel magnitude, eight times whatsobel()returns by default, which reaches 4 for a unit step in a[0, 1]image, so any0 < low_threshold <= high_thresholdis accepted. An input whose channel count is not 1 or 3 raises anImageErrorinstead of a raw convolution error. (#5275)VisionTransformer.from_config("vit_s/32", pretrained=True)now loads its weights. The URL pointed at a Hugging Face repository that does not exist, so the download failed with HTTP 401; the checkpoint is hosted atkornia/vit_s32_i21k_augreg_i21k_r224. (#5277)filter3d,correlate3dandconvolve3dnow accept non-contiguous kernels withnormalized=True, preserving the filtering values and gradients of their contiguous equivalents. (#5278)edge_aware_blur_pool2dandEdgeAwareBlurPool2Dnow reflect-pad the input bymax(2, kernel_size // 2)pixels before blurring it, so the blur no longer reaches the zero padding ofblur_pool2dnear the image border (#5228). The input used to be reflect-padded by a fixed 2 pixels, which covers the blur only up tokernel_size5: an image of ones came back with a bottom-right corner of 0.939 forkernel_size=6, 0.969 for 7 and 0.931 for 9. Afloat16orbfloat16input is now blurred infloat32and cast back. Infloat16the output used to be 0 away from edges fromkernel_size9 and NaN everywhere from 12, because the normalised Pascal kernel overflowed (#5229). (#5282)EfficientViT.from_confignow loads the pretrained backbone weights: the hosted checkpoints store them under abackbone.prefix, which the previous non-strict load silently dropped, so every "pretrained" model was randomly initialised. The load is now strict: a checkpoint whose backbone entries do not match the model raisesRuntimeErrorinstead of returning a partly loaded model. A state dict saved from the backbone itself, without the prefix, still loads. (#5283)OnnxLightGluenow goes through theonnxruntimelazy loader instead of probing the module withimportlib.util.find_spec, sokornia_config.lazyloader.installation_modeapplies to it. The probe returned before anything reachedkornia.core.external.onnxruntime, so with the mode set to"auto"the constructor raisedImportErrorand installed nothing, and with"ask"it never asked, while every otheronnxruntimeconsumer installedkornia[onnx]or prompted. Under the default"raise"mode a missingonnxruntimestill raises anImportErrornaming the extra to install, now with the loader's wording:Optional dependency 'onnxruntime' is not installed. Install it with: pip install "kornia[onnx]".(#5287)Resizewith an integer size,LongestMaxSizeandSmallestMaxSizenow return an empty batch with the resized spatial shape for a(0, C, H, W)input, whateverpis, instead of raisingKeyError: 'output_size'(#4429). (#5288)GeometricAugmentationBase2D.inverse_masksnow keeps mask-specific sampling overrides local to the call, so a failed inverse no longer changes interpolation for subsequent images. (#5300)filter2dandfilter3dwith one kernel per sample now accept an input whose batch and channel axes cannot be merged without a copy (#5292). Previously a channels-last input raised torch's "view size is not compatible with input tensor's size and stride" when the batch and channel axes were merged for the grouped convolution, and withpadding='valid'so did afilter2dinput whose batch and channel axes are swapped in memory or that is expanded along the batch. A shared kernel and a contiguous input were unaffected, as wasfft_conv. The error reachedgaussian_blur2dwith a per-samplesigmaon a channels-last image. The output values do not change. (#5301)fft_convwithpadding='valid'now raises aBaseErrorfor a kernel taller or wider than the input, asfilter2ddoes (#5285). Previously the kernel was truncated to the input size in the frequency domain and the crop read its negative size from the end of the tensor, so on a 5 x 6 image a 7 x 3 kernel returned a 4 x 4 tensor and a 6 x 3 kernel an empty one. A kernel as large as the input still gives one output pixel, andpadding='same'is unchanged. (#5302)rgb_to_linear_rgbno longer returns NaN gradients for inputs below -0.055, and neither dorgb_to_labandrgb_to_luv, which call it. The forward result is unchanged. (#5329)Fix
ZCAWhitening.inverse_transformto use the fitted sample dimension, restoring data correctly for nonzero and negativedimvalues instead of raising shape errors or mixing feature values. (#5331)ZCAWhiteningnow stores its fitted mean and transforms as buffers:state_dictsaves them, loading a fitted state into an unfitted module fits it, and.to()moves and casts them. Before, a fitted module'sstate_dictwas empty and.to()left the fit on its original device and dtype, so the moved module raised on input of the new dtype. A checkpoint saved before this change still loads withstrict=Trueand keeps the current fit. (#5338)Fix
apply_colormapmutating input tensors and rejecting leaf tensors requiring gradients. (#5341)Fix
rgb_to_luvandluv_to_rgbreturning NaNs for float16 black pixels and their gradients. (#5342)load_state_dict_from_url,download_file_from_urlanddownload_hf_filekeep handling a failed transfer as such when its temporary.partialfile cannot be removed, for example because another process still holds it open on Windows. ThePermissionErrorfrom that cleanup used to replace the transfer error: a truncated or timed-out transfer was then not retried, theRuntimeErrornamed thePermissionErroras its cause, and aKeyboardInterruptduring the transfer was swallowed and the next source tried. Now the transfer error is kept and the leftover file is reported in a warning, to be deleted by hand. (#5344)add_weightedandAddWeightednow accept tensoralpha,betaandgammathat broadcast to the input shape, such as a 0-d scalar or a per-image(B, 1, 1, 1)weight. Before, a tensor coefficient had to match the input shape exactly, even though the docstring said broadcastable shapes were allowed. Shapes that would change the output shape are still rejected. (#5349)MS_SSIMLossnow computes integer and bool images in the dtype of its Gaussian masks, float32 for a default module and float64 for a module moved with.double(), and returns the loss in that dtype (#5351). Previously such an image reachedF.conv2dwith a dtype that did not match the masks and raised torch's error,expected scalar type Byte but found Floatfor uint8. Floating images are unchanged and pixel values are not rescaled. (#5353)rgb_to_hsvreturns hue 0 instead of the period itself for a hue just below 0:[1, 0, 6e-8]used to return6.2831855in float32, above 2π, and[1, 0, 0.003]returned6.28125, float16's 2π. Hues now stay in[0, 2π)in every dtype, as documented and asadjust_hue_rawreturns them. All other values are unchanged. (#5356)get_box_kernel1dandget_box_kernel2dnow return an ordinary contiguous tensor, so an in-place edit changes only the taps it addresses (#5160). Previously they returned a stride-0 view of one value: writing one tap rewrote every tap, and writing more than one raised torch's "more than one element of the written-to tensor refers to a single memory location" error. The kernel values and thebox_blurresults are unchanged. (#5357)adjust_hue_raw,adjust_gammaandsolarizebuild a Python-float parameter in the image dtype instead of rounding it tofloat32first. Afloat64image used to get afloat32-roundedfactor,gamma,gain,thresholdsoradditions(relative error up to 6e-8, sosolarize(x, 0.1)left a pixel equal to0.1uninverted); it now gets the value as given.float32results are unchanged, andfloat16/bfloat16ones change only where rounding the float once instead of twice gives a different value. (#5358)ImageSequentialandAugmentationSequentialwith image and mask data keys compile withtorch.compile(..., fullgraph=True)on torch 2.5.1: theirisinstancechecks use tuples of classes instead ofX | Yunions, which that version of Dynamo cannot trace. (#5361)load_imageraises theOSErrorsubclass thatopen()raises (FileNotFoundError,IsADirectoryError,PermissionError), naming the path, for a missing, directory or unreadable file of every format. A JPEG path raised a bareOSErrorwithout the file name, so did a TIFF or WebP directory or unreadable file, and a directory or unreadable file with another suffix raisedValueErroras an unsupported format. (#5362)MotionBlurandMotionBlur3Dnow honormode="bilinear"instead of silently using nearest interpolation, and show the selected mode in their representation.MotionBlur3Daccepts tensor and integer angles and rejects sequences whose length is not three at construction. Nearest-mode outputs and border defaults stay unchanged. (#5364)equalize,equalize3d,RandomEqualizeandRandomEqualize3Dnow count float16 and bfloat16 histograms in float32. float16 rounded counts above 2048 and their total overflowed to inf once it passed 65504, so a float16 image or volume with about 65500 or more pixels per channel could come back as NaN; bfloat16 rounded counts above 256, which shifted the output: a 300x300 two-level image equalized to 0.992 instead of 1.0. (#5374)LightGlue ONNX downloads (
download_onnx_from_url, whichOnnxLightGlueuses) now go throughkornia.core.download. A server that stalls fails the attempt afterKORNIA_DOWNLOAD_TIMEOUTseconds (30 s by default) instead of hanging, a transfer shorter than itsContent-Lengthis no longer cached as the model, transient failures are retried, a~inmodel_diris expanded, andcheck_hash=Truealso checks a file already in the cache and fetches it again on a mismatch. A failed download now raisesRuntimeErrornaming the URL and the cache path, with the original error chained as its cause; it used to raise that error (urllib.error.HTTPError,urllib.error.URLError) directly. (#5375)MS_SSIMLossnow filters float16 and bfloat16 images in float32 with autocast disabled and returns the loss in the input dtype, asssimandSSIMLossdo (#5148). A float16 pair with local means above about 181, such as pixel-range data atdata_range=255.0, used to give a NaN loss, and bfloat16 was 2.5 % low on such images (12.06 instead of 12.37). A float16 or bfloat16 module renormalises its rounded Gaussian masks, which no longer summed to one. Undertorch.autocasta float32 input used to be filtered in the autocast dtype (12.04 instead of 12.37 under CPU bfloat16 autocast, NaN under float16) and is now filtered in float32. Images whose dtype differs from the module's, which used to raise torch's dtype-mismatch error, are now accepted: integer and bool images count as the mask dtype, and the loss is returned in the promoted dtype of the two images. (#5377)rgb_to_hlsreturns hue 0 instead of the period itself for a red hue just below 0:[1, 0, 6e-8]used to return6.2831855in float32, above 2π, and[1, 0, 0.001]returned6.28125, float16's 2π. Hues now stay in[0, 2π)in every dtype, as documented and asrgb_to_hsvreturns them. All other values are unchanged. (#5378)filter2d,filter2d_separable,filter3d,fft_conv,box_blur,gaussian_blur2d,laplacian,get_spatial_gradient_kernel2d,get_spatial_gradient_kernel3d,spatial_gradientandspatial_gradient3d, and the functions and modules that pass these options on, now accept the upper- and mixed-case spellings ofborder_typeandmodethat their checks already accepted (#5156). Previouslyborder_type='REFLECT'passed kornia's check and then raised torch'sNotImplementedError: Unrecognised padding mode REFLECT, andmode='Sobel'or'Diff'raisedNotImplementedErrorfrom the kernel dispatch. Each spelling now takes the same path and gives the same result as its lower-case one, a spelling outside the set still raises kornia's error, and lower-case calls are unchanged. (#5379)Normalize,DenormalizeandRescalekeep Python-numbermean,stdandfactorarguments as Python numbers and apply them in the input's dtype and device, so a float64 input no longer gets a float32-rounded constant. Such arguments are no longer registered as buffers andreprshows them as given; tensor arguments are still non-persistent buffers that move with.to(). (#5380)solve_quarticno longer loses the small real roots of a quartic whose other root pair is much larger. Ferrari's small quadratic factor is now rebuilt from the large one with Vieta's relations instead of a cancelling difference. In float32,(x - 0.5)(x + 0.25)(x^2 + 1e7)used to return no real roots and(x - 0.5)(x + 0.25)(x - 1e4)(x - 2e4)only the two large ones; both now return all their real roots. In float64, a close small pair next to a large complex pair could lose both roots ((x - 0.01)(x - 0.0105)(x^2 + 2000 x + 4e9)) or come back about 1e-7 off; such roots are now accurate to about 1e-15. Rows whose two quadratic factors are not separated (constant terms within a factor of 16) are unchanged. (#5382)grayscale_to_rgbreturns independent storage again instead of an expanded view of its input: writing one channel of the result no longer changes the grayscale input and the other two channels, and in-place operations on the result, such asadd_, no longer raiseRuntimeError. Values and shapes are unchanged; the result is now a copy. (#5383)denormalizeandDenormalizecheck a(C,)mean or std against dimension 1, asnormalizedoes, so every documented(B, C, *)rank works: rank-2 input no longer raisesIndexError, and rank-3 or rank-5 input whose dimension -3 differs from C, including float statistics, is no longer rejected. (#5384)EfficientViT.from_confignow loads local checkpoint paths as well as checkpoint URLs. (#5385)gaussian_blur2dnow rejects a tensorsigmawhose batch is neither 1 nor the input batch at its entry with an error that namessigma, before any kernel is built (#5169). Previously the mismatch surfaced from the kernel batch check offilter2d_separable, or offilter2dwithseparable=False, with a message about the kernel.bilateral_blurandjoint_bilateral_blurnow raise a kornia error for a floatsigma_colorof 0 instead of Python'sZeroDivisionError, andmotion_blur,motion_blur3d,get_motion_kernel2dandget_motion_kernel3dnow raise a kornia error for akernel_sizethat is not anintinstead of aTypeError. (#5387)kornia.onnx.download.CachedDownloader, whichONNXLoader,kornia.models.small_srandkornia.contrib.super_resolutiondownload through, now useskornia.core.download's transfer: a server that stalls fails withTimeoutErrorafterKORNIA_DOWNLOAD_TIMEOUTseconds (30 s when it is unset) instead of blocking forever, and a leading~in the cache directory or file path is expanded instead of creating a literal~directory. (#5389)AugmentationSequential.transform_matrixcomposes the matrix that a nestedAugmentationSequentialrecorded for the current call. Depending on the child order it used to raiseTypeError, omit the nested transform, or reuse the matrix of the nested container's last direct call. A nested container whose children are all non-rigid is skipped like a non-rigid child, in either order, andImageSequential.get_transformation_matrixreads the nested container's current matrix too. A plainImageSequentialchild is still omitted (#4476). (#5391)mean_iou_bboxnow computes float16 and bfloat16 boxes in float32 and returns the IoU in the box dtype. In float16 the IoU came out 0 or NaN once the two areas together overflowed: a 181 x 181 box against itself gave 0 and a 256 x 256 box NaN, somean_average_precisionscored a perfect float16 detection of a 512 x 512 box as 0 instead of 1. bfloat16 rounded the areas before the ratio (0.9766 instead of 0.9805 for a 200 x 200 and a 200 x 204 box). float32, float64 and integer boxes are unchanged. (#5392)The docstrings of
rotate3d,RandomRotation3D,RandomAffine3D,RandomMotionBlur3D, their 3D parameter generators andmotion_blur3dread as ifyaw,pitchandrollwere Euler angles, most of them as rotations about the x, y and z axes. They now say that the three form one axis-angle vector in degrees, converted with Rodrigues' formula: a single non-zero component is the rotation about its axis, while(90, 90, 0)is one turn of 127.3 degrees about(1, 1, 0) / sqrt(2), which neither Euler order gives.MotionBlur3Dsays the same. The behaviour is unchanged. (#5393)Vector3.from_coords,Vector2.from_coordsandHyperplane.signed_distancecompile withtorch.compile(..., fullgraph=True)on torch 2.5.1: theirisinstancechecks, and the five others left inkornia/, use tuples of classes instead ofX | Yunions, which that version of Dynamo cannot trace. (#5394)get_gaussian_kernel1d,get_gaussian_erf_kernel1d,get_gaussian_discrete_kernel1dandgaussiannow accept a Pythonintsigma, andgaussiananintmean, and return the same kernel as for the equalfloat; they used to raise aTypeCheckErroror anAttributeError. With nodtypethe kernel has the default floating-point dtype, as for afloatsigma. (#5396)A tensor method called through a
TensorWrappersuch asVector3, for exampleVector3(t.clone()).sum(), compiles withtorch.compile(..., fullgraph=True). Dynamo used to fail on it when the wrapper held an intermediate tensor, and on torch 2.5.1 for any wrapper. (#5397)RgbToYuv420,RgbToYuv422,Yuv420ToRgbandYuv422ToRgbno longer declareONNX_EXPORTABLE = False, so reading that attribute on them now raisesAttributeError, as on the other color modules. All four export withtorch.onnx.export(..., dynamo=True)and match eager execution under onnxruntime. They declareONNX_DEFAULT_INPUTSHAPElike the other color modules; for the two decoders it is the shape of the luma plane. A test now exports every class that declares these attributes with its declared shape and checks that a class keepingONNX_EXPORTABLE = False(Canny, #5398) still fails to export. (#5399)KORNIA_CHECK_SAME_DEVICESnow returnsFalsewithraises=Falseand raisesTypeCheckErrorwithraises=Truefor an empty list, a non-list container or a list holding a non-tensor. Previously[]and tuples returnedTruewithraises=False, and a non-tensor element raisedAttributeError, or was compared by itsdeviceattribute if it had one (aVector3, for example). (#5401)kornia.enhance.normalize,denormalizeand theNormalize/Denormalizemodules no longer castmeanandstdto an integer input's dtype. For a uint8 image a fractional statistic truncated to 0, sonormalize(x, 0.5, 0.5)returnednan/inf, and the arithmetic wrapped around in the integer dtype:normalize([0, 128, 255], 100.0, 50.0)returned[3.12, 0.56, 3.10]instead of[-2.0, 0.56, 3.1], anddenormalize([0, 128, 255], 10.0, 2.0)returned[10, 10, 8]instead of[10, 266, 520]. An integer or bool input is now converted to torch's default floating dtype first; a bool input, which used to raiseNotImplementedError, is accepted. Floating and complex inputs are unchanged, and pixel values are not rescaled: givemeanandstdin the 0-255 scale for a uint8 image. (#5407)kornia.core.utils._l2_normalize, the L2 normalisation behind the feature descriptors, no longer turns a vector holding a NaN into an all-zero vector. Only a vector whose largest magnitude is exactly zero takes the zero branch; a NaN now propagates as it does fromtorch.nn.functional.normalize. (#5409)kornia.core.download.load_state_dict_from_urlanddownload_file_from_urlnow raiseValueErrorfor aurlstring without a scheme, such as a local path, before looking in the cache. The cache is keyed by the URL's base name, so a mistyped local path used to load whichever cached checkpoint shared that name. Load a local file withtorch.load.ModelBase.load_checkpointnow expands~before checking for a local file. (#5410) (#5410)Error messages that read "Gotcha " now read "Got ", across
kornia.filters,kornia.augmentation,kornia.feature,kornia.enhanceandkornia.constants, andfilter2dnames a badbehaviouras an invalid behaviour mode instead of an invalid padding mode. (#5411) (#5411)max_blur_pool2dandMaxBlurPool2Dnow emit aDeprecationWarningwhenceil_modeis passed. The flag never had an effect: it went to a max pool that runs at stride 1, where floor and ceil rounding agree, and the strided blur has no rounding mode. Results are unchanged; stop passingceil_mode, which will be removed in a future release. (#5412)Geometric annotation replay now uses the transformation parameters supplied to the replay call, even after a later image call updates the augmentation state. (#5416)
kornia.metrics.mean_iou_bboxnow computes integer and bool boxes infloat32, souint8,int8andint16boxes no longer wrap around in widths, areas and the union (which gave IoUs outside [0, 1] or NaN, accepted inverteduint8boxes and rejected wideint8ones). The result is stillfloat32. An integer box set paired with a float16 or bfloat16 one inxyxyorxywhformat now returnsfloat32, ascxcywhalready did, instead of the half dtype. (#5417)bilateral_blur,joint_bilateral_blur,BilateralBlurandJointBilateralBlurnow reject a tensorsigma_colororsigma_spacewhose batch is neither 1 nor the input batch at their entry with a kornia error that names the argument and both sizes, before any padding or kernel is built (#5430). Previously the mismatch surfaced as a torch broadcast error from inside the filter that named neither argument. (#5432)in_rangeandInRangenow respect fractional and out-of-range bounds on integer images without truncating bounds or overflowing the image dtype. (#5434)motion_blurandmotion_blur3d(andMotionBlur,MotionBlur3D) now accept a tensorangleordirectionwith a Python number for the other again, whatever the tensor's dtype and device, and blur as the two-tensor call does (#5429). Previously, since #5270, such a call raised aTypeCheckErrorunless the tensor was in the input's dtype promoted to at least float32, and aDeviceErrorfor a tensor on an accelerator, because the number was built on the CPU in that promoted dtype instead of like its tensor partner. (#5436)total_variationandTotalVariationavoid overflow in adjacent differences for uint8, int8, int16, and int32 images, preserving the output dtypes for both reductions. (#5439)otsu_thresholdandOtsuThresholdsupporttorch.exporton the default path again, and compile withfullgraph=Truewithout graph breaks: the per-plane histograms are computed in one batched operation, without.item()or a data-dependent branch for constant planes. (#5441)KORNIA_CHECK_SHAPEnow accepts every tensor shape for["*"], treats an empty pattern as scalar-only, and reports the tensor dimension when a leading-wildcard check fails. (#5442)Fixed
dataclass_to_dictraisingTypeErrorfor anamedtuplereachable from a dataclass, instead of preserving its fields. (#5444)The
kornia.core.checkfailure paths now report the rejected value:KORNIA_CHECK_TYPEhandles aint | strunion instead of crashing while building its message,KORNIA_CHECK_IS_LIST_OF_TENSORnames the first non-tensor element, the colour and gray checks print the failing shape and raise theirImageErrorunder TorchScript, andKORNIA_CHECK_DM_DESCreturnsFalse(or raisesShapeError) for a distance matrix or descriptor of the wrong rank instead of anIndexError. (#5445)crop_by_indicesno longer allocates a full-batch input gradient and a copy of the whole output gradient for each image crop when gradients flow to a batch of images, so the backward of slice-mode crops (RandomCrop,RandomResizedCrop,CenterCrop2D) grows linearly with the batch size instead of quadratically. (#5447)Named input conversion now binds positional arguments to
forwardparameters in image modules and sequential containers, rather than to the internal PyTorch call wrapper. Selective conversion also handles bound decorated methods and variadic arguments. (#5448)Made the eager backward pass of
ColorJiggleandColorJitterwith a fixedorderabout 30x faster (about 170 ms to 6 ms with gradients on a(8, 3, 64, 64)CPU batch) by selecting each step withtorch.whereinstead oftorch.cond. Every step is now computed even when its range is neutral, so without gradients a fixed order with a step configured off (for examplehue=0) costs up to about 1.6x more than before. (#5450)So3.matrix(),So3.adjoint()andSo3 * pnow use the rotation ofq / |q|for a non-unit quaternion, asQuaternion.matrix()does, instead of returning a scaled matrix that is not a rotation and scaling points by|q|^2.Se3andNamedPoseinherit the fix. The quaternion is still stored as given, so annn.Parameterstays registered; gradients with respect to it now pass through the normalisation. (#5452)So2module dtype conversions now preserve both complex rotation components:float()andto(float32)use complex64, whiledouble()andto(float64)use complex128. Parent modules andSe2inherit the same behavior; device-only moves preserve precision. Complex checkpoint keys and shapes remain unchanged. Half precision uses PyTorch's experimental complex32 support. Since PyTorch has no complex bfloat16 dtype, bfloat16 casts keep the rotation's existing complex precision while following device moves; other floating module state still converts to bfloat16. (#5453)kornia.core.utils.is_autocast_enablednow reports CPU, CUDA, MPS and XPU autocast on every supported torch version. It used to miss MPS autocast on torch 2.5.1 and XPU autocast on every version, so on torch 2.5.1 insidetorch.autocast("mps", dtype=torch.float16)augmentations such asRandomGaussianBlurreturned float16 for a float32 input; they now return the input dtype, as they already did on torch 2.14.LightGluenow checks autocast for the device type of its descriptors, so running it on CPU inside an MPS autocast region no longer raises a dtype-mismatchRuntimeErroron torch 2.14. (#5454)RandomMotionBlur3Dnow raises aValueErrornaming the class, the drawn kernel, the border type, the axis and the input shape when a volume is too small forborder_type="reflect"or"circular"along depth, height or width, asRandomMotionBlurdoes for an image, instead of letting a raw torch padding error out. The sizes it accepts are unchanged. (#5455)kornia.core.utils.batched_forwardnow rejects a non-positivebatch_sizeinstead of failing later withZeroDivisionErroror an empty-listtorch.caterror, andsafe_solve_with_mask/_torch_solve_castreject a non-tensor operand withTypeCheckErrorlike their siblings_torch_inverse_castandsafe_inverse_with_mask. (#5456) (#5456)On MPS with PyTorch before 2.7,
dilation,erosionand the operators built on them (opening,closing,gradient,top_hat,bottom_hat) now propagate a NaN inside the window when they use theshiftengine, whichengine="auto"(the default) selects on MPS. They used to return a finite value there, becausetorch.maximumandtorch.minimumignore NaN on those versions. (#5457)OperationBasenow applies softbatch_probblending independently of the wrapped augmentation'sporp_batch, so replayed fractional probabilities produce consistent results (#4809). (#5460)Fixed
convert_points_to_homogeneous, and through ittransform_pointsandRANSAC("homography_from_linesegments"), returning wrong values on MPS once the third-from-last dimension of the points (fortransform_points, the flattened batch) reaches 65536; RANSAC on line segments picked a wrong homography. (#5462)thresholdandThresholdnow compare an integer image withthreshas given: a fractional threshold is rounded down instead of truncated toward zero, and a threshold outside the image dtype's range passes every pixel or none instead of wrapping or raising. (#5465)RandomCrop(cropping_mode="slice")now scales bounding boxes and keypoints only along axes where the requested crop exceeds the padded input, matching the image resize. (#5466)RandomMosaicwithcropping_mode="slice"no longer offsets bounding boxes from the image content by the fractional part of the crop start (up to 1 px up and left): the sampled start corner is now floored to a whole pixel, which the image crop and the boxes share.cropping_mode="resample"crops from the same integer corner, so it no longer interpolates a sub-pixel shift into the image. (#5467)Boxes.compute_area,Boxes.transform_boxesandBoxes.translate(andBoxes3D.transform_boxes) now accept non-contiguous box tensors, such as a(B, N, 4, 2)tensor made by transposing the batch and box axes. They used to raiseRuntimeError: view size is not compatible with input tensor's size and stride;compute_areanow returns the documented(B, N)areas. (#5468)transform_pointswith unbatched(N, D)points and a batch ofB > 1transforms now raises its batch-sizeValueErroralso whenN == B; that case used to fail insidetorch.bmmwith an unrelatedRuntimeError.PinholeCamera.projectwith(B, 3)points on a batch-Bcamera raises the sameValueError. (#5469)The convolution engine of the morphology operators no longer raises
NotImplementedErroron MPS with torch 2.5.1: the non-finite codes are now matched by scalar comparison instead oftorch.isposinf/torch.isneginf, which lack an MPS kernel there (#5472)solve_quarticnow rescales small-root quartics before evaluating Ferrari's thresholds. It preserves four real roots and rejects non-real candidates when changing the variable's scale previously changed the returned root set. Ordinary and large-root rows retain their existing evaluation path. Rescaling remains bounded by the compute dtype's normal-exponent range and cannot recover underflowed input coefficients. (#5474)otsu_thresholdon the default path now finds the right split for float32 and bfloat16 planes whose range timesnbinsexceeds the float32 maximum (above about 1.3e36 for 256 bins). Such planes used to get a wrong threshold and mask, or a NaN threshold once the range itself overflowed. (#5479)Keep binary focal-loss gradients finite for large finite logits with a fractional focusing parameter (
0 < gamma < 1). (#5484)ScalePyramidand its feature detector callers can now be constructed under an MPS default device, preserving Gaussian kernel precision and module device placement. (#5489)fit_linenow fits points of dimension 3 and higher at large and small coordinate scales, and in float16 and bfloat16, without overflowing the scatter matrix. A fit with float32 points and float16 weights, or float64 points and float32 weights, no longer raises a dtype error: the line comes back in the promoted dtype, as in 2-D. (#5498)solve_quarticrecomputes float32 rows with a rounding-sensitive resolvent discriminant in float64, preserving close real roots that were misplaced or returned as zero padding. Results retain the input dtype and device; MPS performs the precision retry on CPU with autograd preserved. (#5501)Descriptor matching now computes half-precision distances in float32 to avoid overflow and lost nearby matches, while returning distances in the input dtype. (#5503)
ImageModuleandImageSequential(core and augmentation)show()andsave()raise the documentedValueErrorbefore the first call instead of anAttributeError, and again afterdisable_features = True, which now clears the cached output instead of leaving the last image to be shown. An output that is not 3-D or 4-D gets one clearValueErrorfrom both instead of an emptyValueErrorfromshow()and anUnboundLocalErrorfromsave().show()keeps a unit height or width: a(3, 1, 5)image renders as a 5 x 1 RGB picture instead of a 3 x 5 grayscale one.output_type="numpy"turns abfloat16output into afloat32array instead of raisingTypeError, and the cached output is no longer pickled with the module, sotorch.save(module)no longer grows by the size of the last output (#5211). (#5504)kornia.metrics.angle_error_matandkornia.metrics.angle_error_vecnow read the sine of the angle from the skew part of the relative rotation and from the cross product of the two unit vectors and returnatan2(sin, cos), so a float32 angle is resolved to about 2e-5 degrees over the whole range (#5500). Previously both usedacosof the cosine, which returned exactly 0 for every angle below about 0.03 degrees and 180 for 179.99 degrees in float32, and had an infinite or NaN gradient at exactly 0 and 180 degrees on older torch versions; the gradient there is now the subgradient 0.angle_error_vecalso scales each vector by its largest absolute entry instead of its norm, so very long and very short vectors keep their angle: two float32 vectors 45 degrees apart with lengths 1.8e19, 1.9e19, 1e30, 9e-23 or 1e-40, or two float16 vectors with lengths 255, 257 or 6e4, now return 45.0, where previously the squared norms or their product overflowed or underflowed and the result was 90, NaN, NaN, 41.4 and NaN in float32 and 90, NaN and NaN in float16. (#5505)ParametrizedLine.intersectnow keeps gradients finite for parallel lines, including mixed batches of parallel and intersecting lines. (#5517)kornia.core.download.load_state_dict_from_urlanddownload_file_from_urlno longer advise passingpath.as_uri()when given apathlib.Path: afile://URL is cached by its base name like any other URL, so a cached checkpoint of the same name, when there was one, was loaded instead of the local file. TheTypeErrornow says to load a local file withtorch.load.DexiNed.load_from_fileinkornia.filtersandkornia.modelsnow reads a string that names an existing file withtorch.load(..., weights_only=True). (#5477) (#5520)find_essentialnow documents thatweightsis intentionally ignored for compatibility, including forN > 5, rather than listing it as a known defect. Positive weights leave an exact five-point sample's null space unchanged; for larger sets they can affect the least-squares fit. (#5522)bilateral_blur,joint_bilateral_blur,BilateralBlurandJointBilateralBlurmove a tensorsigma_spaceto the device of a floating input, as they already moved a tensorsigma_color. A CPUsigma_spacewith a CUDA or MPS image used to raise a device-mismatch error. (#5524)RandomCrop.inversewithpaddingand a crop size equal to the input size (#5512) now followsforwardfor a hand-made mixedbatch_prob: the applied rows are inverted and unpadded on their own and the skipped rows stay untouched, where previously it raised with the internal padded canvas in the message. A mixed gate whose unpadded crop does change the shape is still rejected, and the message now names the unpadded shapes. (#5525)median_blurnow returns NaN for every window of more than one pixel that holds a NaN or an infinity on every backend, as documented. Windows of 7x7 and larger, and inputs that require grad, no longer depend on how the backend's convolution handles0 * NaNand0 * Inf(CPU bfloat16 on x86 returned finite values there). (#5529)kl_div_loss_2dandjs_div_loss_2dnow apply the0 · log 0 = 0convention, so a distribution with empty cells compared with itself gives 0 with finite gradients instead of NaN (#5554). A zero cell also no longer makes a gradient NaN where the value was finite: the gradient ofkl_div_loss_2dwith respect totarget, and ofjs_div_loss_2dwith respect to either input, was NaN at every zero cell of that input. Every other cell keeps its value, including+infwherepredis zero andtargetis positive, and NaN for a NaN or negative entry and for an infinitepredwheretargetis zero; strictly positive heatmaps are unchanged. (#5557)MILossFromRef,NMILossFromRefand their2D/3Dvariants now followModule.to(device)andModule.to(dtype)(#5547):bin_centersis a non-persistent buffer, so a moved module no longer raises a device-mismatch error, andepsis read from the cached signal's dtype, so a module moved to float64 no longer keeps float32's epsilon. Thestate_dictkeys are unchanged. (#5559)ssim3dnow builds its Gaussian window in the device and dtype of the inputs, asssimdoes, and filters mixed inputs in their common dtype (#5534). Float64 results are accurate to float64 roundoff instead of carrying the rounding of a float32 window, which moved them by under 1e-6 on uniform random volumes and by more on low-contrast ones, 8.3e-5 for values in [0.9, 1.0]. Float32 and half results on the CPU are unchanged; on a GPU the window is now computed on the device, which moves float32 results by float32 roundoff (1.1e-6 on MPS). (#5560)focal_lossno longer returns NaN gradients with a fractional focusing parameter (0 < gamma < 1) when the softmax probability of any class rounds to 1, for a correct and a wrong prediction alike. (#5563)ssimnow computes a pair of a float64 image and a float32, half-precision or integer image in float64, with the Gaussian window built in float64 (#5574). Previously the window was built in the dtype ofimg1and each image was filtered in its own dtype, so the float64 result depended on the argument order: on the low-contrast pair of #5574 it missed the all-float64 map by 1.1e-4 in one order and 5.7e-5 in the other, and swapping the arguments changed it by 1.3e-4. Both orders now equal the all-float64 map. Pairs without a float64 image, same-dtype pairs included, are unchanged, andSSIM,ssim_lossandSSIMLossinherit the change. (#5578)mutual_information_loss,normalized_mutual_information_loss, their_2dand_3dforms and theMILossFromRefandNMILossFromRefmodules now give a constant input, target or reference a zero gradient (#5575). Previously the discarded branch of thetorch.wherethat normalises a constant signal to zero backpropagated0 / 0, so the constant sample's gradient was NaN, and with it the gradient of any parameter shared across the batch. Loss values are unchanged. (#5579)ImageSequential,AugmentationSequentialandVideoSequentialnow accept a nestedPatchSequential(#5584). Previously the parent's shape tracking read the nested container'sPatchParamItementries asParamItemand raisedAttributeError: 'PatchParamItem' object has no attribute 'data'for everyPatchSequentialchild, with and withoutpatchwise_apply. The image shape tracked after the nested container is now its input shape, cropped to a multiple of the grid size forpadding="valid", so a size-dependent sibling such asRandomCropdraws its parameters for the image it receives. (#5588)charbonnier_lossandCharbonnierLossnow evaluatesqrt(r² + 1) - 1asr² / (sqrt(r² + 1) + 1)for residuals withr² < 1, so a small residual keeps its loss of aboutr² / 2. Previously the subtraction cancelled: the loss was exactly 0 for|r|up to about 4e-4 in float32, 0.04 in float16, 0.1 in bfloat16 and 2e-8 in float64, and inaccurate above that (a relative error of 6e-5 atr = 2**-6in float32). Losses forr² >= 1are unchanged, and the gradients, which were already accurate, stay within 2 eps (relative) of their previous values. (#5589)AugmentationSequentialwith a(B, H, W)mask now compiles withtorch.compile(..., fullgraph=True), with and withoutkeepdim=True: the mask's batch size comes from the per-sample gate instead of theforward_input_shapetensor. A(B, T, H, W)mask underVideoSequential(same_on_frame=True)no longer raises. (#5602)Nested augmentation containers now track size changes correctly during export, and nested
PatchSequential(padding="valid")containers track their cropped image shape. (#5603)welsch_lossandWelschLossnow evaluate1 - exp(-r² / 2)without cancellation for residuals withr² < 1. Previously the loss was exactly 0 for|r|up to about 0.022 in float16, 0.0625 in bfloat16, 2.4e-4 in float32 and 1e-8 in float64, and lost precision above that. Losses forr² >= 1are unchanged, and the gradients, which were already accurate, change by about 2 eps (relative) at most. (#5604)normalize_min_maxnow returns an empty tensor with the input's shape, dtype and device for an empty batch, and keeps the empty leading dimensions of a higher-rank input; it used to raiseValueError: Invalid input tensor, it is empty.for any empty input.RandomAutoContrast,RandomGaussianIlluminationandRandomLinearCornerIllumination, which call it, now preserve an empty batch instead of raising that error. Inputs that stay invalid (an empty channel or spatial dimension, fewer than two dimensions, a non-tensor) raise the same exception types as before, with new messages. (#5605)charbonnier_loss,cauchy_loss,geman_mcclure_lossand their modules evaluate float16 and bfloat16 inputs in float32 and return the input dtype. In float16 they returnedinfor NaN from a residual of 256 (181 for Geman-McClure), with a zero, infinite or NaN gradient, and the Geman-McClure gradient was more than 10% off from a residual of about 25 in float16 and 10 in bfloat16, and exactly 0 from about 74 and 26. (#5609)Indexing a
VideoBoxesnow returns aVideoBoxesthat keepstemporal_channel_size, sovideo_boxes[i].to_tensor()no longer raisesAttributeError. (#5613)AugmentationSequential.inverseof an empty-batch mask no longer raisesIndexError(frompadding_size[0]) when it replaysRandomCropparameters other than the dict the last forward call used, such as a copy.VideoSequentialno longer raisesIndexErroron an empty batch when it contains aResize,LongestMaxSizeorSmallestMaxSize. Part of #4429. (#5620)Accept non-contiguous label tensors in
confusion_matrixandmean_iou. (#5625)Under graph capture (
torch.jit.trace,torch.export, ONNX export),safe_inverse_with_maskand_torch_inverse_castnow return the finite inverse of a regular 2x2, 3x3 or 4x4 matrix at any scale the inverse fits in, and the mask ofsafe_inverse_with_maskisTruefor it (#5507). Previously the closed-formadj / detoverflowed or underflowed the dtype long before the inverse did, so the traced mask rejected1e13 * Iand1e-13 * Iof order 4 in float32 that eager accepts, and2**40 * Icame back as the zero matrix with maskTrue. The adjugate is now taken on a copy balanced by powers of two per row and column, which leaves every result whose adjugate and determinant were normal numbers unchanged to the bit; where one of them overflowed or went subnormal the result wasinf,nan, zero or rounded, and is now the inverse. Eager mode is unchanged. (#5633)dice_lossandDiceLosswitheps=0no longer return a NaN loss ('micro') or a NaN gradient ('macro') for a sample whose pixels are all ignored, nor a NaN'micro'loss for aweightthat is 0 for every class: such a sample enters the batch mean as loss 1 with a zero gradient, as it does ateps > 0. In float16 the'micro'gradient for an all-zeroweightis now finite at the defaultepstoo. (#5637)solve_quartickeeps repeated roots, tells close real pairs from nearby complex pairs across coefficient scales, finds roots that span many decades or sit in a tight cluster, and returns its genuine roots in descending order followed by padding.solve_cubickeeps exact double roots.solve_quadraticandsolve_cubichandle coefficients whose products leave the dtype range, float32 cubics are solved in float64 on every device, so a row's roots no longer depend on the rest of its batch, and all three solvers keep finite gradients in mixed batches and support full-graph compilation. On MPS, float32 quadratics and cubics are solved on the CPU in float64, as quartics already were, which fixes flushed subnormal products and misclassified close pairs; this is slower than an on-device solve from about 10^3 rows for quadratics and beyond about 5 * 10^5 rows for cubics. Undertorch.compilewith Inductor on CUDA, Triton's fused multiply-adds can still lose exact double roots ofsolve_cubicandsolve_quartic; this is documented and not planned to be fixed. (#5639)fit_linewith weights now fits 2-D points at any weight scale, and float16 points whose weighted sums exceed the float16 range, as the D ≥ 3 branch already did: each row's weights are divided by their largest value, and float16 and bfloat16 fits are computed in float32. Previously, float32 weights of 5e36, and 256 float16 points near x = 1500 with unit weights, gave aninfor NaN origin and direction, and float32 weights of 1e30 or 1e-30 gave a finite line whose direction had a zero gradient with respect to the points. The returned line keeps the dtype promoted from points and weights. Other float32 and float64 fits change only by rounding, and are bit-identical when the largest weight of each row is a power of two, as with unit weights; float16 and bfloat16 fits can change in the last bits. (#5641)focal_lossno longer produces NaN losses or gradients from overflowing non-target log probabilities. (#5642)MILossFromRef,NMILossFromRefand their2D/3Dforms store a copy of themaskpassed at construction. Editing that mask tensor in place afterwards used to change the loss silently (same number of selected positions) or make the forward pass raiseIndexError(a different number); it now changes nothing. (#5645)keypoints_to_grid, used byWunschLineMatcher, divides by the image size as a tensor. On CUDA it is now correctly rounded and matches CPU and the reference normalization; before, it multiplied by a rounded reciprocal and could differ in the last bit. (#5646)ImageSequential,AugmentationSequentialandVideoSequentialno longer raiseIndexError: index 0 is out of bounds for dimension 0 with size 0on an empty batch when they contain aCenterCrop. A stage after theCenterCroprecords the crop size, whatever itsp, as its forward pass does, so a laterCenterCroplarger than that size raises the sameAssertionErroras for a non-empty batch (#4429). (#5647)kornia.geometry.homography.find_homography_dltwith the defaultsolver="lu"and five or more points, andfind_homography_dlt_iterated, return the homography instead of an all-NaN matrix on exact correspondences whose normal matrix has an exactly zero last LU pivot, such as identical point sets, integer shifts and exact 90-degree rotations of integer keypoints. How often that happens depends on the BLAS and LAPACK in use: 98 of 500 random sets of 10 integer keypoints with an integer shift on the reporter's Windows machine, 6 of 500 on macOS arm64. Only the last pivot being zero means the system has rank 8, so the homography is unique; it now matchessolver="svd"andcv2.findHomography. Systems with an earlier zero pivot, such as coincident points, still give NaN. (#5648)GaussianBlur2d, andUnsharpMaskwhich blurs with it, now export through the legacy ONNX exporter (torch.onnx.export(..., dynamo=False), the default on torch 2.5.1) with a dynamic batch, height and width. The export used to fail with "Unsupported: ONNX export of convolution for kernel of unknown shape". A per-samplesigmakeeps a static batch, and its height and width are dynamic too. (#5650)RandAugment,AutoAugmentandTrivialAugmentcan now be pickled and saved withtorch.save. The default magnitude mapping was a local function, so every policy failed to pickle. A restored policy replays the same draw under the same seed. (#5651)gftt_responsereturned a NaN gradient wherever the discriminanttrace**2 - 4 * detof the structure tensor rounded to exactly 0: on every flat 9 x 9 patch of the image (zero padding, a black border, a saturated region) in every dtype, and in float16 and bfloat16 on many textured pixels too (766 float16 and 3364 bfloat16 pixels of a random(2, 3, 33, 29)image, out of 5742). The gradient is now finite, and 0 on flat patches. The discriminant is now computed as(dx2 - dy2)**2 + 4 * dxy**2, so the response values also move at rounding level, toward the exact smaller eigenvalue: in float32 the largest deviation from it falls from up to 2e-5 to below 2e-7 of the largest response. (#5653)Affine,Rotate,Scale,TranslateandShearnow move their constructor tensors with.to(). Before, a module moved to another device raised in its forward; one moved to another dtype raised forRotate,ScaleandAffinewithout acenter, and otherwise computed part of its matrix in the old dtype. Plain tensors are stored as non-persistent buffers, sostate_dict()keys are unchanged, and annn.Parameterargument stays a parameter. (#5663)Move constructor tensor weights and coefficients with
.to()in DiceLoss, FocalLoss, BinaryFocalLossWithLogits, LovaszSoftmaxLoss, RgbToRgba, BgrToRgba and AddWeighted, preserving explicit Parameters and checkpoint keys. (#5664)distort_points_kannala_brandtnow returns finite point and camera-parameter gradients at the optical axis, including in mixed batches. (#5666)On MPS with torch 2.9.1, or torch 2.5.1 with
PYTORCH_ENABLE_MPS_FALLBACK=1,find_fundamentalwithmethod="7POINT", or withmethod="8POINT"and exactly eight unweighted points, and the minimal homography and fundamental matrix solvers insideRANSACreturned wrong models (in our tests RANSAC found no inliers). MPSsolve_triangularmisread the strided LU blocks that the shared null-space solver passed to it; the solver now makes them contiguous on MPS. Results on the CPU and on MPS with torch 2.14 are bit-identical to before. (#5667)Preserve sensor tilt gradients at zero tilt in
distort_pointsandundistort_points, so gradient-based calibration can learn tilt from a zero initialization. (#5668)filter2d,filter2d_separable,filter3d,fft_conv,gaussian_blur2d,box_blur,laplacian,bilateral_blur,joint_bilateral_blurandcannyfilter an integer or bool image in float32 with a floating kernel, as the color conversions do (#4053). A uint8 image used to blur to zeros, because the fractional kernel taps were cast to uint8; integer sums wrapped (a 3x3 box of ones over 100 gave 132);normalized=Trueraised a dtype error; asigmabelow 1 was truncated to 0 and rejected;bilateral_blursubtracted uint8 values and blended the edges it should keep; andcannyfound no edge on a signed integer image and raised on uint8 or on a 3-channel integer image (#5155). Through them,motion_blur,pyrdownandScalePyramidno longer return zeros for an integer image, andresizeandrescalewithantialias=Trueno longer reject it. (#5669)ScaleSpaceDetectornow searches exactlyn_levelsresponse levels per octave and uses the levels below and above them only as NMS neighbours. With a per-level response such asBlobHessianorCornerGFTTand aScalePyramidwith three extra levels, it used to search one more level. That level has the same scale as level 1 of the next octave, so every octave-boundary scale was detected twice, and the near-identical twins failed the ratio test in matching.HesAffNetHardNetandGFTTAffNetHardNetwere affected. Their scale pyramid now also builds one level fewer per octave. (#5672)Accept channels-last and other strided heatmaps in convolutional soft-argmax and quadratic subpixel refinement, including strided precomputed NMS masks. Coordinates and responses match contiguous copies. (#5673)
extract_tensor_patchesandcombine_tensor_patches, including their module wrappers, now handle empty image batches without ambiguous reshape errors. Patch counts, spatial sizes, dtype, device and autograd connections are preserved.PatchSequentialalso supports empty batches when its children do, preserving the existingsamepadding andvalidcropping behavior. Geometric patch inverses and mask transforms remain unsupported. Part of #4429. (#5674)LightGlueno longer printsLoaded LightGlue modelevery time it is constructed, andmatch_adalam(also used byGeometryAwareDescriptorMatcher("adalam", ...)) reports a configuration key it does not recognize with aUserWarninginstead of printing aWARNING:line to stdout; the key is still skipped. (#5676)ScaleSpaceDetectornow places each detection where its octave pixel lies in the input image. It used to scale octave coordinates by the nominal spacing2**o, butScalePyramidresizes withalign_corners=True, which maps octave pixeluto input pixelu * (W - 1) / (W_o - 1)and the same alongy. Detections from a doubled first octave were up to half a pixel too far from the origin. Detections from every coarser octave were pulled towards the origin, by several pixels on large images.HesAffNetHardNet,GFTTAffNetHardNetandSIFTFeatureScaleSpace(with its default"patch"backend) are affected. TheScalePyramiddocumentation now states the map and thatpixel_distsis nominal. (#5677)extract_patches_simpleandextract_patches_from_pyramidnow sample the pixels a LAF describes. They built their grids in the corner-aligned frame (2x / (W - 1) - 1) and then sampled withalign_corners=False, so a LAF centred on pixelxwas read atx * W / (W - 1) - 0.5: up to half a pixel off, and stretched byW / (W - 1). An axis-aligned LAF of scalePS / 2with oddPSnow returns exactly the image crop, and a LAF covering a wholeW-pixel axis has scaleW / 2, where it used to be(W - 1) / 2. Descriptors, LAF orientations and AffNet shapes change for every pipeline that cuts patches from LAFs:SIFTFeatureandSIFTFeatureScaleSpacewith the"patch"backend,HesAffNetHardNet,GFTTAffNetHardNet,KeyNetHardNetandKeyNetAffNetHardNet. The"pyramid"SIFT backends are unchanged. (#5681)Unweighted 2D
fit_linenow fits float16 and bfloat16 points in float32, as the weighted 2D and D >= 3 paths already did, and returns the origin and direction in the input dtype. In float16 it used to return an infinite origin and a NaN direction when two coordinates differed by more than 65504 (for example points at x = -40000 and x = 40000), and a horizontal or NaN direction when a set of more than 65504 points overflowed the second moments. bfloat16 results change only by rounding. (#5684)Weighted
geometry.fit_linein three or more dimensions no longer allocates a quadratic-size diagonal weight matrix, reducing memory use for large point sets. (#5685)augmentation.CenterCrop,augmentation.CenterCrop3Dandgeometry.transform.CenterCrop2Dnow raiseTypeErrorwhensizeis neither an int nor a tuple, and DeDoDe'sConvRefinerraisesValueErrorwhen a depthwise block'sout_dimis not a multiple of itsin_dim. Both used to raise a bareException; code that catchesExceptionis unaffected. (#5686)Fix half-precision mutual descriptor matches on MPS in
match_smnnand replace its quadratic match-intersection allocation with an integer lookup. (#5687)Cannyandcannywithhysteresis=Truecan now be exported. Undertorch.exportthe hysteresis loop is atorch.while_loop, so the exported graph repeats until nothing changes for any input, and the dynamo ONNX exporter writes it as an ONNXLoopfrom torch 2.11. Before, both exporters failed on the data-dependent loop.Canny.ONNX_EXPORTABLEis nowTrue. (#5689)HardNet8(pretrained=False)now gives distinct, trainable descriptors. Its placeholder PCA projection was an all-ones matrix, which mapped every patch to the same descriptor up to sign; it now keeps the first 128 of the 512 features until the pretrained weights replace it. (#5693)ImageModule,ImageSequentialand the augmentation containers keep the container type of a multi-outputforward: a tuple stays a tuple and a one-element tuple stays a one-element tuple with the helper features enabled, the same as withdisable_features = True. Aforwardthat returns a dict,Noneor a Python scalar passes that output through, with the tensors of a dict cached detached, instead of raisingRuntimeError: Unexpected object ...after the work has already run, and a list output converts its elements foroutput_type="numpy"/"pil"like a tuple does instead of raisingTypeError: Input type not supported.AugmentationSequentialwithoutput_type="numpy"or"pil"used to raiseTypeError: Input type not supportedfor more than one data key or a dict input. It now converts the images and masks, positional or in a dict, and leaves a dict value under an unrecognized key as it is. A mask converts like the image: a(B, 1, H, W)mask becomes a(B, H, W, 1)array, the layout a NumPy mask input is read in, or one PIL image per sample; a(B, H, W)mask returned underkeepdim=Truegets its channel axis back first, and a per-sample list of masks converts element by element. Boxes, keypoints and labels are not images: with any of them in the data keys such a call raisesValueErrorbeforeforwardruns. (#5695)SIFTDescriptornow centres its grid of spatial cells on the patch centre(patch_size - 1) / 2, where its Gaussian weighting window already was. The grid, inherited from pytorch-sift, sat above and to the left of it: by 1.5 pixels at the default patch size 41, and by more at larger patch sizes. A mirrored orrot90-rotated patch therefore did not give a permuted descriptor; with the default 8 angular bins it now does, up to rounding. At some patch sizes, 41 among them, the centred grid needs a pooling kernel one pixel wider (17 instead of 16 pixels), andget_sift_bin_ksize_stride_padreturns it with the newpad. Descriptors change forSIFTDescriptor,sift_describeand the"patch"backend ofSIFTFeatureandSIFTFeatureScaleSpace; the"pyramid"backends andDenseSIFTDescriptorare unchanged. A state dict holding the former, untrained pooling kernel still loads. (#5696)MultiResolutionDetector, the detector ofSIFTFeature,KeyNetHardNetandKeyNetAffNetHardNet, no longer reports spurious keypoints beside its 15 px border strip. It zeroed the strip before non-maxima suppression, so a pixel next to the strip whose real maximum lay inside it survived the suppression. The suppression now reads the whole response and the border is applied to its output, as the mask already was, so a keypoint is a maximum of its fullnms_sizewindow wherever it lies. A stronger response inside the strip therefore suppresses a weaker maximum up tonms_size // 2pixels beside it, as a stronger neighbour does anywhere else, so detections in that band can change.remove_bordersnow receives the suppression output instead of the response, and it writes an exact zero, so an infinite score inside the strip no longer becomes NaN. (#5697)euler_from_quaternionnow returns a triple that represents the input rotation at gimbal lock (pitch = ±pi/2). There,rollandyawused to come fromatan2(0, 0), so the triple did not match the input and the round trip throughquaternion_from_eulerwas off by up to 2 in rotation-matrix entries. It now returnspitchexactly±pi/2,rollexactly0and the one determined combination inyaw, within[-pi, pi]; the input triple itself cannot be recovered at the pole. The gradient there is finite and small, where before it was of order 1e6 to 1e17 (andnanon older PyTorch), and rotations withw = x = 0(such asyaw = pi) keep a finite gradient on PyTorch 2.5.1 as well. Away from the pole nothing changes: outputs are bit-identical. A pitch within2 * sqrt(eps)of±pi/2is treated as gimbal lock and snapped to the pole.Quaternion.to_euleris fixed the same way. (#5702)Weighted
geometry.find_homography_lines_dltno longer allocates a quadratic-size diagonal weight matrix, reducing memory use for large line-segment sets. (#5703)confusion_matrix,mean_iouandmean_iou_bboxnow trace undertorch.compile(fullgraph=True)on torch 2.14: their data-dependent label-range and box checks are skipped wherevertorch.compiletraces them, as they already were undertorch.export. Eager calls still raise on an out-of-range label or an invalid box; a compiledmean_iou_bboxnow gives an invalid box an IoU of 0 or NaN instead of raising. (#5704)BlurPool2DandMaxBlurPool2Dpreserve their stored kernel across forward calls, so earlier input dtypes no longer corrupt later floating-point results. The kernel is a non-persistent buffer: module.to()moves it whilestate_dict()remains unchanged. (#5707)distort_points_kannala_brandtno longer returns -inf/NaN float16 point gradients for points at a small nonzero normalized radius (below about 4e-3). Its outputs, its camera-parameter gradients and the other dtypes are unchanged. (#5708)cannyandCannywithhysteresis=Trueundertorch.jit.trace, and so the legacy TorchScript ONNX exporter (torch.onnx.export(..., dynamo=False)), no longer repeat the hysteresis round only as many times as the traced image needed. The loop is now a scripted function that the trace calls, so the traced graph and the exported ONNXLooprun until nothing changes on every input. Before, a longer edge chain than the traced one was cut short without an error, with only aTracerWarning. If TorchScript cannot compile the loop, aRuntimeWarningreports it. On torch 2.5.1 and 2.9.1, where that exporter is the default, the trace raisedexpected padding to be a single integer value or a list of 2 valuesinstead. (#5710)HausdorffERLossandHausdorffERLoss3Dnow trace undertorch.compile(fullgraph=True)on torch 2.14: their data-dependent label-range check is skipped wherever a graph captures the call, as it already was undertorch.export. Eager calls still raise on an out-of-range label; a captured call now scores such a voxel in no class and returns a finite loss instead of raising. (#5712)Fit planes with reduced SVD factors, avoiding an unused quadratic-size matrix for large point clouds and their backward passes. (#5718)
LoFTR("indoor_new")no longer switches every LoFTR created afterwards in the same process to theindoor_newpositional encoding. It used to writetemp_bug_fix = Trueinto the shared module-leveldefault_cfg(and into a config dict passed by the caller), so a laterLoFTR("outdoor")ran with the wrong positional encoding and matched almost nothing. EachLoFTRnow works on its own deep copy of the config. (#5720)zca_mean,zca_whitenandZCAWhiteningfit float16 and bfloat16 data in float32. In float16 the unnormalized scatter overflowed, so eight samples of 0 and 255 gave NaN transforms. Eager fitting also runs with autocast disabled: undertorch.autocasta float32 input used to give transforms in the autocast dtype (NaN for pixel-range data under float16 autocast), and now gives the float32 transforms it gets outside autocast. TorchScript fitting does not disable an enclosing autocast region. (#5721)SOLD2.matchno longer replaces the globaltorch.diagwith a tensor, which made every latertorch.diag(...)call in the process (includingMKDDescriptor(whitening=...)) raiseTypeError.SOLD2(config=cfg)no longer setsuse_descriptor = Trueon theDetectorCfgit is given; it works on a copy.WunschLineMatcher.needleman_wunschnow allocates its table in the dtype of the scores; float64 scores used to raise an index_put dtype error, and half-precision scores gave a float32 result.SOLD2.matchnow samples each descriptor map with a grid in that map's dtype, so segments in any floating-point dtype, including the float32 segmentsSOLD2.forwardreturns, match against the descriptors of a float64 or half-precision model; that, and float64 segments with float32 descriptors, used to raise agrid_sampledtype error such asexpected scalar type Half but found Float. (#5723)match_adalam(dm=...)now uses the distance matrix for the nearest-neighbour matches and their ratio scores; the argument was documented but never read, so anydmgave the same matches as nodm.dmholds plain (not squared) distances, like thedmof the other matchers, and AdaLAM squares it internally, sodm=torch.cdist(desc1, desc2)gives the matches ofdm=None, which uses the squared L2 distances as before. Admof the wrong shape raises.match_adalamwith aconfigthat does not set"device", andGeometryAwareDescriptorMatcher("adalam"), now run on the device of the descriptors; they used to move everything to the CPU and return CPU tensors for CUDA or MPS input. The unique-pair step no longer needstorch.unique(dim=0), which torch 2.5 lacks on MPS.match_adalam(hw1=..., hw2=...)now honours the image sizes when they are lists; only tuples were used and a list silently fell back to the keypoint spread.get_laf_descriptorsandLAFDescriptorchanged the caller's descriptor module: they called.eval()on it and cast it to the image's device and dtype in place, so a module shared with other code (a train-mode module, a float64 module) was silently switched to eval and to the image's dtype. The descriptor still runs in eval mode with its parameters cast to the image's device and dtype for the call (a TorchScript module runs as a cast copy), and the descriptors are unchanged, but once the call returns the module is as it was: its device, dtype, parameters and the train/eval mode of every submodule. Gradients still reach its parameters. Undertorch.compilea descriptor whose dtype differs from the image's is now cast as in eager mode, also withfullgraph=True; such a compiled call used to raise a dtype error, or, on torch 2.14, break the graph.make_uprightturned the all-zero padding LAF of an unfilled detector slot into a tiny nonzero frame, whichlaf_is_filledreported as a detection; it now returns the padding unchanged, and its gradient at a padding slot is finite.laf_to_boundary_pointsbuilt its circle in float32 for float64 LAFs, so the points carried float32 rounding; it is now built in the LAF's dtype.laf_from_three_pointsnow checks its input shape likelaf_to_three_pointsinstead of failing deep inside the stack or returning a wrong-shaped LAF.HyNetnow raises aShapeErrorfor patches that are not(B, 1, 32, 32), likeHardNet,SOSNetandTFeat; a(2, 1, 40, 40)input used to return a descriptor of another width,(2, 1152). TheValueErrorfor a non-positivescaling_coefofLocalFeature(andscale_lafofKeyNetHardNetandKeyNetAffNetHardNet) now says> 0, matching the check that rejects0, and anintsuch asscale_laf=2is converted tofloat; it used to pass the constructor and fail inforwardwith aTypeError. The keypoint-range error ofLightGlueandOnnxLightGlueused to be an emptyBaseError; it now names the expected[-1, 1]range and the size orders:image_sizeis(width, height)forLightGlueandOnnxLightGlue,hw1/hw2is(height, width)forLightGlueMatcher.gftt_responsenow validatessigmaslikeharris_responseandhessian_response(TypeErrorfor a non-tensor,ValueErrorunless it has shape(B,)); a batch of one with threesigmasused to return a(3, C, H, W)response. (#5726)LoFTRmisplaced its keypoints for image sizes that are not multiples of 8. It converted the coarse cells of both images to pixels withH0 / ceil(H0 / 8)instead of the 8-pixel stride of the coarse feature map, cut the fine-matching windows of both images on a grid of the wrong stride, and scaled the fine offsets byH0 / ceil(H0 / 2); its FPN also upsampled each level to the size of its skip connection, which reads the coarser level at other positions than the trained weights expect whenever a side is not 0 or 7 mod 8. On crops of Oxford graf 361 to 366 px high and three known homographies, 4 % of the matches were within 1 px of the ground truth, with a median error of 3.1 px and errors up to 9.4 px. Coarse and fine cells are now converted with the 8- and 2-pixel strides of the feature maps for any image size,mask0/mask1are read at the pixels the coarse cells sit on, and the FPN upsamples by 2 and crops to the skip size: 99 % of the matches are within 1 px on the same crops (median 0.23 px), and on IMC PhotoTourism validation with images resized by 0.6 the pose mAA@10 goes from 0.49 to 0.72. Inputs whose heights and widths are all multiples of 8 give the same results as before.LoFTRwithmask0/mask1now runs in float16. It raised aRuntimeError, because the similarity -1e9 given to masked pairs does not fit in float16, and padded queries overflowed the linear attention's normaliser to inf, which made the features nan. Masked pairs now take the lowest finite float16 value, and padded queries, whose output is 0, divide by 1 instead of by eps, so they no longer make the output or the gradients nan; float32 results are unchanged. (#5729)DeDoDe.detectnow pads an image to a multiple of 14 the wayDeDoDe.forwardandDeDoDe.describedo: after the ImageNet normalisation, so the pad is the mean colour. Previouslydetectcalled directly padded first and normalised after, so the network saw a black strip on the bottom and right, and on a 370x504 crop of Oxford graf img1 it selected 94 of 2000 keypoints different fromforward(describeandforwardalready normalised first).DeDoDe.describenow also cuts the padding off its descriptor map: withkeypoints=Noneit returns the(B, DIM, H, W)map its docstring states instead of a map padded to a multiple of 14, and the descriptors it samples at the normalised keypoints ofdetectcome from the right pixels whenHorWis not a multiple of 14.detectfollowed bydescribenow returns the same keypoints (in normalised coordinates), scores and descriptors asforward, and images whose sides are multiples of 14 are bitwise unchanged. The mean-colour pad is the closer one to the reference implementation (Parskatt/DeDoDe), which does not pad.DeDoDe.forwardwithpad_if_not_divisible=Falsenow runs on the unpadded image; its innerdetectanddescribecalls used to pad it anyway.SOLD2andSOLD2_detectornow pick junctions like the reference implementation (cvg/SOLD2). The junction suppression keeps the stronger of two junctions that are at most 8 pixels apart along both axes (grid_sizein general), where it kept both when either distance was exactly 8 pixels; and the junctions are in raster order, so the first endpoint of every line segment is the one with the smaller row or, on the same row, the smaller column. Before, the junctions came in score order. Withuse_junction_refinement=Falsethe endpoints followed the junction score, and[[70, 100], [30, 20]]came out where the reference returns[[30, 20], [70, 100]]. With the defaultTruethe refinement sorted the endpoints, but it breaks ties between candidate positions by endpoint order, so a refined endpoint could differ from the reference's (by 0.5 px on a drawn line). With the pretrained weights on Oxford graf img1 the junction set drops from 416 to the reference's 399, and in both modes the 246 segments become the reference's 229 with identical coordinates.ALIKED.forward_lafno longer returns mirrored frames. Its 2x2 block isU · diag(√λ)of the covariance of the soft-argmax weights, andtorch.linalg.eighfixes each eigenvector only up to sign and lists them in ascending order of eigenvalue, sodet Uwas often -1: no keypoint of Oxford graf or boat img1 had a positive determinant with the pretrainedaliked-n16. The first eigenvector is now negated where needed, so every frame hasdet > 0. The ellipseA Aᵀand the scale are unchanged; a frame that was mirrored gets a different orientation. The docstring now states that the frame's scale is the spread of the soft-argmax weights, about a pixel or less (0.14 to 1.25 px on graf img1), not a keypoint size.compute_affine=FalseandLightGlueMatcher("aliked"), which reads only keypoint positions and descriptors, are unaffected. (#5731)Below
p=1,RandomEqualize,RandomEqualize3DandRandomClaheno longer raise for an out-of-range image the gate skips, andRandomGammano longer gives a skipped sample a NaN gradient where its value is 0. These classes now run the transform on 0.5 for skipped samples; the selected samples and every other augmentation are unchanged. (#5732)laf_is_inside_imagenow tests the exact extent of each region. It used to check ten points sampled on the region's boundary, so an ellipse that crossed an image edge between two of them, by up to 4.9 % of its extent along that axis, was reported as inside. It now compares the exact span of the ellipse along each image axis,c_i ± ‖A[i, :]‖, with the sameborderand the same closed0 .. w - 1/0 .. h - 1bounds.ScaleSpaceDetectorapplies the same rule to half of each candidate's frame against a 5-pixel octave border, and therefore so doHesAffNetHardNet,GFTTAffNetHardNetandSIFTFeatureScaleSpacewith its default patch backend: a candidate whose half frame overhung that border along x by less than 4.9 % of its radius used to be kept and is now discarded. Its slot goes to the next candidate among thenum_featuresbest of each octave, and stays empty when there is none. On the first image of each of the eight Oxford affine sequences, this replaces 10 to 15 of the 16384 detections per pipeline.SIFTFeatureand the KeyNet pipelines are unchanged.LAFAffineShapeEstimatorandLAFAffNetShapeEstimatornow compose the shape they estimate with the shape of the input LAF. Both sample each patch through the upright form of the input LAF, so the estimate is in that frame's coordinates; it used to be written over the input shape as if it were measured in the image, which is right only for an isotropic input. For an anisotropic or skewed input the output was the correction rather than the corrected shape, and applying an estimator to its own output alternated between the region's shape and a circle (axis ratios 2.00, 1.01, 2.01, 1.02 on a Gaussian blob of ratio 2). The output region is now that frame composed with the estimate, with the input's centre and scale and the samepreserve_orientationbehaviour, so an input that already matches the region keeps its shape and repeated application converges. An isotropic input gets the same result as before. The framesScaleSpaceDetectorhands to its affine module are circles in octave pixels, which the octave-to-image factors(W - 1) / (W_o - 1)and(H - 1) / (H_o - 1)stretch by up to 1.8 % between x and y on the Oxford affine images (more on very elongated images), so the frames ofHesAffNetHardNetandGFTTAffNetHardNetmove by about 1e-4 of their scale (median), and on the first images of the eight Oxford affine sequences about 50 of each pipeline's 16384 descriptors change by more than 0.01.KeyNetAffNetHardNetis unchanged.DenseSIFTDescriptornow spaces itsnum_spatial_binsxnum_spatial_binscellsspatial_bin_sizepixels apart, asSIFTDescriptorand VLFeat's dense SIFT do. They were one pixel apart, so at the defaults the cells of one output covered a 7 x 7 window instead of the 16 x 16 pixels of 4 cells of 4-pixel bins, and an edge in that window lit up to three cell columns at once. Descriptor values change, and the output size follows (see the breaking change). The docstring now states the size rule, the input position of each output and the defaultpaddingof 1 (it said 0). (#5734)equalize,equalize3d,posterizeandsharpness, and theRandomEqualize,RandomEqualize3D,RandomPosterizeandRandomSharpnessaugmentations built on them, now return an empty tensor with the input's shape, dtype and device for an empty batch, and keep the empty leading dimensions of a higher-rank input. They used to raiseValueError: Invalid input tensor, it is empty.for any empty input. An empty channel or spatial dimension still raisesValueError, with a new message. Results for non-empty inputs are unchanged. Part of #4429. (#5735)spatial_softmax2d,spatial_expectation2d,spatial_soft_argmax2dandSpatialSoftArgmax2dnow return an empty result for an empty batch or channel axis instead of raising a reshape error. (#5739) (#5739)SIFTFeaturenow detects bright blobs as well as dark ones. Its detector,MultiResolutionDetector, keeps the maxima of its response only, andSIFTFeaturegave it the single-scale DoG ofBlobDoGSingle, whose maxima lie at dark blobs: a bright blob was never detected, only weaker maxima on the ring around it.SIFTFeaturenow gives the detector the magnitude of the DoG, so a keypoint is a maximum or a minimum of the DoG; the DoG detectors of Lowe, OpenCV and VLFeat keep both signs too. The suppression rule is not theirs: a keypoint must be the strict maximum of the magnitude in itsconfig["nms_size"]window (15x15 by default) on its pyramid level, so a stronger response of the other sign in that window suppresses a weaker extremum, be it the ring around a blob or a nearby blob of the other polarity, where they test each sign against its 3x3x3 scale-space neighbours separately. An image can therefore yield fewer extrema in all than it had maxima, and whennum_featuresexceeds them, more slots than before are padded with a zero response and a zero LAF: the first image of the Oxford graf sequence fills 4509 of the defaultnum_features=8000slots instead of 5285.SIFTFeaturereturns different keypoints, many of them at bright blobs, and its responses are the magnitude of the DoG. An image and its negative give keypoints at the same positions and scales, up to rounding and not in half precision; withoutuprighttheir orientations differ by pi.MultiResolutionDetectoritself and the Key.Net features are unchanged. (#5744)DeDoDe.detectandDeDoDe.describenow work undertorch.compile. They were decorated with@torch.inference_mode(), and inductor failed on the inference tensors they produce: withRuntimeError: Cannot set version_counter for inference tensoron torch 2.14, and with the tensor-storage error on torch 2.9.1 that the export-support page reported as an inductor bug. They now run under@torch.no_grad(), likeDeDoDe.forwardcompiled before. Gradients stay off and the eager outputs have the same values; they are ordinary tensors now instead of inference tensors, so they can be used in autograd or modified in place afterwards. The compileddetectcan return keypoints with equal scores in a different order from eager. (#5746)LoFTR's coarse matching no longer returns a pair of masked cells as a match. Withmask0/mask1, a pair whose two cells are both masked got the confidence1 / (L * S)from the two softmaxes (a fully masked row or column is uniform there, and all its other entries are exactly 0, so the pair was also a mutual nearest neighbour), and whenevermatch_coarse.thrwas below1 / (L * S)it was returned with keypoints in the padding of both images. The confidence of a pair that involves a masked cell is now 0 after the softmaxes, and a zero confidence is never a match (a negativethrnow behaves likethr=0), so a masked pair is not returned for anythrandborder_rm. (#5749)warp_perspectivegives the same image fors * Mas forM, and a finite homography gradient (1/stimes the gradient forM), whensis very large or very small. For a homography with entries between 0.01 and 1,1e15 * Mreturned NaN images and1e-12 * MNaN gradients in float32, and1e110 * Mand1e-110 * Mreturned NaN images in float64. Undertorch.jit.trace(float32 and float64) and the legacy ONNX exporter,1e8 * Malready sampled the wrong pixels without any NaN. A matrix whose nonzero entries all have magnitude above 1, or all have magnitude below 1, is now divided by a detached scale before the warp, which changes its results at rounding level; any other matrix, such as one withM[2, 2] = 1, gives bit-identical results. (#5752)On CPU, float16 and bfloat16 warps no longer return corrupted values (NaN, values up to 3.4e38, and in bfloat16 a sampling grid off by more than half a pixel) on images of about 128 px and more.
warp_affine,warp_perspective,remap,warp_affine3d,warp_perspective3d,homography_warp3d,homography_warpwith a pixel homography, and the augmentations and crops built on them now build their sampling grid and sample in float32 and return the input dtype;homography_warpwith a normalized homography,HomographyWarperand the depth, elastic and thin-plate-spline warps sample in float32. On torch 2.5.1, which has no CPU half-precisiongrid_sample, these warps now run instead of raising. Other devices and dtypes are unchanged. (#5758)spatial_gradient3dandSpatialGradient3ddifferentiate an integer or bool volume in float32 and give the result of the same volume in float32: uint8 and int8 differences no longer wrap, the mixed second derivatives of an integer volume are no longer zero, and a uint8 volume withorder=2and a bool volume no longer raise.gaussian,gaussian_discreteand the kernel builders that call them (get_gaussian_kernel1d,get_gaussian_kernel2d,get_gaussian_kernel3d,get_gaussian_discrete_kernel1d) build the kernel of an integersigmatensor in the default floating dtype, asgaussian_discrete_erfdoes.gaussian_discreteused to cast the taps to the sigma's dtype, which made them all 0, andgaussianwrapped the offsets of a uint8 sigma, which made the taps before the centre wrong. (#5759)DeDoDe.detectandDeDoDe.forwardnow run with float16 and bfloat16 weights on CPU and MPS.DeDoDeDetector.forwardlifted the decoder context to float32 for the interpolation and fed it back to the half-precision decoder, which raisedRuntimeError: Input type (float) and bias type (c10::Half) should be the same. The context is now converted back to the input dtype after the interpolation. Results in float32 and float64 are unchanged. (#5760)SIFTFeature(descriptor_backend="pyramid")andSIFTDescriptorFromPyramidnow estimate orientation from smoothed, densely sampled gradient maps without extracting image patches. Descriptor histograms are independent of orientation resolution, and separable spatial pooling reduces CPU extraction cost. (#5762)make_grid,ImageModule.showandImageModule.saveno longer raiseZeroDivisionErrorfor an empty batch with the defaultn_row:make_gridreturns an empty grid, as it already did for an explicitn_row. Ann_rowbelow 1 now raises aValueErrornamingn_rowinstead of aZeroDivisionError(n_row=0) or an unrelated reshape error (negativen_row). (#5755) (#5763)conv_soft_argmax3dandConvSoftArgmax3dreturn correctly shaped empty outputs when the batch or channel axis is empty. (#5764)The blur-pool functions and modules export through the legacy ONNX exporter with dynamic batch, height and width. Edge-aware blur pooling combines its edge maps with a boolean OR instead of adding booleans, so it also exports with static shapes, and its dynamo export on torch 2.14 no longer gives a graph that onnxruntime rejects.
EdgeAwareBlurPool2D.forwardtakesepsilon=None(meaning1e-6) by default, so a legacy export of the module no longer addsepsilonas a second graph input. (#5765)get_rotation_matrix2dreports mismatched input dtypes separately from mismatched devices, instead of describing both as a device mismatch. Both checks retainValueErrorand identify the values forcenter,angleandscale. (#5767)js_div_loss_2devaluates float16 and bfloat16 inputs in float32 before forming the mixture, avoiding infinite loss and non-finite gradients for small positive probabilities while preserving the output dtype. (#5771)cauchy_loss,charbonnier_loss, andgeman_mcclure_losspromote half-precision inputs before subtracting them, avoiding spurious infinite/NaN losses and NaN gradients when finite inputs have a residual outside the float16 range. (#5772)conv_soft_argmax3dandConvSoftArgmax3dexport with the legacy TorchScript ONNX exporter (torch.onnx.export(..., dynamo=False)) again; the per-window softmax change of this release (#5134) had broken that export withUnsupported: ONNX export of operator Unfold. (#5775)welsch_lossnow evaluates float16 and bfloat16 inputs in float32 and returns the input dtype, likecharbonnier_loss,cauchy_lossandgeman_mcclure_loss: finite float16 inputs whose difference is outside the float16 range no longer give NaN gradients, and half-precision losses are the float32 values rounded once. (#5777)fit_planenow fits float16 and bfloat16 points in float32 and returns the plane in the input dtype. It used to fit them in their own dtype: a float16 point cloud in millimetres, such as a depth frame, was rejected as collinear because the largest singular value, which grows with the square root of the number of points times their spread, overflowed float16 (#5821), and half-precision offsets lost bits to cancellation (float16 returned -18.5 and bfloat16 -18.0 for an offset of -18.475). The collinearity test keeps the input dtype's tolerance but now applies it to the given points rather than to their half-precision centring, so a near-collinear half-precision set that this rounding let through now raisesValueCheckError. float32 and float64 results are unchanged. (#5783)solve_pnp_dltwith more than six points, andrun_5pointandfind_essentialwith more than nine, no longer build the full square matrix of left singular vectors of their linear system, which they never used (2N-by-2N for N points insolve_pnp_dlt, N-by-N in the other two). Their memory now grows linearly with N instead of quadratically, with or without autograd, and large point sets run much faster. (#5786)Make
AdaptiveDiscriminatorAugmentation(same_on_batch=True)share its global probability gate across the batch instead of independently selecting image rows. (#5787)LoFTR coarse matching now applies either supplied padding mask independently, treating an omitted mask as all-valid. (#5788)
rgb_to_hlsandRgbToHlsnow export to ONNX with the TorchScript exporter and compile withtorch.compile(fullgraph=True). For an input that does not require grad they used to write the H, L and S channels without=into views of one preallocated tensor. The TorchScript exporter (thetorch.onnx.exportdefault before torch 2.9, anddynamo=Falsefrom it) did not record those writes, so the exported graph ignored its input and returned zeros, andtorch.compile(fullgraph=True)raised on the non-contiguousout=tensor. The channels are now computed as separate tensors and stacked; eager results are bit-identical. (#5790)EfficientViTnow runs with float16 weights on CPU.LiteMLA.relu_linear_attlifts a float16 input to float32 for its matrix products and returned the float32 result to a float16 projection layer, which raisedRuntimeError: expected scalar type Float but found Half. The result is now converted back to the input dtype. float32 and bfloat16 results are unchanged. (#5793)raw_to_rgbnow accepts non-contiguous leading batch dimensions, including video tensors with transposed batch and time axes. (#5804)load_imagereturns an 8-bit palette PNG's colours under every load type exceptUNCHANGED, which still returns the palette indices: it used to return the indices as gray for every type.RGBA8takes alpha from thetRNSchunk, and the RGB and gray types composite transparent entries over white, as for any RGBA file; under these types, a palette that is malformed or too short for its pixels, or aPLTEortRNSchunk that is truncated or fails its CRC check, raisesValueErrornaming the file instead of being used. 1-, 2- and 4-bit palette PNGs still raise, because kornia-rs cannot decode them. AtRNScolour key on an 8-bit gray or RGB PNG now makes the key colour transparent in the same way instead of being ignored. Compositing a semi-transparent pixel over white rounds to the nearest level instead of truncating, which made it up to one level too dark.write_imagewrites 4-channel (RGBA) PNGs and accepts.tifand extensions in any letter case, such as.JPG, all of which it used to reject; a channel count the format cannot store raisesShapeError, still aValueError, naming the supported counts instead of kornia-rs's "expected 3 channels".get_sample_imagessaves a download byte for byte instead of decoding it and re-encoding JPEGs at Pillow's default quality 75, so it no longer needs Pillow. It writes each download to a temporary file of its own that replaces the cached file only when complete, so an interrupted download leaves no partial file in the cache and concurrent downloads of the same image do not interfere. A cache filled by an earlier version keeps its re-encoded files until they are deleted. It creates its cache directory only when it has to download, not for local paths, and treats a path as a URL only when its scheme ishttporhttps, so a local file namedhttp_local.pngloads, and names the cached file after the URL's path, without its query or fragment; a URL whose path names no file raisesValueErrorbefore anything is downloaded. (#5808)draw_convex_polygonoverwrites NaN and infinite pixels inside the polygon, which used to come out NaN, and fills auint8image with a float colour, which used to raiseRuntimeError; the colour is cast to the image dtype. Its edges are computed in at least float32 and without rounding the slope first, so they add no error tobfloat16orfloat16vertices, which are used as given (bfloat16vertices at x = 260 and 280, both exact, used to fill columns 259 to 281), a pixel centre lying exactly on a sloped edge is filled, and a long, shallow edge whose vertices lie outside the image is placed correctly.tensor_to_imagereturns abfloat16tensor as afloat32array instead of raisingTypeError.Image.from_numpyaccepts a 2-D gray array, which raisedIndexError.Image.toandImage.floatsetbit_depthfrom the new dtype, soclone()of a converted image no longer raisesBaseError.Image.writeandImage.printconvert aBGRimage to RGB first, so the file and the terminal show the true colours instead of red and blue swapped.print_imageaccepts anyos.PathLikepath, such as apathlib.Path. Docstrings: theImage.from_dlpackexample passes a(C, H, W)array,Image.heightandImage.widthname rows and columns the right way round,Image.writeno longer says it writes only JPEG, and theimage_to_tensor,tensor_to_imageanddraw_convex_polygonargument descriptions are corrected. (#5813)Mutual-information and normalized mutual-information losses now compute half-precision normalization, kernel weights, joint histograms and entropies in float32 and return the input dtype. float16 losses and gradients, NaN from about 184 × 184 pixels with the default kernel, are now finite, and both half dtypes lose the empty-bin bias on small images (12 × 20 seeded pair: float32 −2.662; float16 −2.547 → −2.662; bfloat16 −2.063 → −2.656). The histogram contraction now ignores autocast, so a float32 input inside an autocast region is computed and returned in float32; before, the contraction ran in the autocast dtype, which gave NaN under float16 autocast on large images and a bfloat16 result under CPU bfloat16 autocast.
entropies()of a half-precision module returns float32. Cached reference modules keep the original dtype's constant-signal threshold and the same state dictionary keys. (#5815)average_quaternionsnow compiles withtorch.compile(..., fullgraph=True). It used to fail Dynamo graph capture on the data-dependent column index that selects the eigenvector of the largest eigenvalue; it now gathers that column, with the same result in eager mode. (#5829)MKDDescriptorandWhiteningwithwhitening="pcaws"andoutput_dimsof 40 or less raisedIndexError: index 40 is out of boundsat construction, because the shrinkage weight (the eigenvalue at indexkeval=40) was read after the spectrum had been truncated tooutput_dims. It is now read from the whitening model's full spectrum, so a smalleroutput_dimskeeps the leading columns of the larger transform;output_dimsof 41 or more gives the same descriptors as before. Akevaloutside0 <= keval < len(eigvals)now raises aValueErrorthat says so: a negativekevalofWhitening, which indexed the spectrum truncated tooutput_dims(or raisedIndexErrorbelow-output_dims), is no longer accepted.MKDDescriptornow raises aShapeError(aValueError) for patches that are not(B, 1, patch_size, patch_size); a patch of another size used to fail deep inside with torch's broadcastRuntimeError, a three-channel patch with aValueErrorthat reported five channels, and an input that is not 4-D with a plainValueError.laf_is_valid,get_laf_scaleandmake_uprightformed products of two LAF entries in float16, which broke every float16 LAF for which such a product exceeds 65504. Any LAF of scale 256 px or more was reported invalid, had aninfscale and ananupright frame;make_uprightalready overflowed for an elongated LAF whose first row is 256 px or longer (300 x 20 px, a scale of 77 px), for whichLAFAffineShapeEstimatorreturned aninfframe. They now compute in float32 for float16 LAFs and return the mask, scale and frame as before; float32, float64 and bfloat16 results are unchanged. With it,LAFAffineShapeEstimatorandLAFAffNetShapeEstimatorestimate such a float16 LAF instead of returning a zero-shape orinfframe (or the input unchanged withpreserve_orientation=True), andSIFTFeatureScaleSpacewithdescriptor_backend="pyramid"describes it instead of returning the zero descriptor of a padded slot.get_laf_descriptorsandLAFDescriptorraisedRuntimeError: view size is not compatible with input tensor's size and stridewhen the descriptor module returned a tensor whose per-patch dimensions are not contiguous, such as a transposed block or a channels-last convolution output; the output is now reshaped instead of viewed. (#5834)LightGlueandLightGlueMatcherwith point pruning on (the defaultwidth_confidence=0.99, and thesuperpoint,disk,aliked,raco-aliked,dedodeb,dedodeg,siftandxfeatfeature types) raisedRuntimeError: Index put requires the source and destination dtypes matchfor float64, float16 and bfloat16 models, and for float32 models withmp=Trueon CPU, where autocast computes the scores in bfloat16. This happened at any number of keypoints, because the scores are scattered back whenever pruning is enabled. Pruning now keeps the dtype the scores are computed in: the input dtype, or withmp=Truethe dtype autocast gives them, bfloat16 on CPU and float32 on CUDA and MPS. The early return for every point pruned now gives its zero scores in that dtype as well. The early return for an image without descriptors runs no layer and gives the input dtype, so withmp=Trueon CPU its scores are float32 while the other paths give bfloat16. Both early returns gave float32 before. Withoutmp=True, float32 results are unchanged. (#5837) (#5838)AugmentationSequentialwith aVideoSequentialchild accepts non-contiguous video keypoint and box tensors, clips with no keypoints or boxes, and empty batches, andVideoKeypoints/VideoBoxeskeep those shapes throughfrom_tensorandto_tensor. Each of these used to raise aview/reshapeRuntimeError. (#5840)Keep pretrained
SOSNetandHyNetfloat16 descriptors accurate, called directly or throughget_laf_descriptorsandLAFDescriptor, by preserving final BatchNorm statistics and avoiding overflow in filter response normalization.FilterResponseNorm2dnow computes bfloat16 inputs in float32 too, which brings pretrainedHyNetbfloat16 descriptors closer to float32. Convert models to float16 before scripting them. (#5842)So2.inverse(), and soSe2.inverse(), now run on CPU float16 rotations, where they raisedNotImplementedErrorbecause the CPU has no ComplexHalf reciprocal: the reciprocal is computed in complex64 and returned in the input dtype. On MPS, float16 inverses of rotations scaled far from unit length no longer return 0 or NaN, and inverses of unit rotations are more accurate. (#5843)The README and precision-guide half-precision tables no longer say that
dice_lossaveraging overflows in float16: the overflow was in the float16 reference value of its tests, not in the library. (#5844)AugmentationSequentialannotation-only replays andinversecalls now recompute a geometric child's transform matrix when a value in the params dict was replaced or edited in place after the image call, instead of reusing the image call's matrix (#5846). (#5854)AugmentationSequentialcalled with a dictionary now converts a PIL image or an image file path under an image key (input,image) as it converts the same value given positionally, instead of failing withAttributeError. A path under an image key that does not exist raisesFileNotFoundError. (#5855)filter2d,filter2d_separableandfilter3daccept an empty batch with an empty per-sample kernel, sogaussian_blur2dwith a(0, 2)sigma,motion_blur,motion_blur3d,RandomGaussianBlurand fixed-sizeRandomMotionBlurandRandomMotionBlur3Dreturn an empty batch instead of raisingRuntimeError: cannot reshape tensor of 0 elements. Ranged motion-kernel sampling remains outside this fix. Part of #4429. (#5857)Palette PNGs with an empty transparency chunk now load with opaque palette entries. (#5858)
OnnxLightGlue(device=None)no longer raises torch'sTypeErrorfromtorch.device(None).Noneis now treated as"cpu", as in the other kornia feature constructors, and thedevicedocstring says so. (#5859)match_adalam,GeometryAwareDescriptorMatcher("adalam"),AdalamFilter.match_and_filterandAdalamFilter.filter_matchesnow return their outputs in the usual order when nothing matches: with fewer than two descriptors on either side, or when no seed survives and no ratio-test match remains,match_adalamused to return the(0, 2)int64 indices first and the(0, 1)float32 distances second, andAdalamFilter.match_and_filter, andAdalamFilter.filter_matcheswhen no seed survives, returned the float(0, 1)tensor as their indices.match_fginnnow masks out the candidates withinspatial_thof the nearest neighbour when it picks the second neighbour, so the ratio no longer depends on the scale of the distances. It used to add1e6to their distance, so with distances of that order, such as squared distances between unnormalised SIFT descriptors, one of them could still be the second neighbour. When every candidate is withinspatial_th, the match is accepted with ratio0; it used to be the nearest distance over the second-nearest plus1e6, which is close to0only for small distances. (#5860)decompose_essential_matrix_no_svdno longer returns NaN gradients when the translation is perpendicular to a column of the rotation, for example a stereo rig or forward motion without rotation, or planar motion that rotates about the camera's y axis and translates perpendicular to it. Its outputs are unchanged. (#5876)kornia.contrib.histogram_matchingsums the histogram counts inint64and computes the quantiles infloat32(float64for afloat64source) instead of in the input dtype. Auint8sum wrapped past 255 and anint16sum past 32767, so a 50x50uint8image mapped to values above 255 and a 64x64 one to NaN everywhere;float16andbfloat16sums stopped being exact past 2048 and 256 pixels, and about half of random image pairs at those sizes returned NaN pixels.kornia.contrib.interpreturns the right endpoint on a zero-width last segment instead of NaN, which a template of more than 2**24 pixels could produce infloat32. (#5878)LoFTR.forwardis faster and needs less peak memory: it cuts fine-level windows only at the matched cells, selects coarse matches from row and column maxima, runs the coarse-level linear attention as dense matrix products, and computes the dual softmax without PyTorch's slowsoftmax(dim=1)kernel outside float16. On 1024 px image pairs from the IMC 2021 PhotoTourism validation set (RTX 4090, float32), inference was about 1.3x faster with 30 % less peak GPU memory. Outputs change at rounding level, and coarse match selection differs only when a row of the confidence matrix has two exactly equal maxima. (#5879)AdaptiveDiscriminatorAugmentationaccepts the dictionary input its signature allows. No dictionary reached the augmentations: a plain call raisedValueErrorbecause the preset always setsdata_keys,forward(..., data_keys=...)with the dictionary's own keys raised the same error whenever a sample was drawn, andforwardwithoutdata_keysraisedKeyError: 'IMAGE'unlesspwas 0. The dictionary's keys now name the data, the same samples are augmented in every entry, and an entry that names no data key is returned unchanged. Whenpis above 0,data_keyspassed with a dictionary must name the same data keys, in any order, or aValueErroris raised. (#5882)ONNX exports of
pyrdown,PyrDown,build_pyramidandrescalewith a dynamic height or width now follow the input size instead of returning the output size of the traced input. Where the exported graph computes the size in float32 (rescaleunder both exporters,pyrdownunder the dynamo exporter), a factor that is not a power of two can be one pixel off eager (rescale0.7 at a side of 90,pyrdown1.1 at a side of 33); therescalemodes that stay static are listed in its docstring. (#5883)AugmentationSequential.inverseno longer raisesIndexErrorwhen aVideoSequentialchild withp < 1skips some frames of a video bounding-box batch: the inverse now lands on exactly the frames that were transformed.VideoBoxesindex assignment (video_boxes[key] = other) no longer raises for clips with no boxes. (#5884)resize,Resize, andrescalenow support antialiased downsampling of images with a single row or column. (#5889)guided_blurandGuidedBlurconvert integer and bool images to float32 before covariance products, avoiding wrapped products and dtype errors while preserving the original image scale. (#5890)total_variationwithreduction="mean"now returns finite values for one-row and one-column images, with axes that have no adjacent pixels contributing zero. (#5891)warp_affine3draisedValueError: Expected non-zero, positive output sizefor an empty(0, C, D, H, W)batch, and so did everything built on it:affine3d,rotate3d,crop_by_transform_mat3d,RandomAffine3D,RandomRotation3D,CenterCrop3DandRandomCrop3D. They now return an empty batch of the requested output size, connected to both inputs for backward. (#5892)Rt_to_matrix4x4,camtoworld_graphics_to_vision_Rtandcamtoworld_vision_to_graphics_RtraiseValueErrornaming the dtype whenRandtpromote to an integer or boolean dtype. They used to raise torch'sRuntimeError: result type Float can't be cast to the desired output type Long(orInt,Bool, ...) from inside the 3x4 to 4x4 homography conversion, so code that caught thatRuntimeErrorhas to catchValueErrornow. Pairs that promote to a floating point or complex dtype, mixed integer/floating pairs included, return the same matrices as before. (#5894)A float32
LightGluewithmp=Trueon CPU now gives bfloat16 zero scores when point pruning removes every point, for every feature type, like the scores of the same model when it keeps points. Withinput_dimequal todescriptor_dim(thesuperpoint,dedodebanddedodegfeature types, andLightGlue(None)by default), it gave float32matching_scores0,matching_scores1andscoresthere before, andLightGlueMatcherreturned its empty scores in float32. (#5877) (#5896)A misspelt name given to the
.getof akornia.constantsenum (Resample,BorderType,SamplePadding,DType,DataKey), and an unsupportedtorch.dtypegiven toDType.get, now raise an error that names the value and lists the valid names. This covers thekornia.augmentationarguments that are looked up in these enums, such asresampleandpadding_modeofRandomAffine,border_typeofRandomGaussianBluranddata_keysofAugmentationSequential, and theformatofkornia.contrib.object_detection.results_from_detections. The error is aValueError, like the one for an out-of-range integer, and still aKeyError. A value of the wrong type raises aTypeErrorthat names the enum and the value, instead of listing every member of both enums. (#5908)kornia.filters.guided_blurandGuidedBluraccept an empty batch with a multichannel guidance. They raisedRuntimeError: cannot reshape tensor of 0 elementsbecause the input channel count was inferred with-1, which an empty tensor cannot provide; this happened both when the guidance is the input and when it is a separate tensor. (#5909)kornia.core.utils.dict_to_dataclassnow converts nested dicts in fields annotatedOptional[...], other unions,list,tupleanddictof a dataclass, and in string annotations (including modules withfrom __future__ import annotations), and keeps a value that is already an instance of the field's dataclass instead of raisingTypeCheckError. The API reference now renders thekornia.core.utilsdevice and autocast helpers that thekornia.utilsdeprecation warnings point to. (#5910)kornia.onnx.utils.ONNXLoadercaches every remote file under a path of its own.HFONNXComunnityModelLoader.load_preprocessing, whichDepthAnythingBuilder.buildcalls, caches each repository'spreprocessor_config.jsonbeside its model in<cache_dir>/<model_name>/; every repository used to share<hub_cache_dir>/preprocessor_config.json, so a model built after another one could load the other model's preprocessing.ONNXLoader.load_model("hf://<folder>/<a>/<b>")caches<a>/<b>.onnxinstead of<a>.onnxfor every model under<a>.load_modelandload_configcache a URL at<scheme>/<host>/<directories of its path>/<file name>undercache_diror the default directory, with%3A<port>after the host when the URL has a port and a%3F<hash>directory before the file name when it has a query. A URL used to be cached under its last path component alone, query included, so two URLs that ended in the same file name, such as theonnx/model.onnxof two onnx-community repositories, shared one file. Files cached under the old names are neither reused nor moved, since they may hold another file's content: the affected configs and models are downloaded once more, and the old files,<hub_cache_dir>/preprocessor_config.jsonamong them, can be deleted. The ONNX models ofHFONNXComunnityModelLoaderandDepthAnythingBuilder, andhf://<folder>/<name>models, keep their cache paths.kornia.onnx.download.CachedDownloader.downloadanddownload_to_cacheaccept a path without a directory part, which is a file in the working directory (orcache_dir=""), instead of raisingFileNotFoundError.kornia.io.get_sample_imagestakes its download timeout fromKORNIA_DOWNLOAD_TIMEOUT(30 s when it is unset), as kornia's other downloads do, instead of always using 30 s. (#5911)The deprecated
kornia.utilsnames and the deprecated top-level aliases such askornia.create_meshgridwork as the 0.8.2 functions did again.kornia.utils.<name>resolves after a plainimport kornia, where it raisedAttributeErrorunlesskornia.utilshad been imported first, and the 0.8.2 pathkornia.utils.sample.get_sample_imagesis back as a deprecated alias. Each shim takes the signature of the function it forwards to, soinspect.signatureandhelp()show the real parameters. Code that calls a shim compiles withtorch.compile(fullgraph=True)and scripts withtorch.jit.scriptwherever the function it forwards to does: the deprecation warning is skipped while a graph is captured and inside TorchScript, and eager calls still warn.kornia.losses.one_hotscripts withtorch.jit.script.torch.load(..., map_location=kornia.utils.map_location_to_cpu)warns at the line that calledtorch.load, so the default warning filters show it there once.from kornia import to_jax, and the same forto_numpy,to_tensorflowandkornia.transpiler, imports again, and calling the name raises theRuntimeErrorthat explains the removal instead of a bareImportError. The deprecation messages no longer say that thekornia.utilsmodule has been removed. (#5912)KMeans.cluster_assignmentsnow uses the final cluster centers, matchingpredicton the training data when fitting stops before assignments have converged. (#5922)RandomMotionBlurandRandomMotionBlur3Dwith a rangedkernel_sizeaccept an empty batch and return it unchanged. They raised before the blur ran because they choose the batch's kernel size from the sampled sizes, of which an empty batch has none:RandomMotionBlurwithIndexError: list index out of rangeandRandomMotionBlur3DwithRuntimeError: a Tensor with 0 elements cannot be converted to Scalar. (#5923)SOLD2.matchnow returns an int64 tensor when either set of segments is empty (it returned int32), andXFeat.detectAndComputeDensewithmultiscale=Trueno longer returns every cell of a scale whose share of a small positivetop_krounds down to 0: the budget is splitint(0.2 * top_k)/ the rest, so for a positivetop_kthe result never exceeds it (zero and negative values still keep every cell) (a defaulttop_k=4096now yields 4096 keypoints instead of 4095 on images with enough cells). (#5926)LightGluematches a batch of image pairs with point pruning, which is on by default, instead of raising anIndexError: each pair gives the matches and scores it gives on its own, and a batch that can prune runs its pairs one at a time. A batch with too few keypoints for pruning to start (on CUDA, 1536 by default) no longer raises either, and early stopping ends such a batch once every pair meets its own criterion, rather than counting the unconfident points of all pairs together. A float16 model withmp=Trueon CPU now autocasts to float16 and returns float16 scores, instead of raising aRuntimeErrorin its first layer, or with"keynet_affnet_hardnet"already when it reads the LAFs. (#5928)So3.matrix()(andadjoint()),So3 * So3,So3 * points,Se3 * Se3andSe3 * pointsnow compute in float32 for float16 and bfloat16 inputs and return the input dtype, rounding once;Se3.matrix()andSe3.inverse()follow throughSo3. Evaluated in half precision, each drifted 3 to 6 units of roundoff from the exact result, and identities such asR.T @ R == I,(s * s.inverse()).t == 0and chained point transforms missed by up to about 12 units; they now hold to about 2. float32 and float64 results are unchanged. Building a bfloat16So2orSe2(exp,identity,random,from_matrix,Se2.trans,trans_x,trans_y, and aNamedPoseof anSe2pose) used to fail insidetorch.complexwith aRuntimeError, since PyTorch has no complex bfloat16 dtype; it now raisesTypeCheckErrornaming the limitation..bfloat16()on a builtSo2orSe2keeps working and keeps the rotation's complex precision. (#5936)kornia.color.apply_colormapandkornia.color.ApplyColorMapaccept empty tensors. An empty batch or an empty channel dimension raisedRuntimeError: cannot reshape tensor of 0 elements, and a floating image with zero height or width raisedIndexErrorfromamax. They now return an empty tensor of the documented(B, 3*C, H, W)shape. Non-empty outputs are unchanged. (#5937)DeDoDe()with the defaultamp_dtype=torch.float16now runsdescribeandforwardon CPU and MPS with float32 weights and images instead of raisingInput type (c10::Half) and bias type (float) should be the same.amp_dtypeis CUDA mixed precision in every component: theGdescriptor's DINOv2 backbone is cast to it only for CUDA inputs, and on other devices follows the dtype of the input (a float32 backbone stays float32, a.half()model gets a half one), so a.half()or.bfloat16()model with a differentamp_dtypealso runs there now. The CUDA path casts on the host and then moves the backbone, as before; the one difference is that the cast happens at the first CUDA call instead of at construction, so about 0.6 GB more host memory is held in between. (#5939)AdaLAM now retains well-supported exact local affine correspondences, including self-matches and noise-free translations, while discounting repeated keypoints and the points used to fit each hypothesis. (#5941)
ImageStitcher.postprocessnow removes only the empty columns at the right edge of the mask, and keeps every column that has a covered pixel in any sample. It used to cut at the first empty column. A full-height gap in the mask, such as an invalid column in astitch_pairmask or a pair of images that do not overlap, dropped every column after the gap. A first column with no covered pixel made it return the full width, empty columns included. Masks whose covered columns start at the first column and have no gap, such as thoseforwardbuilds for overlapping images, give the same result as before. (#5942)ObjectDetector.visualizeandObjectDetector.saveaccept supplied detection tensors, including tensors with no detections, without raising an ambiguous truth-value error. (#5945)unsharp_maskandUnsharpMaskfilter an integer or bool image in float32 and return float32 on its own scale, likegaussian_blur2d, instead of raising a dtype error. (#5946)render_gaussian2devaluates float16meanandstdin float32 and returns the heatmap in float16. A narrow float16 Gaussian, such as a one-pixelstdin normalized coordinates on a grid more than about 550 pixels wide, used to return a NaN heatmap and NaN gradients. (#5948)warp_grid,warp_grid3d,homography_warp(with the defaultnormalized_homography=True),HomographyWarper,homography_warp3dandwarp_perspective3dnow give the same result fors * Has forH, apart from grid points whose homogeneous coordinate is still within1e-8of zero after the matrix is rescaled. A homography and any nonzero multiple of it describe the same projective map, but the grid passed every point with|w| <= 1e-8togrid_sampleundivided, so the arbitrary scale of the matrix changed the output without a NaN or an error: for a homography with entries between 0.01 and 1,1e-8 * H(1e8 * Mforwarp_perspective3d, which inverts its pixel matrix first) differed fromHby up to 0.50 of the image range in float64. The grid warps now divide the matrix by the detached projective scale #5752 introduced forwarp_perspective, so gradients followdL/d(s*H) = (dL/dH)/s. A matrix whose nonzero entries all have magnitude above 1, or all below 1, changes its results at rounding level; any other matrix, such as one withH[2, 2] = 1, gives bit-identical results.warp_perspective3drescales the normalized inverse of its pixel matrix, so its results can change at rounding level even whenM[3, 3] = 1. (#5949)kornia.geometry.bbox.transform_bboxaccepts zero boxes and an empty batch. A(0, 4)box tensor, or a(0, N, 4)or(0, N, 4, 2)batch, raisedRuntimeError: cannot reshape tensor of 0 elementsand now returns an empty tensor of the input's shape. Non-empty results are unchanged. (#5950)combine_tensor_patchesandextract_tensor_patchesnow recombine and extract patches exactly:- An all-zero padding or unpadding tuple such as
(0, 0)or(0, 0, 0, 0)no longer switches offallow_auto_padding/allow_auto_unpadding: a 5 x 7 image with 2 x 2 windows gave 6 patches and dropped the last row and column, and now gives the same 12 patches aspadding=0. combine_tensor_patchesdivides each covered pixel by its exact overlap count instead ofcount + eps, so afloat64value of1000.0is no longer returned as999.99999. Pixels no patch covers are0, whereeps=0gavenanat them and a negativeepsgaveinfat singly covered pixels.combine_tensor_patchesrecombines integer patches inint64without overflow, so16777217is no longer returned as16777216and2**63 - 2no longer as2**63 - 1: the overlap mean is exact for every integer value and truncates toward zero. On MPS this needs torch 2.9 or newer: older torch keeps the float32 sum, exact up to 2**24. Complex patches are folded as complex instead of losing their imaginary part.combine_tensor_patchessumsfloat16andbfloat16patches infloat32: 289 overlapping values up to 255 overflowed toinfinfloat16and were off by 64 inbfloat16.- The
epsargument ofcombine_tensor_patchesis deprecated and has no effect; a value other than the default used to change every recombined pixel. Passing it emits aDeprecationWarning.
histogram_matchingandinterpnow return exact values:interpreturnsfpexactly at a knot, andnp.interp's5.0instead of6.0left of a repeated first knot (interp([-1, 0, 0.5], [0, 0, 1], [5, 6, 7])).- Matching an image to itself is the identity (132 of 5328
float32and 178 of 5328float64pixels used to change),[3, 1, 2]matched onto[10, 20, 30]gives[30, 10, 20]instead of[29.999998, 10, 20](which became29asuint8), and afloat32result no longer leaves the template's range by one ulp. - An empty source returns an empty tensor of the same shape instead of raising
IndexError. interpkeeps non-finitefpvalues asnp.interpdoes:interp([0.5, 1, 1.5, 2], [0, 1, 2], [3, 4, inf])gives[3.5, 4, inf, inf], where it used to give[3.5, nan, inf, inf].interpreturnsnanfor ananquery on a repeated last knot, asnp.interpdoes:interp([nan], [0, 1, 1], [5, 6, 7])gave7.0.interpsubtracts integer coordinates inint64:uint8x = [0, 3]withxp = [1, 2]andfp = [10, 20]gives[0, 30]instead of the wrapped[5120, 2590].
(#5960)
- An all-zero padding or unpadding tuple such as
connected_componentsaccepts batches that cannot be viewed as one block (for example permuted leading dimensions) and inputs withH = 0orW = 0, which used to crash.KMeans.fitwithtolerance=0.0now stops at the fixed point instead of never returning, and a secondfitsamples fresh initial centres from its own data (it reused the first fit's centres, and raised for data of another dimension) unless explicitcluster_centerswere given. Distances infitandpredictare computed in at leastfloat32(and in the promoted dtype of data and centres), sofloat16squared distances no longer overflow toinfand pick cluster 0. Integer data against integer centres is handled inint64: it was compared and summed in the narrow integer dtype, which wraps (uint8data: the mean of 200 and 210 came out as[77, 77]), and the convergence shift wrapped the same way, so the fit could stop while the centres were still moving.predictchecks that its input is 2-D.Lambdanames the right argument (func) in its non-callable error message; it used to name a non-existentlambdargument. (#5961)kornia.contrib.diamond_square, and soRandomPlasmaBrightness,RandomPlasmaContrastandRandomPlasmaShadow, now generate an unbiased map. The seed divided its corners and centre by three, took the wrong corner for the right-edge midpoint and never interpolated the interior row-1 points of an elongated seed, and the square step at the border over-weighted a neighbour. A 9x9 map averaged 0.167 at the corners and the centre, 0.611 at columns 3 and 5 of the border rows and columns, and 0.39 to 0.48 in the interior (row 0:[0.167, 0.503, 0.500, 0.611, 0.500, 0.611, 0.500, 0.503, 0.167]), so a plasma brightness or shadow map darkened the corners and the centre of every image; the expected mean map is now a flat 0.5 fortorch.randwithrandom_scale=1, and an unnormalized map stays in [0, 1] fortorch.randwhenrandom_scaleandroughnessare in [0, 1]. The diamond and square centres are chosen by index parity, so a signedrandom_fnsuch astorch.randnno longer leaves most pixels at zero; a tensorroughnessorrandom_scalefollows the requesteddtypeanddevice; and an integernormalize_rangesuch as(0, 1)is accepted. The random numbers are drawn in a different order, so a fixed seed gives a different map than before. (#5964)HomographyTracker.set_targetnow extracts the target's features once forLoFTRandLocalFeatureMatchermatchers and reuses them for every frame, where they were extracted again on every frame; a matcher replaced afterwards, or a target assigned directly, gets the target extracted again, once, where a customextract_featuresmatcher was passed the replaced matcher's or the old target's cached entries. The target is extracted without gradients, so aLocalFeatureMatchertracker no longer passes gradients to the target, as it did when it extracted the target on every frame.set_target, or a target assigned directly, also starts a new track, where the previous homography, which maps the old target's coordinates, was kept. Fewer than 4 matches count as a failed match instead of reaching RANSAC, which raised.ImageStitcherwarps its validity mask bilinearly, so a sub-pixel shift no longer leaves a dark seam or an extra dark column, and half images are warped in float32 internally (transiently), so half panoramas on MPS lose their dark border pixels and float32 keypoints with half images no longer raise.kornia.contrib.auditaccepts(B, H, W)masks, which raised aValueErrorsaying the inputs must be batched. (#5965)Float16 and bfloat16
LoFTR,DISK,ALIKED,ScaleSpaceDetector,MultiResolutionDetectorandSIFTFeatureScaleSpace(both backends), withKeyNetDetectorand theLocalFeaturepresets built on them, now return float32 keypoints and LAFs, formed in float32 where they are computed; scores, responses, confidences and descriptors keep the model's dtype. In bfloat16 the coordinates were rounded to a 2 px grid above x = 256 and a 4 px grid above 512, and in float16 to a 0.25 px grid above 256. A half-precision module fed these coordinates directly has to cast them:LightGluenow accepts float32 keypoints with a float16 or bfloat16 model (it raisedexpected m1 and m2 to have the same dtype), andLocalFeatureMatcherreturns the same keypoint and LAF dtype whether or not a pair matches (it returned half keypoints and LAFs when no pair matched and float32 ones otherwise).ImageStitcherwith a float16 matcher andestimator="vanilla"could give a NaN panorama, because the DLT ran on float16 keypoints; it now runs on float32 keypoints. (#5966)RandomJPEGaccepts an empty batch and returns it unchanged. It raisedValueError: Invalid input tensor, it is empty.before the codec ran, because the differentiable JPEG codec rejects an empty input. (#5972)When the samples
x1and the bin centres ofhistogram2dpromote to float16 or bfloat16, it now evaluates them in float32 and casts the result back to that dtype. In float16 the joint histogram of an ordinary input, such as a 128x128 image or 1024 samples with a 0.2 bandwidth, used to come back all zero or NaN; the histogram and its gradient now follow a float64 reference. (#5973)spatial_gradientandsobelnow differentiate an integer or bool image in float32 instead of raising, matchingspatial_gradient3d. They cast the Sobel kernel to the input dtype before, so inuint8,int16orint32the call failed, and withnormalized=Falsean integer accumulation wrapped silently instead. (#5974)kornia.io.write_imagerejects an image whose height or width is zero with aShapeErrornaming the shape, before the file is created. It used to reach kornia-rs, which raised a bareExceptionand left a truncated file behind (#5770). (#5975)find_homography_lines_dltandfind_homography_lines_dlt_iteratedreturn an empty(0, 3, 3)batch for an empty batch of line segments, asfind_homography_dltdoes, instead of raising areshapeerror. (#5976)StereoCamera.reproject_disparity_to_3Dandkornia.geometry.camera.stereo.reproject_disparity_to_3Dreturn an empty(0, H, W, 3)point cloud for an empty batch of disparity maps, instead of raising areshapeerror. An empty rig has been accepted since #4281. (#5979)2D intensity augmentations whose arithmetic assumes unit-range images now clamp their input into
[0, 1]before operating, as well as their output. This fixes the NaN thatRandomGammareturned for a negative input and a non-integer gamma,RandomPosterize's platform-dependentuint8conversion of out-of-range values, and the negative valuesRandomPlanckianJitterkept.RandomEqualizeandRandomClaheclamp an out-of-range input instead of raising;kornia.enhance.equalizeandequalize_clahestill raise.RandomHue,RandomSaturation,RandomSnow,ColorJiggleandColorJitter(also with neutral or hue-only steps), andRandomPosterizeatbits=8used to pass out-of-range values through and now clamp them. Range-independent augmentations (blurs, noise, channel operations, erasing, grayscale, inversion,Normalize,Denormalize,RandomAutoContrast) and samples skipped by the probability gate keep their values;RandomBrightnessandRandomContrastkeep the unclipped arithmetic withclip_output=False. (#5980)adjust_brightness,adjust_brightness_accumulative,adjust_contrast,adjust_contrast_with_mean_subtraction,adjust_saturation_with_gray_subtraction,adjust_gamma,adjust_sigmoid,adjust_log,posterize,solarize,sharpness,shift_rgbandjpeg_codec_differentiableraiseTypeCheckError(aTypeError) for an integer image, with a message that names the conversion (image.float() / 255). Previously eleven of them returned a saturated, wrapped or negative result for auint8image without an error, and the other two raised an unrelated PyTorch error. Floating-point input is unchanged, and the check is skipped underdisable_checks(). (#5983)The image and mask inverse of the 2D crops also changed in resample mode. With
align_corners=True,CenterCropandRandomCropspread a crop with a one-pixel axis over the whole canvas axis, and now paste it back.RandomResizedCropwith a one-pixel output or crop axis and corner alignment returned NaN in resample mode, and now samples the crop's first row or column (or repeats a one-pixel crop), as slice mode does.RandomCropinverted an oversized crop (larger than the padded canvas) without its scale, returning the top-left corner of the upscaled crop, and now scales it back. Its mask inverse raisedValueErrorwhen the imagefillhad one value per channel, and now removes the added padding without a fill and pads a border that negativepaddingcropped with zeros. (#5984)image_histogram2dnow returns float32 counts and pdf for float16 and bfloat16 images, with automatic centers or centers of the image dtype, instead of the image dtype; cast the result if you need the image dtype. In float16 a bin count above 65504, such as the black half of a 512x512 image, used to becomeinfand its pdfNaN, and bfloat16 counts were rounded (66048 instead of 65998). The 1-Dhistogramnow evaluates float16 and bfloat16 kernels in float32 and still returns the input dtype: at 65536 samples, 64 bins and bandwidth 0.01 its float16 gradient had a 34 % relative error against float64 and now follows it. (#5988)median_blurandMedianBlurfilter an integer or bool image in float32 and return float32 on its own scale, likebox_blur, instead of raising a dtype error. (#5989)find_homography_lines_dltandfind_homography_lines_dlt_iteratedraiseAssertionErrorfor fewer than four line segments, asfind_homography_dltdoes for fewer than four points. Previously they returned an arbitrary homography from the under-determined system (all NaN for zero segments) without an error. (#5993)LightGlue now uses math attention for CPU float64 inputs on Windows with PyTorch 2.5, avoiding corrupted attention outputs, premature stopping, and incorrect point pruning. (#5994)
find_homography_lines_dlt_iteratedaccepts unbatched(N, 2, 2)line segments and treats them asB = 1, asfind_homography_lines_dltdoes. Previously it solved once and then raised aShapeErrorfromline_segment_transfer_error_one_wayin its re-weighting step. (#5996)Reduce scalar gamma adjustment overhead, batch confusion-matrix accumulation, skip settled distance-transform inference iterations, avoid dense one-hot intermediates for unweighted reduced focal loss, and reuse sampling grids for shared non-trainable rotation and affine transforms. Preserve TorchScript gamma adjustment and dynamic image/angle batches in rotation traces. Keep real-mode FX capture static and preserve affine-warp empty-batch validation in traces. (#5997)
Rescaleworks withinterpolation="nearest","nearest-exact"and"area". Previously its defaultalign_corners=Truewas passed totorch.nn.functional.interpolate, which rejects any value butNonefor these modes, so every call that did not passalign_corners=NoneraisedValueError.align_cornersnow applies to thebilinearandbicubicmodes only, whose results are unchanged; the other modes ignore it, an explicitalign_corners=Trueincluded. (#6010)AugmentationSequentialnow propagates all three output spatial dimensions afterCenterCrop3DandRandomCrop3D, so later transforms generate parameters for the volume they actually receive. Previously, later 3D crops,RandomAffine3DandRandomPerspective3Ddrew their parameters for the original D/H/W even for nonempty batches: a later crop could read outside the cropped volume and return zero-filled voxels, and one larger than the cropped volume returned such a zero-filled result where it now raises the sameValueErroras a direct call. Statically applied empty crops also propagate their configured size. This corrects newly generated parameter sequences; previously saved coordinates and shape history are not recalculated. Part of #4429. (#6011)resize,Resize,rescaleandRescaleraiseValueErrorforinterpolation="linear"and"trilinear", with a message that names the supported modes, and so doresize_to_be_divisible, andcrop_by_indiceswhen a crop has to be resized. Their docstrings no longer list these two modes. Every input is resampled as a 4-D(B, C, H, W)batch, whichtorch.nn.functional.interpolaterejects for them, so these modes previously raised its rawNotImplementedError("Got 4D input") for every input; only a target size with a zero side returned an empty tensor, and it now raises too. The other modes are unchanged. (#6013)The weighted builders of
kornia.modelsreturn the model in evaluation mode:Sam.from_configwithpretrained=Trueor acheckpoint(and soVisualPrompterwith such a config),RTDETR.from_pretrained,RTDETR.from_configwith acheckpoint,TinyViT.from_configwithpretrainedand the checkpoint's class count,EfficientViT.from_config,VisionTransformer.from_config(pretrained=True),SigLip2Builder.from_pretrained_hfandKimiVLBuilder.from_pretrained_hf. They returned training mode, so MobileSAM, RT-DETR, TinyViT and EfficientViT normalised with batch statistics, an image's output depended on the rest of the batch, and inference overwrote the BatchNorm running statistics; TinyViT-11M and -21M also dropped residual paths at random. Randomly initialised models stay in training mode, and so does a pretrained TinyViT whose classification head is reset to zeros becausenum_classesdiffers from the checkpoint's, includingpretrained="in22k"(a 21841-class head) with the defaultnum_classes=1000: passnum_classes=21841, or call.eval()before extracting features. Code that fine-tunes a model returned by one of these builders must now call.train()first, or BatchNorm keeps its running statistics frozen and, in TinyViT-11M and -21M, DropPath stays off. After loading your own weights, call.eval(). TinyViT's attention bias is no longer cached ateval(), soload_state_dict, a parameter update, or.to()/.half()/.bfloat16()aftereval()no longer gives a stale bias (wrong logits) or a device/dtype error. The cache was filled without gradient, so in evaluation modeattention_biasesreceived none, and fine-tuning with BatchNorm frozen through.eval()silently froze them; they now get gradients. (#6014)LightGluebuilt with complete learned weights (afeaturesname, or a localweightsfile) now comes back in evaluation mode, like the otherkornia.featuremodels built with pretrained weights. Missing derived buffers do not prevent evaluation mode, but checkpoints missing learned parameters leave the model in training mode, as doesLightGlue(features=None)without weights. Its output does not depend on the mode. (#6017)equalize_claheandRandomClahenow count, clip and accumulate the tile histograms of float16 and bfloat16 images in float32 on the default (fast) path, and cast only the finished lookup tables back. Before, with clipping enabled, a float16 image whose tiles hold about 65520 or more pixels, such as 2048 x 2048 with the default 8 x 8 grid, came back entirely NaN. Once the per-bin capclip_limit * tile_pixels // 256passed 65504,equalize_claheraised an overflow error on a float16 image instead (and aborted the process on MPS); at the defaultclip_limit=40.0that is any tile above about 419,000 pixels, such as the 8 x 8 grid of a 7680 x 4320 image. Smaller half-precision tiles got lookup tables one or more gray levels off in float16 and several in bfloat16. The lookup tables now equal those of a float32 image that holds the 8-bit levels the lookup reads,(x * 255).long()in the image dtype. float32 and float64 results, and theslow_and_differentiablepath, are unchanged. (#6018)normalize_min_maxpromotes integer and boolean images to torch's default floating dtype before subtracting, asnormalizeanddenormalizealready do. A signed image such as anint8one holding-128and127used to wrap and return values outside the requested range, and a boolean mask raised. (#6022)warp_affine,warp_perspectiveandRandomAffinewithpadding_mode="fill"keep the input's channel count. Afill_valuethat does not broadcast to the warped image without changing its shape now raises aValueErrorthat names both shapes. Previously it was broadcast against the image regardless, so a one-channel image with a three-value fill came back with three channels, and other mismatches raised a raw broadcasting error. Fills that do broadcast, such as a per-sample(B, C, 1, 1)or a per-pixel(B, C, H, W)fill, give the same results as before.warp_perspectivenow defaults to one zero per channel and accepts the same fills aswarp_affine. Previously it substitutedzeros(3)and required a three-value fill, so a one-channel image gained channels even without afill_value. InAugmentationSequential, a per-channelRandomAffinefill_valuepads masks with zero unless the mask sets its ownfill_value, as a per-channelfillalready does, both when augmenting and when inverting. Matching fills give the same results as before. (#6023)torch.exportof anAugmentationSequentialholding aResizewith an integersize, aLongestMaxSizeor aSmallestMaxSizeno longer fails in the container's shape tracking. The integer side length is now converted to the aspect-preserving output size, as the eager path already does, so a later shape-dependent transform such as a resample-mode crop sees the shape it actually receives. (#6027)focal_lossandFocalLossaccept a one-element tensoralphaagain withreduction="mean"or"sum". Since #5997, a(1,)or(1, 1)tensor, or a 0-d one that requires grad, raisedTypeError: new_full(): argument 'fill_value' ... must be Number, not Tensorwhilereduction="none"accepted it, andtorch.compile(fullgraph=True)failed for every tensoralpha. Analphathat is not a Python number takes the dense path again, as before #5997; a Python-numberalphakeeps the reduced path. (#6028)The model
DepthAnythingONNXBuilder.buildreturns resizes each image to the size transformers'DPTImageProcessorcomputes from the model'spreprocessor_config.json: it keeps the aspect ratio, fitting the side whose scale is closer to 1, and makes each side a multiple of 14. The filter is an antialiased bicubic, the one of transformers' DPT image processor (its torchvision backend,torchvision.transforms.v2.functional.resizewithantialias=True), which approximates PIL's resize. The depth is resized back to the image size bicubically, as transformers'post_process_depth_estimationdoes; it was resized back bilinearly. Every image used to be squashed to 518 x 518 with a bilinear resize without antialiasing, so a 16:9 frame was squeezed 1.78x horizontally before the network saw it; a 300 x 400 image now reaches the network at 392 x 518, and a 1080 x 1920 frame at 518 x 924. Every image other than 518 x 518 is now resized by this rule and these filters, so its depth changes. The config parser behind it readskeep_aspect_ratio,ensure_multiple_ofandresample(PIL's nearest, bilinear or bicubic), with the processor's defaults (False,1, bicubic) when they are absent, and raisesNotImplementedErrorfor any otherresamplefilter, which it used to replace with bilinear.DepthEstimationaccepts images of any floating dtype: it runs the graph in float32 and returns the depth in the image's dtype, where a float64, float16 or bfloat16 image raised inside ONNX Runtime or NumPy. An integer image raises kornia'sBaseErrorinstead of ONNX Runtime'sInvalidArgument.DepthEstimation.visualizeandsaveaccept a tensor batch, on which they raisedValueError. (#6030)The mix augmentations (
RandomMixUpV2,RandomCutMixV2,RandomMosaic,RandomJigsaw,PatchMix,RandomTransplantationandRandomTransplantation3D) raise the documentedRuntimeError: Inverse for <Class> is not supported.frominverse(output)andinverse(output, params=...). Previously only a call without positional arguments did; these call forms raisedTypeError: MixAugmentationBaseV2.inverse() takes 1 positional argument but 2 were given. (#6033)The
kornia.morphologyoperators run about 2x faster with less memory on CUDA, and withengine="unfold"on CPU, for a kernel withoutstructuring_elementwhen no gradient is recorded: theunfoldengine masks the windows once and reduces them withamax/amin, without indices. Values are unchanged; as on every engine, anerosionwindow that ties+0.0with-0.0may return either zero. Calls that record gradients, forward-mode AD,torch.functransforms and traces keep the previous reduction. (#6034)Detection, processor and super-resolution wrappers of
kornia.modelsandkornia.contribreturn correct results:DETRPostProcessorscales each image's boxes by that image's own row oforiginal_sizes. It used the first image's size for the whole batch: with sizes[[100, 200], [400, 800]](H, W), the normalised box(0.5, 0.5, 0.25, 0.25)of image 1 came back as[75, 37.5, 50, 25](xywh) instead of[300, 150, 200, 100], soObjectDetectoron images of different sizes misplaced the boxes of every image but the first. The boxes also keep their own dtype when the sizes have another one.RTDETRDetectorBuilder.build(confidence_filtering=False)builds a post-processor that does not filter and returns the(B, Q, 6)tensor; the flag was ignored and the detections were filtered into a list.None, the default, still filters.ResNetDruns on inputs that give an odd feature map, such as 636 x 636, which raisedRuntimeError: The size of tensor a (80) must match the size of tensor b (79): the stride-2 shortcut pools withceil_mode=True, as in the referencepresnet.py.RTDETRthen runs wherever its neck can join the three feature levels, as in the reference: 636 x 636 runs, while 600 x 600 still stops in the neck. Inputs at multiples of 32 give the same outputs as before.rtdetr_r50vd_mdecodes with the third of its six decoder layers (eval_idx: 2in the reference configs of that checkpoint), as the published R50-M model does; it ran all six, which moved its logits by up to 3.5 on a sample image.RTDETRConfiggainseval_idx(Noneselects the variant's layer) andRTDETRHeadaneval_idxargument; an index outside the decoder raises.ResizePreProcessorrecords the original sizes asint64on the images' device. It stored them in the image dtype, so abfloat16667 x 1000 image was recorded as 668 x 1000 and afloat164097 x 2051 image as 4096 x 2052, andResizePostProcessor, as inEdgeDetector, returned a map one row too tall.output_type="pil"in thevisualizeofObjectDetector,EdgeDetector,SuperResolution,SemanticSegmentationandDepthEstimationreturns a list ofPIL.Image.Image, one per(C, H, W)or(H, W)image; it returned NumPy arrays.ModelBase.load_checkpoint(path, device=...)moves the model todevice; the parameters stayed where they were, on the CPU afterdevice=torch.device("mps").SuperResolutionbuilt byRRDBNetBuilderruns a list of images one at a time; a list, even of one image, raisedRuntimeError: Sizes of tensors must match except in dimension 1.save(output_type="pil")raised inSemanticSegmentation,EdgeDetector,SuperResolutionandDepthEstimation(SemanticSegmentation: aValueErrorfor a batch tensor and aTypeErrorfor a list of images; the others: anAttributeErroron the NumPy arrays). It now writes the same files asoutput_type="torch", with the same pixels.
(#6035)
KeyNetandKeyNetDetectorbuild their learnable block withnum_filterschannels per level, so anum_filtersother than the default 8 no longer crashes inforward. The default architecture and the pretrained weights are unchanged. (#6036)HyNet(pretrained=True, is_bias_FRN=False)now raisesValueErrorbefore downloading the weights. Previously it loaded the checkpoint without error but left the trained FRN biases unused, so its descriptors differed from the pretrained ones. Passpretrained=Falseto buildHyNetwithis_bias_FRN=False. (#6037)guided_blurandGuidedBlurnow compute window statistics for float16 and bfloat16 images in float32. With scalar regularization, coefficients are also computed in float32 and only the result is cast back, so a half-precision call returns the float32 result for the same pixel values, rounded once. A float64 tensorepswidens coefficient arithmetic and the grayscale result to float64; multichannel guidance solves in float64 before casting its coefficients back. Before, the local varianceE[I^2] - E[I]^2was formed in half precision, whose rounding at mid-gray (about 2e-4 in float16, 2e-3 in bfloat16) swamped a smalleps: witheps=1e-4on two 512 x 512 test photographs, float16 results were off by up to 1.5 with grayscale guidance and 36 with RGB guidance, gradients came back non-finite, and with RGB guidancetorch.linalg.solvecould fail on a singular matrix. A float16 or bfloat16 multichannel guidance with aninputof another dtype (float32, uint8 or the other half-precision type) raised a dtype mismatch; it now returns float32. Autocast is now disabled inside the filter: a float32 call in an autocast region used to be filtered in the autocast dtype, with the same errors, and returned that dtype with RGB guidance; it now returns the float32 result. float32 and float64 results outside autocast are unchanged. (#6038)VisualPrompter.predict(boxes=...)uses a box prompt given as a tensor; it was dropped, and the prediction was the one without prompts. A(1, K, 4)box prompt is read as the K boxes of the image; for K > 1 it raised a tensor size mismatch, and box prompts for more than one image now raise a clear error instead of a batch size mismatch.VisualPrompterresizes the image as SAM's reference does, withtorch.nn.functional.interpolate(image, size, mode="bilinear", align_corners=False, antialias=True), and keypoint prompts follow the same half-pixel map: it resized withalign_corners=Truewhile the masks are resized back withalign_corners=False, which shifted the masks by up to 0.48 original pixels, and it did not antialias when it downscaled. On a 1380 x 2076 image, the mask IoU against SAM's own pipeline goes from 0.957, 0.966 and 0.943 to 0.969, 0.969 and 0.968. Box prompts are mapped as SAM'sapply_boxesmaps them: kornia'sxyxycorners are pixel edges and scale asx * s, so the box(0, 0, W, H)covers the whole resized image; they went through theBoxesvertex atx2 - 1and the corner-aligned map, which put the box(10, 20, 60, 50)of a 77 x 128 image at(80.55, 161.84, 476.25, 397.51)instead of(80, 160, 480, 400).VisualPrompter.predictandSam.forwardrun in float16, bfloat16 and float64, with or without prompts: the SAM prompt encoder built its positional encoding in float32, and they raisedRuntimeError: expected m1 and m2 to have the same dtype; it now computes the encoding in float32 (float64 for a float64 model), with autocast disabled, and casts it to the dtype of the model. Keypoint and box prompts are mapped to the resized image in float32 (float64 for a float64 model) and handed to the prompt encoder in that dtype, which also shifts them to pixel centres in that dtype.kornia.models.common.LayerNorm2doverflowed in float16 once a value was more than 255.9 from its channel mean, so pretrained MobileSAM gave empty masks in float16; float16 and bfloat16 inputs are now normalised in float32.Sam.from_configbuilds a custom ViT image encoder fromSamConfig(encoder_embed_dim=..., encoder_depth=..., encoder_num_heads=..., encoder_global_attn_indexes=...)withencoder_global_attn_indexesa tuple, a list or an int; it raisedNotImplementedErrorfor a tuple or a list andTypeErrorfor an int. A custom encoder config withpretrained=Trueand nomodel_typeraises aBaseErrorsaying that the released weights need amodel_type; it raisedKeyError: None. (#6040)Image.from_dlpacktakescolor_spaceandchannels_orderarguments, asImage.from_numpydoes, so a channels-last(H, W, C)capsule is read with the right height, width and channels, andImage.from_dlpack(img.to_dlpack(), img.pixel_format.color_space, img.channels_order)round-trips any image. Previouslyfrom_dlpackalways read the capsule as(C, H, W)and labelled it by its channel count, so the round trip of a channels-last image, thefrom_numpydefault, silently swapped its height, width and channels, and aBGRimage came back labelledRGB. The defaults are unchanged, andto_dlpacknow documents that the capsule keeps the image's own layout. (#6041)FaceDetectorflips its input from RGB to BGR before YuNet, whose weights were trained on BGR images. It fed RGB, which found far fewer faces: run on the docs figureyunet.jpgas rendered before this change (421×1185, input and output panels together), the detector now returns 600 detections instead of 221, and 225 instead of 50 above a score of 0.6. The re-rendered figure's title reports 320 faces where it reported 228. The input stays RGB in [0, 255]; the bareYuNettakes BGR in [0, 255]. A caller that already passed BGR, for example acv2.imreadarray, must now pass RGB, since the flip happens inside. An input that is not(*, 3, H, W), such as a 1- or 4-channel or a channels-last image, raises aValueErrornaming that shape from the flip; it raised aRuntimeErrorfrom inside YuNet.EdgeDetectorBuilderfeeds DexiNed BGR in [0, 255] minus the BGR mean[103.939, 116.779, 123.68], the input it was trained on, instead of RGB minus the ImageNet RGB mean; on two street photos this changed 8–11 % of thep > 0.5edge decisions. The input stays RGB in [0, 1].DexiNed(kornia.models.dexinedandkornia.filters.dexined) no longer raises aRuntimeErrorabout an in-place operation in backward; its forward output is unchanged.FaceDetectorResultchecks the last dimension of its data, so(15,)and(N, 15)are accepted and a row of fewer than 15 values raisesValueError. It checked the first dimension, so a(3, 15)tensor raised and a(20, 14)one was accepted until.scoreraisedIndexError. (#6042)The vision-language models of
kornia.modelsfollow their reference implementations in more places:SigLip2Model(..., return_loss=True)returns SigLIP's pairwise sigmoid loss over every image-text pair of the batch, with the matching pairs labelled +1 and every other pair -1. It used only the matching pairs, so the negatives never entered and the loss fell to zero aslogit_biasgrew:0.0on a batch of 4 withlogit_bias = 10, where SigLIP's loss is38.54. The loss pairs the i-th image with the i-th text, so unequal image and text batches raiseBaseErrorwithreturn_loss=True: 3 images with 1 text raisedIndexError, and 1 image with 3 texts returned the loss of its first pair only. Without the loss, unequal batches still give rectangular logits.- The
attention_maskofSigLip2VisionModelandSigLip2Model.get_image_featuresreaches the attention-pooling head as well as the encoder, so the pixels of masked patches no longer change the pooled embedding. For a(B, N, N)or(B, 1, N, N)mask, the head leaves out the patches no query may attend to. - An image whose patches are all masked is pooled by
SigLip2VisionModelwith uniform weights over its patches, as transformers' pooling mask gives: it addstorch.finfo(dtype).minto the masked scores, not-inf. The weights are exactly uniform in float32, float64 and bfloat16. In float16, as in transformers,finfo(float16).minplus a score rounds to a multiple of 32, so they are only roughly uniform, and a head whose scores are all below about -16 gives a non-finite output. - A
(B, N, C)patch output ofNaFlex's patch embedding carries no grid and is read as a square grid, which is silently wrong for a non-square grid (128 x 512 at patch 16) and an error for a token count that is not a square number (192 x 336): pass the newpatch_sizeargument, which gives such an output the grid(H // p_h, W // p_w), or return patch embeddings of shape(B, C, h, w). Withoutpatch_size, the square reading is unchanged, and a token count that is not a square number raisesBaseErrorsaying so, where it raised a shape error or gave wrong values. A float16 or bfloat16 table on the CPU is resized in float32. A position table passed as annn.Parameterstays a parameter of the module and is trained with it; it was registered as a buffer. KimiVLModelandMoonViTapply a(B, N, N)attention mask per sample, shared by the heads. The mask's leading dimension lined up with the attention heads: outputs were wrong when the batch size equalled the number of heads, and batch sizes other than 1 and the number of heads raised.- When the checkpoint of a repository outside its supported list does not fit the configuration
SigLip2Config.from_namereads from the name,SigLip2Builder.from_pretrained_hfraises aRuntimeErrorthat gives that configuration (hidden size, layers, heads, patch size, image size, vocabulary) and lists the supported names. It raisedload_state_dict's bare size-mismatch error. A fine-tune or mirror whose checkpoint fits the configuration read from its name loads as before. An image size in such a name counts only as a whole number, of the repository part after the last/and else of the owner part:org2560/siglip2-base-patch16-384andorg-256/siglip2-base-patch16-384read 384 where they read 256, andx/siglip2-base-patch16-ckpt2560reads 224 where it read 256, whilesiglip384/finetunestill reads 384.
(#6044)
Two corrections in
kornia.contrib:kornia.contrib.distance_transformandDistanceTransformclamp the mask to [0, 1], so a mask with values above 1, such as 0/255, no longer collapses the result to all zeros: every value above 1 counts as a full source, and negative values as background. Mask values outside [0, 1] now get a zero gradient; they had one before, when the mask was used as given. Values in [0, 1], the bounds included, keep theirs.kornia.contrib.diamond_squarewithrandom_scaleother than 1 no longer scales the seed byrandom_scale. The expected value is 0.5 at every pixel withtorch.rand; it was 0.5·random_scaleat the seed nodes and moved towards 0.5 level by level elsewhere (0.25 vs 0.31–0.35 at 0.5).random_scale=1, the default used byRandomPlasmaBrightness,RandomPlasmaContrastandRandomPlasmaShadow, gives the same output as before. Withdtype=None, a float64 tensorroughnessnow gives a float64 map at every size, as a float64 tensorrandom_scalealready did; with onlyroughnessin float64, a map with a side of 3 px or less came out float32 and a larger one float64.
(#6045)
ImageSequentialandAugmentationSequentialaccept integer, boolean and tensorrandom_apply_weights. Previously integer or boolean weights raisedRuntimeError: multinomial only supports floating-point dtypeson every call, and a tensor of weights raisedRuntimeError: Boolean value of Tensor with more than one value is ambiguousin the constructor. Non-floating weights are converted to the default floating dtype, and float weights keep their dtype, so existing selections are unchanged. Weights that are not one-dimensional now raise aValueError; a nested float list used to be accepted and drew a selection per row, sorandom_apply=1applied more than one transformation. (#6050)More vision-language fixes in
kornia.models, following #6044:- Under
torch.autocast, an image whose patches are all masked no longer pools tonaninSigLip2VisionModel's attention-pooling head: the head filled the masked scores with the float32 minimum, which rounds to-infin float16 and bfloat16, and now builds the mask in the dtype the scores are computed in, with that dtype's minimum (a float64 model, which autocast leaves alone, keeps float64's). Such an image gets uniform weights under bfloat16 autocast, as without autocast. Under float16 autocast it gets float16's rounding, as in float16 without autocast: roughly uniform weights, and a non-finite output for a head whose scores are all below about -16. MoonViTAttention,MoonViTandKimiVLModelread a(B, N)attention mask as a padding mask over each sample's keys, asSigLip2Attentiondoes. It went toscaled_dot_product_attentionas anN x Nquery x key mask: a batch size other than 1 andNraised a size mismatch, andB == Nmasked query rows by batch index. An integer mask, such as a tokenizer'sint64padding mask, is read as a boolean one, wherescaled_dot_product_attentionraised for it.NaFlexwarns, namingpatch_size, when it reads a(B, N, C)patch output withoutpatch_sizeas a square grid that takes rectangular patches: 256 tokens of a128 x 512image, the8 x 32grid of #6004 at patch 16, are read as16 x 16. It added the table in that layout silently. A rectangular patch embedding gets the same warning, andpatch_sizesilences it; a square-patch convolution padded by at most half its kernel never gets it. The warning names the line that calls the module.SigLip2Config.from_name,SigLip2Builder.from_nameandSigLip2Builder.from_pretrained_hfread names in any case:Google/SigLIP2-Large-Patch16-384is the supported checkpoint, whichfrom_pretrained_hfdownloads and caches under its listed spelling, andsomeone/SigLIP2-Large-patch16-256the large architecture, where it was read as base. A fine-tune or mirror ofgoogle/siglip-base-patch16-224under another owner, such assomeone/siglip-base-patch16-224-finetuned, gets SigLIP 1's 32000-token vocabulary, where it got SigLIP 2's.
(#6051)
- Under
ScaleSpaceDetector(forwardanddetect) and the patch descriptorsSIFTDescriptor,HardNet,HardNet8,HyNet,TFeatandSOSNetaccept an empty batch and return empty outputs of the documented shapes: responses(0, N)and LAFs(0, N, 2, 3)from the detector, descriptors(0, D)from the descriptors. So doLocalFeature,SIFTFeatureScaleSpaceandget_laf_descriptorson zero images. They raised an unrelated reshapeRuntimeError; an invalid input still raises what the same invalid non-empty input raises. AScaleSpaceDetectorcall on one image with no detected candidates returns responses linked to autograd, so a backward through them gives the input a zero gradient; it used to raise. (#6052)scaleandScalenow accept one isotropic scale factor per image as a(B,)tensor when the batch contains more than one image, instead of raising a broadcasting error. (#6054)Fixes in the vision backbones of
kornia.models:MobileViTraisesValueErrorfor amodeother than"xxs","xs"or"s", where it raisedUnboundLocalError.TinyViT.from_config("21m", ...)builds the"in1k_384"and"in1k_512"checkpoints, named explicitly or picked bypretrained=Truefor animg_sizeof at least 384 or 512, with the window sizes they were trained with,[12, 12, 24, 12]and[16, 16, 32, 16], as the reference TinyViT does. It built them with the 224-px windows[7, 7, 14, 7], so their 12- and 16-px attention biases were bicubic-resized to 7 px without a warning, e.g.(6, 144)to(6, 49)in stage 1. Random init and the other checkpoints keep[7, 7, 14, 7].TinyViT.from_configpassesembed_dims,depths,num_heads,window_sizesanddrop_path_rateto the model in place of the variant's values. Each of them raisedTypeError: ... got multiple values for keyword argument.
(#6056)
ImageSequentialandAugmentationSequentialwith arandom_applyrange that includes 0, such as(0, 2),(0,)or0, apply no transformation when 0 is drawn, a mix augmentation included, and return their inputs unchanged. Previously such a call raisedRuntimeError: cannot sample n_sample <= 0 samples, so a range that includes 0 crashed at random. A negative bound, or an upper bound below the lower one, now raises aValueErrornamingrandom_applywhen the container is constructed, instead of a rawtorch.multinomialortorch.randinterror at call time. Ranges that never draw 0 select exactly as before. (#6057)kornia.contrib.interpcomputes afloat16orbfloat16result infloat32and rounds once, so every half-precision result can differ from before (it was up to about five ulps of the larger end value off in an ordinary segment). Integer coordinates, and half-precision coordinates, with a difference above 65504 no longer overflow the weight:interp(x=100000, xp=[0, 200000], fp=float16 [0, 2])gave NaN,x = 60000andx = 1000gave a silent 0 where the values are 0.6 and 0.01, andfloat16coordinates[-60000, 60000]withfp = [0, 2]gave NaN or 0 where the values are in[0, 2]. An integerxorxpmixed with half-precision coordinates is no longer rounded onto the half-precision grid:interp(x=3001, xp=float16 [3000, 3010], fp=float16 [-40000, 40000])gave -40000 where the value is -32000. A segment whose value difference overflows the half dtype is within about half an ulp of its larger end value, and its knots are exact. (#6059)kornia.enhance.normalizeandkornia.enhance.denormalizeaccept a Pythonintmeanorstdand treat it as the equalfloat, asNormalizeandDenormalizealready did.denormalize(x, 0, 255)andnormalize(x, 0.5, 2)raisedAttributeError: 'int' object has no attribute 'shape'. (#6061)guided_blurpromotes a multichannel guidance to the dtype it shares with the input, so a float16, float32 or uint8 guidance next to a float64 input no longer raisesRuntimeError: expected scalar type Float but found Double. (#6062)Input checks no longer make a dynamic-shape
torch.compilerecompile for each new input size: their messages formatted tensor sizes orintarguments on every call, which specialized them. Over three sizes,get_motion_kernel2d,motion_blur,fft_convwithpadding="valid",gaussian_blur2dwith a varyingkernel_sizeand DeDoDe'sPatchEmbednow compile one graph instead of three,solve_pnp_dlttwo instead of four,jpeg_codec_differentiablefour instead of eight (its quality-range message also read the tensor twice per call, which broke the graph and synchronized with the device in eager mode), andScaleSpaceDetector10 instead of 15. Size checks now raiseShapeErrorwith both sizes, and the messages are no longer built on every call in eager mode. (#6063)Fix
rotate,Rotate,scale,Scale,rotate3dandAffinetreating the channels of an unbatched input as a batch. Multichannel inputs now retain their shape instead of gaining an extra dimension or raising an error. (#6065)SigLip2AttentionandMoonViTAttention, withMoonViTEncoderandMoonViT, check the trailing dimensions of an attention mask: the last one, the keys, must be the sequence length, and in a 3-D or 4-D mask the one before it, the queries, the sequence length or 1. A mask with a key dimension of 1, such as(B, 1)or(B, N, 1), used to be broadcast over every key: on the CPU and in CUDA float64 it gave the output of no mask, and in CUDA float32, float16 and bfloat16scaled_dot_product_attentionraisedRuntimeError: (*bias): last dimension must be contiguous. A query dimension other than 1 or the sequence length raised a broadcastingRuntimeError. Both now raise aShapeError, aValueError, that names the sequence length. (#6070)With
random_applyand a mix augmentation,ImageSequential,AugmentationSequentialandVideoSequentialinsert only a mix member at the mix-insertion step. That step drew among every member whose weight was 0, so an ordinary member given weight 0 inrandom_apply_weightscould still be applied, and was reported as the added mix. (#6071)find_homography_dlt,find_homography_dlt_iterated,find_homography_lines_dlt,find_homography_lines_dlt_iterated,find_fundamental,run_7point,run_8pointandRANSACrun with autocast disabled, so a caller'storch.autocastregion no longer changes their result. Under bfloat16 autocast a float32 input used to be fitted with its matrix products in bfloat16 and returned as bfloat16: the iterated DLT homography of 500 points with 1 px noise moved the corners of a 600 x 450 image by 3 to 5 px, aRANSAC("homography", local_optimization="dlt")estimate was about 3 px off instead of 0.5 px, andfind_fundamentalreturned a bfloat16 matrix far from the float32 one. On CUDA and MPS, the 8-pointfind_fundamentalwith more than eight points or with weights, andRANSAC("fundamental", local_optimization="dlt")andRANSAC("essential", local_optimization="dlt"), raisedNotImplementedErrorfromtorch.linalg.eigh. The defaultlocal_optimization="lm"solved and scored its minimal samples in the autocast dtype, which could change its estimate. They, andfind_affine, enter that autocast-free region only inside an autocast region, so the direct solvers keep running on themetadevice, andfind_affine, which raisedRuntimeError: unsupported scalarTypethere, now runs too. The 8-pointfind_fundamental,RANSAC("fundamental", local_optimization="dlt")andRANSAC("essential", local_optimization="dlt")with float16 or bfloat16 points solve their eigenproblem in float32: with more than eight points or with weights they raisedNotImplementedErrorfromtorch.linalg.eighoutside CPU autocast and on every other device, and now return the input dtype. Weights of another dtype than the points take the points' dtype infind_homography_dlt,find_homography_dlt_iterated,find_homography_lines_dltand the 8-pointfind_fundamental: autocast used to cast them together, so half-precision points with float32 weights fitted only inside it, and now fit in and out of it. (#6072)equalize,equalize3d,RandomEqualizeandRandomEqualize3Dnow count each pixel of a float16 or bfloat16 image in the histogram bin of the lookup-table entry it reads. The bin was computed in the input dtype, where an 8-bit level v rounds up to bin v + 1 for v >= 240 in float16 and v >= 128 in bfloat16, so neighbouring levels merged and the whole table moved:[10, 100, 254, 255] / 255equalized to[0, 150, 255, 255]instead of the[0, 100, 200, 255]that float32 andPIL.ImageOps.equalizegive, and a random 64 x 64 8-bit image was up to 16 gray levels off. Half-precision results on 8-bit images now match float32 up to output rounding; float32 and float64 results are unchanged. (#6075)ONNX exports that declare a dynamic batch now run at every batch size.
to_onnxtraced them from a batch of 1, whichtorch.exportspecializes. On torch 2.9, the exported DexiNed edge detector and SAM image encoder kept that batch inside the graph, and ONNX Runtime rejected any other.ResizePreProcessorlooped over the batch, so the loop unrolled at the traced size. On every torch release, the default exports ofEdgeDetectorandSmallSR, which include that pre-processor, returned one image's output for a batch of any size.to_onnxnow traces each dynamic dimension at a size of at least 2, andResizePreProcessorresizes a tensor batch in one call. AnObjectDetectorwhose post-processor returns a list of per-image detections, as the default confidence-filtered RT-DETR detector does, used to declare a dynamic batch and return the first image's detections for any batch. It is now exported for a batch of one image; build an RT-DETR detector withconfidence_filtering=Falseto export a batch of any size. (#6076)With
random_apply,ImageSequential,AugmentationSequential,PatchSequentialandVideoSequentialsample with replacement when the drawn count cannot be filled from the children with a nonzero weight inrandom_apply_weights, as they already did when it exceeded the sum of the weights. A count above the number of children raisedRuntimeError: cannot sample n_sample > prob_dist.size(-1) samples without replacementwhenever the weights summed to at least the count, for examplerandom_apply=4with weights[7, 2, 1]. A count above the number of nonzero weights but not of children filled the remaining places with children of weight 0, which the caller had excluded, or with a mix augmentation outside the mix-insertion step. (#6078)bilateral_blurandjoint_bilateral_blurrun faster on CPU float32 and float64 inputs with at least 65,536 values whose gradient is not recorded: the filter is accumulated tap by tap from shifted slices of the padded input instead of from its unfolded windows, whose eight temporaries ofkernel_sizetimes the image were fresh memory faulted in on every call. On batches of 256 x 256 images with a 5 x 5 kernel, measured on an i7-14700K under WSL2 (where page faults cost more than on native Linux), the RGB filter is 3.0-3.2x faster at batch 8 and 2.8-3.0x at batch 32 in eager mode, and the grayscale one 17-20x and 13-17x; with the faults removed from both paths byGLIBC_TUNABLES, the speed-ups are 1.8x and 1.75x (RGB) and 8.7x and 8.0x (grayscale). Undertorch.compilethe RGB filter is 1.06x and the grayscale one 2.9x faster; kernels of more than 25 taps keep the unfold path there, because the compiled tap loop takes longer to compile with every tap. The values agree with the unfold path to rounding. Exported and traced programs, reverse-mode gradients, CUDA, MPS and half precision keep the unfold path. (#6079)ssimandSSIM, andssim_lossandSSIMLossevaluated without a recorded gradient, run faster on the CPU for two contiguous images computed in float32 (float32, half-precision and integer images): the five Gaussian filterings now run on channels-last copies of the images, which oneDNN convolves directly, and the local moments are combined in place. Previously each of the ten depthwise convolutions copied its NCHW input into blocks of 8 or 16 channels and back, buffers 2.7 to 5.3 times an RGB batch that a large batch got as fresh memory on every call. On batches of 256 x 256 RGB images, measured on an i7-14700K under WSL2 (where page faults cost more than on native Linux),ssimis 2.9x faster at batch 8 and 32, and 2.0x to 2.3x at batch 8 and 1.4x to 2.0x at batch 32 with the faults removed from both paths byGLIBC_TUNABLES. The map was bitwise equal to the NCHW path's in every case measured. A call that records a gradient, float64, channels-last and other non-contiguous images, CUDA and MPS inputs,vmapand othertorch.functransforms, builds without oneDNN (such as the macOS arm64 wheels) or with it switched off, and exported and traced graphs keep the NCHW convolutions; undertorch.compile, a channels-last reverse pass was slower than Inductor's own layout choice. (#6080)focal_lossandFocalLossrun faster on the CPU for'mean'and'sum'without class weights, on float32 and float64 logits with at least 2**19 values: the target-class log-probability comes from a custom autograd function that works through the batch in chunks and saves only the logits and two values per pixel, instead of a full-sizelog_softmaxwhose output and gradients were fresh memory faulted in on every call. On 21-class 256 x 256 logits, forward plus backward, measured on an i7-14700K under WSL2 (where page faults cost more than on native Linux), the loss is 1.9x faster at batch 8 and 1.8x at batch 32 in eager mode, 1.4x at both with the faults removed from both paths byGLIBC_TUNABLES, and 1.16x at batch 8 undertorch.compile. Values and gradients agree withlog_softmaxto rounding, with the same NaN and infinity positions; double backward is supported, and exported, traced, autocast, functorch and forward-mode AD calls keeplog_softmax. (#6081)dice_lossandDiceLossrun faster on the CPU for float32 and float64 logits with at least 2**15 values (and class weights, if any, of the logits' dtype): the loss no longer builds a one-hot target and full-size products of it. The intersection takes each pixel's target-class probability, the micro average sums the (weighted) probabilities over the classes of each pixel, and the macro average gets each class's probability mass from a batched matrix-vector product and adds the per-class sums into (batch, class) bins. On 21-class 256 x 256 logits, forward plus backward, measured on an i7-14700K under WSL2 (where page faults cost more than on native Linux), the default micro loss is 4.5x faster at batch 8 and 4.2x at batch 32 in eager mode, the macro loss 3.3x and 3.1x and the class-weighted micro loss 3.1x and 2.9x; with the faults removed from both paths byGLIBC_TUNABLESthey are 2.9x to 4.3x faster, and 1.1x to 1.2x undertorch.compileon torch 2.14. CUDA is unchanged. Values and gradients agree with the one-hot sums to rounding, with the same NaN positions, and labels outside the classes raiseone_hot's errors, also undertorch.compile; exported, traced, autocast and functorch calls, and smaller inputs, keep the one-hot target. So do compiled calls on torch releases that report atorch.compilecapture as an export (2.5.1 and 2.9.1 among them), and there a compiled call does not check the labels, as on main. (#6082)geometry.bbox.nmscomputes half-precision and narrow-integer box areas in a wider dtype, preventing duplicate boxes from surviving or distinct boxes from being suppressed because areas or unions overflow on image-sized coordinates, and bfloat16 rounding from moving an IoU across the threshold. (#6083)Augmentations no longer synchronize with the GPU to move their parameters in eager mode: parameters sampled on the CPU and per-call constants reach CUDA inputs without a
cudaStreamSynchronize, in every 2D, 3D, mix, container and automatic-policy augmentation, inforwardandinverse, and with mask, box, keypoint and class inputs. Values are unchanged bit for bit, and compiled graphs keep their copies. The synchronizations that remain are the ones whose result the host needs:inverse()and the 3D warps invert the transformation matrix withtorch.linalg.inv, which raises for a singular matrix;RandomThinPlateSplinesolves its spline system withtorch.linalg.solvefor the same reason; box inputs are validated (now in one host read instead of three); andRandomTransplantationandAdaptiveDiscriminatorAugmentationdraw from data on the device. Parameters as large as the image (noise, plasma and illumination maps, elastic noise, salt-and-pepper masks) still cost the host the time of a pageable copy, and an augmentation moved to the GPU with.to("cuda")samples its parameters on the GPU and still reads them back. (#6084)BoxFiltering.to_onnxwithoutfilter_as_zeronow exports a fixed batch: the batch ofinput_shape, else ofpseudo_shape, else one image. With the TorchScript exporter (the default before torch 2.9), the graph used to declare a dynamic batch but return only the traced batch's per-image outputs: it ran correctly only at a batch of 5, failed in ONNX Runtime at smaller batches and silently dropped images at larger ones. The dynamo exporter failed. Passinput_shape=[5, -1, 6]to keep exporting for 5 images. Aninput_shapewith a dynamic (-1) batch now raises aValueErrorthat points tofilter_as_zero=True, which exports a batch of any size as one(B, D, 6)tensor. (#6086)kornia.geometry.bbox.bbox_generator3dnow places each far corner atstart + size - 1, soinfer_bbox_shape3dreads back the requested width, height and depth andbbox_to_mask3dcoverswidth * height * depthvoxels, as withbbox_generatorandBoxes3D.from_tensor(..., mode="xyzwhd"). Before, the far corner was atstart + size, and every box measured one voxel larger than requested on each axis. Code that passedsize - 1to work around this now gets boxes one voxel smaller on each axis and should passsize.CropGenerator3Ddid this and now passessize, soRandomCrop3Dand the generator'ssrcanddstboxes are unchanged. (#6088)rgb_to_hlsandRgbToHlsnow subtract color channels before dividing by chroma, avoiding NaN float16 hue gradients for near-gray pixels such as normalized RGB(250, 251, 250). Hue values also move by rounding-level amounts in every dtype, closer to a float64 evaluation. (#6089)kornia.geometry.camera.dx_distort_points_affinereturns one Jacobian per point: its batch shape is the broadcast of the points' and the params' leading shapes, as documented and asdistort_points_affineanddx_distort_points_kannala_brandtgive.Npoints with one set of params returned a single(2, 2)Jacobian, and(B, N, 2)points with(B, 1, 4)params returned(B, 1, 2, 2). A params batch that does not broadcast against the points now raises, where it was ignored. (#6091)On torch 2.9.1,
torch.onnx.export(..., dynamo=True)exportspyrdown,build_pyramidandgaussian_blur2dwith a dynamic batch again. They used to fail with "Constraints violated (batch)": the batch check offilter2dand ofgaussian_blur2d'ssigmacompared a kernel orsigmabatch of 1 with the input batch before it accepted the 1, and the size-oblivioustorch.exportthat this exporter runs then guarded the batch against 1.KORNIA_CHECK_SAME_SIZEwithallow_one=Truenow accepts a size of 1 before comparing it with the other size. (#6094)camtoworld_to_worldtocam_Rt,worldtocam_to_camtoworld_Rt,camtoworld_graphics_to_vision_4x4andcamtoworld_vision_to_graphics_4x4now return a result in the input's dtype foruint8,int8,int16,int32andint64input on CUDA, as they already did on the CPU and MPS. CUDA has no integer matrix multiplication, so these functions used to raiseNotImplementedError: "baddbmm_cuda" not implemented for 'Long'(or the matching error for another integer dtype) there. (#6096)jpeg_codec_differentiableandJPEGCodecDifferentiablenow computefloat16andbfloat16images infloat32, quality and quantization tables included, and return the input dtype. The codec ran in the input dtype before, where pixels scaled to [0, 255], DCT coefficients of about 1000 and a quality scale of 2500 do not fit an 8-bit or 11-bit significand: on random 64x64 images, outputs were 0.15 to 0.25 (bfloat16) and 0.11 to 0.18 (float16) away from thefloat64codec, and image gradients were off by about their own magnitude (relative L2 error 0.5 to 0.9). The output is now thefloat32codec's output rounded once to the input dtype.JPEGCodecDifferentiablealso no longer rounds itsfloat32tables to the image dtype before passing them to the codec. Insidetorch.autocastthe output now keeps the input dtype too: afloat32image under CPUbfloat16autocast used to come back asbfloat16. (#6100)find_homography_lines_dlt,find_homography_lines_dlt_iteratedandfind_homography_dlt(..., solver="svd")return NaN for a batch element whose DLT system is not finite, such as one with a NaN or infinite point, endpoint or weight, and the usual homography for the rest of the batch, on CPU and CUDA, eager and compiled. On CPU, one such element madetorch.linalg.svdraise for the whole batch; the solvers then warned "SVD did not converge" and returned uninitialized memory fromtorch.empty. Every homography of the batch was then garbage that changed from call to call and had no gradient. Compiled and exported programs raisedLinAlgErrorinstead. On CUDA, a non-finite weight could give a finite but meaningless homography. If the SVD fails on a finite system, the whole batch is now NaN, with the same warning. (#6103)focal_lossandFocalLossraise aRuntimeErrorfor a label outside the classes undertorch.compileon the CPU, as they do in eager mode. Withreduction='mean'or'sum'and noweight, the loss gathers the target class, and Inductor's CPU gather checks its indices inside an OpenMP parallel region: a label past the classes terminated the whole Python process (exit code 134, "index out of bounds") on torch 2.5.1, 2.9.1 and 2.14, a negative label did the same on 2.14, and 2.5.1 and 2.9.1 returned a loss for a negative label when no gradient was needed. The labels are now checked withtorch._assert_asyncbefore the gather, and on torch 2.14 a compiled gather reads them clamped into range, so it stays in bounds until the check raises. Inductor before torch 2.9 compiles the assert to nothing, so there a compiled call still fails as before. The check usesone_hot's messages: an eager CPU call now raises "Class values must be non-negative." or "Class values must be smaller than num_classes." where the gather raised "index ... is out of bounds for dimension 1 with size C", as the'none'and weighted losses already did. CUDA is unchanged: an out-of-range label still fails the gather's device-side assert there. (#6104)PinholeCamerasList.clone(),scale()andscale_()now preserve camera-list dimensions and apply per-batch scale factors across cameras. (#6106)TinyViT.from_config("21m", ...)with the'in1k_384'or'in1k_512'checkpoint (also reached bypretrained=Trueatimg_size384 or more) builds withdrop_path_rate=0.1, the stochastic depth rate those checkpoints were fine-tuned with (Creamtiny_vit_21m_384andtiny_vit_21m_512). It used TinyViT-21M's 224-px rate of 0.2. Only training changes: DropPath does nothing in evaluation mode. Adrop_path_rateargument still overrides the default. (#6107)jpeg_codec_differentiableandJPEGCodecDifferentiable, and soRandomJPEG, run with autocast disabled, so a caller'storch.autocastregion no longer changes their output, or their gradients when the backward pass runs after the region (on CUDA, up to the run-to-run spread of its atomic accumulation unless deterministic algorithms are enabled). Autocast ran the codec's matrix products and convolutions in its lower dtype, which rounds pixels scaled to [0, 255], DCT coefficients and the quality scale too coarsely: on random 64x64float32images at qualities 99, 90, 50 and 10, outputs were up to 0.109 (CPUbfloat16autocast), 0.014 (MPSfloat16) and 0.088 (MPSbfloat16) away from thefloat64codec on an Apple M1, and up to 0.03 (float16) and 0.12 (bfloat16) under CUDA autocast. They now equal the call outside autocast, 8.4e-7 from thefloat64codec on the CPU and MPS and 6.9e-7 on CUDA. A backward pass inside the region, whichtorch.compileassumes by default, still computes part of the gradient in the autocast dtype. (#6109)sampson_epipolar_distance,symmetrical_epipolar_distance,left_to_right_epipolar_distanceandright_to_left_epipolar_distanceaccept a single(3, 3)fundamental matrix, as their(*, 3, 3)shapes document, and return the distances of the batched call without its batch axis. They raisedValueError: Fm must be a (*, 3, 3) tensor. Got torch.Size([3, 3]), except the first two on CUDA with fewer than 10,000 points, which accepted it. AnFmwhose last two dimensions are not(3, 3)now raises thatValueErroron every path. On CUDA the first two raised aRuntimeErrororIndexErrorfrom the matrix product instead, and returned values for a(4, 4)Fmwith 4-component points; with one point set and several matrices on the CPU,sampson_epipolar_distanceraised aRuntimeError, or reshaped anFmsuch as(2, 9, 1)into3 x 3matrices. (#6110)get_hanning_kernel1dandget_hanning_kernel2dexport with torch 2.14's default (dynamo) ONNX exporter again. Built without adtype, the window multiplied an int64 ramp by a float, anaten.mul.Scalarthat the exporter has no translation for with onnxscript 0.7.1 (ConversionError). The ramp is now converted to the default dtype first, the conversion the multiplication made implicitly on the CPU. Eager outputs are unchanged bit for bit with an explicitdtype, with a float32 or float64 default dtype, and on the CPU with any default dtype. With a float16 or bfloat16 default dtype on MPS, windows from 2057 (float16) or 259 (bfloat16) taps now round the ramp to that dtype as the CPU does, and differ from before by up to about 16 units in the last place. (#6129)to_onnxno longer overwrites the output cache thatshow()andsave()read. On the TorchScript exporter (theto_onnxdefault below torch 2.9, ordynamo=False), the export's run on its random dummy input used to leave that output in the exported module's cache and in the cache of every image module inside it,AugmentationSequentialincluded, soshow()rendered noise after an export. Every cache now holds the same object as before the export, whether the export succeeds or raises.HFONNXComunnityModel.to_onnxreturns a copy carrying that call's metadata. It used to add the metadata to the stored graph, which is theModelProtothe model was built from, so the keys of one call appeared in the caller's graph and in every later export.HFONNXComunnityModel.resize_backwith atarget_imagesthat is not a tensor raises aTypeErrornaming the type; it raised aRuntimeErrorwithout a message.
(#6130)
Super-resolution weight loading in
kornia.contribandkornia.models:- The pretrained Real-ESRGAN weights of
RRDBNetBuilder(also reached throughSuperResolution.from_config) and theSmallSRNetweights behindSmallSRBuilderare cached in the torch hub directory throughkornia.core.download.load_state_dict_from_url, as kornia's other checkpoints are. They were cached underkornia_config.hub_onnx_dir(.kornia_hub/onnx_models, relative to the working directory), so each new working directory downloaded them again; existing users download them once more. A copy kept for offline use goes to<torch.hub.get_dir()>/checkpoints/under the URL's file name:small_sr.pthbecomessuperres_epoch100-44c6958e.pth, and the Real-ESRGAN files keep their names. - A Real-ESRGAN checkpoint without
params_emaloads itsparams, the fallback of Real-ESRGAN's own loader; it raisedKeyError: 'params_ema'. SmallSRNet.load_from_filereads a local checkpoint file, as its docstring said; a path raisedValueError: URL must start with 'http:' or 'https:'. A path that names no file raisesFileNotFoundError.
(#6131)
- The pretrained Real-ESRGAN weights of
PatchSequentialwithrandom_applynow permits a mix augmentation such asRandomMixUpV2to be selected, at most once per forward call. Previously, mix members were never selected. ARandomTransplantationmember, which needs a mask thatPatchSequentialdoes not take, now raises its missing-mask error when it is selected, as it already did withoutrandom_apply. (#6132)AugmentationSequential,ImageSequentialandVideoSequentialnow track the size thatPadTo, andRandomMosaicwith anoutput_size, return. Every later child used to draw its parameters for the canvas before them, so the pipeline differed from applying the children one at a time. An integer-sizeResize,LongestMaxSizeorSmallestMaxSizereturned the wrong size:PadTo((40, 40))thenResize(16)gave a(16, 26)image instead of(16, 16). A resample-mode crop,RandomCrop,RandomResizedCrop,RandomAffine,RandomPerspectiveandRandomErasingused the old size for their windows, centres and corners,RandomElasticTransformraised a size-mismatchRuntimeError, and a laterResize, slice-modeCenterCroporRandomHorizontalFlipmoved boxes and keypoints for the old canvas. The resample-mode crop was also wrong undertorch.export. (#6133)kornia.onnxcomposition and loading:ONNXSequential, andHFONNXComunnityModel/DepthEstimationbuilt on it, chain models whose metadata differ for a key: a graph exported by another kornia release (itsversion), exports given differentadditional_metadatavalues, or an onnx-community model whosesourcediffers from the kornia pre-processor's. They used to raiseValueError: Can't merge models with different values for the same model metadata property. The combined model holds one entry per key, at its first position, with the value of the last model that sets it; the models passed in are not modified.ONNXSequentialappliestarget_ir_versionandtarget_opset_versionwithoutauto_ir_version_conversion=True, asONNXModuledoes; it used to ignore them silently. Without the flag, only the versions given are changed, and a model that already has them is not converted again (ONNXModuleas well).- A conversion to a target version, by
ONNXModuleorONNXSequentialwith or without the flag, accepts a model that lists a metadata key twice, as kornia 0.9.0rc1 wrote afteradd_metadata, and keeps one entry per key with its last value, the one ONNX Runtime reads; it used to raiseValidationError: Your model has duplicate keys in metadata_props. A combined model lists each operator-set domain once, so it can be converted and chained again; the conversion used to update only one of the repeated entries, and the next merge raisedCan't merge two models with different operator set ids. ONNXSequentialwarns (UserWarning) when the tensor element types of an output and the input it feeds differ at a joint: the merged graph does not check a later model's declared input types, so such a chain runs on the earlier model's type, or fails later with ONNX Runtime'sType Error, as before. Declared dimensions are not compared.- A malformed
io_mapsraises aValueCheckError(aValueError) that saysio_mapsholds one list of(output, input)name pairs per joint, where it used to raiseIndexError(an entry missing) orValueError: Output K00-m is not present in g1(a flat list of pairs, the form the ONNX guide showed). A pair with more than two names, whose extra names were ignored, now raises it too. An entry may still be any iterable of pairs (azip,dict.items(), a generator, a numpy array) andio_mapsanything indexed by the joint, and entries past the last joint are still not read. Theio_mapsannotations ofONNXSequential,ONNXSequential.combineandHFONNXComunnityModelare nowlist[list[tuple[str, str]]], and the guide's example is a list of lists. ONNXModule,ONNXSequential,kornia.onnx.load,ONNXLoader.load_modelandONNXLoader.load_configtake file paths asos.PathLikeobjects such aspathlib.Path(always a local file), and expand a leading~in a local path. A path object used to raiseValueError: Invalid argument type(AttributeErrorfrom the two loaders). An argument of another type now raises aTypeErrorthat names what is accepted, instead ofValueError(AttributeErrorfrom the two loaders); forbytes, which ONNX Runtime reads as a serialized model, it says to passonnx.load_model_from_string(data).- Calling
ONNXModuleorONNXSequentialtakes CPU torch tensors of a dtype numpy has (not bfloat16 or the float8 types) as well as numpy arrays, and still returns numpy arrays; a tensor used to raise ONNX Runtime'sRuntimeError: Input must be a list of dictionaries or a single numpy array. A tensor on another device raises aValueErrorthat says to move it to the CPU, and a sparse tensor or one of a dtype numpy lacks aTypeErrorthat names the input and how to convert it. ONNXLoader.load_configreads an existing local JSON file, which it used to report as not found ("You may setdownload=True"). An argument that is neither an HTTP(S) URL nor an existing file (a directory, for one) raises aRuntimeErrorthat says so.- The
ONNXModuledocstring documents its parameterop, one model, andio_name_conversiondocuments that it applies any mapping in place, returns the same model, and leaves initializers,value_infoand subgraphs alone.
(#6134)
ONNX exports of
EdgeDetector, MobileSAM and RT-DETR declare and return what they compute:EdgeDetector.to_onnxwith the pre- and post-processor exports a graph whose edge maps have the input's size, as eagerforwardreturns them. The graph returned the maps at the pre-processor's size (352 x 352 for the default builder) whatever the input, and only warned thatResizePostProcessoris not exported. With aResizePostProcessorin"bilinear","bicubic","nearest"or"nearest-exact"mode it now returns one(B, 1, H, W)tensor, resized with that mode: thetorch.catof the eager per-image list. A directtorch.onnx.export(detector, ...)gives the same graph on the TorchScript exporter and, from torch 2.9, on the dynamo exporter.image_sizeis documented as the graph's input size, which the maps have too: the pre-processor keeps the size it was built with. EagerforwardandResizePostProcessorare unchanged, and aResizePostProcessorsubclass that overridesforwardis exported as itsforwardcomputes.Sam.to_onnxof a MobileSAM (TinyViT image encoder) on the TorchScript exporter, the default before torch 2.9 ordynamo=False, traces the encoder at the batch ofpseudo_shape(1 by default) and declares that batch static, so the graph states the one batch it runs at. It declared a dynamic batch, but ran only at the traced batch. Other encoders, and the dynamo exporter, keep a dynamic batch.ObjectDetector.to_onnx(include_pre_and_post_processor=False)names both outputs of an RT-DETR model,pred_logitsandpred_boxes(now declared once asRTDETR.ONNX_OUTPUT_NAMES), each with the input's dynamic batch, and keeps the detector's dynamic height and width forimage_size=None. Only the logits were named (output), and the boxes came out under an exporter-generated name, such as2814from the TorchScript exporter. A caller'soutput_namestake their place, with the same batch; a model that declares no output names keeps the singleoutput.RTDETR.to_onnxgiven its ownoutput_namesdeclares the input's dynamic batch on them too; it declared it onpred_logitsandpred_boxes, which the graph then did not have.
(#6135)
Hyperplane.signed_distance,abs_distanceandprojectionnow preserve point gradients for plain tensor inputs, matching their behavior forVector3inputs. (#6136)depth_to_normalsnow widens float16 and bfloat16 inputs to float32 and runs its gradient convolution outside autocast. float16 depth maps gave NaN normals for near surfaces (closer than about 0.25 m at a 1000-pixel focal length) and inside zero-depth holes, normals off by tens of degrees at 0.5 to 1 m, and non-finite gradients; bfloat16 depth maps wider than 256 pixels gave zero normals; float32 depth maps inside an autocast region gave normals off by a median of 1 to 40 degrees (and, under float16 autocast, non-finite gradients); and float16 or bfloat16 depth maps inside a CPU autocast region of the other half dtype raisedRuntimeError. The output dtype inside autocast now follows the inputs, as it does outside: under CPU autocast, float32 and integer inputs used to return the autocast dtype, and under CUDA autocast, half-precision inputs used to return float32. (#6137)Fixed
VideoSequentialraising anIndexErrorforRandomCutMixV2with the defaultsame_on_frame=True, and withsame_on_frame=Falsewhen the CutMix hassame_on_batch=Trueand the batch holds more than one video. Withsame_on_frame=Truethe mix parameters are now repeated over the frames along the video axis, so every frame of a video cuts the same box from the matching frame of the same partner video. (#6138)LoFTRin float16 or bfloat16 no longer raises a dtype-mismatchRuntimeErroron images taller or wider than 2048 pixels: the positional-encoding cache it grows for feature maps above 256 cells now keeps the model's dtype instead of becoming float32. (#6141)decompose_essential_matrix,decompose_essential_matrix_no_svd,motion_from_essential,motion_from_essential_choose_solutionandproject_to_essentialrun with autocast disabled, as the solvers of #6072 do, so a caller'storch.autocastregion no longer changes their result. Under bfloat16 autocast a float32 essential matrix was decomposed with its matrix products in bfloat16: the rotations came back in bfloat16, about1.6e-3off and no longer orthogonal, next to a float32 translation, andmotion_from_essential_choose_solutiontriangulated its points with bfloat16 projection matrices, which moved them by up to0.2at depths of 5 to 9.motion_from_essential_choose_solutionnow castsK1andK2to the dtype ofE_mat, so half-precision intrinsics with a float32 matrix, which autocast used to cast to one dtype, still run, and run outside autocast too, where they raised. Any other call made outside autocast is unchanged, and a TorchScript-compiled call keeps the products in the caller's precision as before. (#6147)KORNIA_CHECK_TYPEnow names an expected union by its members, such asexpected int | str, on every Python version. Its error message saidUnionfortyping.Union[...],Optionalfortyping.Optional[...], and on Python 3.14 alsoUnionforint | str. (#6149)kornia.morphology.dilation,erosionand the operations built on them (opening,closing,gradient,top_hat,bottom_hat) give the same result for a bool or integerstructuring_elementas for the equal float one, on every engine. In 0.9.0rc1 auint8orint8structuring element raised an overflowRuntimeError, a bool one raisedNotImplementedErrorinerosionand gave wrong values indilationwhenkernelexcluded a cell, and every integer or bool one raised underengine="convolution". The same functions also accept a non-contiguouskernel, such as a transposed view, underengine="convolution", which used to raiseRuntimeError: view size is not compatible with input tensor's size and stride. Other calls are not affected. (#6150)transform_pointsno longer truncates integer operands. Integer points, such as pixel indices fromtorch.nonzero, used to come back in their integer dtype, truncated whenever the transformed coordinate was fractional; they now return in the floating dtype of the transform, or in the default floating dtype when the transform is integer too. An integer transform used to truncate floating points before the product; it is now applied in the points' dtype.transform_bboxandKeypoints.transform_keypointschange with it. (#6152)Fixed
VideoSequentialmixingRandomMixUpV2,PatchMixandRandomMosaicwith the wrong frames. Withsame_on_frame=Truethe partner indices drawn per video now point at frametof the partner video, and withsame_on_batch=True,RandomMixUpV2andPatchMixdraw one sample per video instead of mixing every frame with the first one. Withsame_on_frame=Falseandsame_on_batch=Truethose two are now drawn for allB * Tframes, instead of once per frame index with every partner taken from the first video. (#6154)RandomCrop3DandCropGenerator3Dnow reject a fixed crop size larger than the input volume for empty batches, consistently with non-empty batches. Crops that fit after padding remain valid. A fixed size is now checked without reading tensor data, so on torch 2.14torch.compile(..., fullgraph=True)ofCropGenerator3D, and ofRandomCrop3Dwithp=1.0, no longer fails with a data-dependent branch. (#6156)MS_SSIMLossnow requiresimg1andimg2to be 4-D(B, C, H, W)tensors with the same channels, height and width and equal batch sizes, or a batch size of 1 that is compared with every image of the other batch as before, and raisesValueErrorotherwise (aShapeErrorfor a shape mismatch), also with Kornia checks disabled (#6157). It used to compare only the number of dimensions: a height or width of 1 was broadcast and returned a wrong loss, and so did some 3-D(C, H, W)pairs. Inputs of different ranks already raisedValueError; every other mismatch or input that is not 4-D ended in a torchRuntimeErrororIndexErrorand now raisesValueError. (#6158)The torch 2.14 default (dynamo) ONNX exporter now exports
BoxFilteringand the detectors that contain it. Withdynamo=True(the default from torch 2.9), aBoxFilteringwithout aconfidence_thresholdexported a graph that filtered at0.1wherever the export succeeded (torch 2.9.1, for example); it now filters at0.0, as eager does. (#6159)ObjectDetector.to_onnxandBoxFiltering.to_onnxraise aValueErrorwhen adynamic_axesordynamic_shapesargument makes the batch of a per-image-list export dynamic. Such an export has one graph output per traced image, so it used to succeed, declare a dynamic batch, and give wrong results at any other batch size: a detector returned one image's detections for a batch of 3, and aBoxFilteringtraced at a batch of 5 returned 5 outputs at a batch of 7 and failed in ONNX Runtime at batches of 1 and 3. The check reads the exported graph, so it covers every form of the two arguments, and an override that keeps the batch fixed, such astorch.export.Dim.STATIC()or a dynamic detection count only, still exports. Nothing is saved when it raises.filter_as_zero=True, and an RT-DETR detector built withconfidence_filtering=False, export a dynamic batch as before. (#6162)to_onnxkeeps the parameters and transformation matrices that augmentations and their containers stored from their last call, soinverse()andtransform_matrixafter an export still describe that call. The export's run on its dummy input used to replace them: after a legacy TorchScript export (the default before torch 2.9,dynamo=Falsefrom it),inverse()raised or inverted the dummy's transform. They now come back as the same objects with the same items, also when the export fails, as theshow()/save()output cache now does (#6130). The export also gives back the global random state it drew from, so the draws after it are the ones they would be without it; it removes the global buffer-registration hook that torch 2.9'storch.exportleaves after a failed trace, which made every latertorch.compile(..., fullgraph=True)that registers a buffer raiseUnsupported; andRandomResizedCropno longer stores each call's crop sizes on its generator, where a torch 2.9 dynamo export left a fake tensor that madedeepcopyandpickleraise. (#6163)solve_pnp_dltandget_perspective_transformrun with autocast disabled, as the solvers of #6072 do, so a caller'storch.autocastregion no longer changes their result. Under bfloat16 autocast,solve_pnp_dltraisedNotImplementedError: "lu_cpu" not implemented for 'BFloat16'on the CPU for float32 inputs, andget_perspective_transformran its closed form in bfloat16: the homography between the corners of a 640 x 480 image and four targets mapped those corners 1.36 px off. A call made outside autocast is unchanged, and a TorchScript-compiledget_perspective_transformkeeps the caller's precision as before. (#6169)rgb_to_yuv422andRgbToYuv422export correctly with the legacy (TorchScript) ONNX exporter on torch 2.9.1 and 2.14. Before, the exported graph returned the UV planes with the window and window-count axes swapped, shape(*, 2, H, 2)instead of(*, 2, H, W/2). On torch 2.5.1 that export still raises, as it did before. (#6171)ColorMapuses the default floating dtype for custom palettes with integer RGB values whendtypeis omitted, instead of failing during interpolation. (#6172)KRt_from_projectionandtriangulate_pointsrun with autocast disabled, as the solvers of #6072 do, so a caller'storch.autocastregion no longer changes their result. Under float16 or bfloat16 autocast, for float32 inputs,KRt_from_projectionreturnedKandRin the autocast dtype on the CPU, withRabout 3e-3 from orthogonal in bfloat16, and raisedRuntimeError: geqrf: MPS currently supports float32 onlyon MPS;triangulate_pointswith its defaultsolver="eigh"raisedNotImplementedErroron MPS. A call made outside autocast is unchanged, and a TorchScript-compiledKRt_from_projectionkeeps the caller's precision as before. (#6175)get_closest_point_on_epipolar_lineruns with autocast disabled, as the solvers of #6072 do, so a caller'storch.autocastregion no longer changes its result. Under CPU autocast it computed the epipolar lines in half precision and raisedRuntimeError: expected scalar type Float but found BFloat16(orHalf) for float32 points andFm; under MPS autocast it returned float32 points several pixels off.Fmandpts2now take the dtype ofpts1, as autocast used to arrange for half-precision operands: anFmorpts2in another dtype thanpts1, which raised outside autocast (on MPS a mixedpts2returned wrong values instead), now gives the result in the dtype ofpts1. A call with all three in one dtype outside autocast is unchanged, and a TorchScript-compiled call keeps working as before. (#6179)unsharp_maskandUnsharpMaskrun undertorch.autocast. Under autocast the blur, a convolution, came back in the autocast dtype, andtorch.lerp, which does not promote, raisedRuntimeError: expected dtype ... for 'end' but got dtype floaton the mismatch with a float32 image. The blur is now cast to the image's dtype before thelerp, so the result keeps the image's dtype, as2 * image - blurwould and askornia.enhance.sharpnessdoes; outside autocast the cast is a no-op and every result is unchanged. (#6183)BoxFilteringwithclasses_to_keepnow runs on boxes on another device than the class list, such as after.to(device)or.cuda(), instead of raisingRuntimeError: Expected all tensors to be on the same device:forwardmoves the class list to the boxes' device, also one passed toforward. Aconfidence_thresholdtensor of more than one element no longer raisesRuntimeError: Boolean value of Tensor with more than one value is ambiguousin the constructor. (#6184)Boxes.to_mask,Boxes3D.to_mask,kornia.metrics.psnr,kornia.losses.psnr_lossandkornia.losses.PSNRLossexport correctly with the legacy (TorchScript) ONNX exporter (torch.onnx.export(..., dynamo=False)) on torch 2.5.1, 2.9.1 and 2.14. Before, the twoto_maskgraphs had no input and returned an all-zero mask for any box: the legacy exporter traced the CPU loop and lost its in-place writes. Under the legacy exporter andtorch.jit.tracethey now compare a coordinate grid against the box bounds, as the dynamo exporter already did (andBoxes.to_maskon CUDA). The PSNR graphs returned a one-element vector of shape(1,)where eager returns a 0-d scalar; they now return the eager shape.Boxes.to_maskof an image with a side of 0, andBoxes3D.to_maskof such a volume, return an empty mask on the loop path (CPU, and CUDA forBoxes3D) as the grid path does, instead of raisingRuntimeError: cannot reshape tensor of 0 elements. Every other eager result is unchanged. (#6188)RandomMixUpV2andRandomCutMixV2now applybatch_probto the class labels. Aparamsdictionary whosebatch_probselects only some rows, such as a draw replayed on a subset or hand-built parameters, used to label the unselected rows as mixed with their drawn partner and weight although their images came back unchanged; those rows now get their own class twice with lambda 0, matching the image. (#6189)equalize,equalize3d,RandomEqualizeandRandomEqualize3D, andequalize_claheandRandomClaheon their default (fast) path, now count each pixel in the lookup-table entry it reads: its 8-bit level(x * 255).long()in the input dtype. Before, they counted it infloor(256 x), thetorch.histcplacement, which put every value in[k/256, k/255)one bin above the entry it reads; that is about half of a continuous image (#6181).equalizeof a float32 or float64 image is nowPIL.ImageOps.equalizeof those levels, as long as a float32 channel holds at most2**24pixels (4096 x 4096). A channel whose lookup step is 0 is still returned unchanged.On continuous float32 input, over 20 random images per size:
equalizechanges 48–49% of the pixels:- at 64 x 64, 42% move by 1 gray level and 1.8% by 2;
- at 300 x 300, 49% move by 1 and 0.04% by 2;
- in one 64 x 64 image the lookup step went from 16 to 15, and its pixels moved by up to 18 levels.
equalize3dchanges 50% of the voxels of 4 x 64 x 64 volumes.equalize_clahewith the default arguments changes about 77% of the pixels at 256 x 256 and 296 x 296. The pixels that change move by 0.73 gray levels on average, and by at most 3.6.
8-bit images in float32 and float64 are unchanged. On 8-bit images, half-precision
equalize_clahenow stays within 0.2 gray levels of float32 in float16 and within 1.5 in bfloat16 (default arguments, 256 x 256 and 296 x 296).(#6190)
homography_warp(..., normalized_coordinates=False)andHomographyWarper(..., normalized_coordinates=False), on both the direct and theprecompute_warp_gridpath, now warp by a destination→source pixel homography: the warped grid of source pixel coordinates is normalized under the call'salign_cornersbeforegrid_sample, aswarp_perspectivedoes. Previously the pixel grid reachedgrid_sampleunnormalized, so almost every sample fell outside the image and an identity homography returned a nearly blank image instead of the input. The result now matcheswarp_perspectivewith the inverse homography; the pixel grid is warped and normalized in at leastfloat32, also under a half default dtype and in a caller's autocast region, scripted or not, so pixel coordinates are not rounded to half precision before normalization; only the normalized grid takes the half dtype, as on the default path. Callers that pre-multiplied the homography bynormal_transform_pixelto work around this must drop that factor. The defaultnormalized_coordinates=Trueis unchanged. Fixes #6170. (#6191)ObjectDetector.to_onnxexports a detector whose post-processor returns a tuple with one tensor per image for a batch of one image, as it does for a list, and raises aValueErrorwhen adynamic_axesordynamic_shapesargument makes that batch dynamic. It used to declare a dynamic batch: the TorchScript exporter's graph then returned only the traced images' detections at a larger batch, and the dynamo exporter of torch 2.9 and later failed with an error that did not name the cause. A tuple of batched outputs, such as(boxes, scores), still exports a dynamic batch. (#6192)AugmentationSequentialwithmask, box orkeypointsdata keys, and theManyToManyAugmentationDispatherandManyToOneAugmentationDispatherbuilt from it, export again with torch 2.9's dynamo ONNX exporter when replayed with constantparamsand aRandomAffinechild. Since #5416 the annotation handlers recompute the child's matrix from the caller's params under export, andRandomAffinecopiescenterfrom them as-is, which that exporter turns into a renamed graph constant and rejects. The handlers now compute from a copy of the params, as the image call does. Eager outputs are unchanged. Fixes #6166. (#6196)EdgeDetector.to_onnxandSuperResolution.to_onnxwith the pre- and post-processor export a model whose output is a list with one item per image for a batch of one image, asObjectDetector.to_onnxdoes for per-image detections. A tuple with one item per image, which the output kind's reading tells from a fixed set of batched outputs by its length at two batch sizes, counts as such a list, as forObjectDetector(#6192). Such a list comes from a post-processor that returns one, or, forSuperResolution, from the network itself or a pre-processor that returns a list of images, whichforwardruns one at a time. Both used to declare a dynamic batch, and the TorchScript exporter (dynamo=False) turned the list into one graph output per traced image: the graph returned two maps for a batch of three images, and two maps, one of them empty, for a single image. From torch 2.9 the dynamo exporter failed on such a model, and now exports it as well. Adynamic_axesordynamic_shapesargument that makes the batch of such an export dynamic raises aValueErrorafter the export, before anything is saved. The kind of output is first read from a one-image forward pass outside the export, so aResizePostProcessorsubclass whose ownforwardreturns a list eagerly is now exported for one image too, even if it returns a tensor under export, and a dynamic override of it raises.EdgeDetectorwith aResizePostProcessorthat keeps its ownforward(under the class's ownforward, without forward hooks),SuperResolutionwith known tensor-output networks and the builders' pre- and post-processors (with unchanged forwards), and a model that returns one tensor keep the dynamic batch. The check after the export reuses a positive list reading. A tensor reading is checked again at the actual tracing batch, so batch-dependent per-image outputs cannot silently produce a dynamic graph that drops images. (#6197)kornia.enhance.thresholdandkornia.enhance.Thresholdcompile withtorch.compile(..., fullgraph=True)on torch 2.9 and earlier, where they failed: the supported-type check no longer iterates theThresholdTypeenum while tracing, which Dynamo there cannot do. (#6199)lovasz_hinge_loss,lovasz_softmax_lossand their module wrappers raiseValueErrorwhen the prediction and target batch sizes differ, instead of anIndexErrororRuntimeErrorfrom inside the loss. Alovasz_softmax_lossprediction batch of one is still scored against every target, as before. (#6200)StableDiffusionDissolvingnow reports the unsupported version and lists the supported versions when raisingNotImplementedError. (#6202)RandomCutMixV2withsame_on_batch=Trueandnum_mix > 1repeated the first mix's pairing and cut in every mix, while the class output credited that donor once per mix; each mix now draws its own pairing and cut, shared by every row of the batch. Calls withnum_mix=1orsame_on_batch=Falsedraw exactly as before; withsame_on_batch=Trueandnum_mix > 1, a seeded pipeline now draws differently after this augmentation. (#6203)Improve float16 and bfloat16 accuracy in Lab/Luv conversions,
rgb255_to_normalsvisualization, Gaussian kernels and blur, and Canny by computing intermediates in float32 and returning the input dtype. Canny no longer overflows when squaring gradients of common 255-level float16 inputs, and decoding a zero float16 normal remains finite. (#6212)GFTTAffNetHardNet,HesAffNetHardNet,DoGHardNet,DoGAffNetHardNet,KeyNetHardNet,KeyNetAffNetHardNetandLightGlueMatchernow return in evaluation mode (training=False), matchingLocalFeatureMatcherand the pretrained-model convention; outputs are unchanged because their pretrained networks were already in evaluation mode. (#6221)homography_warp3d(..., normalized_coordinates=False)now warps by a destination→source voxel homography: the warped grid of source voxel coordinates is normalized under the call'salign_cornersbeforegrid_sample. Previously the voxel grid reachedgrid_sampleunnormalized, so almost every sample fell outside the volume and an identity homography returned a nearly empty volume instead of the input. An identity now returns the input and a whole-voxel translation moves the volume by whole voxels under bothalign_cornerssettings, and atalign_corners=Truethe result matcheswarp_perspective3dwith the inverse homography. The voxel grid is warped and normalized in at leastfloat32, also under a half default dtype and in a caller's autocast region, scripted or not, so voxel coordinates are not rounded to half precision before normalization; only the normalized grid takes the half dtype, as on the default path. Callers that pre-multiplied the homography bynormal_transform_pixel3dto work around this must drop that factor. The defaultnormalized_coordinates=Trueis unchanged. Fixes #6187. (#6224)Resize,LongestMaxSizeandSmallestMaxSizewith an int size,Boxes.from_tensor,Boxes.to_mask,Boxes3D.from_tensor,Boxes3D.to_mask,validate_bbox3dand the 3D box functions that call it (bbox_to_mask3d,infer_bbox_shape3d,center_crop3d,crop_and_resize3d),StereoCamera,So2.from_matrix,Se2.from_matrixandjpeg_codec_differentiable/JPEGCodecDifferentiablenow compile withtorch.compile(fullgraph=True)on torch 2.12 and later (CI checks 2.14). Their data-dependent input checks and host-side code paths now follow any graph capture, as they already did undertorch.exportand undertorch.compileon earlier torch releases. A compiled call on torch 2.12 and later therefore no longer checks for invalid input, as on earlier releases: boxes with a non-finite coordinate (inBoxes3D.from_tensor, the'xy*'modes ofBoxes.from_tensorand the 3D box functions that callvalidate_bbox3d) or a non-positive extent, unequal 3D box edges, a stereo rig with differing intrinsics or a zero or reversed baseline, a rotation block that is not of the form[[a, -b], [b, a]], or a JPEG quality outside[0, 100].crop_by_boxes3dskips the same 3D box checks in a compiled call, but it reads its output size from the boxes and still does not compile in one graph. Eager calls still raise. Under capture,Boxes.to_maskandBoxes3D.to_masktake their vectorized path, which fills the same mask. (#6226)The
[0, 1]input clamp that range-dependent 2D intensity augmentations gained in #5980 is cheaper. A call that records no reverse-mode gradient and carries no forward-mode tangent now costs a singleclamp. A call that needs either derivative costs a comparison with the clamped copy and a selection, instead of two bound comparisons, their conjunction and a selection. Values and gradients are unchanged, apart from the sign of a zero: on MPS and undertorch.compilea-0.0pixel can now come back as+0.0, asclampreturns it there. On an i7-14700K CPU (4 threads, batch 8, 256×256, float32),RandomBrightnessandRandomContrasttake about 300 µs per call instead of 830 µs, against about 240 µs in 0.8.3, which had no input clamp. On an RTX 4090 they are 1.2–1.4× faster. (#6267)ColorJiggle's channel order andRandomMixUpV2's pairs are drawn as an int64 permutation, whatever the dtype the parameter generator samples in. A generator set tobfloat16used to raise"randperm_out_cuda" not implemented for 'BFloat16'on CUDA. That happened throughset_rng_device_and_dtype, through.to(torch.bfloat16)on the augmentation, and, since containers and parent modules now pass.to()on to their augmentations, through.to(torch.bfloat16)on any model that contains one. Infloat16, a MixUp batch above 2048 could not be permuted exactly. torch draws the same permutation for every dtype, so the parameters of every call that worked before are unchanged. (#6268)unproject_points_z1andcompute_correspond_epilines, compiled withtorch.jit.scriptand run on CUDA, returned an emptyint32tensor for an empty batch (no points) once the scripted function had run on non-empty inputs: TorchScript's CUDA fuser miscompiles a concatenation of a fused product when every input is empty. Both now avoid that group:unproject_points_z1concatenates the depth expanded to the product's shape, andcompute_correspond_epilinesscalesF xdirectly instead of concatenating the scaled components. Eager results are bitwise unchanged.unproject_points_z1also accepts a depth whose leading dimensions broadcast against the points, where it used to raise fromtorch.cat, and raisesShapeErrorfor a depth whose trailing size is not 1, where a(..., 2)depth used to return a meaningless(..., 4)result.kornia.image.image_to_stringandprint_imagematch an integer image's pixels at their exact 0–255 values on every device, as documented. The image was divided by 255 and multiplied back, which is exact on CPU but moved 126 of the 256uint8levels off their integer on CUDA, where a division by a scalar is a multiplication by its reciprocal. A CUDA image could therefore print some pixels in a different colour than its CPU copy. CPU output is unchanged. (#6269)An empty batch through a shape-changing augmentation with
p < 1now comes back at the configured output size, as withp=1, instead of at the input size:RandomCrop((4, 4), p=0.5)on a(0, 3, 6, 8)batch gives(0, 3, 4, 4), as in 0.8.3. This coversRandomCrop,CenterCrop,RandomResizedCrop,Resize,LongestMaxSize,SmallestMaxSize,RandomCrop3DandCenterCrop3D, the masks that follow the image, and the sizesAugmentationSequentialrecords for its later stages andinverse. A non-empty batch that the gate skips entirely still keeps its input size (#4429). (#6272)Video boxes passed through
VideoSequential(RandomMosaic)now follow the mosaic of their own frame, as image boxes do, withsame_on_frame=TrueorFalseand withp < 1; before, they were returned untransformed. Frames that a partial gate leaves with fewer boxes are padded to the mosaic box count with rows that export as zero in every mode, also after a later geometric transform, andVideoBoxes.to_tensor()returns them as one(B, T, N, ...)tensor. (#6273)distance_transformon MPS now stops once its cascade settles, as on CPU and CUDA: an 8 x 1 x 256 x 256 blob mask takes 9 ms on an M1 Pro, against 79 ms before and 12 ms in 0.8.3. Reading whether the cascade has settled costs MPS a few rounds' work, so it reads less often there; a cascade that cannot stop early, such as one from a single corner source, takes 5 % (512 x 512) to 20 % (64 x 64) longer than before. CPU and CUDA are unchanged. (#6274)adjust_brightnessandadjust_contrast, and with themRandomBrightness,RandomContrastandColorJiggle, clamp their own freshly computed result in place when no gradient is recorded. That saves one image-sized temporary per call. At batch 32 of 3×256×256 float32 on CPU, the extra 25 MB buffer made glibc trim and re-fault the heap on every call (18,400 page faults per call against 12,256), andRandomBrightnesstook 8.6–9.7 ms against 6.2 ms in 0.8.3. It now takes 7.5 ms, the remaining cost being the[0, 1]input clamp added in #5980. Values, gradients and the caller's tensor are unchanged. (#6276)RandomCutMixV2and the PatchMix generator draw their Beta mixing coefficient in float32 when their parameter generator is set to float16 or bfloat16, as the position samplers already do (#4553). torch draws Beta through Dirichlet, which has no CPU half-precision kernel. A CPU generator in half precision used to raise"dirichlet" not implemented for 'Half'on every call. That happened afterset_rng_device_and_dtype, after.to(torch.float16)on the augmentation (in 0.8.3 too), or, since containers and parent modules now pass.to()on to their augmentations, after.to(torch.float16)on any model that holds one. CutMix builds the concentration frombetadirectly in float32, so abetaoutside the float16 range keeps its value. Float32 and float64 draws are unchanged. (#6277)bilateral_blurandjoint_bilateral_blurare much faster on MPS: an 8 x 3 x 256 x 256 batch with a 5 x 5 kernel takes 40 ms on an M1 Pro, against 556 ms before and 30 ms in 0.8.3; a grayscale batch takes 18 ms, against 378 ms before and 208 ms in 0.8.3; and the RGB forward and backward pass takes 127 ms, against 1.1 s before. The filter's window tensors are now laid out in their memory order, which also makes CPU inputs that take the unfold path (small or differentiated ones) up to 30 % faster. Without a gradient the unfold path frees each window-sized temporary once used, so its peak memory is 27-42 % lower. Values change only by the rounding of a different summation order. (#6280)A fresh transfer that
validaterejects is now removed even when no other source could have used the emptied path -- which is everydownload_hf_filecaller, since it passes one URL. Those bytes arrived during the call and were refused, so unlike the ambiguous load failuresload_state_dict_from_urlweighs, keeping them would end the call having added a poisoned entry to a cache that had none. An offline re-fetch also reports the validator's rejection rather than the network error stacked on top of it, so the message names the file rather than an entry that is intact and, by then, restored. (#4367)Canny hysteresis preserves the input dtype, avoiding a convolution dtype mismatch for half-precision images. (#4393)
Constructing
ScaleSpaceDetectorwithcompile_modulesno longer permanently mutates the process-globaltorch._dynamo.config.capture_dynamic_output_shape_opssetting. (#4134)Correct non-zero sensor tilt in
tilt_projectionanddistort_pointsto match OpenCV, restoring forward/inverse round trips and correctingundistort_imagesampling. (#4384)Corrected stereo disparity validation errors to describe the required channels-last
(B, H, W, 1)layout and report the received shape. (#4380)Corrected the matrix-shape checks shared by
PinholeCameraandPinholeCamerasList, thepixel2camcoordinate-shape check, and thecam2pixelcoordinate/projection checks. Invalid inputs now raise the intendedValueErrorinstead of being accepted or failing later in tensor operations. The rank-4 matrices used byPinholeCamerasListremain supported. (#4387)DeDoDe's vendored DINOv2 no longer probes for
xformers; the pure-PyTorch path it always ran is the only one. (#4288)Define singleton pixel axes at normalized center, reject non-positive normalization sizes, preserve empty warp destinations, and deprecate the now-unused
epsnormalization parameters (#4006). The four{de,}normalize_pixel_coordinates{,3d}helpers andnormal_transform_pixel{,3d}now derive their scale from the size directly instead of rounding the size into the coordinate dtype first, so results at non-degenerate sizes can move toward the exact value: by up to one ulp infloat32/float64, but materially more infloat16/bfloat16, where the old code could not represent the size at all (denormalize_pixel_coordinatesatbfloat16and size 3000 returns 1496 where it returned 1504).A singleton axis previously divided by zero (or by the
epssubstituted for it), so the change is not confined to those helpers: it reaches every operation that normalizes a coordinate frame with a size-1 dimension.create_meshgrid(1, 4, normalized_coordinates=True)returnednanin the singleton component and now returns0;warp_perspective,crop_by_transform_mat,homography_warpandwarp_image_tpsonto a 1-pixel-high destination returned all-nanand now return the finite row the 2-pixel control produces;spatial_soft_argmax2dandspatial_expectation2don a 1-pixel-high input returnednanand now return0; andconv_soft_argmax2d,conv_soft_argmax3dand theirConvSoftArgmax*module forms shift by one normalized unit when a kernel or input axis is1(conv_soft_argmax2dwith a(3, 1)kernel returned[-1.6667, -1.0, ...]and now returns[-1.0, -0.3333, ...]).Drop the constant homogeneous row from
laf_to_boundary_points. The function appended a[0, 0, 1]row to every LAF so that it could divide the result by a homogeneous coordinate that is always exactly1; it now multiplies by the(2, 3)LAF directly, and moves its 3-column basis to the LAF's device and dtype before broadcasting it instead of after (the previous order materialized, and on an accelerator transferred, one copy per LAF -- ~12 MiB per call atN = 20000for a tensor withn_ptsdistinct rows). The win is not the transfer: torch's CPU batched gemm falls off a fast path at the third row, sobmmon a(B, 3, 3)operand costs 23x a(B, 2, 3)one for 1.5x the arithmetic. Quiet back-to-back A/B against base8db1499aviabenchmarks/feature/laf_ops.py(Apple M1, torch 2.14.0, 4 threads, B=1 N=20000):laf_to_boundary_points1.07M -> 29.6M LAFs/s eager on CPU and 1.77M -> 4.27M on MPS;laf_is_inside_image, which calls it withn_pts=12on every detector forward, 9.75M -> 29.0M on CPU and 2.70M -> 8.53M on MPS. Results are bitwise identical on CPUfloat16andbfloat16and shift by at most 1.42 machine epsilon elsewhere, relative to the largest coordinate of the call -- the two gemm shapes round differently. Mean error against afloat64reference is slightly lower than before, andlaf_is_inside_image's boolean masks were bitwise identical across a 126-case device/dtype/shape sweep. (#4217)Eager bbox validation now rejects NaN and infinite coordinates:
validate_bboxreturnsFalseandBoxes.from_tensor(..., validate_boxes=True)raisesValueErrorfor thexyxy,xyxy_plusandxywhmodes, instead of accepting them as valid geometry (closes #4238). (#4243)Fix 2-D, 3-D, and mix augmentations raising a cross-device
RuntimeErrorwhen their random parameters are generated on the default CPU device and their input is on MPS or CUDA (#4164). Since #3722, four branchlesstorch.whereblends used the CPUbatch_probmask directly with accelerator outputs or transformation matrices. The selection mask now moves to the output device at each blend boundary, preserving CPU random-number generation and the ONNX/fullgraph-friendly blend. Callingaugmentation(x_accelerator)therefore works again without first moving the augmentation module or its RNG to the accelerator (#4151).Fix
Boxes.mergeconcatenating along the vertex axis instead of the box axis for unbatched(N, 4, 2)input. The olddim=1was correct for batched(B, N, 4, 2)data (where dim 1 is the box axis) but wrong for 3-D tensors (where dim 1 is the vertex dimension);dim=-3is correct in both cases and the behaviour of the batched path is byte-identical. For list-backed inputs, each batch row is now repacked with its real boxes before all trailing padding, and the combined per-image padding counts are retained. This makesto_tensortrim only padding instead of dropping merged boxes or exposing old padding as real boxes (#4168, #4175).Fix
Boxes3D.from_tensor(..., mode="xyzwhd")to preserve width, height, and depth field order for asymmetric boxes. (#4189)Fix
DenseSIFTDescriptorregistering a process-global cached tensor as its_poolingconv_weightbuffer, so that one instance'sload_state_dictsilently corrupted every other instance and every instance constructed later (#4068)._get_reshape_kernelmemoisestorch.eye(numel)pernumeland used to return a view of the cached tensor;.float()on an already-float tensor returns the same object, so no copy happened between the cache and the buffer, andload_state_dictcopies into buffers in place. Loading a checkpoint into oneDenseSIFTDescriptortherefore overwrote the shared identity matrix, with no error raised and every descriptor built from it wrong from then on. The cache is removed rather than made safe: cloning on the way out is what a safe cache requires, and a clone costs more than rebuilding the identity at every size measured (2.6 us against 2.0 us at the defaultnumel = 8 * 4 * 4; 3.9 ms against 2.8 ms at the former 4096 bound, which also retained 67 MB for the lifetime of the process). Descriptor output is byte-identical to before.Fix
SIFTDescriptor.gk,PatchDominantGradientOrientation.weightingandPatchAffineShapeEstimator.weightingbeing plain attributes, sonn.Module.to()left them behind on the original device and dtype (#4069). They are now non-persistent buffers:.to(),.cuda(),.half()and friends move them, and because they are fully determined bypatch_sizethey stay out ofstate_dict(), so existing checkpoints still load withstrict=True. The threeforwardmethods also cast into a local instead of rebinding the attribute, so a call no longer leaves the module's kernel in whatever dtype and device the last input happened to have. Numerical output is unchanged: the kernels were already cast to the input's dtype and device insideforward.Fix
find_essentialandrun_5pointraisingTypeError: all() received an invalid combination of argumentson PyTorch before 2.2 (#4043).run_5point,_solve_2x2_tikhonov_safeand the scripted Nister helper each reduced over two axes at once withTensor.any(dim=(-2, -1))/Tensor.all(dim=(-1, -2)), and multi-dimensionany/allonly landed in PyTorch 2.2, so the whole five-point solver was unusable on the declaredtorch>=2.0floor. The reductions now flatten the two trailing axes first, which is equivalent on every version.Fix
laf_is_inside_imagetreating the image extent as(w, h)rather than(w - 1, h - 1), which made its bounds asymmetric: the lower bound rejected anything left ofx = 0, but the upper bound acceptedx = w, a full pixel past the last valid columnw - 1(#4064). Valid pixel coordinates run0 .. w-1and0 .. h-1-- the conventionget_laf_centerdocuments and the onenormalize_laf/denormalize_lafalready use -- so the upper bound is noww - 1 - borderandh - 1 - border. A LAF whose boundary points reach past the last valid pixel coordinate is now reported as outside; anything strictly inside is unchanged. The equivalent inlined check inScaleSpaceDetector._process_octavemoved with it, so detections within one pixel of the right or bottom edge that used to survive itsborder=5filter are now discarded. That inlined check also computed itsmax |sin|constant with the wrong angular spacing (2*pi/11instead of the2*pi/10thatlaf_to_boundary_points(n_pts=12)actually samples), inflating the tested x-extent by 4% and making the inline check stricter than the reference it claims to reproduce; the two now agree exactly. That correction is a loosening in x, so it can changeScaleSpaceDetectoroutput on its own: a detection whose x-extent falls between the two constants used to be discarded and is now kept. It is rare -- the detection has to land in a band of width0.039 * half_sagainst the x bound -- but when it fires it can promote the strongest response in the image, so it is not output-neutral.Fix
match_fginn's geometric consistency check comparing every query's candidates against query 0's candidates instead of against the query's own 1st nearest neighbor, which changes everymatch_fginnandGeometryAwareDescriptorMatcher("fginn")result -- the latter being that class's default mode (#4062). The distancekdist[i, k] = || xy2[idx[i, k]] - xy2[idx[0, k]] ||was measured from a slice of dim 0 that broadcast query 0's whole candidate list over the batch; it is nowcandidates_xy[:, 0:1], i.e.kdist[i, k] = || xy2[idx[i, k]] - xy2[idx[i, 0]] ||. Three consequences disappear with it. The geometric term was inert -- an unrelated query's candidates are almost always farther apart thanspatial_th, so nothing was penalized and the raw 2nd nearest neighbor was used, makingmatch_fginnbehave asmatch_snn: on a 300x300 descriptor set with planted near-duplicates, 15 of the 15 matches shared withmatch_snnhad an identical ratio before and 14 of 15 after. Query 0 always matched, sincecandidates_xy[0] - candidates_xy[0]is identically zero, so all of its candidates were penalized and its ratio collapsed to ~0. And a query's ratio depended on the other queries in the batch: with only query 0 changed, one query's ratio moved between0.9005and2.8e-08. The seven existing FGINN tests pass unchanged on both sides, which is how this survived; two tests that discriminate it were added.match_fginn's docstring now also records the saturation corner, where every candidate falls withinspatial_thof the 1st nearest neighbor, the ratio collapses towards zero and the match is accepted.Fix
symmetric_transfer_errorreturningNaNinstead ofmax_numfor singular homographies. Whensafe_inverse_with_maskflags an input as non-invertible, the unshielded inverse matrix containing non-finite values propagatedNaNthroughoneway_transfer_errorand the arithmetic mask(there + back) * mask + max_num * (~mask), poisoning both the forward error and autograd gradients. Singular rows are now replaced by the identity before the differentiable inverse is taken, so the gradients with respect to both the correspondences andHitself stay finite (zero on the singular rows), and the final masking usestorch.whereto cleanly assignmax_num. Values for invertible homographies are unchanged; forsquared=Falsea singular row now scoresmax_numrather than the previous(max_num + eps).sqrt(), matching the documented contract. (#4203)Fix
torch.jit.scriptofrgb_to_yuv,yuv_to_rgb,rgb_to_xyzandxyz_to_rgbon older PyTorch (#4043). Their sharedkornia.color.utils._apply_linear_transformationhelper annotated its optional argument with the PEP 604torch.Tensor | Noneform, which the TorchScript compiler on the declared floor does not accept (reproduced on PyTorch 2.1.2, while PyTorch 2.9.1 compiles it), so scripting any of the four conversions failed. The annotation isOptional[torch.Tensor]now, which every supported version accepts.Fix patch extraction on MPS returning darkened patches for any LAF that touches an image border (#4063). MPS has no
padding_mode="border"fortorch.nn.functional.grid_sample, soextract_patches_simpleandextract_patches_from_pyramidemulate it with zero padding and a clamped grid. The clamp wasgrid.clamp(-1, 1), but withalign_corners=Falsenormalized coordinate±1is the outer edge of the border pixel, not its center, so bilinear sampling blended the border pixel with the zero padding and returned roughly half its value. The grid is now clamped to the outermost pixel centers,±(1 - 1/size)per axis, which reproducespadding_mode="border"exactly. On a patch overlapping the image corner the maximum deviation from the CPU result drops from0.395to2.5e-6on a[0, 1]image, with 64.7% of the patch's pixels previously off by more than1e-3. Every descriptor built on these patches —get_laf_descriptors,LAFDescriptor,SIFTFeature,KeyNetAffNetHardNetand the rest — moves with them for keypoints near the border. The CPU and CUDA paths never took this branch and are byte-identical to before.Fix the empty-result paths in
kornia.feature.integrateddisagreeing with the corresponding non-empty ones (#4065).get_laf_descriptorsreturned a hardcoded width of 128 with the LAF's dtype and device when it was handed no keypoints, so an empty batch through, say, a 256-d descriptor produced a(B, 0, 128)result that could not be concatenated with a real one; it now runs the descriptor once on a zero patch and returns its actual width (the flattened per-patch output, matching the non-empty path's.view(B, N, -1)), dtype and device. That is a widening of the empty path's failure surface: a third-party descriptor that raises on a zero input now raises here where it previously returned quietly.LocalFeatureMatcher.no_match_outputreturnedlafs0/lafs1of shape(0, 0, 2, 3)where the success path returns(1, NC, 2, 3), solafs0[0]raisedIndexErrorexactly when nothing matched; the empty tensors now keep the leading batch of 1. That is a shape change on a public return value -- code usingout["lafs0"].shape[0] == 0as its no-match signal now sees1and should testout["keypoints0"].shape[0] == 0, which was already the consistent signal.LocalFeatureMatcher.forward's docstring also stops claimingconfidenceis in[0, 1]: it is1 - distance, which for the raw-distance matchersnnandmnngoes at least down to -1 on unit-norm descriptors, and is unbounded below for arbitrary ones.Fix the inverted
SigLip2attention-mask polarity, so every call that passes anattention_maskchanges (#4043). All three mask branches ofSigLip2Attention(2-D(B, N), 3-D(B, N, N)and 4-D(B, 1, N, N)) negated the mask before handing it totorch.nn.functional.scaled_dot_product_attention, whose boolean form readsTrueas attend, not as mask out. Every position the caller asked to attend to was masked out and every padded position attended to, so an all-ones mask left every query row fully masked. The symptom is version-dependent because a fully masked row returns0from SDPA on PyTorch 2.5 and later andnanon PyTorch 2.4 and earlier:SigLip2.get_text_features(..., attention_mask=...)has been returning a zeroed attention output on current PyTorch andnantext features on the declaredtorch>=2.0floor. 2-D padding masks are now broadcast over the key axis only, matchingSiglipTextTransformer.create_bidirectional_maskin Hugging Facetransformers, so a partially padded sequence no longer produces a fully masked row. A row whose mask is entirely zero — an empty caption in a batch — is still fully masked and still follows the SDPA behavior above.Fixed
RandomPlasmaBrightness,RandomPlasmaContrast, andRandomPlasmaShadowto replay deterministically from storedparams=. (#4462)Fixed
dx_distort_points_kannala_brandtto return the true Jacobian ofdistort_points_kannala_brandt, including a finite affine Jacobian at the origin. (#4277, #4368)Fixed
unproject_points_z1depth shape handling for singleton and multi-axis batches, accepting both trailing-singleton and flat depth tensors. (#4355)Fixed fixture teardown between files when running half-precision tests with
--isolate-half-precision, including reporting parent fixture finalizer errors. (#4388)Follow-up fixes to the documentation revamp (#4155): the landing page's filtering card quoted the combined
filters/color/enhance/morphologycount next to akornia.filterslabel, the "Why Kornia?" hero carousel resumed after a visitor picked a tab, the Community page linked to the now-unregisteredlibrecv.org, and the GPU page promised CUDA measurements the committed benchmark runs do not yet contain.pydata-sphinx-themeis now version-bounded, since the site's CSS and JS target theme internals. (#4173)Keep
extract_patches_simpleandextract_patches_from_pyramidoff a broken reduced-precision CPU kernel: for afloat16/bfloat16CPU image, thegrid_samplekernels in torch <= 2.9 read out of bounds when a rotated patch straddles the image border and return NaN or garbage values far outside the image's range. Both extractors now sample reduced-precision inputs infloat32on every device and cast the patches back. This fixes the CPU kernel bug and avoids normalized-coordinate precision loss on large images; half-precision patches change on every backend, with the CUDA cost described under Breaking changes. Both extractors also replace their per-image Python loop with a folded batchedgrid_sampleover a(B, N*PS, PS, 2)grid, split alongNwhen needed to bound its workspace. Both forms compile underfullgraph=True, but the loop was unrolled at trace time into onegrid_sampleper batch element, so the graph grew with the batch and was recompiled for every new batch size: tracingextract_patches_simpleover batches of 2, 3, 5 and 7 built four graphs of 2/3/5/7grid_samplenodes before and builds two graphs with one node each now.Made uncompiled
RandomGaussianIlluminationinstances serializable withpickleandtorch.save, preserving parameter replay and thecompile()execution path after restoring the module. (#4457)Make YUV and XYZ transformations compute integer inputs in
float32instead of truncating their kernels, and preserve directly constructedfloat64coefficients. This makesrgb_to_yuv(uint8)returnfloat32on the input's original 0--255 scale, fixes signed-integer YUV results, and removes the existing float32 coefficient loss from float64 XYZ conversions. The two private linear-transformation helpers are now one implementation, whose CPU path uses its dtype/device-aligned compute operands (#4053).Make
guided_blur/GuidedBlurwork infloat16andbfloat16when the guidance has more than one channel. Multi-channel guidance solves a per-pixelC x Csystem, andtorch.linalg.solvehas no half-precision LU kernel, so every such call failed: on CPU withNotImplementedError: "lu_cpu" not implemented for 'Half', and on MPS with a hardOnly MPSDataTypeFloat32 is supportedassertion that aborted the process rather than raising. The system is now solved infloat32and cast back. A tensorepsalso takes part in dtype promotion, so the commoneps=torch.tensor(0.1)(float32) widened the matrix past the right-hand side and madesolvereject the pair; both operands are now solved in one dtype. Single-channel guidance never reached the solver and is unaffected.float32andfloat64results are bit-identical to before, and the op still compiles withfullgraph=Truein one graph. This takestests/filters/test_guided.pyfrom 98 failed / 67 passed to 169 passed under--dtype=float16,bfloat16.Make
load_pointcloud_plyandload_pointcloud_ply_binaryparse the PLY header instead of skipping a fixed number of lines. Both loaders skippedheader_size=8lines and read everything after them asx y ztriples, so a minimal PLY file (seven header lines, nocomment) lost its first point to a header line -- the binary reader returned header bytes decoded as doubles -- and any file with extra vertex properties (normals, colours) or afaceelement after the vertices was rejected or misread. The readers now stop atend_header, take the point count fromelement vertex N, selectx,y,zby property name whatever their scalar type, skip trailing elements, and read big-endian payloads.header_sizeis deprecated and ignored (aDeprecationWarningis emitted when it is passed). Files without a proper PLY header, which the old line-skipping loader could read by accident, are now rejected with aValueError, and so is a file that declares alistproperty among the vertex properties -- a list has no statically known length, so the columns after it cannot be located. The binary reader additionally rejects alistproperty in an element that precedes the vertices, whose byte length it would have to know to reach the vertex data; the ASCII reader reads such a file, since every ASCII element instance is one line whatever it contains.Make
yuv_to_rgbthe exact inverse ofrgb_to_yuv, so an RGB → YUV → RGB round trip is now limited only by the input dtype instead of losing up to1.36e-3(in B, atrgb = (1, 1, 0)) at every precision,float64included (#4044). The inverse kernel was a separately rounded copy of the published BT.470-5 M/PAL inverse relations rather than the inverse of the rounded forward kernel kornia actually ships, and one of its literals —2.029, where the inverse of kornia's forward kernel is2.03199968— carried most of the error.yuv_to_rgboutput therefore moves by up to1.23e-4in R,9.13e-4in G and1.60e-3in B over the documented YUV domain, andyuv420_to_rgbandyuv422_to_rgbmove with it. The forward direction (rgb_to_yuv,rgb_to_yuv420,rgb_to_yuv422) is unchanged. Agreement of the inverse with the standard's own relations improves overall, from1.54e-3to5.24e-4, though R alone moves the other way (1.54e-4to2.77e-4). The.. warning::blocks that documented the defect on the six affected functions and classes are gone.Make calibration
distort_pointsandundistort_pointstilt checks compatible withtorch.compile(fullgraph=True), preserving eager behavior. (#4391)Non-maxima suppression with a window larger than
(7, 7)no longer builds a(k*k, 1, k, k)one-hot convolution to gather each neighbour into its own channel. On CPU in half precision that convolution has no vectorized kernel and falls back to_slow_conv2d_forward, where it accounted for 99% of aMultiResolutionDetector.detectcall. The window minus its centre is now covered by rectangularmax_pool2dregions whose full-width slabs share one column pass, costingO(ky + kx)taps per position rather thanky * kx - 1, with the centre excluded by construction so the suppression stays strict.detecton a 240x240 image drops from 5757 ms to 27 ms in float16 and from 73.8 ms to 13.8 ms in float32; a 353x353k = 15suppression drops from 3150 ms to 10.5 ms in float16 and from 42.6 ms to 8.7 ms in float32, and from 12.1 ms to 0.15 ms for 1024x1024k = 21on CUDA. (#4242)Preserve empty color tensors on accelerator backends instead of asking
reshapeto infer an ambiguous batch dimension. This lets the YUV420 and YUV422 empty-input conversions return their documented empty RGB output on MPS, matching CPU behavior (#4185).Raise
NotImplementedErrorinstead ofRuntimeErrorfor an integralsrcon the empty-dsizepaths ofwarp_affine,warp_perspective,remap,warp_affine3dandwarp_perspective3d, matching what the non-empty path already raises fromgrid_sample(#4031). The degenerate path had its own explicit guard that fired first with a different exception type, so the exception a caller saw for the same invalid input depended on whetherdsizehad a zero dimension. The message is unchanged.NotImplementedErrorderives fromRuntimeError, soexcept RuntimeErroraround these functions still catches it; only code matching on the exact type sees a difference.Reduce local-feature extraction overhead by accumulating orientation histograms directly, batching built-in DoG extrema refinement, selecting coordinates before combining response signs, and using faster activation layouts in KeyNet and CPU HardNet. Detector settings and pretrained checkpoint formats are preserved. On CUDA the orientation histogram now accumulates with atomics, so identical inputs can differ at the ulp level between calls unless
torch.use_deterministic_algorithms(True)is set. (#4254)Replace the batched
torch.inverseinellipse_to_lafwith the closed-form inverse of its lower-triangular 2x2 matrix. Results agree with the previous implementation to1.6e-7 relative in1500x once measured ad hoc at N=20000 on Apple Silicon; rerun the benchmark there for a citable number). The function now compiles withfloat32(machine epsilon infloat64). Reproducible numbers viabenchmarks/feature/ellipse_to_laf.py(float32, N=1e3..1e5, torch 2.9.1, Linux/WSL2, base2009933e): throughput improves ~2.4-5.3x eager / ~3-6.5x compiled on CPU (i7-14700K) and ~1.4-1.7x eager / ~4.2-5.5x compiled on CUDA (RTX 4090). The largest win is MPS, where the batched inverse hit a pathologicallinalgpath, emitted a deprecated-resizeUserWarningon every call, and failed totorch.compile(fullgraph=Trueon every backend and acceptsfloat16/bfloat16on CPU, where the raw.inverse()call raised for low-precision dtypes (_torch_inverse_castwould have lifted that restriction too; the closed form is for speed). The off-diagonal dividesa21 = b / (a11 + a22)by the product of the diagonal square roots, which can neither overflow nor round to zero: every ordering of the reciprocal product overflows toinf(or flushes a representable value to0) on a sufficiently lopsided or subnormal diagonal, and when that product is subnormal the division loses precision but never corrupts a representable result to a zero,inf, ornan.Reset an automatic augmentation policy's cached transformation matrix before applying it again, both for a sub-policy inside
TrivialAugment,RandAugmentandAutoAugmentand for those policies nested insideAugmentationSequential. Consecutive calls that selected the same geometric policy could transform the input with the latest parameters while exposing the previous call's matrix throughtransform_matrix, the sub-policy accumulated one matrix per call for the lifetime of the module, and a nested policy never recorded its parameters or matrix at all.transform_matrixon a policy that has not run yet now returnsNoneinstead of raisingAttributeError(#4171).Restore the YUV test coverage that #3539 deleted, and fix the
kornia.colorYUV docstring examples (#4045).rgb_to_yuv422andyuv422_to_rgbboth documented an example that called the 4:2:0 function instead of themselves, so a reader copying either got the wrong conversion and the wrong chroma shapes; several other examples stated a shape in a trailing comment that disagreed with what the function returns (RgbToYuv420said2x1x2x3for a(2, 2, 2, 3)chroma plane). Every example inkornia/color/yuv.pynow asserts its output shape as a doctest instead of stating it in a comment. The 4:2:2 docstrings also claimed the input only had to be divisible by 2 "vertical" while the guard rejects odd height and odd width, so a reader padding one axis hit aShapeError, andyuv422_to_rgblabelled its chroma argument "UV (luma)". The fourShapeErrormessages those guards raise said "evenly disible by 2" and now say "divisible", as do the two identical messages inkornia/color/raw.py.yuv422_to_rgb/Yuv422ToRgbalso gained a.. warning::naming a known defect: they validate only the chroma width, so a wrong chroma height surfaces as a bareRuntimeErrorfromtorch.cat(#4050). The same entry gave every YUV-to-RGB form a second warning, for the round trip that #4044 has since fixed; those blocks are gone, see the entry above. On the test side, both gradcheck skips now cover the XLA/TPU fixture as well as MPS, since XLA lowers a float64 request to float32, where gradcheck's defaulteps=1e-6makes the numerical Jacobian invalid: the name-based marker inconftest.pyfor tests called*gradcheck*, and the device guard inBaseTester.gradcheckfor the six callers named something else. No runtime behavior changed.Stop
MultiResolutionDetector(and thereforeKeyNetDetector) fabricating detections, honour itsmaskargument, and keep its LAFs in the input dtype (#4089, #4090, #4091).Padded slots are zero, and the shape is always
num_features.detect_features_on_single_levelmasked every non-candidate position totorch.finfo(dtype).min / 2and then rantopkwithkclamped against the pixel count rather than the number of surviving candidates. Once a pyramid level ran out of above-threshold maxima,topkcould no longer rank -- every remaining position carried the same sentinel -- so it returned an arbitrary tie-break subset, in practice the low flat indices, which is exactly the border stripremove_bordershad just zeroed.MultiResolutionDetector(BlobHessian(), num_features=100)on a plain64x64image returned 70 of its 100 features that way, each with a response of-1.7e38and a real-looking coordinate. Those slots are now padded with a zero response and a zero LAF, which is whatScaleSpaceDetector.detectalready does for a short result, andforwardre-applies that padding after the affine-shape and orientation modules, which would otherwise normalise a zero frame into a finite one.detectalso only ever trimmed an over-long result, so a level capped at its own pixel count, or a per-level quota rounded down to zero, produced a short one: a one-level8x8image asking for 100 features returned 64, and the default configuration asking for 1 feature returned 0, which madelafs[0, 0]raise. The result is now padded up tonum_featureswith the same zero response and zero LAF. Callers that tested for the sentinel (resp < 0) should testresp == 0; callers that consumed the responses as scores no longer need to.num_features=1returns a real detection. The per-level quotas each truncate independently, and atnum_features=1the six default shares are0.508 .. 0.016, so every one of them rounded to zero and no level was asked for a single candidate. The apportionment now hands its one slot to the level with the largest share whenever truncation would otherwise lose every slot, sonum_features=1returns the same best feature thatnum_features=2returns first. An apportionment that already gives out a slot is untouched, which with the default configuration is everynum_features >= 2(verified byte-identical withtorch.equalover 16 size/count combinations).The
maskargument works, and means "where a detection may be".forward(img, mask)anddetect(img, mask)accepted amask, documented it as "a mask with weights where to apply the response function", and ignored it -- an all-zero mask returned bit-identical output. Anyone who was passing a mask and silently getting unmasked detections now gets masked ones. The semantics are the same in both detectors and are chosen from the caller's side. A boolean or integer mask is binary: any non-zero value keeps a position, so a 0/1 mask, an OpenCV 0/255 mask andimg > 0all mean the same thing (a raw cast would have multiplied the responses by 255 and defeated an absolutescore_threshold). A floating-point mask is used as weights on the detection scores: a weight in(0, 1]scales a score toward the worst -- a non-negative score is multiplied by it, a negative one divided -- so a down-weighted candidate never outranks a full-weight one with an at-least-as-good score (a plain multiply pulled a negative score toward zero, i.e. up the ranking of a signed response), and a zero or negative weight suppresses. The weights are cast to the image dtype, so a weight a half-precision image cannot hold rounds to zero and suppresses, and clamped to one, so a float 0/255 mask (an OpenCV mask through.astype(np.float32)) means what the integer one means rather than scaling every score by 255. The weighting runs in float32 for half-precision input and is bounded at the dtype's most negative finite value, so a negative score divided by a small weight cannot overflow to-inf; an unfilled slot is ranked with-inf(not a finite sentinel such asfinfo.min / 2, which a genuine extreme response could sort below, and did: four float32 maxima at-2e38were returned for a single image and dropped for a batch), so every finite detection precedes the padding. The mask is checked at the integer maximum and again at the sub-pixel-refined centre, conservatively (every octave pixel the centre touches), so the refinement cannot carry a detection into the zero region. A NaN weight suppresses rather than winning the ranking. The mask must be(1 or B, 1, H, W)with the image's spatial size. It is resampled onto every pyramid level or octave with a min-pool rather than an interpolation, so a zero region suppresses every level pixel it touches and a two-pixel zero stripe does not vanish at a factor-four level. And it is applied to the non-maxima-suppression output, not to the response the suppression reads: multiplying the response first carves an edge into it, and the bilinear ramp of that edge was a "maximum" on the suppressed side, so a blob wholly inside the zero region was still detected (#4102).ScaleSpaceDetector, which did multiply its response per octave, takes the same path; its detections inside the region kept by a binary mask are unchanged. A floating-point mask used to weight the response before the non-maxima suppression and the sub-pixel refinement, so a graded mask moved maxima and their refined positions; it now weights only the score of a maximum found in the unweighted response, so the set of candidates and their positions are those of the unmasked image and the weight decides their rank.LocalFeatureMatchernow carries those masks through the full extraction-and-matching path. It documentedmask0/mask1as(B, H, W)inputs but never passed either to its local feature module; that historical shape is accepted by adding the singleton channel, and the detectors'(B, 1, H, W)form is also accepted directly.A mask no longer changes the response dtype. It is resampled and cast onto the response map, where the multiplication used to promote it, so a
float16image with afloat32mask returnedfloat32responses besidefloat16LAFs. This also applies toScaleSpaceDetector, which shares the resampling helper: afloat32image with afloat64mask used to returnfloat64and now returnsfloat32, i.e. the image dtype, in both detectors.ScaleSpaceDetectorgains the same shape check, and accepts a boolean or integer mask through the same helper (it raised on one before). It resampled a mask of any size onto its octaves without complaint, so a stale mask from before a resize, or a transposed one, was silently stretched onto the wrong geometry, and a multi-channel mask was broadcast over the scale levels rather than the channels -- an error when the counts differed, the wrong weighting when they matched. Both detectors now require(1 or B, 1, H, W).ScaleSpaceDetectorno longer leaks its own top-K sentinel for a batch. ForB > 1the per-octave top-K ranks over the whole scale-space volume with non-candidates masked totorch.finfo(dtype).min / 2, and an image with fewer maxima than requested got those sentinels back as detections:ScaleSpaceDetector()ontorch.zeros(2, 1, 32, 32)returned 70 slots per image with a response of-1.7e38and an arbitrary LAF, where the same input atB = 1returned 500 zeros. Which slots a detection filled is now tracked through the top-K rather than inferred from the response, and an unfilled one -- the sentinel, the padding that tops a short result up tonum_features, or a candidate whose frame reached outside the image -- carries a zero response and a zero LAF, indetectand, after the affine-shape and orientation modules have run, inforward, and sorts after every real detection, including a negative one. The mask is deliberately notresponse == 0: the response function is pluggable and may be signed, so an exact zero can be a genuine maximum and keeps its frame. The border-rejected candidate is the one visible change atB = 1: it used to keep its coordinates beside a zero response, i.e. a keypoint that was never detected, and its scale was often the largest in the result. Both detectors'forwardread occupancy off the zero LAF, so a subclass overridingdetectis honoured whole.Half-precision input yields half-precision LAFs.
detect_features_on_single_levelhardcoded.float()on the pixel coordinates, so afloat16/bfloat16image came back withfloat32LAFs beside half-precision responses. The index-to-coordinate arithmetic runs in float32 (float64 for a float64 image) and only the finished coordinate is cast to the input dtype;float32andfloat64output is unchanged. A half-precision LAF centre carries the dtype's integer resolution: exact up to 256 inbfloat16and up to 2048 infloat16, then on a 2 px grid up to twice that, 4 px up to four times, and so on -- where the oldfloat32LAFs were exact.A detector model must return one spatial response map.
detect_features_on_single_levelflattened the whole response tensor and decoded the flat top-K index with the width alone, so a candidate from channelclanded aty + c * H;BlobHessianon an RGB image put 56 of 100 LAFs outside a64x64frame, up toy = 179.9. Merely decoding the channel would still spend the budget on duplicate LAFs -- a grayscale image repeated into RGB returned three copies of almost every feature, whose grayscale descriptors are identical.MultiResolutionDetectorandScaleSpaceDetectornow require their detector model to emit one response channel and fail with a named error otherwise. This does not restrict the model input: a learned detector may consume RGB (or any other channel count) and collapse it to one response map itself, which is the intended color-image path. Single-channel input and response output are unchanged.score_thresholdmust be non-negative, andMultiResolutionDetector.__init__raisesValueErrorotherwise: non-maxima suppression writes an exact zero at every suppressed position, so a negative threshold admitted all of them as detections (withscore_threshold=-1.0on a64x64image, 70 of 100 returned features were suppressed border pixels) and would now also be indistinguishable from the zero response that marks an unfilled slot.detectenforces its documented(1, C, H, W). It is public, and a larger batch was flattened across the batch axis and silently returned coordinates for the wrong image.forwardalready had that guard, so only directdetectcallers see a difference.A short result is sorted.
MultiResolutionDetector.detectonly ran its final top-K when the levels had produced more slots thannum_features, so a short result came back in level order with each level's own padding left in place: withpyramid_levels=2, up_levels=0, num_features=6000on a48x48image the three real detections sat at flat indices 0, 1 and 2304. The ranking is now unconditional, as it is inScaleSpaceDetector.detect, and the zero-response padding sorts to the end.Padding is not a correspondence.
LocalFeatureMatcherused to describe and match every fixed-shape slot, soDescriptorMatcher("nn")returned every padded origin frame andmnnreturned one false origin match even when neither image contained a detection. Zero LAFs are honest, but they are also identical, and identical descriptors match each other at zero distance -- with plain nearest-neighbour matching the padded block became the largest consistent set of "correspondences" and captured RANSAC (SIFTFeature(400)on two crops of one image: 0.09 px mean reprojection error onmain, 31 px with the zero LAFs matched, 0.09 px with them dropped). The matcher now filters zero LAFs before matching, and skips a pair when either side has nothing left (matcheris an arbitrary module with no obligation to accept a(0, D)input); the ratio testsmatch_snnandmatch_smnnreject the block on their own (match_mnnandmatch_nndo not: identical zero descriptors are mutual nearest neighbours at distance zero), andLocalFeature.forwarddocuments the one-line filter for a hand-rolledmatch_nnpipeline. The feature benchmark does the same before affine/orientation/description, avoiding meaningless descriptor work and the quadratic distance-matrix cost of padded rows; its CUDA timers also synchronize around the measured detector and full matching regions.The
Argsblocks ofColorJitter,RandomBrightnessandRandomGaussianBlurno longer document asilence_instantiation_warningargument that none of them accepts, andColorJitternow documents itsorderargument: a fixed (sub)set of brightness/contrast/saturation/hue indices that makes the transformtorch.compilefullgraph-safe, with the drawn_params["order"]entry ignored when it is set. (#4437, #4490)The
Import SurfaceCI check accepts deliberate public-name removals recorded in the same change. Edits totests/api_surface.jsonmust correspond to actual export removals and acknowledge only the exact recorded module/name. Submodule APIs recorded only under an ancestor, and APIs outside the inventory, use exact module/name entries intests/api_surface_removals.json; only new entries matching a current__all__removal count. Malformed records, deleted inventory module keys, unrelated Python edits, and acknowledgements staged in earlier changes cannot authorize removals. Both record files trigger the workflow. The export resolver includes implicit submodule bindings and rejects unsupported dynamic binding expressions as evidence of removal. Deprecation windows and release notes still apply. (#4190, #4230)The generated example figures in the API reference are rendered from RGB input.
docs/generate_examples.pydecoded the sample images withcv2.imdecodeand wrote them withcv2.imwrite, both BGR, so every tensor the examples fed to kornia held reversed channels. The two swaps cancel in the written file for channel-agnostic operations, but 35 colour-dependent figures change, and the ones that depend on which channel is which (rgb_to_hsv,ColorJitter,apply_colormap, the bbox and keypoint colours ofAugmentationSequential, ...) showed a blue cast or swapped overlay colours. The generator now decodes and writes with PIL, draws the KeyNetAffNet LAF figure with kornia's ownget_laf_pts_to_draw, andopencv-pythonandkornia_moonsleave the[docs]extra. (#4306)The pinned-torch CI legs no longer run against the lockfile's
triton.uv syncinstalls the locked torch's dependency set, and each matrix leg then swaps torch alone for a+cpubuild -- whose wheels declare notritonat all -- so the lockfile's triton survived as an orphan of a torch that was no longer installed. torch guards its inductor triton path on import availability rather than on version, so it dispatched onto that orphan and the2.6.0leg died infrom triton.backends.compiler import AttrsDescriptoron 32 dynamo and export tests, having never been green. The install step now drops sidecar packages the installed torch does not declare, and the verification step asserts the whole environment against that torch (.github/scripts/check_torch_env.py) so a mis-provisioned venv fails at setup instead of as a wall of unrelated-looking test failures. The fivetests/core/test_small_linalg.pyONNX cases the import error was masking now export withexternal_data=False, which torch 2.6's dynamo exporter requires when the destination is aBytesIO. (#4199, #4200)Validate the chroma plane height in
yuv422_to_rgb, so a chroma plane whose height does not match the luma now raisesShapeErrorinstead of reachingtorch.catand dying there with a bareRuntimeError(#4050). 4:2:2 subsamples width only, so chroma keeps the full luma height; the guard checked only the width ratio, where the 4:2:0 twinyuv420_to_rgbchecks both axes. This is observable to callers on the error path:ShapeErrorderives fromBaseError, notRuntimeError, so code catchingRuntimeErroraroundyuv422_to_rgbto handle a malformed chroma plane will stop catching it. No previously working input changes behaviour —torch.catalready rejected every mismatched height. A zero-width chroma plane whose height also differs now reaches the guard, since the new clause short-circuits the width division; the matching-height case still raisesZeroDivisionErrorand remains open as #4056.Boxes.pad,Boxes.unpadandBoxes.clampaccept the unbatched(N, 4, 2)container the class documents and constructs. All three assumed the batched(B, N, 4, 2)indexing:padandunpadbroadcast the padding as(B, 1, 1), which does not fit the unbatched(N, 4)coordinate view and raisedRuntimeError: output with shape [1, 4] doesn't match the broadcast shape [1, 1, 4], andclampmaterialized its bounds withrepeat(1, _data.size(1), 4)and raisedIndexError: too many indices for tensor of dimension 2. Adding a leading singleton batch axis to the same boxes made all three work. They now broadcast against whichever rank the container holds and match the singleton-batch result; an unbatched container carries one image, so a per-image tensor with more than one row is rejected. Batched results are byte-identical, including for a non-finite bound:clampstays comparison-based, so aNaNbound leaves the coordinate alone rather than propagating into it (closes #4244). (#4372)Boxes.to_maskleaves list-padding channels empty, including after coordinate transforms, instead of treating padding entries as real boxes. (#4390)Boxes3D.from_tensor(..., validate_boxes=True)rejects non-finite coordinates, andvalidate_bbox3dreturnsFalsefor them instead of raising anAssertionErrorthat names the wrong defect. This is the 3D counterpart of #4243. Aninfpassed the positive-extent checks outright, and aNaNpassed them because every comparison againstNaNisFalse, so the box was constructed with non-finite vertices; invalidate_bbox3dtheNaNinstead reached theallcloseextent comparisons and raised "Boxes must have be cube, while get different widths".validate_bbox3d's four internal callers use it for its raise and discard the result, so they now convert theFalsethemselves and keep raising the sameAssertionErrorthey did before, with a message that now names the non-finite coordinates instead of reporting mismatched cube extents. Thevalidate_boxes=Falseopt-out and the export gate are unchanged (closes #4258). (#4343)Boxes3D.to_tensorandBoxes3D.get_boxes_shapeare differentiable again (#1396). Both reduce a box's 8 vertices to its min/max corner withamin/amax, which is a genuine kink -- not differentiable in the classical sense -- wherever multiple vertices exactly tie for an axis extremum. Every face of an axis-aligned box has such a 4-way tie by construction, where PyTorch'samin/amaxbackward splits the gradient evenly across the tied vertices (1/4each): a valid subgradient, usable for optimization, but one thattorch.autograd.gradcheck's central-difference estimate does not match at that exact point -- the same non-uniqueness any reduction has at a kink (torch.max,ReLU). That mismatch was previously taken for a genuine gradient bug andto_tensorraisedRuntimeErrorwhenever its input required grad, unconditionally, including for the common case of a caller who never differentiates through a tie at all (an oriented, non-axis-aligned box, or a loss that never reaches the tied component). The guard is removed; the docstring documents the tie behavior instead of calling it a bug.Boxes(2D) uses the same reduction and was never guarded, because an axis-aligned rectangle's ties are always 2-way, where the1/2split happens to numerically coincide with the central-difference estimate -- the same kink, just invisible togradcheckthere.CameraModelBase.__init__now validatesparamsagainst the shape it documents, instead of storing whatever it is given. The typed constructors (PinholeModel,BrownConradyModel,KannalaBrandtK3,Orthographic) each apply the same two comparisons, so only the direct-construction path -- which is public, and is what the class docstring's own example uses -- was unguarded. A short vector used to construct and then fail with anIndexErrorfrom insideAffineTransform.distort, naming neitherparamsnor the camera; a rank-3(B, 1, N)tensor used to construct, project, and silently return a(1, 1, 2)result. Both now raiseValueErrorfrom the constructor. (#4316, #4369)ConvQuadInterp3d/conv_quad_interp3dno longer return NaN gradients forfloat16input. The Hessian determinant_solve_cramer_sym3x3divides by is a product of three second derivatives, so for a[0, 1]response it lands around 1e-4 and below and still clears theepsgate. The forward divides by it once and stays finite, but the backward scales by1 / det**2, whichfloat16cannot represent (finfo(float16).tinyis 6.1e-5), so the gradient overflowed and reduced to NaN over part of the volume. The solve is now promoted tofloat32forfloat16input and the shifts cast back, as #4231 already does for the half-precision meshgrid.bfloat16keepsfloat32's exponent range and was never affected;bfloat16andfloat32outputs are unchanged. (#4305)HyNetandSOSNetnow run in half precision, on CPU and on GPU, and no longer return NaN for a degenerate patch (closes #4224). Two defects sat on the same line. On CPU both raisedNotImplementedError: "avg_pool3d_out_frame" not implemented for 'Half'(and the'BFloat16'spelling): their finalLocalResponseNormis handed a 4-D(B, C, 1, 1)tensor, which routestorch.nn.functional.local_response_normthroughavg_pool3d, and that kernel has no CPUfloat16/bfloat16implementation. Separately, infloat16on a device where the kernel does exist (MPS, CUDA), the descriptors came back all-NaN for any patch the network maps to exactly zero: theepsthat keeps the normalisation's division defined (SOSNet.forward'seps,HyNet'seps_l2_norm, both1e-10) is not representable infloat16and flushes to0.0, leaving0/0. EveryConv2dinSOSNethasbias=Falseand everyBatchNorm2disaffine=False, so any constant patch reaches the normalisation as exactly zero;HyNetreaches it only withis_bias=False.bfloat16keepsfloat32's exponent range, so the guard survives there and only the CPU kernel gap applied to it. Both models now take that one normalisation step infloat32for either half-precision input and cast the result back -- a wider lift than thefloat16-only onekornia.feature.siftdescgives its own1e-10guards, because the CPU kernel gap covers both dtypes.float32andfloat64take the original expression and are bitwise unchanged on CPU, CUDA and MPS. Half-precision output does change, by 0.25-2.25 eps, and where it moves most it moves towards thefloat64reference rather than merely away from NaN:SOSNetfloat16goes from 2.15e-03 to 2.28e-04 of maximum absolute error against afloat64model carrying the same weights, and the configurations that do not improve stay within one eps of where they were. Half-precision descriptors are therefore not comparable bit-for-bit across this release. (#4225)ManyToManyAugmentationDispathernow rejects mismatched numbers of input bundles and augmentations before applying any transformation, instead of silently dropping surplus inputs or skipping augmentations. (#4461)ModelBase.saveand_save_outputswrite the visualizations they are given instead of raising. They handedvisualize's float output towrite_imageunder a hard-coded.pngname, but PNG isuint8/uint16only, so every container'ssave(SemanticSegmentation,ObjectDetector,EdgeDetector,DepthEstimation) raised on its first write and left an empty directory behind. Float images are now converted touint8, clamped to[0, 1]first so an out-of-range visualization does not wrap. A batched(B, 3, H, W)output -- the shape the containers document -- is written as one file per item rather than passed whole towrite_image, which takes(3, H, W)and rejected the rank with a message naming neither. (#4322)MultiResolutionDetector.detectapportionsnum_featuresacross pyramid levels with largest-remainder (Hamilton) apportionment instead of flooring each level's fractional share independently (#4101). The floors used to discard every fractional part, so a smallnum_featurescould round the whole apportionment down: with the default configuration the six shares are0.508 .. 0.016, and every level but the finest lost its entire quota to truncation, so the detector effectively searched a single scale. The shortfall --num_featuresminus the sum of the floors -- is now handed to the levels with the largest fractional remainder, one slot each, so the quotas always sum to exactlynum_featuresand stay spread across scales. #4098's narrowernum_features=1fallback, which handed the request's one slot to the largest-share level when every quota floored to zero, is the special case where the shortfall equalsnum_featuresand is superseded by the general apportionment. The apportionment was then removed again by #4222, inside this same unreleased window, so no release ever carries it; thenum_features=1behaviour it fixed still holds.MultiResolutionDetector.detectnow returns thenum_featureshighest responses in the image (#4222). Each pyramid level used to be asked only for its own share of the budget, so a level could contribute at mostquotas[0](the upscaled level) orsum(quotas[: i + 1 + up_levels])(pyramid leveli) -- both well undernum_featuresfor the finer levels. When an image's strongest maxima concentrated on one level, which is the common case rather than a corner case, the excess was never requested and so could not be ranked in by the final globaltopk: the detector silently returned something other than the top-k, and the sorted responses ofdetect(k)were not a prefix of those ofdetect(k'). Every level is now searched fornum_featurescandidates, which is exactly sufficient because the detections a level contributes to the global top-k are that level's own strongest. The per-level apportionment, including #4101's largest-remainder rounding, is removed with it. This changes which keypoints are returned for a given image: callers get strictly better-ranked detections, and any result that depended on the old per-level spread will differ. The prefix is on the sorted responses, not on which detection carries a given response:topkbreaks a tie by position, so exactly equal maxima can come back in a different order for a differentnum_features. It carries about 1.2x the candidates through the concatenation, which is not measurable next to the response function and the non-maxima suppression.Normalize,DenormalizeandRescaleregister their constants (mean,std,factor) as non-persistent buffers instead of plain attributes, so.to(device)moves them with the module. Previously they stayed on the CPU: eager tolerates the mix, buttorch.exporttraces with fake tensors and refused it, so exporting a preprocessing pipeline from an accelerator failed while the same pipeline exported fine from the CPU.Denormalizenow coerces a scalarmean/stdto a 1-D tensor, asNormalizealready did, which changes its__repr__to matchNormalize's and lets a scalarDenormalizereach the ONNX export branch instead of raisingIndexErrorthere. The buffers are non-persistent, sostate_dict()is unchanged and existing checkpoints still load. (#4323, #4330)PatchSequentialnow augments every patch of every image and runs the complete selected sequence. The padding, reconstruction and parameter-generation behaviour changes are listed under Breaking changes. Refs #4421. (#4460)PinholeCamera.from_parametersnow fillsheightandwidthfor the whole batch. It built them withheight_tmp[..., 0] += heighton a(B,)zero tensor, so every batch element after the first kept0whilefx,fy,cx,cy,tx,tyandtzwere broadcast correctly, and the camera looked healthy until something read its image size.batch_size=1, the only case that worked, is unchanged. (#4279)PinholeCamera.projectnow reports rank-1 inputs with the same explicitValueErrorused by the point-conversion helpers instead of an internalIndexError. Refs #4266. (#4450)PinholeCamera.scaleno longer shares itsextrinsicstensor with the source camera, soscaled.tx = 7leaves the camerascale()was called on unchanged. The returned camera's numbers are unchanged. (#4264, #4349)PinholeCamera,StereoCamera, andwarp_frame_depthnow support empty batches. (#4386)RandAugment'smguard is exclusive at both ends, but its docstring and its error message both named the closed interval[0, 30], so a user who asked for the maximum strength the message advertised got an exception saying30was in range. Both now read(0, 30); the accepted values are unchanged.nwas validated nowhere:n=0constructed aRandAugmentthat applied nothing, andnabove the policy length was silently clamped, because the sampler draws without replacement. It is now checked against the policy.AutoAugment's magnitude bin indexes two adjacent points of an 11-point scale, so9is the last usable bin; a larger one raised a rawIndexErrornaming an internal tensor, and a negative one wrapped silently onto a reversed range. Out-of-range bins now name the operation and the valid range. Operations that ignore the magnitude entirely keep accepting any bin. (#4447)RandAugment,AutoAugment,TrivialAugmentandAugMixno longer silently upcast half-precision batches tofloat32.OperationBase.forward— the shared gate every auto-augment op routes through — moved itsbatch_probmask toinput.devicebut notinput.dtype, and sincebatch_probisfloat32the expressionbatch_prob * op(x) + (1 - batch_prob) * xpromoted afloat16/bfloat16input up tofloat32(the op output and input are both low precision, only the gate was not).float32/float64inputs are unaffected and their numeric output is byte-identical. The mask is now cast toinput.dtypeas well. Partially addresses #4153: this clears theRuntimeErrorbehind nineteen of that issue's Linux CPU half-precision xfail lines fortests/augmentation/test_auto_operation.py(all tencpu_bfloat16entries, nine of the tencpu_float16), which are removed fromtesting/half_precision_xfails/. The tenthfloat16line is kept:TestAutoAugment::test_reproduce[cpu-float16]still fails, now on anAssertionErrorrather than aRuntimeError— a smaller residual, not a fix. (#4210)RandomBoxBlur'snormalizedargument is documented as what it does. It was described as "if True, L1 norm of the kernel is set to 1", but it was forwarded positionally intokornia.filters.box_blur'sseparableparameter: it chooses between the separable and the single 2D pass, and the kernel is L1-normalized either way, sonormalized=Falsereturns window means, not sums. The call now passesborder_typeandseparableby keyword; outputs are unchanged. (#4433, #4486)RandomChannelDropout.fill_valueandRandomGaussianBlurGenerator.sigma(when passed as a Tensor) are registered as non-persistent buffers instead of plain attributes, so they move withModule.to()/.half()/.cuda()and appear innamed_buffers()like the rest of the module's state;state_dict()keys are unchanged. Neither crashed before this change (both re-derived device and dtype inline on every call), so this is a hygiene fix, not a bug fix for a crash. One user-visible effect: after.half()/.bfloat16()the fill value is now held in that dtype, so an input already in the module's dtype is unaffected, while afloat32input fed to a half-convertedRandomChannelDropout(fill_value=0.3)is filled with0.300048828125(float16) or0.30078125(bfloat16) rather than0.3-- the same buffer semantics asNormalize. (#4337)RandomCutMixV2andCutmixGeneratordocumentcut_sizeas what it is: the[min, max]clamp on the Beta-sampled mixing coefficientlambda, where the cut side isfloor(sqrt(1 - lambda) * side), so a largercut_sizegives a smaller cut. It was described as the "minimum and maximum cut ratio". A minimum of1.0is now rejected with aValueError: it forcedlambda = 1, built an inverted zero-size box and silently made the augmentation an identity. (#4439, #4491)RandomMosaicnow preserves(H, W)for non-square inputs whenoutput_size=None; it previously returned(W, H).start_ratio_rangenow scales x by width and y by height; it previously scaled x by height and y by width. (#4459)RandomRainnow rejects drop heights equal to the image height and absolute drop widths equal to the image width with the documented validation error, instead of allowing boundary-sized drops to reach an internalIndexError. (#4451)RandomRainwithsame_on_batch=Truenow samples the same number of rain drops for all samples in the batch. (#4453)RandomThinPlateSpline(scale=0.0)now generates zero control-point displacement instead of raising an error when constructing a degenerate uniform distribution. (#4463)RandomTransplantationandRandomTransplantation3Dtransplanted nothing on MPS when noexcluded_labelswere given: PyTorch's MPS backend evaluatesall()over the empty excluded-label axis to an undefined value, usuallyFalse, so every donor label was filtered out and the output equalled the input. The filter is now skipped when there is nothing to exclude. (#4160)RenderingDeFMO(used byDeFMO) no longer crashes on a half-precision forward pass. Its rendering time-steps (times) were a plain Python attribute, not a registered buffer, sonn.Module.to()never moved it;forwardre-derivedtimes's device from the input on every call but never its dtype, soRenderingDeFMO().half()lefttimesatfloat32and the first forward raisedRuntimeError: Input type (torch.FloatTensor) and weight type (torch.HalfTensor) should be the same.timesis now a non-persistent buffer (it is fully determined bytsr_steps, not learned, sostate_dict()keys and existing checkpoints are unaffected), andforwardcasts into a local variable rather than depending on the caller having matched dtype. Same bug shape as #4069/#4079 in a different class; the normalfloat32path is byte-identical to before. (#4319)SIFTDescriptor,DenseSIFTDescriptor,HardNetandHardNet8return NaN for a constant patch infloat16, and the SIFT descriptors' backward is NaN infloat16wherever two neighbouring pixels are equal.F.normalize's defaultepsof 1e-12 is not representable infloat16and rounds to zero, so thenorm.clamp_min(eps)that exists to stop a zero-norm input becoming0 / 0was itself zero in exactly that dtype: an all-zero patch normalised to NaN, whilebfloat16,float32andfloat64were fine. A detector that pads a short result hands the descriptor a zero LAF, which samples one image point repeatedly and produces exactly that patch --ScaleSpaceDetector(400)on a random64x64float16image gave 365 NaN descriptor rows -- and a NaN descriptor is worse than a meaningless one, because it propagates throughtorch.cdistand poisons the whole matching. The nineF.normalizecalls in those four modules now go through one helper that normalises afloat16input in float32 and casts back (anepsrepresentable infloat16is safe but not neutral: a norm in the subnormal window came back as 0.5).bfloat16,float32andfloat64results are unchanged: they keep the 1e-12 default.The forward pass was only half of it.
SIFTDescriptorandDenseSIFTDescriptorguardsqrt(gx^2 + gy^2 + eps)andatan2(gy, gx + eps)witheps = 1e-10, which is zero infloat16-- and a squaredfloat16gradient underflows long before that -- so at every pixel with a zero gradient both sat on their singular point and the input gradient came back NaN (9 of 4096 on ordinary random32x32patches). The gradient magnitude and orientation are now computed in float32 forfloat16input and cast back, and the RootSIFTsqrtis computed in float32 forfloat16as well. An exactly flat patch -- what a zero-LAF padding slot samples -- was the remaining case: the guard gave every zero-gradient pixel a magnitude ofsqrt(eps), so a flat patch's descriptor was a unit vector built fromeps(float32) or a subnormal one (float16) whose1 / normgradient, together withatan2's1 / eps, overflowed through the float16 cast into an all-NaN input gradient (and was a meaningless ~1e8 in float32). A zero-gradient pixel now contributes a zero magnitude, a zero vector normalises to zero with a zero gradient (theepsclamp's1 / epswas never meaningful), andPatchDominantGradientOrientationskips its parabolic refinement on an empty or uniform histogram instead of dividing0 / 0; a flat patch has a zero SIFT descriptor and a zero input gradient in every dtype.bfloat16, whose exponent range holds both the guard and the squares, and the wider dtypes are byte-identical at every pixel whose gradient is not exactly zero; a patch with such pixels (a saturated region) loses theirsqrt(eps)contribution, a change of at most1e-5per pixel before normalisation.SemanticSegmentation.visualizeworks for CUDA, MPS and half-precision models. It indexed the CPU-drawn colormap with the mask'sargmax, which raises for CUDA and MPS masks, and recognised a softmax head withtorch.allclose(sum, 1)at float32-sized default tolerances, which a float16 or bfloat16 sum of probabilities never meets; the tolerance now scales with the number of classes and the dtype's epsilon, and the colormap follows the mask's device and dtype, so the visualization keeps the model's dtype instead of coming back as float32.OnnxLightGluewithoutonnxruntimeraises anImportErrorthat namespip install "kornia[onnx]", like the lazy-loader handles do, instead of a bareBaseError. (#4301)So3.exp,So3.log,Se3.exp,Se3.logandSe2.expreturn finite gradients at the identity, andSo3.logalso at a half turn, instead ofnanon every dtype. The forward values are unchanged;torch.wherewas differentiating the singular branch it does not select. (#4405)StereoCameranow rejects projection matrices whose last two dimensions are not(3, 4)with aStereoExceptionnaming the invalid camera. Previously, the shape guards never fired, so malformed matrices could be accepted or fail later with an unrelated tensor error. (#4385)VideoBoxes.get_boxes_shape()andVideoBoxes.to_mask()no longer raiseTypeError. Both are inherited fromBoxesand passas_padded_sequence=Truetoto_tensor, but theVideoBoxesoverride declared onlymode, so every call on aVideoBoxesfailed -- including the containersAugmentationSequentialbuilds for video box inputs. The override now accepts and forwards the keyword; it only changes a list-backed container, and aVideoBoxesbuilt from a(B, T, N, 4, 2)tensor is not one, so no working call changes its result. (#4176, #4365)VisualPrompter.predict()called without any prompt (the "run the prediction without prompts" example on the Segment Anything page) raisedTypeError: object of type 'NoneType' has no len()from the prompt augmentation container; it now predicts from the image embedding alone, as documented. (#4178)Z1Projection.unprojectnow materialises a pythonint/floatdepthon the device and in the dtype ofpoints; it used to build a CPU float32 tensor, which raisedRuntimeErroron every accelerator and widened float16/bfloat16 results to float32. (#4340)_cdistreplacesdm.clamp(min=0.0).sqrt()with a masked argument substitution, avoidingNaNgradients for exact zero-distance pairs on PyTorch 2.5.1 and 2.9.1 whereclamp's boundary gradient passed through tosqrt(0). PyTorch 2.14.0 was already finite, and forward behavior and computed distances are unchanged. (#4233)add_weightednow keeps Python scalar weights in operator math precision instead of rounding them to the input dtype before arithmetic. This improvesfloat16andbfloat16accuracy and makes fractional scalar weights on integer inputs produce the correctly promoted floating-point result instead of being truncated. (#4154)axis_angle_to_rotation_matrixaccepts the(*, 3)shape its own guard message promises, instead of only(N, 3). The body didwxyz.unbind(dim=1)and.view(-1, 3, 3), so an unbatched(3,)raisedIndexError: Dimension out of rangeand any extra batch dimension raisedValueErrorout of the unbind, three frames below kornia's own shape guard. Every sibling conversion in the module already accepted(*, 3), soaxis_angle_to_rotation_matrix(rotation_matrix_to_axis_angle(R))composed for an(N, 3, 3)rotation matrix and for nothing else, including for the shaperotation_matrix_to_axis_angle's own doctest returns. This is additive:(N, 3)output and gradients are byte-identical, and only shapes that used to raise now return (closes #3955). (#4342)bbox_to_mask3dnow preserves the input dtype in the returned mask, matchingbbox_to_maskand theBoxes3D.to_maskcontract: the earlier implementation downcast every result tofloat32, so afloat64or half-precision box produced a mask that silently lost precision. The mask keeps the input box's dtype end to end. (#4376)bbox_to_mask3dnow returns the intersection of the three axis ranges for a box that covers or overhangs a whole output axis, matchingBoxes3D.to_mask, instead of filling the entire volume (#4255, #4303). The old implementation|-ed the three broadcast axis slabs and tried to recover the intersection with a three-wayall()reduction; that recovery breaks the moment any one slab covers a whole axis, since the union is then all-true on that axis and the reduction can no longer see the other two slabs' bounds. Computing the intersection directly with&needs no such recovery step. Interior boxes (the case the old reductions happened to recover correctly) are unaffected and byte-identical.bbox_to_maskbuilt its pixel-position grid in the box dtype. Withfloat16boxes (andbfloat16boxes) on images wider or taller than 2048 px (256 px forbfloat16) consecutive pixel positions collapsed, so rows and columns near the collapse were mismasked; the grid is now built infloat32andfloat16/bfloat16results are byte-identical tofloat32/float64.RandomErasingandRandomCutMixV2build their masks through it. (#4336)depth_from_disparityaccepts Python integers and scalar tensors for the baseline and focal length. (#4392)depth_from_plane_equationreturns a finite depth for a ray exactly parallel to the plane. The near-singular guard waseps * torch.sign(denom), andtorch.signis zero at zero, so at the exact singularity the epsilon was multiplied away and the division still ran against zero, returninginf. A grazing ray is not an exotic input: it is every pixel on the horizon of a ground plane. The guard now picks its sign with a comparison, which has no such hole and keeps the sign the small non-zero denominators already got.torch.copysignreads the same but is not exportable, and this function is in the documented ONNX export surface, so the comparison form is pinned intests/onnx/test_export_coverage.py. The finite-depth promise is bounded by the dtype: the defaulteps=1e-8is below float16 resolution, so half-precision callers must pass a representableeps. (#4280, #4348)depth_to_normalsnow raisesShapeErrorwhenH < 2orW < 2, since surface normals need two tangent directions. Previously, singleton axes could yield zero or non-finite normals, and empty spatial dimensions failed inside padding. Inputs with both dimensions at least 2 are unchanged. (#4458)distance_transformno longer returns NaN gradients when the cascade's convolution is exactly zero, including sparse masks and all-zero inputs; the existing forward output is unchanged. (#4232)distance_transformno longer silently returns a wrong or all-zero result when itsexp(-dist/h)kernel underflows (#4152). The kernel's axis-aligned tap, at distancekernel_size // 2along a single axis, underflowing to exactly zero -- reachable from the documented defaulth=0.35atkernel_size >= 15infloat16-- used to make the convolution silently drop it, returning a plausible-looking but wrong distance field or, with a smallerh, an all-zero one. Two changes:float16/bfloat16inputs now run the cascade infloat32and cast the result back (the defaulth=0.35case is fixed by this alone, matchingfloat32's own working range); and anh/kernel_size/dtype combination whose axis-aligned tap still underflowstorch.finfo(dtype).tinynow raises instead of guessing. This also catches a case that is not itself numerically wrong on CPU (h=0.01atkernel_size=3infloat32tracks the analytic reference to ~2e-4, carried through the subnormal range) but where MPS flushes subnormals to zero while CPU does not, so the same call used to silently disagree across backends; raising there rules out that disagreement rather than trusting which backend a caller happens to run on. Concretely, at the documented defaulth=0.35infloat32,kernel_size >= 63now raises: CPU used to return a usable-looking answer there while MPS silently returned something else for the same call.download_file_from_urlanddownload_hf_filetake an optionalvalidate=callable, andkornia.core.check_safetensorsis the one the KimiVL and SigLIP2 builders pass. A transfer cut short after a 2xx status leaves a truncated file in the cache, which was then returned as a cache hit on every later call --from_pretrained_hf()failed until the user deleted it by hand.validategives a download-only call the quarantineload_state_dict_from_urlgets from its load step: a rejected entry is moved aside, the next source is tried, and the discarded source is re-fetched once. Withoutvalidatethe behaviour is unchanged. (#4309, #4332)elastic_transform2dnow builds its identity sampling grid with the requestedalign_cornersconvention, so a zero displacement field preserves the input image. (closes #4235). (#4382)extract_patches_simpleandextract_patches_from_pyramidreturn an all-zero patch and a zero LAF gradient for a non-finite LAF frame instead of handinggrid_samplean invalid grid. A frame holding a NaN or an infinity anywhere -- including only in its center -- is detected and sanitized before any grid arithmetic, and finite frames in the same batch are untouched. Such a frame previously produced a finite-looking border-sampled patch, and its backward pass could terminate the process inside torch's CPUgrid_sampler_2d_backwardkernel withpadding_mode="border"; a training-time detector that emits a degenerate LAF hits exactly that path throughLAFOrienter,LAFAffNetShapeEstimatorandLAFDescriptor.fft_convnow accepts CPU float16 and bfloat16 inputs by computing the FFTs in float32 and returning the input dtype. (#4394)find_homography_dlt(..., solver="lu")now solves the minimal four-point system with an adaptive homogeneous gauge instead of applying LU to its singular normal matrix. This is the estimatorRANSAC(model_type="homography")calls for every minimal sample, so homography RANSAC results change on every platform, not only where the old formulation broke down: over 2048 minimal samples the median transfer residual drops from 2.3e-5 to 1.9e-6 and the worst case from 4.2e+5 to 4.5e+2. It also fixes the all-NaN homographies seen for a four-point sample on Windows with PyTorch 2.14, and removes the corresponding CPU half-precision known failures. A four-point sample containing a zero weight now returns a finite homography instead of NaN. Samples of five or more points keep the previous normal-equation formulation and are numerically unchanged. (#4197)import korniano longer imports onnxruntime when it is installed (#4295)infer_bbox_shape3dandbbox_to_mask3dreject rank-4(B, N, 8, 3)input with aShapeError, the wayinfer_bbox_shapeandbbox_to_maskhave since #4218.validate_bbox3daccepts the rank-4 form and reshapes internally, but both callers index dim 1 as the vertex axis, so the box axis was read as the vertices: an out-of-bounds error with one box, and three(1, 3)tensors -- one value per coordinate rather than per box -- with eight. (#4248, #4351)infer_bbox_shapeandbbox_to_masknow reject rank-4(B, N, 4, 2)inputs withShapeError. Previously,N < 3raised an incidentalIndexError, whileN >= 3silently returned(B, 2)extents computed from the wrong vertices. (#4218)iterative_quad_interp3d'smax_candidatescap is now a per-image budget rather than one shared across the batch. Thetopkranked the flattened(B*C)candidate list, so an image's refined keypoints depended on which other images shared its batch: a quiet image next to a high-contrast one got none. This also reachesIterativeQuadInterp3dandAdaptiveQuadInterp3dinpatchmode. The docstring already read as a per-image budget. A negativemax_candidatesnow raisesValueError; it previously raised atopkRuntimeError, and under the per-image ranking it would otherwise have silently disabled refinement instead. (#4256, #4350)jpeg_codec_differentiableno longer returns an all-NaNimage atjpeg_quality=0, a value inside the[0, 100]range it documents and validates._jpeg_quality_to_scaledivides5000by the quality on the< 50branch, which isinfat0, and the polynomial floor ofinfisNaN, poisoning the image and its gradient. A quality of exactly0is now given the scale of quality1, which is the table libjpeg gives quality0. The guard is that one point: a fractional quality in(0, 1)was already finite, keeps its own larger scale, and is untouched, so this endpoint is not the limit of the formula from above. Output and gradients for every quality> 0are byte-identical. The tests drew the quality withtorch.randint(low=0, high=100)unseeded at sixteen sites, so roughly one run in twenty oftests/enhance/test_jpeg.pywent red on any job; the draws now start at1and the boundary has pinned cases of its own. (#4205)kornia.contrib.diamond_squaregenerates fractals with a spatial side below 3 px. A 1 px side raisedValueError: math domain errorand a 2 px side aTypeErrorfrom a float in thetorch.randsize, soRandomPlasmaBrightness,RandomPlasmaContrastandRandomPlasmaShadowfailed on such images. A small side is now drawn on the 3 px grid and sliced; outputs for sides of 3 px and more are bit-identical. (#4472, #4488)kornia.contrib.super_resolutionbuilders construct again.SuperResolutionnever implementedModelBase's abstractfrom_configand defined no__init__, soSmallSRBuilder.build()andRRDBNetBuilder.build()both raisedTypeErrorat construction — the whole public super-resolution entry point had been unreachable since the models refactor madefrom_configabstract. It now has aSuperResolutionConfigand afrom_configthat dispatches to either builder family, and both builders are covered by tests. Fixes #4291. (#4335)kornia.enhance.equalize,equalize3d,RandomEqualizeandRandomEqualize3Draise aRuntimeErrornaming the[0, 1]input range for values the 256-bin lookup cannot index, instead of a rawindex 259 is out of bounds for dimension 1 with size 256from the gather. The check usestorch._assert_async, so it adds no device sync andtorch.compilefullgraph still works, and inputs that equalized before (including values a hair above 1) are unchanged. The docstrings now state the range, the 256-bin histogram, and that a 3D volume of at most 255 voxels per channel comes back unchanged. (#4431, #4432, #4489)kornia.feature.LightGlueno longer probes forflash_attn; the SDPA path it always used is now the only one.kornia.feature.lightglue.Attention.enable_flash, the attribute that combined the constructor argument with the probe result (and so always equalled the argument, because SDPA is present on every supported torch), was renamed toAttention.allow_flash. (#4287)kornia.io.get_sample_imagesandkornia.onnx.ONNXLoader.list_operators/list_modelsno longer needrequests, whichpip install kornianever installed; they fetch with the standard libraryurllibinstead. The failure exceptions change with it, all stillOSErrorsubclasses: a sample-image URL that returns 404 now raisesurllib.error.HTTPErrorinstead ofPIL.UnidentifiedImageError, and an unreachable host raisesurllib.error.URLErrorinstead ofrequests.exceptions.ConnectionError. A 404 from the Hugging Face listing still raises the sameValueError(#4302)kornia.io.load_imageandwrite_imagework on the kornia_rs that a plainpip install korniaresolves. kornia_rs 0.1.11 moved its image readers and writers from the package root intokornia_rs.io, and kornia kept calling the root, so on 0.1.11 and newerload_imageraisedAttributeErrorfor every JPEG and every PNG that is not plain RGB, andwrite_imageraised for TIFF, 16-bit and float32 output (8-bit JPEG and PNG writes still worked); the lock's 0.1.10 kept CI green. kornia now callskornia_rs.ioand requires a kornia_rs that provides it (see Breaking changes). That decoder also reads 16-bit PNG/TIFF and float TIFF, which 0.1.10 rejected:ImageLoadType.UNCHANGEDreturns them asuint16/float32, and the 8-bit load types raise aNotImplementedErrorthat says so instead of mislabelling the tensor. The nightly PyPI job now imports the installed wheel from outside the checkout (it used to import the source tree) and round-trips an image instead of only importing. (#4326)nms2daccepts a non-squarekernel_size. It used to raiseRuntimeError: shape '[1, 1, -1, H, W]' is invalid for input of size ..., because the neighbourhood kernel was built with its two extents swapped and the padding was applied to the wrong pair of edges. (#4240, #4242)nms3daccepts anykernel_size. Every size other than(3, 3, 3), the one served by a hand-written branch, used to raise:_compute_zero_padding3ddefined a(k - 1) // 2helper and then returned the full kernel sizes, so the padded volume did not match the kernel it was convolved with. (#4241, #4242)normalize_laf,denormalize_lafandgenerate_patch_grid_from_normalized_LAFcount a singleton image axis as one pixel of extent instead of dividing bysize - 1 == 0.normalize_lafraisedZeroDivisionErrorfor a 1-pixel-wide or 1-pixel-tall image -- and with it both patch extractors on their defaultnormalize_lafs_before_extraction=Truepath -- whiledenormalize_lafsilently collapsed every LAF to zero. The conversions are now finite and round-trip, and both extractors return finite patches for such an image.normalize_quaternionfloors a positiveepsat the smallest positivefloat16subnormal, so its defaulteps=1e-12remains an active division guard and a zero quaternion returns finite zeros instead of NaNs without changing non-zero representablefloat16magnitudes. An expliciteps=0.0still disables the guard. This also keepsQuaternion.normalize,quaternion_to_rotation_matrix, and their downstream pose conversions finite for that input, matching the existingfloat32,float64, andbfloat16behavior (#4162).packagingis no longer a runtime dependency; it was never imported. Thedevextra no longer listspytest-cov(CI runscoverage run -m pytest),ruff(the pre-commit hook installs the pinned copy) or anumpy<3cap, anduv.lockis regenerated to match (#4296).pixel2camnow rejects depth tensors outside the documentedBx1xHxWshape. The guard's predicate bound as(ndim != 4) and (shape[1] == 1), so four-dimensional multi-channel depth bypassed the channel check — a three-channel depth silently broadcast into separate camera coordinates — while scalar and one-dimensional inputs raisedIndexErrorfrom the guard itself. Code that passed those shapes and relied on them being accepted now raisesValueError. ValidBx1xHxWdepth is unaffected and its output is unchanged. (#4314)pixel2camnow validates the fullBx4x4shape ofintrinsics_inv, rejecting invalid matrix sizes before they cause unrelated transformation errors or return the wrong number of coordinate components. (#4381)quaternion_exp_to_logandeuler_from_quaternionno longer returnnan/infgradients at their respective rotation singularities (#4007). Both differentiate an inverse trig function (acos,asin) whose own derivative is unbounded at its domain boundary (w = +-1,sinp = +-1);quaternion_exp_to_loghits that boundary exactly at the identity quaternion(1, 0, 0, 0)-- the standard initialization for pose optimization -- where the unbounded derivative used to multiply the identity's exactly-zero vector part into0 * inf = nan, andeuler_from_quaternion'spitchhits it at gimbal lock. Both now guard the argument fed to the differentiatedacos/asincall away from the boundary while taking the returned value from a detached copy of the real (possibly boundary) argument, so the forward result is unchanged -- verified byte-identical against the previous implementation over 500 random inputs including several forced onto the exact boundary -- while the gradient no longer depends on what a given torch version or backend's ownacos/asinderivative happens to return there.quaternion_exp_to_log's antipode(-1, 0, 0, 0)still returns a large but finite gradient (~pi/eps) from an unrelated, pre-existing division by its clamped (zero) norm; that is unchanged and out of scope here.quaternion_to_axis_anglereturns the correct gradient at every identity-like quaternion, not only the positive unit identity(1, 0, 0, 0)(#4237). Its zero-vector-part branch used the constantk = 2.0, which is only thew = 1case of the true analytic limitk = 2 / w(w= the real component); every other identity-like input got a wrong gradient. That included the negative unit identity(-1, 0, 0, 0)-- the same physical rotation as(1, 0, 0, 0)under the double cover -- which got the wrong sign (+2instead of-2), and any non-unit "identity" such as(2, 0, 0, 0)(a scale this function explicitly permits), which got the wrong magnitude (+2instead of+1). This was a genuine backward-correctness defect, not a missing edge case: a valid unit quaternion could produce the opposite gradient direction in pose optimization depending purely on which sign of the identity it started from. The prior regression test for the#3949NaN-gradient fix only exercisedw = 1, the one point where the wrong constant and the correct formula happen to agree, and so could not have caught this. The division needed for2 / wis guarded atw = 0the same way the function's existingsin_thetadivision already is. That gate is~pos-- the mask that actually selects the branch -- and not merelyw != 0:2.0 / tlowers tot.reciprocal() * 2, whose backward is-grad * result**2, and for a rotation just short of a half turnwis small but non-zero, so(1 / w)**2overflows toinfand meets the exact0.0that the unselected branch receives as0 * inf->nan. Infloat16that would have been every rotation within ~0.45 degrees of 180 -- ordinary inputs, not degenerate ones. The2 / wcoefficient is also detached, because on the branch that selects it the vector part is zero, sod(out)/dwis exactly zero there and computing it through-2 / w**2only reintroduces the same overflow.The fully degenerate all-zero quaternion
(0, 0, 0, 0)-- not a valid rotation -- keeps its(0, 0, 0)forward value. Its gradient there changes, and improves: it was(0, 2, 2, 2)on torch 2.14 but already(nan, 2, 2, 2)on torch <= 2.9.1, whereatan2(0, 0)'s derivative with respect to its second argument -- a0 / 0-- returnsnan.atan2is now shielded across that whole masked branch, which also clears a pre-existingnanfor a zero vector part whosew**2underflows (w = 1e-30infloat32,|w| < 2.4e-4infloat16). No gradient is analytically correct at a point with no well-defined limit, so the changed value is not a regression.The forward value is unaffected everywhere: the
atan2shield deliberately takes its value from the unshielded expression, because routingcos_thetathroughtorch.wherehandsatan2a contiguous tensor instead of a stride-4 view and can select a different kernel. Verified byte-identical against the previous implementation over 2000 random inputs infloat64,float32,float16andbfloat16, including forced unit, negative-unit, scaled, all-zero and near-half-turn quaternions, with no non-finite gradient row remaining at any of those dtypes.rad2deganddeg2radnow handle integer tensor inputs correctly and preserve float64 precision.angle_to_rotation_matrixinherits the corrected conversion, while the implementation preserves ONNX export compatibility. (#4358)reproject_disparity_to_3D(theStereoCameramethod and the module-level function, which share one body) no longer transposes the two pixel indices. The pixel meshgrid was unbound asv, u = torch.unbind(uv, dim=-1), butcreate_meshgrid(normalized_coordinates=False)returns(x, y), so the column fedvand the row fedu:Xwas computed from the row andYfrom the column. Every returned point was the value belonging to its transposed pixel -- kornia's answer at(row, col)was whatcv2.reprojectImageTo3Dputs at(col, row), the OpenCV semantics this function was added to provide (#2042). A square rig withfx == fyandcx == cyagrees only on the diagonal, so the error was silent rather than absent. Output changes at every pixel withrow != col, square inputs included. The real-data regression fixture stored ten points as ten rows of one column while its own comment and its ground truth describe one row of ten columns, which is why it passed against the swapped code; it is now laid out as the comment says, and the fixed code reproduces the unchanged ground-truth values. #4317's two wart pins for this defect are retired and its strict-xfail convention test is now an ordinary passing regression. (#4269, #4366)resizeandrescalereturn an empty image for a zero-sized output instead of raisingZeroDivisionErrorout of the scale-factor computation (#4115).resize(x, (0, 4)),resize(x, 0),Resize((0, 4)), and anyrescalefactor that takes a side to zero (rescale(x, 0.0)) previously died inh / size[0]; they now return an empty tensor of the requested shape, which is the answerwarp_affine,warp_perspectiveandcenter_cropalready gave for the same request. The empty result stays connected to the autograd graph, the way_empty_warp_output_2dbuilds it for the warping ops, so a batch element that degenerates to a zero-sized output still contributes a zero gradient rather than detaching.A degenerate input is a different question and is now rejected rather than divided by: resizing a
(1, 3, 0, 4)image to a positive size, or with anintsize at all -- anintnames one side and takes the other from an aspect ratio a degenerate input does not have -- raisesValueError("Input image size must be positive. Got height=0, width=4."), the message the warping ops already use, instead of the same bareZeroDivisionError. Empty in and empty out is well defined and still comes back empty. (#4140)solve_cubicandsolve_quarticreturn finite gradients for a row whose neighbours in the same batch take a different branch. TheD > 0branch selected its rows withabs(R) > 1e-16alone, so it evaluatedsqrt(D)onD < 0rows too. Those rows are never read back, but the resulting-Q / nanstays in the graph and its backward returnsnan, which reaches every coefficient: a three-real-root cubic differentiated correctly on its own and gavenanas soon as a one-real-root cubic shared the batch, andsolve_quarticinherited it through its resolvent cubic. The forward values are unchanged. (#4334, #4338)solve_cubic'sD <= 0(three-real-roots) branch no longer returnsnangradients for a repeated or near-repeated real root (#4290, #4299). It differentiatesacos(R / sqrt(-Q3)), whose own derivative-1/sqrt(1-x^2)is unbounded atx = +-1; the branch condition guarantees the ratio lies in[-1, 1], but a repeated or near-repeated root pushes it to exactly that boundary, where the value is correct but the derivative diverges. A double-root quartic reaches this throughsolve_quartic's resolvent cubic routinely, not as an edge case: measured on 20,000 random real-rooted quartics, 10.7% hit a non-finite gradient or a disconnected graph overall, 35.3% for exact double-root pairs specifically. Same failure shape as theacos/asinboundary inquaternion_exp_to_log/euler_from_quaternion(#4007, fixed in #4228) — this is a different call site, not covered by that fix, using the same guard: differentiate a substituted safe argument, take the value from a detached copy of the real (possibly boundary) argument. Forward values are unchanged; re-running the same 20,000-trial search with the fix applied drops the failure count to 1,269 — a real, separate residual (a disconnected-graph case with two simultaneous double-root pairs) remains and is tracked in #4290, not fixed here.solve_quarticnow validates Ferrari resolvent candidates with a dtype-aware scaled residual, falls back to the smallest scaled residual when no candidate passes, and keeps the FerrariEfactorization away from an ill-conditionedRdivision. Cancellation-levelR^2is snapped to zero relative to the coefficient scale, and all Ferrari compute dtypes choose between the linear- and constant-termEforms by normalized coefficient error; float32 also refines the selected resolvent root once. The gradient-safe zero-radicand path remains intact, preventing half-precision non-finite or dropped roots and full-precision non-roots while preserving the public contract. (#4357)solve_quarticreturns finite gradients for a pure biquadratic such asx^4 - 16. Its twotorch.clamp(..., min=0.0).sqrt()sites do not guard the gradient they look like they guard:d(sqrt)/dxis unbounded at 0, and on torch below 2.14clamppasses the incoming gradient through at the bound rather than zeroing it, so on the older half of kornia's supported torch range the backward returnedinfand thennan(#4229). Both sites now substitute a safe radicand under thesqrt, assolve_quadraticin the same module already did. Forward values are unchanged. (#4339)tilt_projectionpreserves its documented leading batch dimensions, sodistort_points,undistort_points, andundistort_imageno longer fail on multi-axis batches when tilt distortion is applied. (#4345)undistort_points_kannala_brandtno longer collapses representablefloat16points next to the principal point to the origin, and the exact principal-point path now has finite autograd gradients. The zero-radius decision is made from the unsquared normalized coordinates, and thefloat16radius usesfloat32intermediates so its squared value does not underflow; nonzero radial rescaling remains epsilon-free. (#4308, #4370)unproject_meshgridnow requires camera intrinsics of shape(B, 3, 3), rejecting extra camera axes before they can broadcast across pixel columns and reporting the caller's original shape. (#4383)unproject_meshgridnow returns the documented(*, H, W, 3)shape whenWis 1. It squeezed the meshgrid with a bare.squeeze(), which drops the width axis along with the leading batch axis wheneverW == 1, sounproject_meshgrid(1, 3, K)andunproject_meshgrid(3, 1, K)returned the same shape with different values. The grid then broadcast across a phantom width in the two public functions built on it:depth_to_3d_v2returned(1, 3, 3, 3)for aW = 1depth wheredepth_to_3dcorrectly returns(1, 3, 1, 3), andwarp_frame_depthreturned a 4-pixel-wide image for a 1-pixel-wide input. Only the batch axis is dropped now. Output for everyW > 1is byte-identical, anddepth_to_3d_v2agrees withdepth_to_3datW = 1as it already did everywhere else. (#4278)validate_bboxandvalidate_bbox3dflatten rank-4(B, N, 4, 2)/(B, N, 8, 3)input withreshapeinstead ofview, so a non-contiguous leading-dimension stride (a transpose, a slice that drops boxes, anexpand) returns a boolean as documented instead of raisingRuntimeError. (#4174)warp_affine,warp_perspectiveandremapcrashed on MPS for an empty destination -- adsizewith a zero dimension, or zero-sizedremapmaps -- with an internal[srcBuf length] > 0 INTERNAL ASSERT FAILED ... Placeholder tensor is empty!from PyTorch. The MPS backend rejects any zero-elementgrid_sampleoperand before torch 2.14, including a zero-element grid sampled against a non-empty source, which is what the empty-destination path built. That path now samples a connected 1x1 stand-in and expands the result to the requested empty shape, sogrid_samplenever receives a zero-element operand on any backend and an empty warp costs the same whatever the non-zero side ofdsizeis. The empty path also resolves its output batch the way each operation's non-empty path does, so a singleton transform or map batch broadcasts identically and a mismatched batch is rejected rather than silently returning the wrong cardinality. Outputs, autograd links and the documented empty-source policy are unchanged on CPU and CUDA. (#4032, #4354)ycbcr_to_rgbnow uses the exact inverse of thergb_to_ycbcrcoefficients, so anrgb -> ycbcr -> rgbround trip is lossless to floating-point precision instead of drifting by ~2.7e-4. The forward transform is unchanged. (#4378)
Breaking changes
mean_absolute_disparity_error,root_mean_squared_disparity_errorandmean_bad_pixel_errornow raise a kornia error naming the dtypes when either disparity map is not floating point, as does the newkitti_d1_error. Previouslyreduction='mean'already failed on integer maps with a torchRuntimeErrorfrommean(), butreduction='sum'andreduction='none'returned results: anint64sum and an integer per-pixel map for the absolute and bad-pixel metrics, andfloat32for the root-mean-square one. Those calls now raise. The guard exists because the reductions accumulate infloat32and cast back to the map's dtype, which for an integer map would truncate a ratio such as 0.5 to 0, and KITTI ships disparity as auint16PNG, so a plausible-looking wrong score was the alternative. Convert integer maps with.float()before calling. (#3931)Outputs of
warp_perspective,warp_affine,homography_warp,HomographyWarper,warp_image_tps,crop_by_transform_matandshearchange underalign_corners=False. They now match thealign_corners=Trueresult up to out-of-bounds handling, instead of carrying a spurious sub-pixel scale and shift.align_corners=Truecall sites are bit-identical.Several of these default to
align_corners=False, so plain calls that pass no flag change too. Measured on a 4x5arangeimage with an identity transform,float64, asmax|out - in|:Call, default arguments before after homography_warp(x, I, (4, 5))14.25 1.8e-15 HomographyWarper(4, 5)(x, I)14.25 1.8e-15 warp_image_tps(x, pts, kernel, affine)14.25 1.8e-15 ImageRegistrator("homography").warp_src_into_dst(x), identity model14.25 0.0 shear(ones(1, 1, 4, 4), [[0.5, 0.0]]), first row0.75, 1, 1, 11, 1, 1, 1The augmentations that default to
align_corners=False(RandomAffine,RandomPerspective,RandomShear,RandomTranslate,RandomThinPlateSpline) sample different pixels for the same reason; their transform matrices are unchanged. At those defaults an identity transform is now actually the identity:RandomPerspective(distortion_scale=0.)goes from 0.734 to 6e-07 andRandomThinPlateSpline(scale=0.)from 0.734 to 1.5e-08 on a 6x8 ramp. Refs #3904, #4411. (#3945)PinholeCamera(...)now clones itsintrinsics,extrinsics,height, andwidthinputs instead of storing the caller's tensors by reference.scale_()and thetx/ty/tzsetters still mutate the camera in place, but no longer write through to those constructor arguments; code that relied on bidirectional storage aliasing must mutate the camera's tensors explicitly. A camera returned byPinholeCamerasList.get_pinhole()is likewise independent of the list's backing storage. (#4264) (#4500)A scalar augmentation magnitude
xwhose implied rangecenter ± xreaches past the parameter's upper bound now raises the sameValueError: <name> out of bounds. Expected inside (lo, hi), got tensor([...])that the explicit range form already raised; it used to be clamped to the bound silently. The lower end is still floored at the parameter's lower bound, soRandomContrast(1.5)still means[0, 2.5],RandomSharpness(0.5)still means[0, 0.5],RandomJPEG(50.0)still means[1, 100]andRandomAffine(degrees=360)still means[-360, 360]. The scalar forms that now raise arehue > 0.5(RandomHue,ColorJiggle,ColorJitter),brightness > 1(RandomBrightness,ColorJiggle),thresholds > 0.5andadditions > 0.5(RandomSolarize),jpeg_quality > 50(RandomJPEG),direction > 1(RandomMotionBlur,RandomMotionBlur3D),angle > 360(RandomMotionBlur),degrees > 360(RandomRotation,RandomAffine),shear > 360(RandomShear,RandomAffine),translate > 1(RandomAffine),translate_x > 1andtranslate_y > 1(RandomTranslate) andtimes > 3(RandomRotation90). The 3Ddegrees,shearsandanglearguments go through a different reader and are unchanged. Refs #4563. (#4569)Casting
RandomPlanckianJitterto a dtype no longer changes the dtype of its output. The illuminant table now follows the input rather than the module, soK.RandomPlanckianJitter(p=1.0).to(torch.float64)applied to afloat32input returnsfloat32where it previously returnedfloat64, and a module cast to the other half dtype returns the input's dtype instead offloat32. Casting the module is no longer the way to keep a half-precision input's dtype; it is preserved by default. Refs #4574. (#4578)RandomMotionBlurandMotionBlurGeneratornow raiseValueErrorat construction for a reversedkernel_sizerange such as(20, 3). Previously a reversed range was silently sampled as if it were ordered:(20, 3)drew the odd sizes3to19. (#4610)StereoCameranow rejects a rectified pair whosetx * fxis not strictly negative for every rig in the batch. Its sign guard usedtorch.all, so a batch holding one pair with its cameras swapped was accepted and silently reprojected that pair behind the camera, and a zero baseline passed too, collapsingQso that every disparity reprojected to the origin. A zero baseline now raises with its own message namingtx; an empty batch is still accepted, and valid rigs build the sameQas before. (#4616)AugmentationSequential(data_keys=None)now matches dictionary data-key names exactly or before an underscore/hyphen suffix, preserving coordinate formats for keys such asbbox_xyxy_2and leaving the caller's dictionary intact. Formerly augmented plural names (images,masks,labels,bboxes,inputs), raw suffixes (image2,keypoints2), camelCase (imageLeft), dot-separated names (image.2), and unrelated prefixes (imagenet_id,maskrcnn_boxes,labelled_image,inputsize) are now returned unchanged as metadata without a warning. Rename augmentation inputs to recognized names such asimage,mask_2,label_2,bbox_2orinput_2.classand any key beginning withclass_orclass-, for exampleclass_idorclass_weights, formerly metadata, now route to labels and can raise for unsupported label- changing mix augmentations; rename metadata that must remain untouched. Unrecognizedkeypointremains metadata in dict mode, whereas positional mode rejects it; usekeypointsfor augmentation. A coordinate-box suffix still needs_or-:bbox_xyxy2andbbox_xywh2matchbboxand require vertex boxes. (#4619)A scalar augmentation magnitude of
inf— or a finite magnitude too large to represent in the working dtype, which converts toinf— now raisesValueError: If <name> is a single number, it must be finiteat construction. PreviouslyRandomSharpness,RandomContrast,RandomSaturation,ColorJitter(contrast,saturation) andColorJiggle(contrast,saturation) accepted such a magnitude and the resulting infinite draw range producedNaNpixels at forward time. A scalarnanwas already rejected by the generic range check on every reachable path and now gets the same named message instead.-infstill reports "must be non negative" from the earlier check, and the explicit two-element range form (e.g.RandomSharpness((0.0, float("inf")))) is unchanged and still accepted — tracked in #4635. Fixes #4621. (#4625)The 3D augmentations now reject an angle range wider than one turn at construction, as the 2D ones do:
RandomRotation3D,RandomAffine3D(degreesandshears) andRandomMotionBlur3DraiseValueErrorfor a scalar or explicit range past±360, where they used to sample from it. (#4644)box_blurandBoxBlurnow default toseparable=Trueinstead ofFalse, using two one-dimensional averaging passes. Both dense and separable floating-point paths use average pooling outside autocast (except where oneDNN's CPU convolution is faster), so results can differ by roundoff.BoxBlurno longer stores derivedkernel,kernel_x, orkernel_ybuffers: old checkpoints still load strictly, but their kernel values are ignored. Customizing these buffers no longer changes the filter; usefilter2dorfilter2d_separablefor custom weights. (#4647)AugmentationSequentialno longer converts every mask output to one shared dtype. Previously all mask outputs of a call were cast to the dtype of the last mask argument, so a boolean mask passed before afloat32mask came back asfloat32; it now comes back asbool, like every other mask that keeps its own argument's dtype. Code that did arithmetic on such an output (for example1 - mask, which raises forbooltensors) must convert it explicitly, e.g.mask.float(). (#4665)An explicit augmentation range containing
infornan— for exampleRandomSharpness((0.0, float("inf"))),ColorJitter(contrast=(0.0, float("inf")))orRandomAffine(0., scale=(0., float("inf")))— now raisesValueError: If <name> is a range, it must be finiteat construction. Previously aninfendpoint was accepted whenever the parameter's domain was itself unbounded (the defaultbounds=(0, inf)), because the joint check then comparesinf >= inf; the resulting infinite draw range producedNaNpixels at forward time, the same defect #4621 reported for the scalar form. With a finite domain such a range was already rejected. Ananendpoint was already rejected too, but reported as "out of bounds", naming the domain rather than the endpoint, and now gets the same named message. Finiteness is required of the range, not ofbounds: an unbounded domain stays legal. This completes the scalar-form fix in #4625. Fixes #4635. (#4668)median_blurandMedianBlurtake aborder_type('constant','reflect','replicate'or'circular') and default to'reflect', likefilter2d,box_blurandgaussian_blur2d(#4670). Previously the window was zero-padded and there was noborder_type, so a constant image came back 0 in a triangle at each corner (12 of the 121 pixels of an 11×11 image with a 5×5 kernel). Now a constant image is unchanged.RandomMedianBlur, which has noborder_type, follows the new default. Reflect padding needs each side to be longer than the kernel radius, so an image with a side of at mostk // 2pixels, which used to be filtered, now raises: torch's padding error frommedian_blur, and aValueErrornaming the class and the shape fromRandomMedianBlur. On a torch without a float16 CPU reflection-pad kernel, such as 2.5.1, a float16 CPU input now raises, as it does in the other reflect-padded filters.border_type='constant'reproduces the old output exactly. (#4673)spatial_gradient(..., order=2)andspatial_gradient3d(..., order=2)return second derivatives with the standard sign: onx**2thedxxchannel is positive and onx*ythedxychannel is positive, matching the OpenCVSobel(dx=2)andSobel(dx=1, dy=1)kernels. Previouslymode="sobel"returned-dxx,-dxyand-dyy, the 2Dmode="diff"returned-dxynext to a correctly signeddxx/dyy, and the 3Dmode="diff"returned-dyzand-dxznext to a correctly signeddxy. Code that compensated for the old signs, for example-dxxas a Sobel Laplacian, now gets the opposite result without a warning. The exported kernel gettersget_spatial_gradient_kernel2d("sobel", 2)andget_spatial_gradient_kernel2d("diff", 2)return the negated kernels accordingly, whileget_spatial_gradient_kernel3d("diff", 2)is unchanged because the fix removes the flip inspatial_gradient3dinstead of editing the kernel.hessian_responseis unchanged. The docstrings now list the channel layout,(dxx, dxy, dyy)in 2D and(dxx, dyy, dzz, dxy, dyz, dxz)in 3D. (#4683)AugmentationSequentialnow rejects rank-4 image input when used with a 3D augmentation. Previously, rank-4 input was promoted as(C, D, H, W); this is ambiguous with the container's(B, C, H, W)image layout. To pass a single 3D volume explicitly, useunsqueeze(0)to add the batch dimension and provide input as(B, C, D, H, W). Bare 3D augmentations retain their rank-3 and rank-4 input promotion behavior. (#4697)CenterCropin the defaultcropping_mode="slice"now returns a copy of the cropped region. Previously it returned a view that shared storage with the input: writing to the output changed the input at the crop offset, and writing to the input after the call changed the output. Code that relied on either direction of that aliasing must now write to the tensor it wants changed. The crop now allocates one crop-sized tensor per call, asRandomCropandRandomResizedCropalready do in slice mode, and no longer keeps the whole input alive through the output. Fixes #4413. (#4727)The
kornia.morphologyfunctions (dilation,erosion,opening,closing,gradient,top_hat,bottom_hat) now default toengine="auto"instead of"unfold"."auto"runs"unfold"on CUDA; off CUDA it runs the exact"shift"engine, except that a CPU call which computes in float32 or float64 (the image dtype, or the wider dtype a kernel or structuring element promotes it to) and records a backward graph keeps"unfold". For finite inputs the forward output remains equal to"unfold"(torch.equal), including mixed-dtype kernels and non-flat structuring elements; only the sign of a zero can differ, because a backend'smax/minmay return either tied operand, and because forward-only"shift"skips adding the zero offsets of a call withoutstructuring_element, so itsdilationkeeps a-0.0maximum that"unfold"returns as+0.0. Gradients change only where"shift"is now selected: CPU float16/bfloat16, MPS, and forward-mode AD (torch.func.jvp) off CUDA, which records no backward graph. Previously a window with tied maxima sent its whole gradient to one argmax;"shift"splits it along its traversal order: half goes to the last tied position it visits, a quarter to the one before, and so on, so pixels that received exactly zero can now receive a fraction (the total is unchanged, and in a large flat window the earliest positions' share underflows to zero). Passengine="unfold"to keep the previous gradient behaviour. (#4728)kornia.morphology.dilation(andclosing,gradient,top_hat,bottom_hat,opening, which call it) now anchors the reflected structuring element atorigin. It used to reflect the kernel values but pad with the unreflected origin, so an even-sized kernel (for exampletorch.ones(2, 2)) shifted the result by one pixel toward the bottom-right relative toscipy.ndimage.grey_dilationandskimage.morphology.dilation, and a customoriginmoved the window in the opposite direction to the oneerosionuses. Odd kernels with the default origin are unchanged. (#4737)Morphology operations now raise a
ValueErrornaming the argument for an unknownborder_type(PyTorch raisedNotImplementedError: Unrecognised padding mode) and for astructuring_elementwhose shape differs fromkernel's (PyTorch raised an internalIndexErrororRuntimeError; only an element with extra trailing size-1 axes, such as(k_h, k_w, 1), used to run, and only withengine="convolution"). On a floating-point image, aboolor integerkernelis now a plain membership mask and gives exactly the result and dtype of the same kernel in the image's dtype. Before, auint8orint8kernel raised an overflowRuntimeError, and aboolkernel stored its excluded cells asTrueinstead of-max_val:dilationreturned wrong values on every engine,erosiondid so withengine="convolution"and raised on the other engines, and the five operations built on them inherited this. Non-float images behave as before. (#4744)adjust_gammaandAdjustGammanow raiseValueErrorwhengammaorgainhas more dimensions than the image, the same erroradjust_brightness,adjust_contrast,adjust_saturationandadjust_hueraise for such afactor(#4720). Previously the over-ranked factor silently broadcast the image up to a larger output shape: a(3, 4, 4)image with a(2, 1, 1, 1)gammareturned a(2, 3, 4, 4)tensor. (#4755)crop_by_indicesnow honorsshape_compensationwhen every box in the batch is identical. With ashape_compensationother than"resize"and a slice that does not matchsize, it used to resize the slice tosizewhenever all boxes in the batch coincided (always for a batch of one) and zero-pad or trim it otherwise; it now zero-pads or trims it in both cases, so a row's output no longer depends on the other rows in the batch.RandomMosaic(cropping_mode="slice")crops this way (shape_compensation="F.pad"): for a batch of one, or any batch whose crop boxes coincide, a crop that does not matchoutput_size(for example becauseoutput_sizediffers from the input size) used to be resized tooutput_size, out of register with the transformed boxes; it is now zero-padded or trimmed at the bottom and right, as batches with differing boxes already were, so fixed-seed outputs change. (#4756)ColorJitter(order=...)andColorJiggle(order=...)now raiseValueErrorfor a repeated index. They used to accept it and apply that adjustment once per occurrence with the same drawn factor, soorder=(0, 0, 1)applied brightness twice. (#4719) (#4760)TrivialAugment, andPolicySequentialwhen used directly, now sample each operation through itsOperationBasewrapper, so a policy entry means what it means underRandAugment. They used to call the wrapped augmentation's own sampler, which skipped the wrapper's magnitude mapping:("shear_x", -0.3, 0.3)sheared by at most0.3degrees instead of up to54, and the symmetric ops (rotate,shear_x,shear_y,translate_x,translate_y) never drew a negative magnitude. APolicySequentialbuilt from operations with aninitial_magnitudeused to ignore it; it now uses that magnitude, as the wrapper does, and the magnitude receives a gradient. For a fixed seed,TrivialAugmentnow draws different magnitudes, and a symmetric op draws its random signs from the global generator, so every later random draw in the pipeline changes as well.AutoAugmentsamples as before, up to float32 rounding of the shear values: its shear bins were pre-scaled to degrees to work around the skipped mapping and are now fractions, which the mapping scales once. Fixes #4441. (#4761)ImageSequential(if_unsupported_ops=...)now takes effect.inverseused to skip a plainnn.Modulemember (akornia.filtersblur, for example) under every value of the argument, returning the input with that module still applied and without an error. With the default'raise'it now raisesNotImplementedErrornaming the module, before anything is inverted;'skip'keeps the previous behavior. Code that inverted through a plain module must now passif_unsupported_ops='skip'. A value other than'raise'or'skip'raisesValueErrorat construction, where it was stored silently.VideoSequentialinverts through the same path and now takes the same argument.AugmentationSequentialstill leaves a plain module child applied, also when it is nested in another container, but anImageSequentialorVideoSequentialnested in it follows its own setting and so now raises by default as well.PatchSequentialis unaffected. Fixes #4423. (#4764)spatial_gradient(..., order=2, normalized=True)andSpatialGradient(order=2)now scale every second order kernel by its response to the quadratic it estimates, sodxx,dxyanddyycome out in the same units: onx**2 / 2,x * yandy**2 / 2each channel returns 1 in both modes. Previously each kernel was divided by its own absolute sum, which gave the mixed channel a scale of its own:mode="sobel"returneddxytoo large by64 / 36,mode="diff"returneddxxanddyytoo small by 4.order=1andnormalized=Falseare unchanged.hessian_responseandBlobHessianuse the normalized default, so their values change: the determinant is nowfxx * fyy - fxy**2instead offxx * fyy - (64 / 36)**2 * fxy**2(sobel) orfxx * fyy / 16 - fxy**2(diff). At the centre of a 9x9 grid:surface (true determinant) sobel before sobel after diff before diff after x**2 + y**2(4)4.0 4.0 0.25 4.0 x * y(-1)-3.1605 -1.0 -1.0 -1.0 (x + y)**2 / 2(0)-2.1605 0.0 -0.9375 0.0 With the default
grads_mode="sobel"responses without a mixed term keep their value and thefxy**2term shrinks; withgrads_mode="diff"thefxx * fyyterm grows 16 times. The detections ofScaleSpaceDetector(whose default response isBlobHessian),HesAffNetHardNet, andMultiResolutionDetectorwithBlobHessiancan therefore change. Refs #4710. (#4767)ellipse_to_lafnow returns the LAF of the ellipse it is given. For an Oxford ellipse(x, y, a, b, c)the returned upright, lower-triangularAsatisfiesA @ A.T == inverse([[a, b], [b, c]]), so the LAF maps the unit circle ontoa x**2 + 2 b x y + c y**2 = 1andellipse_to_lafof the ellipse implied by a LAFA0returnsmake_upright(A0). Previously the function took the triangular square root of the lower-triangular matrix[[a, 0], [b, c]]instead of the symmetric[[a, b], [b, c]], so wheneverb != 0the returned region was under-tilted: for(a, b, c) = (1, 0.5, 1)the region it described was[[1.0625, 0.25], [0.25, 1]], for(2, -0.9, 0.5)it was[[2.18, -0.3], [-0.3, 0.5]]. Valid ellipses withb == 0give bit-identical results.LAFAffineShapeEstimatorfeeds its second moment matrix through this function, so its output changes for every patch whose dominant gradient direction is not axis-aligned. On an anisotropic Gaussian blob rotated by 45 degrees the estimated region's major axis is now at 45.0 degrees with axis ratio 4.16; before it was at 51.3 degrees with axis ratio 1.56. Patches whose mixed moment is exactly zero are unchanged.Inputs that are not positive definite (
a,cora * c - b * bnot positive) describe no ellipse. Previously a negativeaorcwas replaced by its absolute value andbdid not enter the diagonal, so a negative diagonal entry orb * b >= a * cstill produced a finite LAF; now such an input givesinfornanentries, or huge finite ones where rounding leavesa - b * b / cbarely positive. Ac == 0input now also hasnaninA[0, 0], which used to be1 / sqrt(a). Screen results withlaf_is_valid. Refs #4684. (#4768)ScalePyramidwith aninit_sigmabelow the assumed input blur (0.5, or1.0withdouble_image=True) now builds and labels every octave from the first level's real blur, so its images andsigmasequal those of a pyramid built withinit_sigmaset to the input blur. Previously the level-to-level blurs andsigmascounted frominit_sigma: the later levels were blurred less,sigmasdid not match their blur (octave 0 labelled two different levels with the same sigma), andinit_sigma=0returned NaN images. Aninit_sigmaat or above the input blur, including the default1.6, is unchanged. (#4812)adjust_contrast_with_mean_subtraction,AdjustContrastWithMeanSubtractionand the contrast step ofColorJitternow blend an input that is not three-channel with each image's own mean over its channels and pixels. They used to blend it with the mean of the whole tensor, batch and any other leading dimensions included, so an image's result depended on the other images in the batch. Batched outputs for such inputs change; a single image,(C, H, W)or a batch of one, and three-channel inputs give the same results as before. Fixes #4806. (#4816)Morphology no longer uses the finite
max_valsentinel for floating-point images. Before, a window with no kernel cell inside the image underborder_type="geodesic"returned a finite value built frommax_val(for example-9999.0fromdilationwith the defaultmax_val=1e4), and a cell the kernel excludes still contributed its pixel minusmax_val, so data of magnitude nearmax_valgave wrong results (dilationof[0, 5e4, 0]by[[1, 0, 1]]returned40000in the middle instead of0). Now an empty window returns-inffromdilationand+inffromerosion, as scipy and scikit-image do;opening,closing,gradient,top_hatandbottom_hatinherit those infinities; andmax_valhas no effect on floating-point images. (#4818)RandomResizedCropnow follows torchvision'sget_paramsin two places. A candidate crop may equal the input's width or height; it used to have to be strictly smaller on both axes. When none of the ten candidates fits, the fallback compares the input's width/height with bothmin(ratio)andmax(ratio): an input already in range is kept whole, a narrower one keeps its full width and a wider one its full height. It used to compare height/width withmin(ratio)only, which could return a crop outside bothscaleandratio.scale=(1.0, 1.0)therefore keeps an input whose width/height is withinratiowhole; with the defaultratioit used to crop every square or portrait input and most landscape ones (an 8x6 input gave a 4x6 crop, a 7x8 input a 6x8 crop). Like torchvision, it also accepts a candidate rounded a pixel short on the longer side: an 8x6 input gives 7x6 in about 18% of draws, and a 6x8 input, which used to be kept whole every time, gives 6x7 as often. Seeded crops change for configurations that reach the fallback (ascaleclose to(1.0, 1.0)), and for draws where a candidate exactly matches the input width or height: about 1% of draws with the defaultscaleandratioon 224x224 or 256x192 inputs, more on small images (7% on 32x32). The fallback crop is still placed at a random position, where torchvision centres it. Fixes #4814. (#4823)spatial_gradient3d(..., order=2),SpatialGradient3d(order=2)and the kernel returned byget_spatial_gradient_kernel3d("diff", 2)(built bykornia.filters.kernels.get_diff_kernel3d_2nd_order) now scale the mixeddxy,dyzanddxzkernels by 1/4, so every channel is exact on quadratic volumes:dxyreturns 1 onx * y, asdxxreturns 2 onx**2. Previously the mixed kernels were[[1, 0, -1], [0, 0, 0], [-1, 0, 1]]without the 1/4 factor, sodxy,dyzanddxzcame out four times too large relative todxx,dyyanddzz.order=1is unchanged. (#4827)solve_pnp_dltnow appliesweightsto the point normalization and the degeneracy check as well as to the linear system, so a zero weight is the same as removing the point. The weights used to scale only the rows of the linear system: a zero-weight point still moved the normalization and counted in the degeneracy check, so coplanar points plus zero-weight points off the plane passed the check and returned a wrong pose (#4799). That input now raises the check'sAssertionError, as do off-plane points whose weights are too small to lift the weighted points off the plane (for example1e-8). Fewer than 6 nonzero weights in a batch element now raiseBaseError, as fewer than 6 points do; they used to return an arbitrary pose, or NaN for an all-zero row. Non-uniform weights on noisy data now return a different pose.weights=Nonegives the same result as before, uniform weights give it up to rounding, and only the weights' magnitudes relative to each other matter. (#4829)RandomRainnow paints a drop of heighthand widthwas a contiguous line ofmax(h, |w|)pixels covering exactlyhrows andmax(|w|, 1)columns. Previously a drop whose larger size was at least 2 spannedh + 1rows and|w| + 1columns with one step skipped, sodrop_height=5, drop_width=0painted rows[0, 1, 2, 3, 5]. The random draws are unchanged, but the admissible start region grew to match (by one row, and by one column unless the width is 0), so the same seed can now place such drops at different positions. Single-pixel drops are unchanged. (#4836)find_essentialandrun_5pointrecover the pose again for the roughly half of all samples whose degree-10 polynomial has a negative leading coefficient. Since #3458, first released in 0.8.3, that coefficient was clamped withclamp_min(1e-8), which turns a negative coefficient into+1e-8, so the companion matrix had the wrong sign and scale and none of the 10 candidates was the true essential matrix. On noise-free scenes the pose was recovered for 992 of 2000 samples at float64 and 880 at float32; it is now 1979 and 1767. At float32 with more than five points, the input gradients of those samples were also NaN, and now they are finite. Only an exactly zero coefficient is replaced now, as before #3458. Samples whose coefficient is at least1e-8are unchanged bit for bit; the candidates of any other sample can change, including degenerate ones whose coefficient is positive but below1e-8. Fixes #4847. (#4848)kornia.morphology.dilation,erosion, and the functions built on them (opening,closing,gradient,top_hat,bottom_hat) now computeengine="convolution"in the same promoted dtype asengine="unfold"andengine="shift". Previously,engine="convolution"returned the image's own dtype for a mismatched-dtype kernel orstructuring_element(for example, a float16 image with a float32 kernel returned float16), while the other two engines promoted to the wider dtype (float32) — so switchingenginesilently changed the result dtype. All three engines now agree. (#4882)RANSACnow returns a one-dimensional(N,)boolean inlier mask when no model is found, matching successful calls. Previously, the no-model mask had shape(N, 1)and could not be used to index the input keypoints. (#4885)find_essentialandrun_5pointnow returnNaNfor all 10 candidates of a sample whose degree-10 polynomial has an exactly zero leading coefficient, which data with no parallax, such as the same points in both images, gives for about half of all samples. Such a polynomial has a lower degree. Before, the solver divided by1e-8in place of the zero and returned up to 10 candidates from the eigenvalues of the resulting companion matrix. None of them satisfied the essential-matrix constraints, and for some samples the backward raisedtorch._C._LinAlgErrorin the backward oftorch.linalg.eigvals. Now the sample returnsNaNfor all 10 candidates and its backward completes. Samples with a nonzero leading coefficient are unchanged bit for bit. Fixes #4831. (#4888)ColorJitternow skips its brightness step when every factor is the multiplier's neutral1, instead of0(#4785). Before, a batch whose brightness factors were all0came back unchanged while the same sample in a mixed batch came back black; now a factor of0gives a black image whatever the rest of the batch drew. Before, the factor1drawn by the defaultbrightness=0.0still ran that step, which clamps into[0, 1]: an out-of-range input was clamped before any later step, and on torch releases whoseclamphas a zero gradient at its bounds, such as 2.14, input pixels at exactly0or1got no gradient. Now the step is skipped; outputs for inputs in[0, 1]are unchanged, and the contrast and saturation steps still clamp when they run. With every step neutral,ColorJitterandColorJigglenow return a copy of the input instead of the input tensor itself. (#4893)A mask override with
align_corners=NoneinAugmentationSequential(extra_args=...)now means the module's ownalign_cornersincropping_mode="slice"as well as in"resample". Slice mode used to keepNone, whichinterpolatereads asFalse, so withRandomResizedCrop's defaultalign_corners=Truea bilinear or bicubic mask was resized on a different grid from its image and no longer lined up with it. Outputs change only for that combination: slice-modeRandomResizedCropwith a bilinear or bicubic mask override,align_corners=None, andalign_corners=Trueon the module. Nearest masks,align_corners=Falseand resample mode are unchanged, as areRandomCropandCenterCrop. Fixes #4854. (#4894)RANSAC("homography_from_linesegments")now compares the squared mean endpoint-to-line distance withinl_th**2, soinl_this in coordinate units, as for the point models. It used to compare the unsquared algebraic residual, which is that distance multiplied by the target segment's length, so each segment had a different effective threshold; re-tuneinl_thfor this model. A zero-length target segment is an outlier.RANSAC.max_samples_by_confreturnssys.maxsizeinstead of1when no finite bound exists (fewer inliers than the sample size, orconf >= 1), and rounds up instead of truncating;1used to stop estimation after the first batch.RANSACnow raisesValueErrorfor a nonpositive or nonfiniteinl_th, a nonpositivebatch_sizeormax_iter, a negativemax_lo_iters, or aconfidenceoutside(0, 1]. These used to be accepted: a negativeinl_thacted as its absolute value, since it is squared, zero counted only exact matches and NaN found no model; a zerobatch_sizeormax_iterreturned the failure result without sampling; a negativemax_lo_itersdisabled local optimization; and aconfidenceof 0 or above 1 stopped after the first batch. An unsupportedscore_typenow raises at construction rather than on the first call.confidence=1now runs the full budget; it used to stop after the first batch. The CPU sampler changed, so a fixedseeddraws different, still reproducible, samples than earlier releases. (#4902)find_fundamental(method="8POINT"),find_homography_dltandfind_homography_lines_dltnow compute the Hartley normalisation with the correspondence weights, as the linear system already did, so a zero-weight correspondence (or segment) no longer changes the result (#4875, #4890). Before, the normalisation used every point unweighted, and on noisy data a far correspondence given weight 0 still moved the estimate: by 97% ofFin the #4875 example. Non-uniform weights on noisy data now give a different result, and so doesfind_homography_dlt_iterated, which re-weights after its first solve, and with it the homography polish inRANSAC.weights=Nonegives the same result as before and uniform weights give it up to rounding; negative weights count as zero in the normalisation, and a batch element whose weights are all zero keeps the unweighted one. (#4908)normalize_transformation, and with itfind_fundamental, now divides by the last entry itself instead ofM[2, 2] + 1e-8, so the returned last entry is exactly 1 (#4874). Before, it wasM[2, 2] / (M[2, 2] + 1e-8): 0.990 forM[2, 2] = 1e-6and 101 for-1.01e-8, and the backward returned NaN for a matrix whose last entry was exactly-1e-8.find_homography_dltandfind_homography_lines_dltnow end withnormalize_transformationas well. They used to divide byH[2, 2] + 1e-8without a guard, so a homography whose last entry was at most1e-8in magnitude came back multiplied by at least5e7, with a last entry anywhere below0.5; it is now returned at its unnormalised scale. At the usual scale,|H[2, 2]|of order 1, the result changes by about1e-8, relative. (#4911)find_essentialandrun_5pointnow returnNaNfor all 10 candidates of a five-point sample whose degree-10 polynomial has no real root, the same as the complex slots of any other sample, so anisfinitefilter andRANSACdrop it. Before, such a sample returned ten 3x3 identity matrices, which are finite but not essential matrices. Code that detected a failed sample by comparing its candidates with the identity should testtorch.isnan(E).flatten(-3).all(-1)instead. The samples that the fixes for #4765, #4820 and #4831 route to the same path (a singular elimination matrix, a non-finite companion matrix, a zero leading coefficient) returnNaNfor all 10 candidates as well. Every other sample, and every gradient taken throughnan_to_num, is unchanged bit for bit. Fixes #4883. (#4922)So3.log, and with itSe3.log, now returns the principal logarithm, the rotation vector with|omega| <= pi, for every element (#4925). Before, an element stored with quaternion real partw < 0, which includes everyexp(v)with|v| > piand half ofSe3.random, returned the vector of length2 pi - thetaabout the negated axis:So3.from_wxyz(-q).log()differed fromSo3.from_wxyz(q).log()for the same rotation,|So3.exp(4 * axis).log()|was4.0and is now2 pi - 4 = 2.2832, andSe3.logof a 1e-6 rad rotation stored withw < 0returned a translation part of size6.4e6where the right one is3.74.So3.logis now also invariant to the scale of the stored quaternion: a non-unitqlogs to the rotation ofq / |q|(So3(Quaternion(torch.ones(1, 4))).log()was[0, 0, 0]and is now[1.2092, 1.2092, 1.2092], the 120-degree rotation about(1, 1, 1) / sqrt(3); #4942 tracks the rest ofSo3for non-unit input), and its gradient with respect to the raw quaternion no longer has a component alongq. The component tangent to the unit sphere, which is all that reaches a caller who goes throughSo3.exp, is unchanged. (#4941)NamedPose.from_rtkeeps the batch of a rotation tensor. A(B, 3, 3)or(B, 2, 2)rotation tensor with a(B, 3)or(B, 2)translation now builds a(B, 4, 4)or(B, 3, 3)pose, asNamedPose.from_matrixand theSo3/So2rotation path do. PreviouslyB > 1raised a torchRuntimeError, andB = 1returned an unbatched(4, 4)or(3, 3)pose with a(3,)or(2,)translation; it now returns(1, 4, 4)or(1, 3, 3)with a(1, 3)or(1, 2)translation. The translation must now have exactly the rotation's batch shape, otherwisefrom_rtraises aValueError: a(1, D, D)rotation with a(D,)translation, and a(D, D)rotation with a(1, D)translation, used to return an unbatched pose and now raise. An unbatched(D, D)rotation with a(D,)translation is unchanged. (#4950) (#4950)Quaternion.__pow__now keeps the norm,q**t == ‖q‖**t (cos tθ + n sin tθ), soq**1 == q,q**2 == q * qandq**-1 == q.inv()for non-unit quaternions. Previously it returned the power of the unit quaternionq/‖q‖for everyq:Quaternion([2, 0, 0, 0])**2was[1, 0, 0, 0]and is now[4, 0, 0, 0]. Callq.normalize() ** tfor the old result. Unit-quaternion results are unchanged up to rounding, andslerp, which normalizes its inputs, is not affected. The gradient ofq**tis now finite for a nonzero quaternion with a zero vector part, such as the identity, where it used to benan. (#4951)RANSACgainsbatch_size="auto", now the default, andmax_samples. Before, every device drew batches of 2048 hypotheses andmax_itercounted them. Now the budget ismax_samplesif given, otherwise2048 * max_iteras before, and the batch is chosen per call: batches of up to 8192 homography or 2048 epipolar hypotheses on CUDA and MPS, fewer once thebatch x Nresidual matrix would exceed2**27entries, and on CPU 256 to 2048 hypotheses for homographies or 128 to 512 for the epipolar models, fewer for more correspondences (RANSAC.resolve_batch_size). Other devices retain 2048-sample batches. Pass an integerbatch_sizeto keep a fixed batch.max_samplesmust be an integer; a float raisesValueError. Results for a given seed depend on the batch, so default results change on CUDA, MPS and on CPU inputs large enough to lower the batch below 2048, and seeded local optimization withlo_sample_sizedraws from a stream offset by the sample budget instead ofmax_iter, so those results change too.find_homography_dlt_iteratedandfind_homography_lines_dlt_iteratedre-weighted each correspondence withexp(-e / (2 * soft_inl_th**2))of the unsquared errore, a kernel in whichsoft_inl_thhad no pixel meaning (#4870). They now use the Gaussianexp(-e**2 / (2 * soft_inl_th**2))of the error in pixels, for line segments the perpendicular distance of the mapped endpoints from the image-2 line, sosoft_inl_this a standard deviation in pixels, andRANSAC's homography polishers set it toinl_th. Polished homographies change accordingly. (#4979)kornia.geometry.posenow defines__all__ = ["NamedPose"], so the stdlib moduleuuid, the__future__featureannotations,torchand the validation helpercheck_matrix_shape(renamed to_check_matrix_shape) are no longer star-imported intokornia.geometry.kornia.geometry.Quaternionstays available through an explicit re-export inkornia/geometry/__init__.py, so it no longer depends on the leak. None of the removed names is documented, and perdocs/source/get-started/stability.rstundocumented helpers are private regardless of importability. The names are dropped fromtests/api_surface.jsonin this change.kornia.geometry.torchremains on the surface untilkornia/geometry/homography.pyalso defines an__all__. (#4939) (#4986)RandomGaussianIlluminationplaces the peak of its field at the pixel-centre positioncenter * L - 0.5on each axis. It used to roundcenter * Lto a whole pixel (half to even), and on an even-length axis the Gaussian kernel took another half pixel off, so the peak moved with the parity of the axis:center=0.5sat one pixel past the middle of a 3-, 7- or 11-pixel axis but on it for a 5- or 9-pixel one. The drawn field now shifts by up to one pixel, so outputs under a fixed seed change. Fixes #4811. (#4990)kornia.geometry.homographynow defines__all__with its eight public functions, so its imports are no longer star-imported intokornia.geometry:torch,warnings,typing.Optional,typing.Tuple, the type aliasTupleTensor,KORNIA_CHECK_SHAPE,safe_inverse_with_maskandsafe_solve_with_mask. None of them is documented onkornia.geometry, and perdocs/source/get-started/stability.rstundocumented helpers are private. They are dropped fromtests/api_surface.jsonin this change. (#4994) (#4994)decompose_essential_matrixandmotion_from_essentialkeep the leading dims of the input for an unbatched(3, 3)essential matrix: the rotations are now(3, 3)and the four candidates(4, 3, 3), matchingtof shape(3, 1)and(4, 3, 1). They used to come back as(1, 3, 3)and(1, 4, 3, 3), so a caller that indexedR1[0]after an unbatched call has to drop the index. Batched inputs are unchanged. Fixes #4878. (#4998)RANSACdefaults changed:score_typeis now"msac"(was"ransac") andlo_sample_sizeis now32(wasNone, iterative full-inlier refits). Candidates are now ranked by truncated squared residuals instead of inlier count, and local optimization fitsmax_lo_itersrandom 32-inlier subsets before one full-inlier refit whenever the consensus set has more than 32 inliers. Estimates for a given seed change accordingly; passscore_type="ransac"andlo_sample_size=Noneto keep the previous behavior. The RANSAC time-mAA benchmark now compares the class defaults, with and without PROSAC, against PoseLib and OpenCV, and skips PROSAC configurations on pairs without a match ranking. (#5002)So2reads a(B, 1)complex number or angle as(B,): an element built bySo2(z)orSo2.exp(theta)from a column now haszandlog()of shape(B,)andmatrix()of shape(B, 2, 2),So2.hat(theta)returns(B, 2, 2), andSo2 * pointsrotates(B, 2)points pairwise into(B, 2). They used to keep the column, sozandlog()were(B, 1),matrix()andhat()were(B, 1, 2, 2)(whichvee()rejects),So2 * pointsbroadcast into(B, B, 2)with every rotation applied to every point, andSe2rejected the element. The given tensor is still what the module registers, so a(B, 1)nn.Parameterstays its parameter andstate_dict()keeps the(B, 1)shape.(B,)and()inputs are unchanged. Fixes #4932. (#5005)kornia.filters.median_blur,MedianBlurandRandomMedianBlurnow reject an even or non-positivekernel_sizeentry with kornia'sBaseError("Kernel size must be an odd integer bigger than 0"), andRandomMedianBlurdoes so at construction. PreviouslyRandomMedianBluraccepted such a kernel at construction, and the call failed with a raw torchRuntimeErrorfrom a reshape, a pad or a convolution, whichexcept RuntimeErrorno longer catches. The one input that used to pass was an even kernel on an empty batch or an image with zero channels, which returned an empty tensor and now raises too. Integral floats and numpy integers such as(3.0, 3.0)are still accepted. (#5007)Se2.t/Se3.t(and.translation) are now always a tensor registered as module state, whichever constructor built the pose:__init__unwraps aVector2/Vector3, andidentity,randomandSe3.from_qxyzpass tensors. Those three used to keep aVector2/Vector3outside module state, soSe3.identity(1).t[..., 0]raisedRuntimeError: Could not infer dtype of ellipsis,Se2.identity(1) * pointsreturned aVector2, andstate_dict()and.to()skipped the translation. Their translation is now annn.Parameterwithrequires_grad=Truelike the other constructors', so.x/.y/.zon it stop working (index the tensor instead) andmatrix(),adjoint()andg * pof such a pose carry agrad_fn;g * pstill returns aVector2/Vector3whenpis one. Numerical results are unchanged. Astate_dictsaved before this change has no_translationentry for such a pose, so a strictload_state_dictof it now raisesMissing key(s); load it withstrict=False, which keeps the translation the constructor built, as loading did before. (#5011) (#5011)fit_linewithweightsnow centresD >= 3points on the weighted centroid and returns it as the origin, as theD = 2branch does, so a point with weight 0 no longer moves the origin or tilts the direction. Previously the points were centred on the unweighted mean, which was also the returned origin, and only the scatter matrix was weighted, so any non-uniform weights gave a different origin and direction from weighted least squares. Uniform weights give the same line as before, and a row whose weights sum to 0 still gets the unweighted mean as its origin. (#5029)RANSACfor homographies and fundamental matrices now defaults tolocal_optimization="lm": it keeps the eight best minimal models of the run, refines them with Levenberg-Marquardt on the truncated Sampson or transfer error after sampling, and refines the winner on its inliers with a Cauchy loss. Previously each new best model was refitted with DLT solutions on 32-inlier subsets and then on all its inliers (lo_sample_size=32).model_type="fundamental"now draws seven-point samples like"fundamental_7pt"; it used to draw eight-point ones, which the new"fundamental_8pt"keeps. With the new default, auto batches grow from 256 samples on CPU instead of a fixed size, early stopping follows the support of the best minimal model instead of the refitted one, and the returned mask holds the inliers of the returned, refined model. Estimates for a given seed change accordingly; passlocal_optimization="dlt"(with"fundamental_8pt"for fundamental matrices) to keep the previous behavior. Essential matrices and line-segment homographies are unchanged. (#5031)homography_warpwithnormalized_homography=Falsenow passesmodeandalign_cornerson towarp_perspective. Previously that path always sampled withmode="bilinear"andalign_corners=True, whatever the caller passed. A call with the default arguments now uses the signature'salign_corners=False: withpadding_mode="zeros"or"border"the output moves only by float rounding, but withpadding_mode="reflection"the out-of-bounds samples change. Passalign_corners=Trueto get the previous output. Callers who passedmode="nearest"ormode="bicubic"now get that interpolation instead of bilinear. (#5032)save_pointcloud_plyandsave_pointcloud_ply_binarynow write every row of the flattened input, including rows whose x, y and z are all non-finite (written asnan/infin ASCII and as IEEE values in binary), so theelement vertexcount equals the number of points and rowiof the file is rowiof the input. Previously such rows were silently skipped and the vertex count excluded them, which broke the row-to-pixel correspondence of an organised cloud such asdepth_to_3doutput with invalid depth. (#5033)spatial_softmax2d,spatial_soft_argmax2dandSpatialSoftArgmax2dnow treattemperatureas a softmax temperature, asconv_soft_argmax2dandconv_soft_argmax3dalready did: the input is divided by it, so a smaller value gives a sharper distribution. Previously the input was multiplied bytemperature, so a larger value was sharper; a Python float raisedAttributeError; and0or a negative value was accepted (0returned a uniform map, a negative value inverted it). A float is now accepted, and a temperature that is not positive raisesValueError. To keep an old result, pass1 / temperature. The default,1.0, gives the same output as before. (#5035)render_gaussian2dnow normalises each axis with a softmax over the Gaussian's exponents instead of dividing by the sum plus1e-8. A Gaussian inside the image now sums to 1 up to roundoff; the1e-8term used to leave it about1e-8short. A mean far outside the grid now renders the grid part of the Gaussian rescaled to sum to one, which puts its mass on the nearest border row or column, in every dtype and with finite gradients. Previously the1e-8term made such a heatmap lose its mass once the mean was about six standard deviations outside the grid, and it was exactly zero once every sample underflowed. (#5036)ParametrizedLine.intersectnow returns twotorch.Tensors, as annotated. Previously the lambda and the point came back askornia.geometry.vector.Scalarwrappers, because the plane's offset is aScalar, andHyperplane.signed_distancerejected the returned point. Code that unwrapped them with.datastill gets the same values, but.dataon a tensor is detached from autograd: drop the.datato keep gradients. (#5044)strict_maxima_bonusis deprecated and ignored inconv_soft_argmax3d,ConvSoftArgmax3d,conv_quad_interp3d,ConvQuadInterp3d,iterative_quad_interp3d,IterativeQuadInterp3dandAdaptiveQuadInterp3d. Previously the quad-interp functions and modules addedstrict_maxima_bonus=10.0by default to the returned value at every converged NMS maximum, andconv_soft_argmax3dscaled its values when given a positive bonus, incorrectly (#5018). Now no bonus is added: the returned values are the refined responses. The argument is still accepted, by keyword or in its 0.8.3 position, but it emits aDeprecationWarningand will be removed in a future release. The default refiners ofScaleSpaceDetectorandSIFTFeatureScaleSpacealready passedstrict_maxima_bonus=0.0, so their detections are unchanged. Code that ranked the dense value map returned by these functions withtopkand relied on the bonus to put strict maxima first should select candidates with anms3d(x, (3, 3, 3), mask_only=True)mask instead. (#5045)ParametrizedLine.through,fit_line,fit_planeandHyperplane.throughnow raiseValueCheckErrorfor input that does not determine a line or a plane: two coincident points forParametrizedLine.through; fewer than two points, identical points, or weights that do not sum to a positive value forfit_line; fewer than three points, identical points or collinear points forfit_planeandHyperplane.through. They used to return an arbitrary valid-looking result: a zero direction, a fixed direction such as (0, 1) or (1, 0, 0), a NaN origin for all-zero weights, or one of the infinitely many planes that contain the line. A batch is rejected when any of its rows is degenerate. The collinearity tolerance is relative and scales with the machine epsilon of the input dtype. The checks are skipped undertorch.compileand afterdisable_checks(), where the previous results come back. (#5054)Hyperplane.throughnow divides the cross product by its Euclidean norm, so the returned normal has unit length andsigned_distance,abs_distanceandprojectionare right for tilted planes. It used to divide by the p = -1 "norm", so the normal of a plane through three generic points was not unit: for the plane through (1, 0, 0), (0, 2, 0) and (0, 0, 3) it was (-6, -3, -2), and distances came out 7 times too large. Axis-aligned planes, whose cross product has a zero component, used to take the SVD fallback, whose sign is arbitrary; they now take the cross-product branch, so their normal is(p2 - p0) x (p1 - p0)normalised and can be the negation of the previous one, which flips the sign ofsigned_distance: the plane through (0, 0, 1), (1, 0, 1) and (0, 1, 1) now has the normal (0, 0, -1) instead of (0, 0, 1). The collinearity threshold is now evaluated per batch row, relative to the dtype's machine epsilon, instead of once over the whole batch. (#5055)conv_soft_argmax2d,conv_soft_argmax3d,ConvSoftArgmax2dandConvSoftArgmax3dnow measure each window's softmax-weighted offset from the window centre in pixels, so a window returns the softmax expectation of its pixel coordinates, as the docstring formula states. Previously the offset kernel ran from −1 to 1 along every axis whatever the window size, which scaled the offset by 2/(k − 1): a 5-wide window reported a peak at x = 8 as x = 7, a 7-wide window as x = 6, and a 2-wide window doubled the offset. Window sizes 1 and 3 (the default) give the same output as before; any otherkernel_sizeentry changes the coordinates along that axis, in pixels and in normalized coordinates. (#5017) (#5059)conv_quad_interp3d,iterative_quad_interp3d,ConvQuadInterp3d,IterativeQuadInterp3dandAdaptiveQuadInterp3dnow reject a maximum whose last iteration still moves its integer centre: it keeps its grid coordinates and its input value. Previously such a point was reported at the new centre plus the shift solved at the old one, one voxel beyond that fit on every axis that moved, with its value read at the moved voxel, and a point alternating between two cells landed one voxel off on either side depending on the parity ofn_iters. A rejected maximum, whatever rejected it, now reads its value at the voxel it reports instead of the voxel it last moved to. With the defaultn_iters=5this changes a few percent of the refined maxima (1.4% to 8.8% on blurred-noise inputs), soScaleSpaceDetectorand the detectors built on it, such asSIFTFeatureScaleSpacewith its defaultdescriptor_backend="patch", return different keypoint positions, scales and responses. (#5038) (#5060)load_imagewithImageLoadType.RGBA8now fills the alpha channel it adds to RGB and grayscale images with 255, so they load opaque. It used to fill that channel with 0, which made them fully transparent. Images that already have an alpha channel keep their own. (#5077)RANSAC("essential")now defaults tolocal_optimization="lm": the run's eight best five-point models are refined by Levenberg-Marquardt on the essential manifold, and the winner by a final Cauchy refinement on its inliers, in the caller's calibrated coordinates. Previously"essential"only supported"dlt", which refits eight-point fundamental matrices on inlier subsets and projects them onto the manifold;local_optimization="dlt"still selects that loop, but its five-point samples now come from the newfind_essentialsolver, so its estimates can differ from before at rounding level and in sign. Estimates for a given seed change; the returned E has unit Frobenius norm and a positive largest entry, and the returned mask holds the inliers of the returned matrix. The returned E no longer carries autograd; its gradient to the correspondences was NaN before. Automatic batches for essential matrices now start at 64 samples on CPU and double up to 1024, and start at 256 on CUDA and MPS and double up to 8192, instead of a fixed 128 to 512 samples per batch on CPU and 2048 on CUDA and MPS. (#5078)mean_average_precisionnow computes each class's recall over the ground-truth objects of that class, as the reference implementation it is adapted from does. It used to divide by the number of ground-truth objects of every class, so when the ground truth held more than one label no class could reach recall 1 and the per-class AP and the mAP came out too low: two objects of different classes, each detected exactly, scored 0.5455 instead of 1. Inputs whose ground-truth objects all share one label give the same values as before. (#5079)kornia.morphology.dilation,erosion,opening,closing,gradient,top_hatandbottom_hatnow raise aTypeErrorfor an image that is not floating point (bool,uint8or another integer dtype), before any padding or engine dispatch. Such images were never supported but used to run, with results that depended on the dtype, the border and the device: under the defaultborder_type="geodesic",dilationof aboolimage on CPU set every border pixel, auint8image raised torch's overflowRuntimeErroron CPU and returned240at the border on MPS, and an integer image kept the finitemax_valsentinel for excluded kernel cells, sodilationof[0, 50000, 0]by[[1, 0, 1]]returned[50000, 40000, 50000]instead of[50000, 0, 50000]. Floating-point images are unaffected. Convert an integer or boolean image with.float()first. (#5081)conv_soft_argmax2d,conv_soft_argmax3d,ConvSoftArgmax2dandConvSoftArgmax3dnow continue the window-centre coordinate grid into the padding, so a window whose centre straddles the border reports the softmax expectation of its in-image pixels. Previously the grid was zero-padded: with an evenkernel_sizeandpadding = k / 2(for examplek = 2with the defaultpadding = 1), the first and last window on an axis averaged the coordinate 0 of a padded pixel into its centre on every channel and reported a point far inside the image (x = 3.5, y = 1.25 for a peak at x = 8, y = 2 on a 5 x 9 map). Odd windows, and even windows withpadding < k / 2, give the same output as before. (#5066) (#5086)conv_quad_interp3d,iterative_quad_interp3dand their modules now treat a fit as singular when|det H| <= 1e-7 * m**3, withmthe largest magnitude among the Hessian entries. Previously the floor was an absolute|det H| <= 1e-7, and the determinant is cubic in the response amplitude, so well-conditioned maxima of a low-amplitude response kept their integer coordinates:ScaleSpaceDetectoron a[0, 1]image returned almost every keypoint unrefined. Those keypoints are now refined to sub-pixel positions, which changes detector output. The solve is scaled so that its largest Hessian entry is about 1, so a flat image region, whose Hessian entries are rounding noise, keeps a finitefloat32image gradient. (#5065) (#5087)fit_linenow raisesValueCheckErrorwhen the points with positive weight are all the same point, for example when the weights are positive on a single point: a point with weight 0 does not count, so such a row does not determine a line. It used to return the fallback direction (0, 1) in 2-D and (1, 0, 0) in 3-D. A batch is rejected when any of its rows is degenerate. The check is skipped undertorch.compileand afterdisable_checks(), where such a row still gets (1, 0, 0) in 3-D, and (1, 0) in 2-D with the total least squares fit of #5094. (#5082) (#5088)fit_linenow fits 2-D points by total least squares, as it does points of higher dimension: the line minimises the perpendicular distances to the points. It used to fit an ordinary least squares slope of y on x, which minimises the vertical distances, so noisy 2-D points gave a direction biased towards horizontal (8.3 degrees off for a near-vertical set whose total least squares fit is 1.4 degrees off), swapping x and y changed the line, and a set withsum((x - x.mean()) ** 2) <= 1e-8, such as a slanted set in small units, came out vertical. Infloat16, steep sets and sets spanning a few hundred units came out NaN or(1, 0). Points exactly on a line give the same direction as before: the 2-D direction still has a non-negative x component, and an exactly vertical line still gets(0, 1). Undertorch.compileordisable_checks(), where degenerate input is not rejected, identical 2-D points now get the direction(1, 0)instead of(0, 1). (#5094)ImageRegistrator's'similarity'and'rotation'models now rotate the image in pixels on a non-square image (#5063).Similarity.forward()used to applyscale * angle_to_rotation_matrix(rot)directly in the normalized[-1, 1]frame, whose x and y units differ byW / H, so on anH != Wimage the model was not a rotation of the pixels and a rotated image could not be registered exactly: a 6 degree rotation of a 32 x 48 image was recovered with a 1.2 px corner error, against 0.001 px on a 40 x 40 image.register()now calls the newSimilarity.set_image_shape(height, width)with the size ofdst_img, andforward()then usesscale * diag(H / W, 1) @ angle_to_rotation_matrix(rot) @ diag(W / H, 1), sorotandscaleare the rotation and scaling of the pixels about the image centre. On a non-square image the matrices returned byregister()and used bywarp_src_into_dst()andwarp_dst_into_src()change. Square images, the'translation'and'scale'models, and aSimilaritywhose image shape was never set are unchanged. (#5096)fundamental_from_projectionsnow divides a float16 result by its largest absolute entry before casting it back to float16, so pixel-unit projection matrices no longer giveinf(#4877). It used to cast the unnormalised float32 determinants back, which overflowed for ordinary cameras (5 of 9 entriesinffor focal lengths of 700-800 px) and flushed projection matrices with entries of order1e-2to all zeros. float16 results that used to be finite now differ from before by a positive scale factor, up to rounding; an all-zero result stays zero. float32, float64 and bfloat16 results are unchanged. (#5097)mean_average_precisionnow compares float64 recalls against the recall thresholdsi / 10, so a recall that lands exactly on a tenth reaches it. Previously the thresholds were the float32 values oftorch.arange(0, 1.1, 0.1)widened to Python floats, and0.10000000149,0.20000000298,0.30000001192,0.40000000596,0.60000002384and0.80000001192lie above the tenths they stand for. A float64 recall of exactly 0.1, 0.2, 0.3, 0.4, 0.6 or 0.8 then skipped that threshold, and the class AP and the mAP came out lower than in float32: 10 objects with detections ranked TP, FP, then 9 TP scored 0.9174 (111 / 121) instead of 0.9256 (112 / 121). float64 now gives the float32 values. float16, bfloat16 and float32 results are unchanged, because each threshold rounds to the same value in those dtypes (#5083). (#5101)Hyperplane.throughnow takes the edges and the cross product of float16 and bfloat16 points in float32 and casts the unit normal back, so the normal keeps the(p2 - p0) x (p1 - p0)orientation. Previously, in float16, the cross product of a small valid triangle underflowed (edges of 1e-4 give 1e-8, below the smallest subnormal) and that of a large one overflowed (edges of 300 give 9e4, above 65504), and the triangle took the SVD fallback, whose sign is arbitrary: the right triangle at the origin with legs of 1e-4 or 300 came back as(0, 0, 1)instead of(0, 0, -1), which flipssigned_distancefor every point. Triangles with edges near the float16 limit were rejected as collinear, and an edge longer than 65504 gave nan. Without the value checks, as undertorch.compile, a float16 or bfloat16 triangle now takes the SVD fallback at the float32 threshold, so a thin one keeps its orientation there too. The collinearity check keeps the tolerance of the input dtype. float32 and float64 results are unchanged (#5064). (#5104)fit_linenow raisesValueCheckErrorwhen a weight is negative. Such weights passed the check that each row's weights sum to a positive value, but a negative weight can make the weighted scatter matrix indefinite, and then the 2-D and the D ≥ 3 fits of the same points disagree: for the four 2-D points of #5106 with weights(1, -3, 1, 2), the 3-D fit of the points with z = 0 returned the direction (0.79, 0.62, 0), while the 2-D fit returned the vertical fallback (0, 1), or, with the total least squares fit of #5094, the perpendicular direction (0.62, -0.79). Any negative weight is rejected, also one small enough to leave the scatter without a negative eigenvalue, such as -0.01 among weights of 1. A weight of 0 or -0.0 is still accepted and drops its point. A batch is rejected when any of its rows has a negative weight. The check is skipped undertorch.compileand afterdisable_checks(), where negative weights are still fitted. (#5106) (#5108)RgbToGrayscale()withoutrgb_weightsnow storesrgb_weights = Noneinstead of the float32 tensor[0.299, 0.587, 0.114], and raisesTypeErrorfor an integer or bool image other than uint8, asrgb_to_grayscaledoes. It used to return all zeros for int8, int16, int32 and int64 images. (#5111)RandomCropandRandomCrop3Dpreviously exposedtransform_matrixin padded-canvas coordinates, so callers had to add the pre-crop left/top (and front for 3D) padding themselves. They now map original input coordinates directly to output coordinates; callers that manually added padding must remove that workaround. (#5114)sampson_epipolar_distance,symmetrical_epipolar_distance,left_to_right_epipolar_distance,right_to_left_epipolar_distance,point_line_distance,oneway_transfer_errorandsymmetric_transfer_errorno longer addepsto their denominators or inside the square root, and returninfin the singular cases instead (#4881): both epilines witha = b = 0for the Sampson distance, either one for the symmetrical distance, the line forpoint_line_distanceand the one-way epipolar distances, and a point thatHmaps tow' = 0for the transfer errors. The values are now independent of the scale ofF,Hor the line,squared=Falsereturns exactly 0 for an exact match, with a zero gradient, and the CUDA matmul and the CPU manual Sampson paths agree. Before, the sameFat‖F‖ = 1e-3scored 90% lower than at‖F‖ = 1(9.3e-6 relative there), an exact match scoredsqrt(eps) = 1e-4, the two Sampson paths differed by that scale-dependent amount, a degenerateFscoredresidual² / eps(1e8forF = diag(0, 0, 1)) on CPU andinfon CUDA, and on CPU an all-zeroFor line put every point at distance 0. Theepsparameters are still accepted and have no effect. (#5116)MS_SSIMLossnow pairs every channel with every scale and averages the MS-SSIM term over the channels. Previously its masks were laid out scale-major while the grouped convolution reads them channel-major, so for RGB input red was filtered at scales 0, 0, 0, 1, 1, green at 1, 2, 2, 2, 3 and blue at 3, 3, 4, 4, 4, and the luminance term saw only blue: withalpha=1andcompensation=1, at the centre of a random 32 x 32 image, brightening the red or green channel by 0.3 cost less than 1e-4 while brightening blue cost 0.28, and swapping RGB to BGR changed the loss. The contrast-structure terms of all channels were multiplied together, single-channel input got the MS-SSIM term cubed, and inputs whose channel count does not divide3 * len(sigmas)(2 or 4 channels with the default sigmas) raisedRuntimeError. The MS-SSIM term is now one minus the mean, over the channels, of the per-channel MS-SSIM (luminance at the coarsest scale, contrast-structure at every scale), as in the reference implementation of Zhao et al., and any channel count is accepted. Withalpha > 0the loss changes for differing images; the Gaussian-weighted L1 term is unchanged. The masks are rebuilt fromsigmasinstead of being persisted: old checkpoints still load strictly, but their_g_masksvalues are ignored. (#5121)conv_soft_argmax2d,conv_soft_argmax3d,ConvSoftArgmax2dandConvSoftArgmax3dnow take the softmax of every window over that window's own values (#5020), so a window's coordinates and value no longer depend on the rest of the map. Previously the exponent was shifted by the maximum of the whole map andepswas added to each window's denominator: a window 15 or more units oftemperaturebelow that maximum was pulled toward its centre and its value toward 0, and from about 30 units it returned its centre with value 0 in float32, float64 and bfloat16; in float16 it was wrong from about 15 units and NaN from about 18. Witheps=0such a window was right untilexpunderflowed and NaN beyond (about 95 units in float32 and bfloat16, 745 in float64). Windows near the map maximum move within precision: on maps spanning a few units oftemperature, by up to about 3e-6 in float32 and float64 and by one to three ulp in float16 and bfloat16.epsis still accepted and has no effect.conv_soft_argmax3dnow runs in float16 and bfloat16 on CPU, where it raisedNotImplementedError(avg_pool3d). Apaddingabove half ofkernel_size, or a negative one, raisesValueErrorinstead of the pooling kernel'sRuntimeError. The windows are unfolded, which takesk*k(2D) ork*k*k(3D) times the memory of the output map, and a CPU forward pass takes about 1.2 to 2.4 times as long as before (3x3 to 15x15 windows). (#5134)line_segment_transfer_error_one_wayreturns the mean perpendicular distance, in pixels, of the two mapped image-1 endpoints from the image-2 line. It used to return that distance multiplied by the image-2 segment length, because the line was not normalised: the same 3-px offset scored 197 on a 66-px segment and 994 on a 331-px one. Values drop by the image-2 segment length, so a threshold tuned on the old values has to be re-tuned in pixels.RANSAC("homography_from_linesegments")andfind_homography_lines_dlt_iteratedalready scored the pixel distance and are unchanged up to rounding. Fixes #4867. (#5135)MS_SSIMLossnow builds an odd, centred Gaussian window of2 * int(2 * sigmas[-1]) + 1pixels (#5126). Previously the window wasint(4 * sigmas[-1] + 1)wide, which is even for a largest sigma such as 1.3 (6 pixels) or 3.3 (14): the window sat half a pixel off centre and thereduction="none"map came out(N, H - 1, W - 1)instead of the documented(N, H, W). Those sigmas now get a window one pixel narrower (5 and 13), the map keeps the input shape and the loss changes by about 2% on random images. Every integer or half-integer sigma, the defaults included, keeps its window size, and its outputs are bitwise unchanged. (#5143)lovasz_softmax_lossandLovaszSoftmaxLossnow compute each class's Lovász gradient from that class's binary foreground mask, as the reference implementation of Berman et al. does (lovasz_softmax(..., classes="all", per_image=True)). Previously they used the integer class labels in place of the mask, so the loss and its gradients did not match the reference and changed when the classes were renumbered: for the three-pixel, three-class example in #5150 the loss was 0.2167, or 0.2389 after relabelling the classes, instead of 1/3. Loss values and gradients change. (#5151)Resize,LongestMaxSize,SmallestMaxSizeand slice-modeRandomResizedCropwithalign_corners=Falseand bilinear or bicubic resampling now record the half-pixel map their resize samples with,x' = (x - x0 + 0.5) * W_out / W_crop - 0.5and likewise fory, astransform_matrix, wherex0andW_cropare the crop's first column and width (0and the input width for the resize classes). They used to record the corner-to-corner mapx' = (x - x0) * (W_out - 1) / (W_crop - 1), so keypoints and boxes moved throughAugmentationSequentiallanded up to|W_out / W_crop - 1| / 2output pixels from the content they annotate (half a pixel at a 2x upscale), and theinverse()of the three resize classes warped the image back with that map, which did not return content to its original place. The resized images,align_corners=True(the default for these classes), nearest resampling and resample-mode crops are unchanged. (#5179)blur_pool2d,BlurPool2D,max_blur_pool2dandMaxBlurPool2Dwith an even kernel size now returnceil(n / stride)samples along each axis, as odd kernel sizes already did, wherenis the input height or width, reduced bymax_pool_size - 1for the max variants. The input is zero-padded by(k - 1) // 2pixels before andk // 2after, the amounts antialiased-cnns uses (antialiased-cnns pads by reflection by default; kornia pads with zeros). Previously both sides were padded by(k - 1) // 2, so an axis lost its last sample whenevern - 1was a multiple of the stride. At stride 1 that is every axis: a 7x10 map returned 6x9 and now returns 7x10. At stride 2 only an oddnis affected:blur_pool2don a 7x10 map returned 3x5 and now returns 4x5 while 8x8 is unchanged, andmax_blur_pool2dwith the defaultmax_pool_size=2on an 8x8 map returned 3x3 and now returns 4x4. The old output is always the leading block of the new one. Odd kernel sizes are unchanged, bit for bit (#5166). (#5184)kornia.core.load_state_dict_from_urlnow loads checkpoints withweights_only=Trueunless the caller passesweights_only=False, and so does everypretrained=Truemodel built on it. The loaders that calltorch.loaddirectly passweights_only=Trueas well:ModelBase.load_checkpointfor a local file,SmallSRNet,RRDBNetBuilderand LightGlue's local weights. Previously the wrapper forwarded theweights_only=Falsedefault oftorch.hub.load_state_dict_from_urlon every supported torch, and the direct calls usedtorch.load's default, which isFalsebefore torch 2.6, so loading a checkpoint unpickled whatever objects it stored. Now only tensors, primitive types and plain containers load. A checkpoint holding any other type fails withpickle.UnpicklingError, whichload_state_dict_from_urlchains to itsRuntimeError. To load such a file through any of these loaders, allowlist its types withtorch.serialization.safe_globals([...])around the call.load_state_dict_from_urlalso acceptsweights_only=False, which the other loaders do not; pass it only for a file you trust. All of kornia's pretrained checkpoints load under the new default, on torch 2.14 and 2.5.1, without an allowlist. On torch before 2.10,weights_only=Truedoes not guarantee that a checkpoint runs no code: PyTorch's advisories GHSA-53q9-r3pm-6pq6 (before 2.6) and GHSA-63cw-57p8-fm3p (before 2.10) report checkpoints crafted to run code despite it. Load a checkpoint from a source you do not trust only on torch 2.10 or later.The fallback download sources on
cmp.felk.cvut.cz(HardNet8, LoFTR, SOLD2, DexiNed and three LightGlue heads) are now fetched overhttpsinstead ofhttp. DeFMO'shttpfallback onptak.felk.cvut.czhas no usablehttpsequivalent and is removed, so DeFMO loads from its Hugging Face mirror only. (#5225)KORNIA_CHECK_IS_IMAGEchecks the shape again with the defaultraises=True, as its docstring says and as it did before #3156. It used to returnTruefor a tensor that is not(*, 1, H, W)or(*, 3, H, W), such as(5, 4, 5), an RGBA(B, 4, H, W),(4, 5)or a 0-d scalar, while the same call withraises=FalsereturnedFalse. It now raisesImageError, so code that passed a non-image through the check getsImageError. So doesimage_to_string, which rendered a 6-channel tensor as if it had 3 channels. A float image containing NaN used to pass the range check for bothraisesvalues. It now fails it:raises=TrueraisesValueCheckErrorandraises=FalsereturnsFalse. (#5232)kornia's validation errors now also derive from the matching built-in exception:
ShapeError,ValueCheckError,DeviceErrorandImageErrorareValueErrors, andTypeCheckErroris aTypeError. Previously all five derived only fromBaseError(anException), so anexcept ValueError:orexcept TypeError:around a kornia call caught the functions that raise the built-ins themselves but let a failedKORNIA_CHECK_*escape, for examplegaussian_blur2don a 2-D tensor. Such clauses now catch these errors as well;except BaseErrorand the specific classes keep working. A failed plainKORNIA_CHECKstill raises the bareBaseError, which is neither built-in. This does not restore v0.8.2, where the shape, device and color/gray image checks raisedTypeError: they areValueErrors now, so anexcept TypeErrorwritten for v0.8.2 still misses them. Separately, a call whose tensors share a device but differ in dtype, such asfind_homography_dltwith afloat32and afloat64point set,get_motion_kernel2d,geometry.transform.Affineor an augmentation's parameter generator given mixed dtypes, now raisesTypeCheckError("expected torch.float32, got torch.float64") instead of aDeviceErrorthat listed the same device twice;except DeviceErrorno longer catches it. When the tensors span more than one device, the call raisesDeviceErroras before, whether or not their dtypes also differ and wherever the mismatches sit in the argument list; its message now names only the two devices ("Passed tensors are not on the same device: expected cpu, got cuda:0."). (#5233)ImageModule,ImageSequentialand the augmentation containers now convert NumPy, PIL and image-path inputs by their dtype, and return channels-last arrays foroutput_type="numpy".to_tensorused to divide every input by 255 whatever its dtype: a float image already in[0, 1]shrank 255 times (0.5 became 0.00196), auint16image or 16-bit PNG reached 257, and aboolmask became 1/255. Now an integer input is divided by the maximum of its dtype (uint8by 255 as before,uint16by 65535,int16by 32767), aboolarray becomes 0 and 1, and a floating array keeps its values;uint8inputs convert to the same values as before, and a PIL input now takes the default dtype, as a NumPy input already did (it was alwaysfloat32). A signed integer image maps to[iinfo.min / iinfo.max, 1], so its negative values stay negative (int8-128 gives -128 / 127).output_type="numpy"(andto_numpy) used to return the(C, H, W)/(B, C, H, W)layout of the output tensor, whichto_tensorread back as channels-last and transposed; it now returns(H, W, C)/(B, H, W, C), the layout NumPy inputs use, with the tensor's values, so a float output fed back in converts to the same tensor. Every 3-D or 4-D output is treated as an image, so a non-image element of a tuple output (such as a(B, N, 4)box tensor) moves its axis too; modules with several outputs are #5210. Code that expected the old layout moves the channel axis withnp.moveaxis(out, -1, -3). (#5239)A missing optional dependency now raises by default.
kornia_config.lazyloader.installation_modeused to default to"ask", which asked on stdin whether to install the package: without an interactive stdin (a CI job, a DataLoader worker) that raisedEOFErrorinstead ofImportError, and on an open stdin that nobody writes to it blocked. The default is now"raise": anImportErrornamingpip install "kornia[<extra>]"."ask"is opt-in and raises the sameImportErrorwithout an interactive terminal on stdin and stdout (for example in a Jupyter notebook, whose kernel's stdin is not a terminal, or with output redirected to a file); its "[A]ll" answer, which used to apply to one loader, now switches the process to"auto"."auto"used to install the loader's import name with-U, even where it is not a package name, and did not check pip's exit status; it now installs the declared kornia extra instead of the import name (pip install "kornia[<extra>]", for examplekornia[image], without-U), raisesImportErrorif pip fails (without running pip again for that loader), and installs nothing for a loader that declares no extra ("ask"does not ask for one either). The newKORNIA_INSTALLATION_MODEenvironment variable sets the mode when kornia is imported (raise,askorauto, any case); another value does not stopimport kornia, but raises aValueErrornaming the variable, the valid modes and the missing package the first time a missing optional package is handled. The undocumentedLazyLoader.auto_installclass switch is removed; set the mode to"auto"instead.InstallationModemembers are now hashable and compare equal only to their upper-case values (InstallationMode.ASK == "ASK"):==used to ignore case while!=did not, soInstallationMode.ASK == "ask"andInstallationMode.ASK != "ask"were both true. Theinstallation_modesetter still accepts any case. (#5240)The in-place operators of
kornia.core.TensorWrapper, and so ofVector2,Vector3andScalar(+=,-=,*=,/=,//=,%=,**=,&=,|=,^=,<<=and>>=), now update the wrapped tensor in place and return the same wrapper, as they do on a tensor. They used to rebind the name to a new wrapper:+=,-=,*=,/=and//=with any operand, and the others with a tensor operand (with a Python number or another wrapper they raisedTypeError). So an alias kept the old values, and the tensor the wrapper was built from was never modified. A wrapper does not copy the tensor it is built from, sov = Vector3(t); v += 1now also modifiest. An in-place operator now raisesRuntimeErrorwhere the tensor's in-place operator raises, where it used to return a new wrapper: on a wrapper of a leaf that requires grad, such asVector3(nn.Parameter(...))("a leaf Variable that requires grad is being used in an in-place operation"), for an update that changes the dtype, such as/=on an integer wrapper ("result type Float can't be cast to the desired output type Long"), and for an update that broadcasts to a larger shape. Writev = v + xto keep the old behaviour.@=still rebinds, as it does on a tensor. (#5243)ONNXExportMixin.to_onnx(behindImageModule.to_onnx,kornia.core.ImageSequential.to_onnxand the model exporters) now requests ONNX opset 18, the opset the dynamo exporter builds natively, and documents it. It used to request 17: the dynamo exporter, the default oftorch.onnx.exportfrom torch 2.9, met that only when every operator had a down-conversion adapter (a convolution came back at 17, aGaussianBlur2dpipeline at 18 after a logged conversion failure), and the legacy exporter of older torch returned 17. Passopset_version=to request another one. To chain an export with the pre-exported Hub operators (opset 17) inONNXSequential, passauto_ir_version_conversion=True; on torch before 2.9,to_onnx(opset_version=17)also works. On torch 2.9 and later the IR versions already differed, so the conversion was needed before as well. The default input shape (ONNX_DEFAULT_INPUTSHAPE) is now[-1, 3, -1, -1]instead of[-1, -1, -1, -1], so a call withoutinput_shapeexports a fixed 3-channel input with a dynamic batch, height and width: on torch 2.9 and later the old default failed for any model with a fixed channel count, and on older torch it declared the channel dimension dynamic even where the model fixed it. A channel-agnostic model exported withoutinput_shapeused to accept any channel count and now takes exactly 3. Apseudo_shapegiven withoutinput_shapesets the default's fixed entries, soto_onnx(pseudo_shape=[1, 1, 32, 32])exports a 1-channel input. Passinput_shapefor a dynamic channel count. An explicitinput_shapewhose fixed entries differ from an explicitpseudo_shapenow raisesValueError; theinput_shapeentry used to win silently, so the model was traced with a shape other than the one given.ONNXSequential(..., auto_ir_version_conversion=True)now converts the models to the highest opset among them instead of to 17, so it accepts kornia's own opset-18 exports; on some of them, such as aGaussianBlur2dpipeline, it used to fail withNo Adapter To Version $17 for Pad. (#5244)motion_blurandMotionBlurnow default toborder_type='reflect', andmotion_blur3dandMotionBlur3Dto'replicate'; previously all four zero-padded ('constant'). The zero padding pulled pixels whose kernel reaches past an edge toward0: a constant image came back as low as0.6at the border forkernel_size=5at angle 0 in 2-D and0.667forkernel_size=3at angle(0, 0, 0)in 3-D, and lower at other angles and directions (measured down to0.16in 2-D, forkernel_size=7at angle 120, and0.2in 3-D). A constant image now stays constant, as it does underfilter2d,gaussian_blur2d,box_blurandfilter3d. Passborder_type='constant'to keep the old output.'reflect'needs each spatial axis longer thankernel_size // 2, so a 2-D image with an axis ofkernel_size // 2pixels or fewer now raises at the default border instead of being zero-padded; the 3-D default is'replicate'so that thin volumes (D = 1) still work. On torch releases without a float16 CPUreflection_pad2d/replication_pad3dkernel (2.5.1 among them), float16 CPU input to these four filters now raises at the default, where it used to run with zero padding; passborder_type='constant'(the old behaviour) or'circular'(which needs each axis at leastkernel_size // 2long) there.RandomMotionBlurandRandomMotionBlur3Dkeep their own'constant'default, so their output does not change. (#5246)guided_blurandGuidedBlurnow raise whensubsampleis not a positive integer, andGuidedBlurraises when it is built rather than on its first call: aBaseError("subsamplemust be a positive integer. Got: 0") for0,-1,True,Falseandnumpy.int64(0), and aTypeCheckErrorfor any other value that is not an integer (1.0,0.5,1.5,2.0, a NumPy float ornumpy.bool_,"2",None, a tensor).TypeCheckErroris aBaseError, and since #5233 also aTypeError. Before, with 1-channel guidance,0,-1,False,True,1.0,0.5,numpy.True_,numpy.False_andnumpy.int64(0)ran as no subsampling, and, on images of 8 x 8 and up, a float above 1 ran as that factor whenfloor(floor(H / s) * s)isHandfloor(floor(W / s) * s)isW(2.0andnumpy.float64(2.0)on 8 x 12,1.5on 12 x 12,2.5on 10 x 10) and failed with a broadcastRuntimeErrorat the final blend otherwise; on a tiny image it failed earlier, ininterpolate(1.5on 1 x 10) or in the reflectpad(2.0on 2 x 12). With multi-channel guidance,0,-1,False,numpy.False_andnumpy.int64(0)failed inviewwith aRuntimeError, every float (1.0,0.5,1.5,2.0,numpy.float64(2.0)) failed inviewwith aTypeErroron images of 8 x 8 and up (earlier on a tiny image, as above), andTrueandnumpy.True_ran as1."2"andNoneraised a builtinTypeErrorfromsubsample > 1, and a tensor aTypeErrorfrominterpolate, with either guidance. A call that passed0,-1,False,True,1.0or0.5to mean no subsampling now has to passsubsample=1, and one that passed2.0has to pass2. Positive integers behave as before, NumPy integers included, with one exception:guided_blurnow continues withint(subsample), so a narrow NumPy integer no longer overflows its own dtype in the arithmetic. On NumPy 2,numpy.uint8(2)raisedOverflowErrorwithkernel_size=301(numpy.int8(2)fromkernel_size=129), and with multi-channel guidance failed with anOverflowErroror aRuntimeErrorfromviewon an image of 256 px or more (128 px fornumpy.int8(2)); those calls now work. (#5253)Rt_to_matrix4x4,camtoworld_graphics_to_vision_Rt,camtoworld_vision_to_graphics_Rt,camtoworld_to_worldtocam_Rtandworldtocam_to_camtoworld_Rt, andARKitQTVecs_to_ColmapQTVecs, which calls two of them, now raiseShapeError(aValueError) whenRandthave different batch sizes;disable_checks()turns the check off like the other kornia checks. PreviouslyRt_to_matrix4x4, the two graphics/vision functions andARKitQTVecs_to_ColmapQTVecsfailed insidetorch.catwith torch'sRuntimeError, and the two worldtocam functions broadcast a batch-1 argument:Rof batch 2 withtof batch 1 returned a(2, 3, 3),(2, 3, 1)pose, andRof batch 1 withtof batch 2 returned(1, 3, 3)and(2, 3, 1). Both calls now raise; any other mismatch used to raiseRuntimeErrorfrom the matrix product. (#5265)AugmentationSequentialconverts each NumPy argument by its data key, and onlyinputtakes the image conversion. A NumPy mask keeps its dtype and values: anint64label 3 used to come out asfloat323 / 255, and auint80/255 binary mask asfloat320/1; they now come out asint643 anduint80/255, as the same mask passed as a tensor does. A NumPy mask is still read like a NumPy image,(H, W),(H, W, C)or(B, H, W, C). NumPy boxes, keypoints and class labels, which went through the image conversion and raised, now convert like their tensors, and a dictionary input with NumPy values, which raisedAttributeError, converts too. (#5236) (#5274)rgba_to_rgbkeeps the leading dimensions of its input whenbackground_coloris a tuple or list: a(4, H, W)image used to come back as(1, 3, H, W)and now returns(3, H, W)(#5323).rgb_to_rgba,bgr_to_rgba,RgbToRgbaandBgrToRgbanow raiseValueErrorunless a tensoralpha_valhas the image's shape with one channel,(*, 1, H, W). A multi-channel alpha used to be appended as is, so a(B, 2, H, W)alpha returned a five-channel(B, 5, H, W)image; an alpha whose batch or spatial size differed from the image's failed insidetorch.catwith aRuntimeError. (#5296)lovasz_softmax_loss,LovaszSoftmaxLoss,lovasz_hinge_lossandLovaszHingeLossnow compute the Jaccard weights and the sum over pixels in the dtype of the prediction, or in float32 for a float16 or bfloat16 prediction, and return the loss in the dtype of the prediction, promoted with the dtype ofweightfor the softmax variant (#5289). Previously the Jaccard weights tooktorch.get_default_dtype(): a float16 or bfloat16 prediction returned a float32 loss, a float32 prediction under a float64 default returned float64, and a float64 prediction had float32 rounding in its weights and gradient. Aweightwider than the loss was cast down to it, so a float32 prediction with a float64weightreturned float32; it now returns float64, asdice_lossdoes. Float32 predictions with noweightor a float32weightunder the default float32 are unchanged. (#5303)ssim,ssim3d,SSIMandSSIM3Dnow compute integer images in float32 and return a float32 map, andssim_loss,ssim3d_loss,SSIMLossandSSIM3DLossinherit the fix (#5297). Previously the fractional Gaussian weights truncated to zero, so the result did not depend on the images: the map came back in the integer dtype, all 1 formax_val=255.0and all 0 for the defaultmax_val=1.0, and each loss returned the same constant for every pair. Pixel values are not rescaled, and floating-point inputs are unchanged. (#5304)image_histogram2dnow raisesShapeError(aValueError) for an image that is not(H, W),(C, H, W)or(B, C, H, W). A rank-0 or rank-1 image used to return a histogram with spurious batch and channel axes, of shape(1, 1, n_bins), and a rank-5 or higher image raised aRuntimeErrorfrom insidepermute. (#5320)zca_mean,zca_whitenandZCAWhitening.fitnow raiseValueErrorwhen the sample dimension has fewer than two entries withunbiased=True(the default), or none withunbiased=False. Previously the covariance was divided by zero, and the result was NaNs, an emptyzca_whitenoutput, or atorch.linalg.LinAlgErrorfrom the SVD, depending on the input shape. Whitening one sample withunbiased=Falseis still supported and returns zeros. (#5332)solve_quarticnow solves a row as a cubic only when its leading coefficient is below the tolerance and the scale-invariant root boundmax(|b/a|, |c/a|^(1/2), |d/a|^(1/3), |e/a|^(1/4))exceeds1 / tol, so a quartic whose roots are all below1 / (4 * tol)in magnitude is solved as a quartic at every scale. Rows such as[1e-7, 0, 0, 0, -1]previously returned[0, 0, 0, 0]and now return their real roots±56.23;(x-50)(x-60)(x-70)(x-80)scaled by2^-21in float32 now returns all four roots instead of a single root near 31.5. (#4954) (#5334)ApplyColorMapregisters its palette as the buffercolors, so.to(device, dtype),.half()and.double()move and convert it with the module, andstate_dict()saves it. Previously the palette stayed where itsColorMapwas built: forward on a module moved to MPS or CUDA raised a device-mismatch error, a converted module kept returning the palette's dtype (float32 after.half()or.double()), andstate_dict()was empty. The output now follows the module's dtype, andstate_dict()gains thecolorskey. A state dict saved by an earlier release still loads withstrict=Trueand keeps the palette the module was built with; one saved by this release carriescolorsand failsstrict=Trueon an earlier kornia, which does not know the key.module.colormapstill holds theColorMapas passed and is not moved by.to(). (#5317) (#5335)integral_tensorandIntegralTensornow raise a kornia error for a repeated axis, including a negative alias of a positive one such as(1, -1)on a rank-2 input, and for an axis outside the input's rank. A repeated axis used to be integrated twice (integral_tensor(torch.ones(2, 2), (1, 1))returned[[1, 3], [1, 3]]), and an axis outside the rank raisedIndexErrorfromcumsum. Distinct axes are accepted in any order. (#5336)Boxes.from_tensorwithmode="vertices"ormode="vertices_plus", andVideoBoxes.from_tensor, now reject a non-finite vertex coordinate whenvalidate_boxes=True(the default). Before, the vertex modes ignoredvalidate_boxesand storedNaNandinfvertices; passvalidate_boxes=Falseto keep them. The check istorch._assert_async, so it raisesRuntimeError(the'xy*'modes keep raisingValueError), runs on CPU and CUDA, is skipped on MPS, and keeps the vertex import, and with itAugmentationSequentialwith"bbox"data, compilable withfullgraph=True. The vertex modes still take no extent or shape check, so the rotated, sheared and projective quadrilaterals oftransform_boxesimport unchanged. (#5337)apply_colormapandApplyColorMapmap the top of the input range to the last palette color:1.0for unit-range input and255for integer or byte-range input. Previously, with three or more palette colors, the top of the range selected the second-to-last color, so no input in the documented range reached the last one: the palette[0, 0.25, 0.75, 1]mapped1.0to0.75, and now maps it to1. Every other input keeps its color, so withnum_colors=256auint8valuevnow selects palette colorvfor everyv(255used to select color254). (#5307) (#5339)rgb_to_rawandRgbToRawnow raiseValueErrorfor acfathat is not aCFAmember, asraw_to_rgbandraw_to_rgb_2x2_downscaledalready did. Previously any other value, such as a string, an integer orNone, silently returned the green channel as the mosaic. (#5340)RgbToHsvnow defaults toeps=1e-8, the default ofrgb_to_hsv, so the module and the function return the same saturation. The module used to default toeps=1e-6, which lowered the saturation of dark pixels: a pure red pixel of value1e-4had saturation0.9901through the module and0.9999through the function; both now give0.9999. PassRgbToHsv(eps=1e-6)to keep the old module output. (#5343)adjust_hue_rawnow wraps the shifted hue into [0, 2π), matchingrgb_to_hsv. A negative sum used to stay negative: hue 0 shifted by -0.5 returned -0.5, and now returns 2π - 0.5. A sum that rounds up to 2π returns 0.adjust_hueoutput changes only by rounding. (#5345)histogram,histogram2dandimage_histogram2dnow reject a bandwidth that is zero, negative or not finite, andimage_histogram2dalso rejectsn_bins < 1and an empty or non-finite[min, max]range when it builds the centers or the bandwidth from them. These inputs used to return NaNs or meaningless values, or a low-level error (n_bins=0raisedZeroDivisionError);histogramandhistogram2dreturned the same result for a negative bandwidth as for its absolute value.histogramandhistogram2dnow raiseRuntimeErrorfrom an asynchronous check, like the other tensor-parameter checks inkornia.enhance(skipped on MPS);image_histogram2draisesValueError.image_histogram2dnow treats its documentedbandwidth=-1as the automatic bandwidth, where it used to apply -1 as a literal negative bandwidth, and an emptycenterstensor as automatic centers, where it used to return zero bins. (#5347)filter2d,filter3d,filter2d_separableandfft_convnow raise aBaseErrornaming both sizes when the kernel batch is neither 1 nor the input batch (#5154). Inputs that used to return a value now raise:filter2d,filter2d_separableandfilter3dapplied a kernel batch that divides the input batch cyclically, sampleifiltered with kerneli % Bk, andfft_convbroadcast one input sample over a batch of kernels, one output per kernel. The same holds for the blurs that build one kernel per sample:gaussian_blur2dwith a tensorsigma, andmotion_blurandmotion_blur3dwith tensorangleanddirection, whose batch divides the input batch. The other kernel batches used to raise torch'sRuntimeErrorand now raise theBaseError, which is not aRuntimeError. The documented(1, kH, kW)and(B, kH, kW)kernels are unchanged. (#5359)shift_rgbnow raisesShapeErrorfor input that is not(B, 3, H, W). It used to accept any input with three channels at axis -3 and broadcast the(B, 3, 1, 1)shifts against its leading axes without an error: a(B, T, 3, H, W)input received the per-batch shifts alongTinstead ofB, and a(3, H, W)input came back as(B, 3, H, W), one copy per shift.RandomRGBShiftalways passes(B, 3, H, W)and is unaffected. (#5360)image_histogram2dnow keeps the bin axis for rank-2(H, W)input with a single bin (n_bins=1or one explicit center): the histogram and the PDF have shape(1,), the documented(bins,). They used to be 0-d tensors, because the synthetic batch and channel axes were removed with an unrestrictedsqueeze()that also dropped the length-one bin axis. Rank-3 and rank-4 input and rank-2 input with more than one bin are unchanged. (#5366)get_gaussian_discrete_kernel1dnow returnskernel_sizetaps and rejects an evenkernel_sizewithforce_even=True(#5158). Previously it returned2 * (kernel_size // 2) + 1taps and never fewer than 3:kernel_size=1gave 3 taps andkernel_size=4withforce_even=Truegave 5.kernel_size=1is now the single tap[1.0], and an even size raises aBaseError, because the discrete Gaussian is defined at integer offsets from the centre tap.get_gaussian_erf_kernel1dwithforce_even=Truenow centres an even kernel on the middle of the window,(kernel_size - 1) / 2, asget_gaussian_kernel1ddoes; previously it was centred on tapkernel_size // 2, so(4, 1.0)gave[0.0654, 0.2608, 0.4131, 0.2608]and now gives[0.1424, 0.3576, 0.3576, 0.1424]. Odd sizes above 1 are unchanged in both builders. (#5376)filter2dandfft_convnow pad forpadding='SAME', and for every other spelling of'same'(#5156), and so dofilter2d_separable,correlate2dandconvolve2d, which passpaddingtofilter2d. Previously the padding check accepted any spelling but only'same'took the padded branch, sopadding='SAME'silently returned the'valid'-size output: a 3×3 kernel on a 5×7 image gave 3×5 and now gives 5×7, the output ofpadding='same'.'VALID'still crops, and lower-case calls are unchanged. (#5379)denormalizeandDenormalizeused to accept a(C,)mean or std whose length matched dimension -3 of a rank-3 or rank-5 input instead of its channel count, and broadcast a 1-channel input to C channels (a(2, 1, 4, 2, 2)input with 4-element statistics returned a(2, 4, 4, 2, 2)tensor). They now raiseValueErrorfor that input, asnormalizedoes. (#5384)bilateral_blur,joint_bilateral_blur,BilateralBlurandJointBilateralBlurnow raise a kornia error for asigma_colorthat is not positive, andedge_aware_blur_pool2dandEdgeAwareBlurPool2Dnow require anedge_thresholdgreater than 1 (#5169). Previously a tensorsigma_colorof zeros returned an all-NaN image and a negativesigma_colorblurred exactly like its absolute value. Anedge_thresholdbelow 1 marked every pixel as an edge and returned the input unchanged, and exactly 1 counted any difference between pixels 4 apart as an edge. Undertorch.compilea tensorsigma_coloris not checked, like the tensorsigmaofgaussian_blur2d. Positivesigma_colorvalues and thresholds above 1, including the default 1.25, are unchanged. (#5387)Sepia()andsepia_from_rgbwith the defaultrescale=Truenow divide all three output channels by one maximum per image, taken over channels and pixels, so the sepia tint survives the rescale. They used to divide each channel by its own spatial maximum, which made the output almost grey: a uniform 0.5 grey image used to give(1.0, 1.0, 1.0)and now gives(1.0, 0.8905, 0.6936). Default outputs change for every image;rescale=Falseis unchanged. (#5388)AugmentationSequentialconverts a mask given as a PIL image or an image file path like the same mask passed as a NumPy array, keeping its dtype and label values. A modeLlabel 3 used to come out asfloat323 / 255 and now comes out asuint83; a palette (modeP) mask used to be replaced by its RGB colours scaled to[0, 1],(1, 3, H, W), and now keeps its indices,(1, 1, H, W). A file-path mask, and a PIL mask in a dictionary input, raisedAttributeErrorand now convert. A mask whose height and width differ from the image's, or whose batch size is neither 1 nor the image's, now raisesValueError; it used to pass unchecked, so a NumPy(B, H, W)label batch was silently read as one(H, W, C)image. (#5291) (#5390)A nested
AugmentationSequentialnow records its transformation matrix under its owntransformation_matrix_modewhen it runs inside another container. A nested container built withtransformation_matrix_mode="rigid"therefore raisesRuntimeErrorfor a non-rigid child, as it does when called directly; it used to run without the check. (#4476) (#5391)The deprecated
gaussian_blur2d_t,get_gaussian_kernel1d_t,get_gaussian_kernel2d_t, andget_gaussian_kernel3d_taliases have been removed; usegaussian_blur2d,get_gaussian_kernel1d,get_gaussian_kernel2d, andget_gaussian_kernel3dinstead. (#5400)otsu_thresholdandOtsuThresholdnow histogram each image/channel plane over its own range, so a plane's threshold no longer depends on the other images and channels in the call (#5172). Previously one range was shared by the whole input. The default histogram path now returns the upper edge of the selected bin,min + (t + 1)·(max − min)/nbins. Previously it readlinspace(min, max, nbins), a threshold up to one bin above the split, which atnbins=2was always the maximum, so nothing was kept. For an integer input the threshold is now the largest integer below that edge. Previously it was truncated toward zero, so a negative edge rounded up and an edge on an integer stayed put, and the level just above the split was dropped from the foreground. A constant plane now uses its own value as the threshold, so none of its pixels is foreground. Previously its threshold was 0. Theslow_and_differentiable=Truepath also uses each plane's own range and the same integer rounding. (#5402)kornia.enhance.denormalizeandDenormalizereturn torch's default floating dtype (float32 unless changed withtorch.set_default_dtype) for an integer or bool input, asnormalizealready did. They used to compute in and return the input's integer dtype, which was exact for integral statistics that did not overflow:denormalizeof a uint8[0, 50, 100]withmean=10.0, std=2.0returned uint8[10, 110, 210]and now returns float32[10.0, 110.0, 210.0]. Both functions now convert an integer input before applyingmeanandstd, so under the default float32 an integer value above 2**24 is rounded first. Cast the result back, for example with.round().clamp(0, 255).to(torch.uint8), where integer output is needed. (#5407)apply_colormapandApplyColorMapno longer choose the input range from the maximum over the whole tensor. Integer inputs always use[0, 255]: previously an integer tensor whose maximum was at most 1, such as a{0, 1}mask, was divided by 1 and mapped to the full palette, and now1maps to the palette entry for 1/255. Floating-point inputs choose[0, 1]or[0, 255]separately for each sample and channel: previously one sample or channel above 1 made every other sample and channel of the tensor use[0, 255]. Refs #5306. (#5413)So2.hat/So2.veeandSe2.hat/Se2.veenow use the standard Lie algebra generators.So2.hat(theta)used to return the symmetric[[0, theta], [theta, 0]]andSo2.veeread its[0, 1]entry; it now returns[[0, -theta], [theta, 0]]andveereads[1, 0].Se2.hat(v)used to put(v_x, v_y)in the bottom row below that symmetric block; it now returns[[0, -theta, v_x], [theta, 0, v_y], [0, 0, 0]], andSe2.veereads the translation from the last column.vee(hat(v))is still the identity, andmatrix_exp(hat(v))now equalsexp(v).matrix(), as it already did forSo3/Se3. Code that builds or reads these matrices in the old layout gets different values. (#5414) (#5414):class:
~kornia.geometry.camera.pinhole.PinholeCameraprojectandunprojectnow build their projection matrix from the top-left 3x3 block ofintrinsicsonly (#4771). A 3x3Kzero-padded to 4x4 (intrinsics[3, 3] = 0) used to project whileunprojectraisedLinAlgErroron the singular 4x4 product; it now round-trips exactly like its homogeneous embedding. The other entries of the 4x4 no longer enter either method: before, a non-zerointrinsics[0, 3]shifted every projectedubyintrinsics[0, 3] / z(withK = [[100, 0, 4], [0, 100, 3], [0, 0, 1]]andintrinsics[0, 3] = 10, the point(1, 2, 4)projected tou = 31.5, now29), andintrinsics[3, 3] = 2doubled every pointunprojectreturned. Intrinsics in the documented homogeneous form give the same results as before, bit for bit on CPU. (#5415)otsu_thresholdandOtsuThresholdwithslow_and_differentiable=Truenow return a threshold with a gradient with respect to the input, and return different threshold values:- The threshold now has a gradient. Its value is the hard Otsu split of the path's histogram, and its gradient is a
straight-through surrogate: the gradient of a soft-argmax over the between-class variance curve of a wider kernel
density estimate, with a standard deviation of 0.5 bin, at a temperature relative to the curve, so it does not depend
on the intensity scale of the input. The threshold used to have no gradient. The thresholded image is still
x * (x > threshold), whose gradient is that mask. - The histogram is now the mass that a Gaussian kernel density estimate with a standard deviation of 0.1 bin puts in
each of the
nbinsbins, so every pixel contributes its full mass. The estimate used to be sampled atnbinspoints with a fixed bandwidth of1e-3in input units, which missed every pixel more than a few1e-3away from a sample point, most pixels at smallnbins. The thresholds change accordingly, and are usually within one bin of the default path's. - The threshold is now read with the default path's bin-edge convention: the upper edge of the selected bin among
nbinsequal bins over the plane's range, or for an integer input the largest integer below that edge. It used to be read from thenbinssample pointslinspace(min, max, nbins), up to one bin above the split. As on the default path, a floating-point threshold is kept at or above the largest background pixel and below the smallest foreground pixel, sox > thresholdreproduces the split. - Of splits that give the same partition, the lowest is now taken on every device: a bin counts as non-empty only above 1 % of one pixel's mass. The kernel tails used to give empty bins a tiny positive mass, the rounding of the cumulative sums chose between equivalent splits, and CPU and MPS could return different thresholds for the same input.
- The path no longer calls
.item(), so it supportstorch.exportand compiles withfullgraph=True. - The slow path now computes its surrogate on the plane shifted by its minimum and divided by its range, or by its largest magnitude when the range overflows, and cancels this normalization from its first-order gradient. Higher-order derivatives through this normalization do not represent the original-unit soft threshold. Finite inputs near the dtype limits or with tiny ranges keep finite thresholds and gradients; hard edges whose range would overflow or whose bin width would underflow are reconstructed in bounded units as well.
(#5426)
- The threshold now has a gradient. Its value is the hard Otsu split of the path's histogram, and its gradient is a
straight-through surrogate: the gradient of a soft-argmax over the between-class variance curve of a wider kernel
density estimate, with a standard deviation of 0.5 bin, at a temperature relative to the curve, so it does not depend
on the intensity scale of the input. The threshold used to have no gradient. The thresholded image is still
bilateral_blur,joint_bilateral_blur,BilateralBlurandJointBilateralBlurnow raise a kornia error when an input of batch 1 is given a tensorsigma_colororsigma_spacewith a larger batch (#5430). Previously the broadcast succeeded silently and returned a batch as large as the sigma batch, for example 3 images from 1 input and 3sigma_colorvalues. A sigma batch of 1, or equal to the input batch, is unchanged. (#5432)The default (
slow_and_differentiable=False) path ofotsu_thresholdandOtsuThresholdreturns different thresholds, and for floating-point input sometimes different masks:- Of the splits across a run of empty histogram bins, which all give the same classes, the lowest is now taken on every device. On MPS with torch 2.14, cumulative-sum rounding used to pick a later split, so the threshold differed from the CPU's (for example 0.4766 instead of 0.4000) while the mask was the same.
- A floating-point threshold is now kept at or above the largest pixel of the background bins and below the smallest
pixel of the foreground bins, so
x > thresholdreproduces the histogram split. The threshold used to be the bin edge itself, in the input dtype: a pixel exactly on the edge, or on a half-precision edge that rounded up onto it, was dropped from the foreground although the histogram counted it there, and a pixel the histogram counted in the background could lie above the interpolated edge and be kept. Thresholds that already separated the classes stay at the bin edge, although the batched edge computation can differ from the previous per-planetorch.linspacein the last bit (seen on MPS in float32). On MPS, a zero foreground boundary in float32 or bfloat16 gives the threshold-torch.finfo(dtype).tiny, because MPS comparisons flush subnormal values to zero. - A plane containing NaN or an infinite value used to raise
RuntimeErrorfromtorch.histc. It now returns a NaN threshold and an all-background mask for that plane; the other planes are unaffected.
(#5441)
Quaternionnow registers plain tensor data as a persistent buffer, preserving autograd history and explicitly suppliednn.Parameterinputs at construction. Previously, plain tensor rotations were omitted from module state;Quaternion,So3andSe3now save and restore them and follow enclosing module device/dtype conversions. This adds_data,_q._dataand_rotation._q._datacheckpoint keys, respectively. Older checkpoints missing these keys now fail withstrict=True;strict=Falsereports the missing keys and retains the target's initialized rotation, which must be supplied separately if needed. (#5446)ImageModule,ImageSequentialandAugmentationSequentialwith parameters or buffers now convert NumPy, PIL and image-path inputs onto the device of their first parameter (or first buffer) and the dtype of their first floating parameter or buffer. Previously a converted image was always created on the CPU, in the default dtype for an integer image and in its own dtype for a floating one: a module moved to CUDA or MPS raised a device-mismatch error, or returned a CPU output when its forward did not touch its state, and afloat64NumPy image fed to afloat32module gave afloat64output where it now givesfloat32. NumPy masks, keypoints and boxes given toAugmentationSequentialmove to the same device and keep their dtype. Stateless modules, tensor inputs and the standalone mixin are unchanged. (#5451)Resize,LongestMaxSize,SmallestMaxSizeand slice-modeRandomResizedCropwithresample="nearest"now resize with PyTorch'snearest-exactgrid, which copies source columnfloor((u + 0.5) * W_in / W_out)into output columnu, and record the matching half-pixeltransform_matrix,x' = (x + 0.5) * W_out / W_in - 0.5(likewise fory). Previously they copied the legacyfloor(u * W_in / W_out)column and recorded a corner-to-corner matrix that the image did not follow, so keypoints and boxes landed up to one output pixel away from the pixels they belong to (#5293). Nearest-resized images and the recorded matrices change. So do masks resized by these augmentations inAugmentationSequential, which resamples masks with nearest even when images use bilinear. (#5458)safe_inverse_with_maskandsafe_solve_with_maskno longer turn the gradient NaN when one matrix in the batch is singular. Validity is decided on a detached pass and the invalid matrices are replaced by the identity before inverting or solving. An invalid row used to hold NaN in eager mode (a finite adjugate under tracing or export); it now holds the identity inverse (orBfor the solve) in every mode. A float16 inverse that overflows is now reported invalid instead ofinfwithmask=True.find_homography_dlt,find_homography_dlt_iterated,find_homography_lines_dltandfundamental_from_essentialstill return NaN for degenerate input. (#5459)quaternion_exp_to_logandeuler_from_quaternionnow normalize their input (#3953), matchingquaternion_to_rotation_matrixandquaternion_to_axis_angle, so a rescaled quaternion gives the same result as the unit one. Unit inputs are unchanged to rounding; non-unit inputs that used to return a wrong value without error now return the value of the rotation they stand for. Before,quaternion_exp_to_log([0.5, 0.5, 0, 0])returned[1.0471975511965976, 0, 0]; it now returns[0.7853981633974483, 0, 0]. Before, a scalar partw > 1was clamped to1, soquaternion_exp_to_log([2, 1, 0, 0])returned the origin; it now returns[0.4636476090008061, 0, 0]([2, 0, 0, 0]still returns the origin, the log of the identity). Before,euler_from_quaternionof2 * q, for theqof(0.3, 0.7, 1.1), returned[1.6560585860248003, 1.5707963267948966, 2.1048169977173687], a pitch of exactlypi/2; it now returns(0.3, 0.7, 1.1).quaternion_exp_to_logcomputes the angle asatan2(||v||, w), which needs no clamp and has a finite derivative atw = +-1. (#5461)A shape-changing augmentation such as
RandomCroporResizegiven a hand-madebatch_probthat mixes applied and skipped rows now raisesValueError, inforwardand ininverse. Before,forwardtransformed the skipped rows too, andinversefailed with a shape mismatch.kornia.contrib.augmentation_audit.auditraises the sameValueErrorfor such a step; before, it returned a report for it. (#5473)motion_from_essential_choose_solutionnow returns a fourth value, the number of correspondences at positive depth in both cameras for the selected pose candidate, with shape(B,)(a 0-d tensor for unbatched inputs), as OpenCV'srecoverPosedoes (#4879). Previously it returned(R, t, points3d), and when no correspondence passed the depth test (for example withmaskallFalse) it returned candidate 0 with nothing to tell the caller. It now returns(R, t, points3d, num_valid), andnum_valid == 0flags that case. Code that unpacks three values,R, t, X = motion_from_essential_choose_solution(...), must unpack four. (#5475):meth:
~kornia.geometry.camera.pinhole.PinholeCamera.intrinsics_inverse, :class:~kornia.geometry.depth.DepthWarperand :func:~kornia.geometry.depth.depth_warpnow read only the top-left 3x3 block ofintrinsics, likeprojectandunprojectsince #5415 (#5480). A 3x3Kzero-padded to 4x4 (intrinsics[3, 3] = 0) used to raiseLinAlgErrorin all three;intrinsics_inversenow returns the homogeneous 4x4 embedding ofinv(K), and the warp equals the one for the homogeneous embedding. The other entries of the 4x4 no longer enter: withK = [[100, 0, 4], [0, 100, 3], [0, 0, 1]],intrinsics[0, 3] = 10used to giveintrinsics_inverse()[0, 3] = -0.1(now0) and, on the destination camera, shifted everyDepthWarpersampling position by10 / zpixels;intrinsics[3, 3] = 2used to giveintrinsics_inverse()[3, 3] = 0.5(now1) and, on the source camera, doubled the depth the warp unprojects. Intrinsics in the documented homogeneous form give the same results as before, bit for bit on CPU. (#5485)RandomCrop(cropping_mode="slice")now places bounding boxes and keypoints on the half-pixel grid of the slice resize when the requested crop exceeds the padded input along an axis,x' = (x + 0.5) * s - 0.5for the stretchs(#5481). Previously the transform matrix scaled about the origin,x' = s * x, so annotations sat0.5 * (s - 1)pixels before the image content along that axis: 0.132 pixels at a 416 / 329 stretch and 0.5 pixels at a 2x stretch. Axes that fit, resample mode and the image itself are unchanged. (#5487)safe_inverse_with_maskandsafe_solve_with_masknow decide the singularity of 2x2, 3x3 and 4x4 matrices by one rule in eager mode and under capture alike, the closed-form determinant against the permanent of the absolute values,|det A| <= 8 n eps perm |A|(#5476). Previously the mask came from LAPACK'sinfoin eager mode and fromdet != 0under capture, so a 3x3 with two equal rows was valid on torch 2.5.1 eager and undertorch.jit.traceand invalid on torch 2.14 eager. A matrix whose determinant is rounding noise is now invalid everywhere, whatever its scale, and_torch_inverse_castdocuments that it does not check singular input. (#5488)get_motion_kernel2dwithmode="nearest", and with itmotion_blur,MotionBlurandRandomMotionBlur, used to let roundoff pick the tap where the rotated line falls exactly between two taps (some multiples of 30 degrees), so the kernel changed with the dtype, the device, the torch version,torch.compileand a full turn added to the angle. The tie now goes to the even coordinate, asgrid_samplebreaks it with exact arithmetic, so at those angles the CPU float32 kernel can differ from the one it used to be:get_motion_kernel2d(5, 330.0, 0.3)gives other taps than before. A nearest kernel still has a zero gradient in the angle. (#5497)get_motion_kernel3dwithmode="nearest", and with itmotion_blur3d,MotionBlur3DandRandomMotionBlur3D, used to let roundoff pick the tap where the rotated line falls exactly between two taps (a pitch or roll that is a multiple of 30 degrees), so the kernel changed with the dtype: float32 and float64 built different kernels at 6 of the 1000 angles of a 10-value grid, by up to 0.16 (#5510). The tie now goes to the even coordinate, asgrid_samplebreaks it with exact arithmetic, so at those angles the float32 kernel can differ from the one it used to be:get_motion_kernel3d(5, (0.0, 330.0, 0.0), 0.3)keeps 7 taps where it used to keep 5. A nearest kernel still has a zero gradient in the angle. (#5516)VideoSequential(same_on_frame=False)now draws separate parameters for every frame in a nested container, such as anImageSequential, as it already did for augmentations placed in it directly. It used to draw one set per video. With a single video, every frame got that same set. With several videos, the call raised, for examplegrid_sampler(): expected grid and input to have same batch sizeforRandomAffine, or a flip gave every frame of every video the same result. A nestedRandomCropraisedIndexErrorin both cases. (#5518)bilateral_blur,joint_bilateral_blur,BilateralBlurandJointBilateralBlurused to return a wider dtype than a floating input when a tensorsigma_spaceor theguidancewas wider, for example float64 for a float32 image with a float64sigma_space, or float32 for a float16 image with a default float32sigma_spacetensor. Both are now cast to the input's dtype, as a tensorsigma_coloralready was, so the output keeps the input's dtype. (#5524)psnr,psnr_lossandPSNRLossnow compute integer and bool images in float32, asssimdoes, and compare the two images in their promoted dtype (#5536). Two integer or bool images give the value of their float32 copies as a float32 tensor. Previously they raised torch's dtype error, except on MPS with torch 2.5.1, whereuint8,int16,int32andboolpairs returned wrong values andint64aborted the process. An integer image paired with a float16 or bfloat16 image now gives a float32 result; previously the result was in the half dtype. Two images of different dtypes no longer abort the process on MPS. Pixel values are not rescaled, and two floating-point images of one dtype are unchanged. (#5552)ssim,ssim3d,SSIM,SSIM3D,ssim_loss,SSIMLoss,ssim3d_lossandSSIM3DLossnow readpaddingcase-insensitively and reject any other value, as the filters do (#5537). Previously every value other than'valid'silently took the'same'branch.padding='VALID'or'Valid'returned the uncropped map, so a 5-pixel window on a 13×17 image gave 13×17 and now gives 9×13, the output ofpadding='valid', and the losses now use that cropped map. A misspelling such as'full'or'bogus'returned the'same'map and now raises kornia'sInvalid padding modeerror, which names the accepted options.'same','valid'and the case variants of'same'are unchanged. (#5553)kl_div_loss_2dandjs_div_loss_2dnow raiseNotImplementedErrorfor areductionoutside'none','mean'and'sum', and check thatpredandtargetare 4-D(B, N, H, W)tensors of the same shape (#5535). Before, any other reduction, torch's'batchmean'andNoneincluded, silently returned the'sum', B · N times the'mean'value; kornia's'mean'is torch's'batchmean'on the(B · N, H · W)reshape. Before,kl_div_loss_2dalso read apredof another shape with the same number of elements, such as one with H and W swapped, in the layout oftargetand returned a value; it now raisesBaseError. Shape mismatches that already failed now raise kornia'sBaseError, orShapeErrorfor an input that is not 4-D, instead of torch'sRuntimeErroror a bareValueError. (#5555)mean_average_precisionnow computes the average precision of integer boxes in float32, and that of two box sets of different dtypes in their promoted floating dtype, with integer boxes counting as float32 as inmean_iou_bbox(#5551). Previously integer boxes raised torch'smean(): could not infer output dtype, and box sets of two floating dtypes kept the TP/FP counts and the result in the prediction dtype and the precisions in the ground-truth dtype: float16 predictions with float32 ground truth returned 0.8486 in float16 where float32 boxes give 0.8485, and they now return that float32 value. Boxes of one floating dtype give the same result as before. A mismatch of the five list lengths, or of the box, label and score counts, now raises kornia'sBaseErrornaming the lengths or counts instead of a message-lessAssertionError, so code that catchesAssertionErrorthere must catchBaseErrorinstead. (#5556)ssim3d,SSIM3D,ssim3d_lossandSSIM3DLossnow reflect the volume at its faces forpadding='same', asssimdoes for images (#5534). Previously they replicated the border, so a stack of identical slices did not reproduce the 2-D map near the faces, by up to 0.61 on random data.'same'results change withinwindow_size // 2voxels of every face; the border does not reach'valid'results. A volume whose depth, height or width iswindow_size // 2or less used to return a'same'map and now raises torch's padding error, asssimdoes for such images. Complex volumes, for whichssim3dreturned a complex map, now raise the error thatssimraises for complex images, because the window is built in the input dtype: aNotImplementedError, or a plainRuntimeErroron torch 2.5.1. (#5560)dice_loss,tversky_loss,DiceLossandTverskyLossnow require atargetof shape(B, H, W)for apredof shape(B, C, H, W)and raiseValueErrorotherwise (#5544). They used to compare onlyHandW, and some mismatched targets returned a value: with a(1, H, W)target forB > 1,tversky_lossreturned the loss of sample 0 alone anddice_lossbroadcast the target over the batch; withB = 1,dice_lossaveraged the prediction's loss over a larger target batch and returned a wrong loss for a(1, 1, H, W)target. Callers that relied on the broadcast must expand the target themselves. Most other mismatches ended in torch'sRuntimeError; they now raiseValueErrortoo, whichexcept RuntimeErrordoes not catch. (#5561)HausdorffERLoss3Dnow validates its target asHausdorffERLossdoes:targetmust betorch.longwith every label in[0, C), otherwise it raisesValueErrornaming the accepted range (#5545). The 3-D loss used to check only that no label exceededC. It returned a loss for float targets and for integer targets other thantorch.long, such asint32oruint8(the right loss when every label was a whole number in[0, C)), and it silently dropped voxels labelled-1,Cor a fractional value from every class map. These targets now raise. A label aboveCused to raiseValueError("Invalid target value.")and now raises the range message. (#5562)dice_loss(average="micro", weight=w)andDiceLoss(weight=w)now weight the intersection once, computing the weighted Dice2 Σ w p t / Σ w (p + t). They used to square the weight in the intersection, so a uniform weight scaled the Dice coefficient (a perfect prediction scored -1 withweight=2) and non-uniform weights could push the loss below -1. Weighted"micro"losses with weights other than 0 and 1 change value. Unweighted, 0/1-weighted and"macro"losses are unchanged. (#5564)confusion_matrixandmean_iounow requirepredandtargetto be integer orbooltensors with values in[0, num_classes), and form the cell index inint64(#5549). Previously the labels were not checked: an out-of-range prediction was counted silently in another cell (with 3 classes, a prediction of 3 for target 0 counted as target 1 / prediction 0), and it now raisesBaseErrornaming the offending range, as an out-of-range target does instead of a raw torch error. A list now raisesTypeErrorinstead ofAttributeError, and a float tensorBaseErrorinstead of a raw torch error. Small integer label maps now give the matrix of theirint64copy. The index used to wrap in the label dtype:uint8maps from 17 classes, so a perfectuint8prediction with 21 classes reported an IoU of about 5e-7 for two classes that do not occur, andint8maps from 12 classes andint16maps from 182, into another cell or a rawbincounterror. Thenum_classesmessage now says "at least two". (#5565)ssim3d_lossandSSIM3DLossnow compute the documented structural dissimilarityclamp((1 - SSIM) / 2, 0, 1), the formssim_lossuses (#5533). Previously they returned the unclamped1 - SSIM, twice the 2-D loss on matched content and above 1 on anti-correlated content. A caller who wants the old value can reduce1 - kornia.metrics.ssim3d(...). (#5567)kornia.metrics.confusion_matrix(normalized=True)now divides each row (target class) by its sum, so every non-empty row sums to 1: the per-class recall, scikit-learn'snormalize='true', as in torchnet'sConfusionMeter, which the code cites (#5550). Previous releases divided each column (predicted class) by its sum, scikit-learn'snormalize='pred': for targets[0, 0, 0, 1, 1, 2, 2, 2]and predictions[0, 0, 1, 1, 1, 2, 2, 0]the rows summed to 1, 0.6667 and 1.3333, and now each sums to 1. Empty rows stay zero, and the1e-6added to each sum is unchanged. For the previous column normalization, computecm / (cm.sum(dim=1, keepdim=True) + 1e-6)from the unnormalized(B, K, K)matrixcm. (#5568)The mutual information losses (
mutual_information_loss,normalized_mutual_information_loss, their_2dand_3dforms and theMILossFromRef*andNMILossFromRef*modules) now normalise each signal onto the bin centres0 … num_bins - 1, so every sample contributes to the histogram and the result no longer depends on the intensity polarity (#5546). Previously the signals were normalised onto[0, num_bins], one bin width past the last centre, so with the defaultMIKernel.xuthe pixels at an image's maximum got no histogram weight, and the other two kernels gave them only part of it: in float64 a binary mask had mutual information 2.4e-13 with itself instead of its entropy, and normalised mutual information 1.77 instead of 2. Integer images with levels0 … Know sit on the bin centres withnum_bins=K + 1, notnum_bins=K. Every value changes, a little on continuous images and a lot on binary, label or saturated images. (#5569)kornia.losses.one_hotnow returns the exact one-hot tensor in the requesteddtype:epsdefaults to 0 and is applied only when it is non-zero, and a non-zeroepswith an integer or booldtyperaises (#5538). Previously every zero waseps = 1e-6, each pixel summed to1 + (C - 1) * eps, and an integer or booldtypecame back as float32.dice_lossandfocal_lossbuild their targets with it, so their values lose the eps terms: the macro Dice loss of a perfect prediction of a 256 × 384 image with a one-pixel class is now 0 instead of 0.0234, and the non-target entries offocal_loss(reduction='none')are 0 instead of1e-6times the class term. Code that takes a log of the output ofone_hotnow needs its own floor, or can passepsexplicitly.dice_lossbuilds its target in float32 for float16 and bfloat16 input, so the float16 gradient of a class absent from a sample stays finite without the floor, including on the few-pixel images where it was NaN before. (#5571)kornia.image.tensor_to_imagenow maps a one-channel(1, H, W)tensor to(H, W)for every H and W:(1, 1, W)gives(1, W),(1, H, 1)gives(H, 1)and(1, 1, 1)gives(1, 1), with eitherkeepdim. They used to come out as the 1-D arrays(W,)and(H,)and a 0-d array, because the 3-D branch squeezed every unit axis, so a 1-row and a 1-column image could not be told apart; code that indexed the 1-D result now gets the 2-D array.kornia.io.write_image, andImageModuleMixIn.save()through it, now saves a 1-row or 1-column grayscale image like any other, where it used to raise aTypeErrorfrom the encoder (anIndexErrorfor(1, 1, 1)) (#5570). (#5572)ssimandSSIMnow raise torch's error for building the Gaussian window in a complex dtype when one image is real and the other complex, in either order (#5574): aNotImplementedError, or a plainRuntimeErroron torch 2.5.1. Previously a realimg1with a compleximg2returned a complex map, while a compleximg1or two complex images raised that error.ssim_lossandSSIMLossalready raised for such pairs. (#5578)mean_average_precisionnow checks in every image that the boxes, labels and, for detections, the scores have one row each, and raisesBaseErrornaming the image and its counts otherwise (#5580). Previously only the totals over all images were compared, so mismatches that cancelled over the images passed the check and the boxes were paired with the wrong image, which returned a wrong mAP with no error: in the issue's two-image example 0.5455 instead of an error. Input whose counts agree in every image gives the same result as before. (#5582)dice_lossandDiceLosswithaverage="macro"now exclude classes with no non-ignored target pixel in each sample, and drop their weights from both the numerator and the denominator of the weighted mean. Previously, each absent class entered the mean as loss 1, so the loss grew when extra class channels were added. Micro averaging and samples containing every class are unchanged. Samples with all pixels ignored, or whose present classes all have weight 0, keep a loss of 1. (#5590)The mutual information losses (
mutual_information_loss,normalized_mutual_information_loss, their_2dand_3dvariants and theMILossFromRef/NMILossFromRefmodules) now validate their arguments (#5548). Inputs that used to return a value now raise kornia'sBaseError: an integer mask (anint640/1 mask indexed positions 0 and 1 and gave MI 0); a mask that is not shaped like one sample,(N,),(H, W)or(D, H, W)(a(W, H)mask on(H, W)images was read in row-major order, a flat(H·W,)mask on the_2dform was accepted, and a one-element or 0-dTruemask on the flat form meant no mask); masks whose intersection is empty (disjoint masks gave MI 0 and an NMI loss of -1); anum_binsthat is not anintof at least 2 (1gave 0, and floats such as2.5or16.0and NumPy integers ran); and a negativewindow_radius. The functions raiseShapeErrorwheninputandtargetdiffer in shape, and the_2d/_3dmodules raiseBaseErrorwhen the compared image differs from the reference: a(W, H)target against an(H, W)input used to be flattened first and return a value. Errors that used to come from torch or Python now come from kornia too: float masks, empty masks, batched masks,window_radius=0(ZeroDivisionError) and a size mismatch in the_2d/_3dmodules raiseBaseError, so code that caught theValueErrorof a batched flat mask or of that size mismatch must catchBaseError. Akernel_functionthat is not anMIKernelmember raises the documentedValueErroron every Python version instead ofTypeErrororAttributeError. Non-contiguous masks are accepted,uint8masks keep working without torch's deprecation warning, andMIKernel.rectangularkeeps the input dtype: float64, float16 and bfloat16 inputs returned a float32 loss computed in float32. Calls with boolean masks and thexuortruncated_gaussiankernels return the same values as before, bit for bit. (#5591)RandomTransplantationinsideAugmentationSequentialnow returns a batched(B, H, W)mask as(B, 1, H, W), like every other child withoutkeepdim=True. Previously it returned the mask as given, so a pipeline whose only child is the transplant, or whose transplant runs after a child withkeepdim=True, returned(B, H, W). With the container'skeepdim=Truethe mask stays(B, H, W). A mask of the wrong rank is now refused with "Every segmentation mask must have one fewer dimension ... than the image" instead of "Every image input must have one additional dimension ...". (#5592)mean_average_precisionnow averages only the foreground classes that have ground-truth objects in the evaluated images, as COCO does (#5540). Previously a class without ground truth entered the mean as AP 0, with or without detections, so mAP depended onn_classes: two perfect detections gave 1.0 withn_classes=3, 0.667 with 4 and 0.5 with 5, and now give 1.0 for each. The dictionary entry of such a class is now-1.0(undefined, as in COCO) instead of0.0, and when no foreground class has ground truth the mAP is-1.0instead of0.0(nanwithn_classes=1). A class with ground truth but no detection still contributes AP 0, and class 0 is still excluded as background. A predicted or ground-truth label outside0 <= label < n_classesused to be skipped silently and now raises kornia'sBaseError. (#5593)tversky_lossandTverskyLossnow compute true positives, false positives and false negatives per class and average over classes present in each sample's non-ignored target. Previously, pooling across classes made false-positive and false-negative mass equal, soalphaandbetaacted only through their sum. Coefficient splits with the same sum now give different losses;alpha=beta=0.5corresponds to macro Dice with exact targets and twice the denominator epsilon, rather than micro Dice. Fully ignored samples retain loss 1 and zero gradients. Half-precision inputs use float32 through softmax and the ratio to keep gradients finite for saturated predictions, while the returned loss keeps the input dtype. (#5594)torch.jit.script(normalize_min_max)now normalises every(H, W)plane of a(*, C, H, W)input, as the eager function does. Previously scripting compiled only the body written for(B, C, H, W), so a scripted call normalised each row of each channel of a(C, H, W)input separately, returned an(H, W)input filled withmin_val, and normalised an input with more than four dimensions jointly over all but its first two dimensions. Scripted(B, C, H, W)calls and eager results for non-empty inputs are unchanged. (#5605)Indexing a
VideoBoxesnow selects videos instead of rows of its flattened(B * T, N, 4, 2)storage.video_boxes[i]used to hold rowiof that storage,(N, 4, 2)(framei % Tof videoi // T), withouttemporal_channel_size; it is now videoiwith allTframes,(T, N, 4, 2), and itsto_tensor()is(1, T, N, 4, 2). Slices, integer tensors and boolean masks index videos too, so a boolean mask has lengthB: a length-B * Tmask, which used to select frames, now raisesIndexError. Index assignment follows the same rule:video_boxes[i] = otherused to write rowiof the flattened storage and now writes allTframes of videoi. (#5613)With static p=1.0, p_batch=1.0, a batch_prob put into params is now ignored by every handler, in eager and compiled runs (#5585). The image and transform_matrix already ignored it, but inverse and, for augmentations such as the flips and RandomCrop, the mask, box and keypoint handlers honored it, so a sample it deselected was transformed in forward and left alone by inverse. Pass p < 1 to skip samples by hand. (#5616)
AugmentationSequentialnow repeats a single tensor mask,(H, W),(1, H, W),(1, C, H, W)or one(C, H, W)mask, to the batch of a(B, C, H, W)image before the first child, so each sample's own parameters apply to its copy and the mask comes back with batchB. Previously the result depended on the child: per-sample warps such asRandomAffine,RandomPerspectiveandRandomElasticTransformraisedgrid_sampler(): expected grid and input to have same batch size,RandomTransplantationrefused the mask, and flips, crops, resizes and color children such asColorJigglereturned it at batch 1, with flips and crops applying sample 0's parameters only, so it did not match images 1 toB - 1. For example, with a batch-2 image a(1, 1, H, W)mask throughRandomHorizontalFlipused to come back as(1, 1, H, W)and now comes back as(2, 1, H, W); underkeepdim=Truea(1, H, W)mask used to come back as(1, H, W)and an(H, W)mask as(H, W), and both now come back as(2, H, W). Mask lists, unbatched images, batch-1 images and masks with one entry per image are unchanged. An(H, W)mask is now checked against the image's height and width like a 3-D or 4-D mask, and a mismatch raises the sameValueError; it used to go through unchecked (a(9, 8)mask with(8, 8)images came back with height 9). (#5618)AugmentationSequential.inversenow reads a 3-D mask the way the forward pass does: a(B, H, W)mask whose leading size is the batch size is inverted per sample, and underkeepdim=True(on the container or the child) the inverse returns the rank it was given. Previously the inverse read every 3-D mask as one(C, H, W)image: per-sample warps and resample-mode crops (RandomAffine,RandomPerspective,RandomCrop, ...) raised a batch-size error,RandomRotationreturned(B, B, H, W), and flips andResizereturned(1, B, H, W). Underkeepdim=True,(H, W),(1, H, W)and(C, H, W)masks used to come back as(1, 1, H, W)or(1, C, H, W)and now keep their shape; underkeepdim=False, a(B, H, W)mask passed toinversenow comes back as(B, 1, H, W)instead of(1, B, H, W). (#5619)On an empty batch, the inverse of a shape-changing 2D geometric augmentation now returns the input height and width recorded in its parameters, keeping the channels, dtype, device and autograd graph of the tensor it inverts. It used to return the transformed size: for a
(0, 3, 6, 8)forward,Resize((5, 7)).inversegave(0, 3, 5, 7)and now gives(0, 3, 6, 8). This coversResize,LongestMaxSize,SmallestMaxSize,CenterCrop,RandomResizedCropand resample-modeRandomCrop, directly and throughAugmentationSequential.inverse. Two empty-batch parameters change with it.RandomCropnow records the unpadded input asforward_input_shape; it used to record the padded canvas, which an empty batch cannot undo because itspadding_sizehas no rows. In a container, a stage after aRandomCroporResize(includingLongestMaxSizeandSmallestMaxSize), whatever itsp, now records its own input size; it used to record the size before that crop or resize. EmptyRandomCropparameters saved before this change still replay but restore the padded canvas, for example(0, 1, 12, 12)instead of(0, 1, 6, 8)withpadding=(1, 2, 3, 4): regenerate them. Non-empty batches are unchanged. Part of #4429. (#5620)AugmentationSequentialnow repeats a single mask to the batch in two more cases, so each sample's own parameters apply to its copy and the mask comes back with batchB: a(1, T, C, H, W)mask next to a(B, T, C, H, W)video (aVideoSequentialchild; next to a BTCHW video a(1, T, H, W)mask too), and a mask replayed alone withparams=and no image, which is repeated to the batch recorded in those params (forward_input_shape[0]; for a video, a newvideo_batch_sizeentry thatVideoSequentialnow adds to each child's parameters). Previously both came back at batch 1: flips and crops applied sample 0's parameters only, andRandomAffineraisedgrid_sampler(): expected grid and input to have same batch size. For example, with a batch-2 video a(1, T, 1, H, W)mask throughRandomHorizontalFlipused to come back as(1, T, 1, H, W)and now comes back as(2, T, 1, H, W). Some inputs that used to run, or to fail late, now raiseValueError: a mask next to a video that is neither 5D nor a 4D mask next to a BTCHW video (it failed later inside theVideoSequentialreshape or came back with a wrong shape; withsame_on_frame=Falsea(1, 4, 8, 8)mask next to a 4-frame BCTHW video came back as(1, 1, 8, 4, 8)), a 1D mask (it used to raiseRuntimeError), a 5D mask next to a non-video image, a mask whose frame count differs from the video's, and a replayed mask whose batch is neither 1 nor the recorded batch (RandomHorizontalFlipandRandomCropused to run silently with a wrong result). Full-batch masks and 3D-augmentation containers are unchanged. AVideoSequentialnested inside another container keeps the old behavior. (#5636)mean_average_precisionnow raises kornia'sBaseError, namingpred_labelsorgt_labels, when a floating-point label is not a whole number (#5629). Previously a fractional label such as1.5passed the range check and matched no class, so the call returned a value without an error: a detection with such a label was dropped, and an object with such a label was not counted (with two perfect detections labelled[1.5, 2.0], class 1 read-1.0and the mAP was the AP of class 2 alone). Integer,booland integer-valued floating-point labels such as1.0give the same results as before. (#5638)In a container, a stage after an always-applied (
p=1)RandomResizedCropon an empty batch now records the crop's output size as itsforward_input_shape, as for a non-empty batch; it used to record the size before the crop. For a(0, 3, 9, 13)batch throughRandomResizedCrop((4, 5))and thenResize((2, 3)), theResizestage used to record(0, 3, 9, 13), so inverting that stage alone returned(0, 3, 9, 13); it now records(0, 3, 4, 5)and its inverse returns(0, 3, 4, 5). The inverse of the whole container still returns(0, 3, 9, 13). Empty parameter lists saved before this change keep the old sizes: regenerate them. Non-empty batches are unchanged. Part of #4429. (#5647)Boxes.filter_boxes_by_areanow marks the boxes it removes as invalid instead of only zeroing their stored inclusive vertices. Previously a removed box exported as[0, 0, 1, 1]in the exclusive'xyxy','xywh'and'vertices'modes,to_maskfilled pixel(0, 0)for it, and a latertransform_boxes,translateorpadmoved it like a real box. Now it exports as exact zeros in every mode, also after later transforms, andto_maskdraws nothing for it.RandomMosaicboxes belowmin_bbox_sizechange in the same way: in direct calls for every box key, and insideAugmentationSequentialfor"bbox_xywh", and for every key when a geometric augmentation follows the mosaic (it used to move them into real-looking boxes; without one,"bbox_xyxy"and"bbox"already came out as zeros). Because zero-width rows are rejected on import, passing such an'xyxy'or'xywh'export back toBoxes.from_tensorwith the defaultvalidate_boxes=True, or a"bbox_xywh"output to anotherAugmentationSequential, now raisesValueErrorwhere it used to import a 1x1 box at the origin. ABoxesobject pickled by an earlier version loads with every box valid. (#5649)equalize_claheandRandomClahenow spread the residual of the clipped pixels the way OpenCV does, one count on everymax(256 // residual, 1)-th histogram bin from bin 0, in the fast, per-sampleclip_limitand differentiable paths. They used to write the residual into the firstresidualbins, which lifted every tile's lookup table: wherever clipping left a residual, the output was brighter thancv2.createCLAHE, by about 40 gray levels on average for 64 x 80 to 96 x 96 images with an 8 x 8 grid and clip limit 2.0, and by 4 to 5 levels at 224 x 224. The output now changes for every tile whose clipping leaves a residual (#5654). On the images we measured (64 x 80 to 512 x 512, 8 x 8 grid, clip limits 2, 4 and 40), the mean signed difference from OpenCV is now within 0.1 gray levels in the fast, per-sample and differentiable paths, with the fast paths rounding each lookup-table entry as OpenCV does (#5659). (#5655)For an integer or bool input,
filter2d,filter2d_separable,filter3d,gaussian_blur2d,box_blur,laplacian,motion_blur,pyrdownandpyrup, the modules built on them (GaussianBlur2d,BoxBlur,Laplacian,MotionBlur,PyrDown,PyrUp), theScalePyramidlevels, everybuild_pyramidlevel after the input itself, and the edge map ofcanny/Cannynow return float32 on the input's scale, without rounding or clamping. They used to return the input's integer dtype, holding zeros for a fractional kernel and wrapped sums for an integer one.joint_bilateral_blurwith an integerinputand a float64guidancenow returns float32 instead of float64. Floating inputs keep their dtype and values (#5155). (#5669)equalize_claheandRandomClahenow round fast-path lookup-table entries to the nearest integer (ties to even), matching OpenCV's LUT quantization, instead of flooring them. In float32 and float64 each fast-path output pixel rises by at most one gray level (1/255), and for the same tile its lookup table now equals OpenCV's (#5659). The differentiable path is unchanged. (#5679)TensorWrapper,Vector2,Vector3andScalarresults now get one type rule, whether a torch function, a tensor method, a tensor attribute or an operator produced them. A result takes the class of aVector2/Vector3operand, on either side, when it ends in that width and has at least as many axes as that operand. Otherwise it takes the class of the first operand without a width, and otherwise it is a plain tensor. Before, a tensor method such asv.clone()returned a plain tensor whiletorch.clone(v)returned aVector3,Scalar * Vector3returned aScalarholding the vectors, andtorch.linalg.norm(v, dim=-1)andv.Traised unless the result happened to end in 3, in which case it was returned as aVector3. Nowv.clone()andScalar * Vector3are aVector3,torch.linalg.norm(v, dim=-1)returns a plain tensor, andv.Treturns a plain tensor unless the batch holds exactly 3 vectors, whose(3, 3)transpose stays aVector3because the rule reads shapes only. The same applies to any torch function that removes an axis:torch.mean(v, dim=0)of an(N, 3)Vector3was aVector3and is now a plain(3,)tensor, asv.mean(dim=0)already was.Vector2/Vector3indexing now usesdata[key]:v[..., 0]andv[:, 0], which raised, and an unbatchedv[0], which raisedIndexError, return the plain tensor the wrapped tensor gives, and keys that keep the coordinate axis return the vector class as before. (#5688)A tuple
forwardoutput ofImageModule,ImageSequentialand the augmentation containers used to come back as a list, and a one-element tuple as its bare element. It now keeps the tuple type and its length. A caller that used the bare element of a one-element tuple output must index it:out = module(x)[0]. A caller that relied on the list type of a multi-element tuple output (isinstance(out, list),out.append) must convert withlist(out); one that indexed it (out[0]) needs no change. (#5695)On an empty batch, a shape-changing 2D augmentation now gives a mask the height and width it gives the image. It used to return the mask at its input size:
AugmentationSequential(Resize((4, 5)), data_keys=["input", "mask"])on a(0, 3, 8, 10)image and a(0, 1, 8, 10)mask gave a(0, 3, 4, 5)image next to a(0, 1, 8, 10)mask, and passing that pair toAugmentationSequential.inverseraisedValueError. The mask is now(0, 1, 4, 5)and the inverse restores(0, 1, 8, 10). This coversResize,LongestMaxSize,SmallestMaxSize,CenterCrop,RandomCrop,RandomResizedCropandPadTo, inAugmentationSequential(also with dictionary inputs and insideVideoSequential) and in a directtransform_maskscall. This holds for anyp: an empty image and mask both take the configured size. Non-empty batches are unchanged. Part of #4429. (#5706)AugmentationSequentialprocessed a mask in its image's dtype, so integer labels above that dtype's exact range were silently rounded:2049became2048next to a float16 image. It now processes integer and boolean masks in at least float32 (float64 next to a float64 image), so their labels come back intact. A label that is not exactly representable even there (for example2**24 + 1next to a float32 or half-precision image) now raisesRuntimeErrorinstead of being rounded; remap the labels to smaller integers or use a float64 image where supported. Next to a float16 or bfloat16 image, a warped integer or boolean mask (rotation, affine, perspective, ...) is now resampled on a float32 grid, so it can differ from before at individual pixels; the half-precision resampling on CPU also picked wrong source pixels, including labels the mask does not contain. Floating masks keep the image's working dtype. (#5711)Affinenow usesshearlikeangle,translationandscale_factorwhen it creates the parameters it was not given and when it checks that its parameters share one device and dtype. AnAffinegiven onlyshearnow creates its default rotation, translation and scale on the shear's device and in its dtype, so it works on float64, float16 and bfloat16 inputs and on accelerators. Before, those defaults were float32 tensors on the default device, and the forward raisedValueErroron any other input. Ashearon another device or of another dtype than the other parameters now raisesDeviceErrororTypeCheckErrorwhen the module is built, as a mismatch amongangle,translationandscale_factoralready did. Before, such a module was built and its forward raised, except for ashearof lower precision than parameters matching the input (a float32shearwith a float64angleon a float64 image), which worked. An integersheargiven alone now gets integer defaults, and its forward raisesValueError, as it already did for an integerangle,translationorscale_factorgiven alone; before, it was combined with float32 defaults. (#5715)equalize_claheandRandomClahenow blend neighbouring tile lookup tables with weight steps of1 / tile_size, instead of1 / (tile_size - 1), anchored at each tile's actual centre. This changes interpolated output values in both the fast and differentiable paths. Kornia intentionally anchors the blend half a pixel before OpenCV/scikit-image's historical phase to preserve flip symmetry on unpadded grids. For the same tiles and lookup tables, the phase difference is at most half an interpolation step per axis; exactcv2.createCLAHEparity is not the contract. On the images we measured with an 8 x 8 grid and even tiles (64 x 80 to 512 x 512, clip limits 2 and 40), the largest difference fromcv2.createCLAHEfell to between one half and two thirds of what it was (21 instead of 39 gray levels on a smooth 64 x 80 image at clip limit 40, 3 instead of 5 on the 512 x 512cameraimage), while the mean difference stayed close to what it was (7.0 instead of 7.6 and 0.54 instead of 0.57 levels), because the half-pixel offset from OpenCV's phase changes every blended pixel. Border regions still clamp to the nearest tile along the border axis. LUT calculation and quantization are unchanged. (#5716)Hyperplanenow registers its normal and offset as module state under the keys_nand_d:state_dict()saves them,load_state_dict()restores them, and.to(),.double()and an enclosing module's conversions move and cast them. Previously a plane'sstate_dict()was empty, loading a state dict into a module holding a plane reported success and kept the old plane, and.to()left the plane on its original device and dtype. As inParametrizedLine, a floating-point tensor without autograd history is now stored as annn.Parameter. So a plane built from plain tensors, including the result ofHyperplane.throughorfit_planeon points without autograd history, has two trainable parameters (an optimizer built frommodel.parameters()now updates them), and the distances and projections it returns require grad (call.detach()before.numpy()). Previously such a plane had no parameters and its outputs did not require grad. A caller'snn.Parameterstays a parameter, a tensor with autograd history keeps it, and an integer tensor is stored as a buffer. A state dict saved before this change has no plane keys, so loading it withstrict=Truenow raises on the missing_nand_dkeys;strict=Falsereports them and keeps the plane the module was built with, as before. A whole module saved withtorch.savebefore this change still loads with its plane, which is moved to registered state. (#5717)DenseSIFTDescriptoroutput is smaller at the defaultpadding=1. It used to return anH x Wgrid, one descriptor per pixel, built from cells one pixel apart. It now returns(H - 9) x (W - 9), with each output centred at input positionj + 4.5along each axis, and an input under 10 pixels per side raises. In general the height is(H + e + 2 * padding - (num_spatial_bins - 1) * spatial_bin_size - 1) // stride + 1, whereeis 1 for an evenspatial_bin_sizeand 0 otherwise; passpadding=6forH + 1at the other defaults. (#5734)make_grid,ImageModule.showandImageModule.savenow readn_rowas the number of images per row, as their docstrings say (the meaning ofnrowintorchvision.utils.make_grid). Previouslyn_rowset the number of rows, so every grid whose row and column counts differ was laid out the other way round: 6 images withn_row=2used to give 2 rows of 3 and now give 3 rows of 2. The defaultn_row=None(the square root of the batch size, rounded up) is now the number of columns, so 2 images used to be stacked vertically and are now side by side, and 5 or 6 images used to be 3 rows of 2 and are now 2 rows of 3. Images still fill the grid row by row in batch order. To keep the old placement ofBimages inRrows, passn_row=math.ceil(B / R). (#5745) (#5745)The kernel builders raise for an integer or bool
dtypethat cannot hold their taps, where they used to return a wrong kernel.get_box_kernel1d,get_box_kernel2d,get_gaussian_kernel1d,get_gaussian_erf_kernel1d,get_gaussian_discrete_kernel1d,get_gaussian_kernel2d,get_gaussian_kernel3d,gaussian,gaussian_discrete,gaussian_discrete_erf,get_diff_kernel3d,get_diff_kernel3d_2nd_orderandget_spatial_gradient_kernel3dhave fractional taps and now raise for every integer and booldtype(for the Gaussians, thedtypethat goes with a Pythonsigma). They used to return:- for the box kernels, the kernel in that dtype with every tap truncated to 0 (all
Truein bool), except a size-1 box, which was all ones and now raises too; - for the sampled and erf Gaussians, a floating kernel for
sigmatruncated to an integer, soget_gaussian_kernel1d(5, 1.5, dtype=torch.int32)was thesigma=1kernel and an integersigmasuch as2gave the right kernel (it now raises); in uint8 the offsets also wrapped, so the taps before the centre were wrong (0 for asigmabelow about 15); - for the discrete Gaussians, the kernel in that dtype with every tap truncated to 0;
- for the 3-D difference kernels in a signed dtype, the kernel with the half and quarter taps truncated to 0, so the
first-order channels and the mixed second-order ones were all zero (bool gave
True/Falsetaps).
A bool
dtypealready raised for the Gaussians, and uint8 already raised for the 3-D difference kernels.get_laplacian_kernel1d,get_laplacian_kernel2dandlaplacian_1dkeep accepting a signed integerdtypewide enough for their centre tap and raise for uint8, bool and a narrower one, where they used to wrap the centre (to 252 for a uint8 size 5, to 88 for an int8 13x13) or make every tapTrue.spatial_gradient3dandSpatialGradient3dnow return float32 for an int8, int16, int32 or int64 input withorder=2; they used to return the input's dtype, with the mixed second derivatives zero.(#5759)
- for the box kernels, the kernel in that dtype with every tap truncated to 0 (all
RandomAffineandRandomShearnow check asheargiven as a 2x2 tensor (or nested pairs((x_min, x_max), (y_min, y_max))) the way they check the flat(x_min, x_max, y_min, y_max)form: each axis range must be finite, ordered and inside[-360, 360], otherwise the constructor raisesValueError(shear-x out of bounds. Expected inside (-360, 360),If shear-y is a range, it must be finite). Previously the 2x2 form skipped the bound and finiteness checks: an endpoint past 360 degrees was accepted, and an infinite endpoint was accepted and produced NaN images at forward time. A reversed range was already rejected; its message now names the axis (shear-x[0] should be smaller than shear-x[1]). (#5766)build_pyramidandbuild_laplacian_pyramidnow reject non-positive integermax_levelvalues with a named validation error instead of returning a single level. Non-integer values, including booleans previously treated as integers, are rejected consistently.ImageRegistrator.registerbuilds its pyramids withbuild_pyramid, sopyramid_levels <= 0(or a boolean) now raises the same error instead of registering at the full resolution only. Positive integer levels and the existing padding behavior are unchanged. (#5778)AugmentationSequentialmask lists now hold one tensor per image sample, each(H, W),(C, H, W)or(1, C, H, W), and every entry follows its own sample's gate, parameters and transformation matrix in forward, replay, nested sequences, auto-augment policies and inverse. Before, every entry received the whole batch's parameters with only samplei's gate: per-sample entries failed in warps or were cropped with sample 0's window, full-batch entries were transformed whole but gated by one sample's draw, and a list longer than the batch raisedIndexError. A list of full-batch tensors, a list whose length differs from the batch, or a non-tensor entry now raisesValueError, with or without an image; pass full-batch masks under separatemaskdata keys. Video, mix and 3D children and a geometricPatchSequentialraiseNotImplementedErrorfor a mask list; before, mix children returned the list unchanged while the image was mixed. Mask-only replay and inverse retain every sample (before, they returned a single tensor or raisedIndexError), and list calls preserve the child's full-batch parameters. A tensor mask next to a rank-2(H, W)image is now checked as next to a(C, H, W)image: another height or width, a 4D batch above 1 or a 5D mask raisesValueError. Before, it was transformed as given, cropped with the image's window, or failed inside a child withIndexErrororRuntimeError. (#5779)CenterCrop3DandRandomCrop3Dnow namesizeand the value passed in their size errors. Asizeof the wrong type or length, or with a float element, raisesTypeErrorin the constructor: before,CenterCrop3D((2, 2))raisedIndexError,CenterCrop3D((2, 2, 2, 2))silently cropped to(2, 2, 2),RandomCrop3DraisedAssertionErrorat the first call for anintor a sequence of other than three elements, and a float element raisedTypeErrorfromaffine_gridat the first call in both classes. A crop larger than the input along any axis now raisesValueErrorin both classes, with the requested and input spatial sizes; before,CenterCrop3DraisedAssertionError.CenterCrop3D(n)still works andRandomCrop3D(n)still does not: pass(n, n, n). (#5789)kornia.contrib.histogram_matchingno longer extrapolates below the template minimum. When the template's darkest value covers a larger fraction of its pixels than the source's darkest value does (for example a template with clipped blacks), the source pixels whose quantile is below that fraction used to map below the template minimum, to negative intensities for a template whose minimum is 0; they now map to the template minimum, as inskimage.exposure.match_histograms. A constant template used to return NaN everywhere and now returns that constant. (#5794)The kornia_rs floor is 0.2.0, the release a plain
pip install korniaresolves and the one CI tests; kornia_rs 0.1.x is no longer tested. (#5797)kornia.onnx.ONNXSequentialandkornia.onnx.ONNXModuleraise aValueErrornaming the expected and received counts when they are called with a different number of arrays than the session has inputs. Extra arrays used to be dropped without a warning, so the call returned the result for the leading arrays only, and too few arrays raised anIndexError. (#5799)resize_to_be_divisiblerounds a side of at most half ofdivisible_factorup todivisible_factorinstead of down to 0: a(1, 3, 10, 14)image with factor 24 now gives(1, 3, 24, 24)where it gave an empty(1, 3, 0, 24)image. An empty side still stays empty. It reads height and width from the last two axes, so(H, W)inputs and inputs with more than one leading axis are resized like inresize; they used to raiseUnboundLocalError. Adivisible_factorthat is not a positive integer raisesValueError: a negative factor used to give the size of its absolute value, 0 raisedZeroDivisionErrorand a float raisedTypeError. (#5802)compute_paddingnow pads an axis that is shorter than the window up to one full window. It used to return only the stride-alignment padding, which can leave the padded image smaller than the window: for a 4x6 image with an 8x8 window and stride 2 it returned(0, 0, 0, 0), andextract_tensor_patches(..., allow_auto_padding=True)andcombine_tensor_patches(..., allow_auto_unpadding=True)raised aRuntimeError. They now extract one window along such an axis and reconstruct the image. Results are unchanged wherever the old padding already fitted a window. (#5806)load_image(path, ImageLoadType.UNCHANGED)returns a grayscale JPEG as one channel,(1, H, W); it used to return three equal channels. Image modules given a file path, such asAugmentationSequentialandImageSequential, now receive(1, 1, H, W)for such a file instead of(1, 3, H, W), so a colour augmentation such asColorJiggleraises for it, as it already did for a grayscale PNG path. Invalid arguments raise a typed kornia error up front:load_imageraisesTypeCheckError(aTypeError) whendesired_typeis not anImageLoadType, where it raisedNotImplementedError, orAttributeErrorfor a 16-bit file.write_imageraisesTypeCheckErrorfor an input that is not a tensor, where it raisedAttributeError. It validatesqualityfor every format, including PNG and TIFF, which used to ignore it: a value that is not an integer raisesTypeCheckError, and one outside [0, 100] raisesValueCheckError(aValueError), where a JPEG accepted 101 to 255 (101 gave the same file as 100) and raisedOverflowErrorbeyond that. A batched(B, C, H, W)tensor raisesShapeError(aValueError) naming the shape, where kornia-rs raised aTypeError. Writing into a directory that does not exist raisesFileNotFoundErrornaming the directory, and writing under a path that is a file raisesNotADirectoryError; both used to raise a bareException.get_sample_imagescaches downloads under<kornia_config.hub_cache_dir>/imagesby default instead of a hard-coded.kornia_hub/images; the two are the same path unlesshub_cache_diris changed. A download that is not an image raisesValueErrorand is not cached, where it raisedPIL.UnidentifiedImageError, anOSError, so anexcept OSErrorclause no longer catches it. (#5808)draw_point2d,draw_lineanddraw_rectangleplace a fractional coordinate on the pixel whose centre is nearest, a coordinate exactly halfway rounding up; they used to truncate toward zero, so 2.7 drew at pixel 2 and now draws at pixel 3.draw_point2danddraw_linecheck their bounds after rounding, so a coordinate lies inside the image from -0.5 up to, but not including,W - 0.5(H - 0.5for y). FromW - 0.5up toW, both used to draw in the last column and now raiseValueError.draw_point2dalso raisesValueErrorfor any other point outside the image: a coordinate between -1 and -0.5 used to draw in the first column, one of -1 or less at the opposite edge, and one ofWor more raisedIndexError.draw_lineaccepts -0.5 up to 0, which used to raise.draw_rectangleno longer draws a side that lies outside the image, and it clips a fill to the image. It used to clamp the corners, which drew such sides along the border; clamp the corners to[0, W - 1]and[0, H - 1]for the old look. It accepts the two corners in either order, where reversed corners drew nothing. It raisesValueErrorinstead ofAssertionErrorwhen the image and rectangle batch sizes differ or the last dimension is not 4, andShapeError, still aValueError, naming the expected shape for an image that is not(B, C, H, W).draw_linedraws, at each step along the longer axis, the pixel nearest to the segment, so a line is the same fromp1top2as fromp2top1. It used to round the shorter-axis coordinate up fromp1, which put sloped lines up to one pixel off and depended on the direction.draw_point2draisesValueErrorfor an image that is not(C, H, W)or(H, W); a batched image used to be drawn along the wrong axes or raise a torch indexing error.Image.toandImage.floatreturn a newImageand leave the original unchanged, liketorch.Tensor.to; they used to change the image in place and return it, so code that ignores the result must now assign it (img = img.float()).Imagechecks its pixel format:GRAYneeds one channel andRGBandBGRneed three (UNKNOWNtakes any count), andbit_depthmust be the storage size,8 * data.element_size(), wherebit_depth9 to 15 used to pass onuint8data and 12 failed onuint16. A mismatch raisesValueCheckError, aValueError. Without a colour space,Image.from_numpyandImage.from_dlpacklabel one channelGRAY, threeRGBand any other countUNKNOWN; they used to label every imageRGB.image_to_stringandprint_imageshow each pixel with the nearest of the 240 fixed xterm colours (codes 16 to 255, the gray ramp included), so printed colours change; they used to pick the nearest of the six colour-cube levels in each channel after truncating a float value to a whole level.print_imageraisesTypeErrorinstead ofRuntimeErrorfor an input that is neither a path nor a tensor.image_to_tensorraisesTypeErrorfor any input that is not anumpy.ndarray, where a list raisedAttributeError.make_gridraisesValueErrorfor a negativepadding, which used to crop the images.draw_point2dno longer exports withtorch.export, nor to ONNX from torch 2.9, because its out-of-image check reads tensor values.draw_rectangleexports withtorch.exportfrom torch 2.14, which it did not before. (#5813)pyrdownandPyrDownnow compute the output width with the same rule as the height,int(width / factor), so both axes follow the documentedfloor(side / factor). The width used floor division of the floating-point values, which could drop a pixel whenwidth / factoris a whole number and the factor's binary value lies slightly above its decimal value (1.1, 1.3, 1.6, 1.8, 2.2, ...): atfactor=1.6a 480 x 640 image used to give 300 x 399 and now gives 300 x 400. Every width that is a multiple of 8 atfactor=1.6, of 13 at 1.3 or of 9 at 1.8, and some multiples of 11 at 1.1, gains that pixel, and the output values change with the new sampling grid. Integer and dyadic factors (2.0, 3.0, 1.5), KeyNet's internal 1.2 and the defaultscale_factor_levelsofMultiResolutionDetector(sqrt(2)) give the same sizes as before; aMultiResolutionDetectorconfigured with an affectedscale_factor_levelscan return different detections. (#5817)ImageModuleMixIn,ImageSequentialandAugmentationSequentialnow load an 8-bit palette PNG image path as its RGB colors, or RGBA colors when the file has atRNSchunk, as they already did for the same image passed as a PIL object. Previously such a path produced one channel of palette indices divided by 255. A palette PNG path whose palette is too short for its pixels, or whosetRNSchunk fails its CRC check, used to load as indices and now raisesValueError, askornia.io.load_imagedoes for that file under every type exceptUNCHANGED. (#5833)equalize_claheandRandomClahenow use tiles of ceil(H / grid_size[0]) by ceil(W / grid_size[1]) pixels, odd or even, and reflect-pad only as needed to complete the grid. Previously, odd tile sizes were rounded up to the next even size and the image was padded to fit, even when the grid divided it. For example, an 8 x 8 grid on a 72 x 88 image used 10 x 12 tiles over an 80 x 96 padded image, shifting tile boundaries and changing output values. These are OpenCV's tiles when the grid divides both image axes or neither. When it divides only one, OpenCV also pads that axis, by one pixel per tile, and Kornia does not, so on such images the difference fromcv2.createCLAHEcan grow. On the smooth images we measured with an 8 x 8 grid at clip limit 2, the mean / max difference fromcv2.createCLAHEfell from 8.0 / 47 to 3.2 / 10 gray levels at 72 x 88 and from 18.8 / 82 to 1.0 / 3 at 100 x 150, and odd tiles on a grid that divides the image are now flip-symmetric. (#5845)Removed the legacy 12-vector pinhole helpers
pinhole_matrix,inverse_pinhole_matrix,scale_pinhole,get_optical_pose_baseandhomography_i_H_reffromkornia.geometry.camera.pinhole. They were never exported or documented, and their docstrings had announced their deprecation in favour ofPinholeCamerasince before kornia 0.2.pinhole_matrixaddedepsto every entry of its output,inverse_pinhole_matrixinverted a perturbed matrix, andget_optical_pose_baseandhomography_i_H_refalways raisedNotImplementedError. Importing them from the module now raisesImportError. UsePinholeCamerainstead:intrinsicsfor the 4×4 matrix returned bypinhole_matrix,intrinsics_inverse()for its 4×4 inverse (camera_matrixreturns only the 3×3 intrinsics block),scale()to rescale, andextrinsicsfor the pose (#4268, #4283). (#5874)ALIKEDandDISKno longer pad their keypoints with non-maxima, nor drop a real maximum, when an image has no more local maxima than the keypoint budget. In top-k mode (ALIKED(max_num_keypoints=k, detection_threshold<=0)), ALIKED used to return exactlykkeypoints per image, filling the slots beyond the score map's maxima with other positions intorch.topk's tie order, including the removed border, the region aforward_lafmaskexcludes and theimage_sizepadding, and it raised whenkexceeded the number of pixels. It now returns at mostk, all of them maxima, andforward_lafpads each image to the largest count of the batch with zero frames (#5862).DISK(...)(images, n=n)used to drop the weakest maximum of an image withnmaxima abovescore_thresholdor fewer, and raised on an image with none; it now returns all of them, the keypointsn=Nonereturns. With more thann, it used to leave out every maximum tied across then-th place, returning fewer thann; it now keeps thenstrongest, taking maxima tied at then-th score in raster order (#5864). In threshold mode, ALIKED fell back to the maxima above the mean score only when no image of the batch had a maximum abovedetection_threshold; the fallback is now decided for each image, so a batch returns the keypoints that one-by-one calls return (#5865). The defaultALIKEDconfiguration on one image at a time, andDISKon an image with more thannmaxima and no tie across then-th place, return the same keypoints as before. (#5875)kornia.contrib.histogram_matchingreturns the source dtype for a floating source andfloat32for an integer source, whatever the template dtype. The output dtype used to depend on the template too: afloat32source with afloat64template returnedfloat64(nowfloat32), afloat16source with afloat32template returnedfloat32(nowfloat16), and auint8source with afloat64template returnedfloat64(nowfloat32). Pairs of the same dtype return the same dtype as before. (#5878)VideoSequential.inverse_keypointscalled with a raw(B, T, N, 2)tensor used to return it shaped(T, B, N, 2), with the values still in(B, T)order; it now returns(B, T, N, 2), astransform_keypointsdoes. The raw-tensor branches oftransform_keypoints,inverse_keypoints,transform_boxesandinverse_boxesused to raise for zero keypoints or boxes, an empty video batch and a non-contiguous tensor; they now return the input's shape. (#5881)kornia.core.utils.dict_to_dataclassnow raisesTypeCheckErrorfor a value that is neither a dict nor an instance of the dataclass its annotation names, wherever the annotation names it: a list or tuple element, a dict value, or a field whose annotation is a string, which includes every field of a module withfrom __future__ import annotations. Such values used to pass through unchanged; a field annotated with the dataclass class itself already raised. For example,[5]for aList[Inner]field,["x", 2]for aTuple[Inner, int]field,{"k": 5}for aDict[str, Inner]field andNonefor a"Inner"field used to be stored as given and now raise, and in a module withfrom __future__ import annotationsthe round trip of asub: Sub = Nonedefault throughdataclass_to_dictnow raises: annotate the fieldOptional[Sub].ParametrizedLine,So2,Se2andSe3given an integer or bool tensor now raiseTypeCheckErrorat construction, naming the field and its dtype; cast the tensor to a floating-point dtype first. In eager mode they used to raise torch's "Only Tensors of floating point and complex dtype can require gradients"RuntimeError. Undertorch.compile,torch.jit.traceand export they used to keep the integer tensor as a plain attribute, and now raise as well.Hyperplanestill stores integer coefficients as buffers. (#5910)kornia.onnx.download.CachedDownloader.download_to_cachetakescache_dirandsuffixas keyword-only parameters and raisesTypeErrorfor any other keyword.ONNXLoader.load_modelandONNXLoader.load_configraise it for any keyword butcache_dir, whatever the model name or URL, andHFONNXComunnityModelLoader.load_modelfor any keyword. An unknown keyword, such as a misspeltcachedir=, used to be ignored, and the file was cached in the default directory.download_to_cachealso raisesValueErrorfor anamethat is absolute or has a drive or an empty,.or..component, and for asuffixthat adds a directory to the file name; so doesONNXLoader.load_modelfor anhf://name whose folder is.., andHFONNXComunnityModelLoaderfor such amodel_name. Such names used to be joined to the cache directory as they were:..stored the file outside the cache directory, and an absolute name was stored below it on POSIX (an absolutemodel_namereplaced it).ONNXLoader.load_modelandload_configraiseValueErrorfor a URL without a host, such ashttps:///a/m.onnx, whichurlopenrefuses to fetch. (#5911)RandomMosaicnow checkspadding_modeat construction, in both cropping modes, and raises aValueErrorthat names the value and listsconstant,reflectandreplicatefor anything else. Previously the constructor accepted any value:cropping_mode="slice"ignored it, andcropping_mode="resample"passed any other string togrid_sample, sogrid_sample's own nameszeros,borderandreflectionworked (asconstant,replicateandreflect) while any other value failed insideforwardwith torch'sgrid_sampleerror. (#5917)So2,Se2andSe3now reject at construction the inputs their methods cannot use.So2(z)with a real floating-pointzused to construct, andinverse(),adjoint(),__getitem__andSo2 * So2worked on it whilematrix(),log()andSo2 * pointsraised torch's "imag is not implemented"; it now raisesTypeCheckErrornamingzand its dtype (buildzwithtorch.complex).Se2/Se3with a translation whose dtype differs from the rotation's (for example a float64 rotation and a float32 translation) used to construct, andmatrix(),inverse(),__mul__and__getitem__worked on some of them whilelog()(Se2) orinverse(),adjoint()andSe3 * Se3(Se3) raised torch's "expected scalar type" error; they now raiseTypeCheckError. A complexSe2/Se3translation and an integer or boolnn.Parametertranslation, which used to construct, also raiseTypeCheckError. A translation on another device than the rotation, which madematrix(),log(),inverse(),adjoint()and*fail, now raisesDeviceError. A bfloat16Se2translation beside a complex32, complex64 or complex128 rotation stays accepted, because.bfloat16()leaves exactly that state, and everySe2method now works on it:log()used to raise torch's dtype error, andinverse()andpose * posereturn a translation of the rotation's real dtype (float32 or float64 as before, but float16 instead of float32 for a complex32 rotation, which the new check would reject). (#5925)histogram_matchingwith an empty template now raises aValueError("histogram_matching needs a non-empty template."); it used to raise anIndexErrorfrom inside the quantile computation. Passingeps=tocombine_tensor_patchesinsidetorch.compile(fullgraph=True)compiled before;epsnow emits aDeprecationWarning, which makes that call fail withUnsupportedunder the default TorchDynamo configuration, so dropepsfrom the call. (#5960)connected_componentsnow returnsint64labels with exact ids. It used to return the input dtype, which merged distinct components infloat16,bfloat16,boolanduint8inputs (ids lost precision or wrapped) and, in any dtype, above 224 pixels. On MPS, which has nofloat64, an image of more than 224 pixels (a single image, not the batch) now raisesValueErrorinstead of returning merged labels.KMeans(tolerance=None, max_iterations=0), a negativemax_iterationsand a negativetolerancenow raiseBaseError. The first never stopped fitting. A negativemax_iterationsused to stop the fit after one iteration, and a negativetoleranceused to be accepted and never triggered the early stop.KMeans.predictwith a 1-D input now raisesShapeErrorinstead ofIndexError.distance_transformandDistanceTransformnow reject anhso small that the kernel's corner tapexp(-sqrt(ndim) * (kernel_size // 2) / h)underflows, which the old axis-tap check let through. Such calls used to return wrong distances (for example float32 17.78 instead of 21.21 atkernel_size=31,h=0.18).distance_transformandDistanceTransformnow reject anhabove a bound that depends onkernel_sizeand the working precision: in 2-Dh < 0.5624atkernel_size=3(0.5626infloat64) and about0.50at larger kernels, in 3-Dh < 0.4070atkernel_size=3(0.4071infloat64) and about0.38at larger kernels. The bound leaves the off-centre kernel taps a margin below 1 for the rounding of the working precision. Such anhused to return 0, as if on the foreground, at background pixels whose window was full of reached pixels. (#5961)ImageStitchernow raisesRuntimeErrornaming the sample and its match count when a sample has fewer than 4 matches (sample 0 when nothing matched), and naming the index when a match's batch index is outside the batch. Before, a sample with 1 to 3 matches, or an unmatched sample ahead of a matched one, raisedValueErrorfrom RANSAC (estimator="ransac") orAssertionErrorfromfind_homography_dlt("vanilla"); unmatched samples at the end of a batch failed later with agrid_samplerRuntimeError; a batch without any match raised aRuntimeErrorthat named no sample; and a batch index outside the batch raised one of these errors, depending on the indexes.HomographyTracker.track_next_framecalled without a previous homography (beforeforward()ormatch_initial()found one) now raises kornia'sBaseErrornaming the missing previous homography; before, it raisedUnboundLocalError. It also raises that error when called right after a target is assigned directly, because the previous homography maps the old target's coordinates; before, it tracked the new target with that homography. (#5965)extract_tensor_patches,combine_tensor_patches,compute_padding,ExtractTensorPatchesandCombineTensorPatchesreject awindow_sizeorstridecomponent below 1 up front withValueCheckError(aBaseErrorand aValueError) naming the argument, also underpython -O. A zero or negativestrideused to fail later withZeroDivisionErroror aRuntimeErrorfromunfold/fold, and the two module classes accepted it at construction;combine_tensor_patchesfailed the same way for a non-positivewindow_size, or raisedAssertionErrorwhen the stride exceeded it;compute_paddingraisedZeroDivisionErrorfor a zero stride and returned(0, 0, 0, 0)for a negative stride or a non-positivewindow_size.extract_tensor_patchesstill raises aValueErrorfor a non-positivewindow_size. (#5969)elastic_transform2dandRandomElasticTransformno longer clamp the displaced sampling grid to[-1, 1]beforegrid_sample, sopadding_modenow applies to coordinates displaced outside the image. Previously"zeros", the default of both, and"reflection"repeated the edge pixel there ("zeros"at half intensity, a quarter in the corners, with the defaultalign_corners=Falseand bilinear sampling); now those samples are zero-padded or reflected as requested. Default outputs therefore change near the image border wherever the displacement points outward, and so do the gradients through those samples."border"output is unchanged. This correctness fix ships without a deprecation window. (#5987)YuNet(phase, pretrained=False)returns the randomly initialised model in training mode; it returned it in evaluation mode. Call.eval()before inference, for example after loading your own weights.FaceDetector, which loads the weights, is unaffected. (#6014)HardNet,HardNet8,HyNet,SOSNet,TFeat,OriNet,LAFAffNetShapeEstimator,KeyNet,KeyNetDetectorandDeFMOdefault topretrained=True. Constructing one downloads its weights (once) and returns the trained model in evaluation mode; forKeyNetDetectorthat is itsKeyNetnetwork, while the detector itself keeps its mode, so anori_moduleoraff_moduleyou pass is not switched. They defaulted to random weights, returned in evaluation mode with BatchNorm, where the network has any, on its initial statistics. Passpretrained=Falsefor random weights. An architecture argument the checkpoint does not fit now needspretrained=Falseas well: with the default,HyNetwith anotheris_biasordim_desc, andKeyNetorKeyNetDetectorwith akeynet_confof anothernum_filters,num_levelsorkernel_size, raiseRuntimeErrorfrom the strict weight load, andHyNet(is_bias_FRN=False)raisesValueErrorbefore downloading the weights, which would load but leave their trained FRN biases unused.Randomly initialised models are returned in training mode:
pretrained=Falseon those classes,SOLD2(pretrained=False),SOLD2_detector(pretrained=False)andLoFTR(pretrained=None). They were returned in evaluation mode. Call.eval()before inference, and after loading your own weights into one of them. A randomLoFTRin training mode runs its supervised training branch, so its forward raises without ground-truth matches until.eval()is called. (#6017)kornia.models.qwen25.Qwen2VLVisionTransformerand thekornia.models.qwen25.qwen2_vlmodule with its blocks (Qwen2VLPatchMerger,Qwen2VLRotaryEmbedding,Qwen2VLVisionAttention,Qwen2VLMLP,Qwen2VLVisionBlock) are removed, so importing them now raisesImportError. They shipped in v0.8.3 and v0.9.0rc1 as a randomly initialised placeholder that was not the Qwen2.5-VL architecture (a plain ViT with a Conv2d patch embedding, LayerNorm, global attention and no positional information), and no weights existed for them. Usekornia.models.qwen25.Qwen25VisionTransformer, which takes aQwen25VisionConfigand loads the released Qwen2.5-VL checkpoints. (#6025)kornia.models.sam3is removed:import kornia.models.sam3raisesModuleNotFoundError. It shipped in v0.8.3 and v0.9.0rc1 as randomly initialised Phase 1–2 modules of #3406 (an image encoder that was a plain single-scale ViT, and a prompt encoder and mask decoder whose masks ignored point and box prompts), with no weights and no loader. SAM 3 is a different model under Meta's SAM License; a port would be a separate decision. (#6029)DepthEstimationcalled on a(B, 3, H, W)tensor returns depth maps of shape(B, 1, H, W), kornia's image layout; it returned(B, H, W). A list of(3, H, W)images still returns(1, H, W)items. The graph exported byto_onnx(include_pre_and_post_processor=True)from aDepthAnythingONNXBuildermodel takes an image that is already resized, such asmodel.resize(image); it took an image of any size and squashed it to 518 x 518. The resize keeps the aspect ratio, so its output size depends on the input size, and it runs in torch before the graph. (#6030)VisualPrompter.predict(keypoints=...)withoutkeypoints_labelsraises; the keypoints were ignored and the prediction was the one without prompts.VisualPrompter.set_imagetakes one image,(3, H, W)or(1, 3, H, W), and raises for a batch: it accepted(B, 3, H, W)with B > 1, after whichpredict()without prompts returned one prediction per image andpredictwith keypoint orBoxesprompts raised. UseSam.forwardto segment a batch of images with per-image prompts. (#6040)In the
EdgeDetectorthatEdgeDetectorBuilder.build("dexined")returns,model[0]is nownn.Sequential(RgbToBgr(), Normalize(...)), and the normalisation ismodel[0][1], with the BGR mean[103.939, 116.779, 123.68] / 255.model[0]was theNormalizemodule itself, with the ImageNet RGB mean[0.485, 0.456, 0.406], so code that readsmodel[0].meanormodel[0].stdnow raisesAttributeError; readmodel[0][1].meanandmodel[0][1].stdinstead. DexiNed stays atmodel[1], so a savedEdgeDetectorstate dict keeps itsmodel.1.*keys. (#6042)Some vision-language calls of
kornia.modelsthat ran now raise:SigLip2Config.from_nameandSigLip2Builder.from_namegive the supported checkpoints (google/siglip-base-patch16-224,google/siglip2-base-patch16-{224,256,384,512}andgoogle/siglip2-large-patch16-{256,384,512}) their 64 text positions, where they gave 512: a random-init model built from one of these names takes at most 64 tokens, and longerinput_idsraise. Other names keep 512 positions.- SigLip2 honours
hidden_act:"gelu_pytorch_tanh"and"gelu_new"give tanh GELU,"gelu"exact GELU, and any other value raisesValueErrorwhen the model is built.hidden_actwas ignored (every MLP used exact GELU), so a config withhidden_act="quick_gelu"or"relu"built and ran. - With the legacy TorchScript ONNX exporter (
torch.onnx.export(..., dynamo=False)), exporting aNaFlexfrom an example input whose patch grid is smaller than its position table along an axis raisesUnsupportedOperatorError, because such a grid is now resized with antialiasing (aten::_upsample_bilinear2d_aa). It exported a plain bilinear resize, whose values were wrong at that size. An example grid at least as large as the table along both axes still exports, and its graph is exact for such grids only. The dynamo exporter (dynamo=True) exports the antialiased resize; with dynamic H and W, export from an example whose grid is smaller than the table along both axes, as theNaFlexnote says.
Some vision-language outputs of
kornia.modelschange with no error, so weights fine-tuned with an earlier kornia give other outputs:- SigLip2's MLPs use the tanh approximation of GELU by default (
hidden_act="gelu_pytorch_tanh", the new config default), as the SigLIP 2 checkpoints do, where every MLP used exact GELU;hidden_act="gelu"keeps exact GELU. SigLip2ImagePreprocessorand itsfrom_configresize bilinearly by default, as the SigLIP 2 checkpoints do ("resample": 2in theirpreprocessor_config.json), where they resized bicubically. That includes the SigLIP 1 checkpointgoogle/siglip-base-patch16-224, whose preprocessor resizes bicubically: passinterpolation="bicubic"for it.PaliGemmafollows Gemma: it scales the text embeddings bysqrt(hidden_size), its embedding's padding row is the newPaliGemmaConfig.pad_token_id(default 0), its MLP uses tanh GELU, andGemmaRMSNormmultiplies by1 + weightin float32 before casting; none of these held before. The padding row wasignore_index = -100, which wrapped to rowvocab_size - 100, a real token whose embedding was zeroed and received no gradient.NaFlexresizes its position table to the image's patch grid whenever that grid is not the table's own square grid, with bilinear interpolation as transformers' SigLIP 2 does, antialiased when the grid is smaller than the table along an axis (transformers always antialiases, which changes nothing when no axis shrinks). It added a table unresized in raster order whenever the patch count matched (4.27 off for an 8 x 32 grid and a 16 x 16 table), and did not antialias a downsampled axis (0.81 off).
(#6044)
equalize,equalize3dandequalize_clahenow raiseTypeCheckError(aTypeError) for an integer or boolean image, with a message that names the dtype and the conversionimage.float() / 255, as the[0, 1]adjustment functions do since #5983; the check is skipped underdisable_checks(). Before, their[0, 1]range check let through an integer or boolean mask whose values are all 0 or 1:equalizeandequalize3dreturned the same result as for the floating-point mask and now raise, so convert such a mask with.float()first;equalize_clahereturned values that did not match the floating-point mask's (by up to almost 1.0 atclip_limit=0), and a boolean mask made it raise a rawNotImplementedError. Auint8image with values above 1 used to raise aRuntimeErrorand now raises theTypeCheckError, whichexcept RuntimeErrordoes not catch. Floating-point input is unchanged, and out-of-range floating-point input still raises theRuntimeErrornaming the range. (#6047)Vision-language calls of
kornia.modelsthat ran now raise, or read a name or a mask differently:SigLip2Config.from_name,SigLip2Builder.from_nameandSigLip2Builder.from_pretrained_hfraiseValueErrorfor a name outside their supported list whose architecture its parts cannot give: agoogle/name, such asgoogle/siglip2-so400m-patch14-384or the SigLIP 1google/siglip-large-patch16-256; a SigLIP 1 repository under another owner, such assomeone/siglip-large-patch16-256, unless it is a fine-tune or mirror ofgoogle/siglip-base-patch16-224; and a repository part with the wordso400m,giantornaflex, orpatch<n>for a patch size other than 16.from_namereturned a base or large patch-16 SigLIP 2 model of the wrong shape or vocabulary for these names, andfrom_pretrained_hffailed on loading its weights.- These calls read the architecture of a name outside their supported list from the whole words of its repository part only, a word being a run of letters and digits:
large-models/siglip2-base-patch16-224andsomeone/siglip2-base-patch16-224-enlargedare base, where anylargein the name made them large. MoonViTAttention,MoonViTandKimiVLModelread a 2-D attention mask as(B, N)padding and a 3-D one as(B, N, N), one mask per sample, asSigLip2Attentiondoes, whatever the batch size, and raise for one whose leading dimension is neither the batch size nor 1. A per-head(H, N, N)mask and an(N, N)mask shared by the batch were passed toscaled_dot_product_attentionas they were, so they raise now unlessBequalsHorN, where they are read per sample: pass them as(1, H, N, N)and(1, 1, N, N).
(#6051)
Some calls of the vision backbones of
kornia.modelsthat ran now raise:VisionTransformerandSigLip2VisionEmbeddings, and soSigLip2VisionModel,SigLip2ModelandPaliGemma, raiseValueErrorfor an input whose height and width are not bothimage_size, andVisionTransformeralso for a channel count other thanin_channels. With abackbone,VisionTransformerchecks the backbone's token grid instead: it raisesValueErrorwhen the grid is not the one the backbone gives for animage_sizeinput, which the position embeddings are built for, and inputs of other sizes that give that grid, through adaptive pooling for example, keep working. An input whose patch count happened to fit the position table returned a result with misplaced position embeddings or dropped columns: forVisionTransformer(image_size=224, patch_size=16),(1, 3, 112, 448)added the 14 x 14 positions to a 7 x 28 patch grid and(1, 3, 224, 239)dropped its last 15 columns. Other sizes and a channel mismatch raisedRuntimeErrorinside the model, for example(1, 3, 240, 240)and(1, 1, 224, 224); theValueErrorofVisionTransformerfired only when both the size and the channel count were wrong.TinyViTraisesValueErrorfor an input whose token grid is not the one its attention stages are built for, that of animg_sizeximg_sizeimage; sides fromimg_size - 7toimg_sizeround to that grid and keep working. An input with the same number of tokens on another grid returned a result with its tokens read as the wrong grid: atimg_size=224,(1, 3, 112, 448)returned(1, 1000)from a 14 x 56 grid read as 28 x 28, and withmobile_sam=Trueatimg_size=1024, a(1, 3, 512, 2048)input returned feature maps. Other sizes raisedRuntimeError, for example(1, 3, 224, 256).TinyViT.from_config("21m", ...)builds the"in1k_384"and"in1k_512"checkpoints with 12- and 16-px windows (see the bug fixes), so a state dict saved from such a model built before, with 7-px windows, no longer loads into the model the same call builds:load_state_dictraisesRuntimeErrorfor the size of every attention bias,(6, 49)against(6, 144)inlayers.1.blocks.0.attn.attention_biasesat 384. Passwindow_sizes=[7, 7, 14, 7]to build the model that state dict belongs to.
(#6056)
HomographyTrackerreturns and stores every homography,no_match()'s included, in float32 for afloat16orbfloat16target and in the target's dtype otherwise, whatever the dtype of the frame, of the matcher's keypoints or of aprevious_homographyassigned from outside. A homography found by matching used to have the keypoints' dtype: afloat64tracker whose matcher returns float32 keypoints returned float32 homographies, and a float32 tracker given float64 frames, by a matcher that returns keypoints in the frame's dtype, returned float64 ones.no_match()returned the half dtype. The tracker now also tracks withfloat16andbfloat16matchers. The second frame raised: inwarp_perspective, which got the half frame with the float32 inverse of the first frame's float32 homography, or inlinalg.invfor a halfprevious_homography. The prior is now inverted and the frame warped in float32, and the fast matcher gets the warped frame in the frame's dtype. Half keypoints are widened to float32 before RANSAC; a bfloat16 fit was rounded to bfloat16 and moved the tracked points by pixels. The caller's autocast no longer runs the tracker's own warp, keypoint mapping andransacfit in half precision; underbfloat16autocast the keypoint mapping was up to 7.6 px off on a 600 px frame, and aRANSAC(local_optimization="dlt")fit was several pixels off. A float32 tracker whose matcher returns float64 keypoints, or with a float64previous_homographyassigned from outside, raised intrack_next_frame. (#6058)ONNXSequentialgiventarget_opset_versionortarget_ir_versionwithoutauto_ir_version_conversion=Truenow converts the models; the targets used to be ignored, and the call ran on the models as loaded. Where the conversion fails, the call now raises its error: the ONNX version converter's where it has no adapter for an operator (for exampleResizeorPadfrom opset 18 to 17),onnx.checker's where the converted graph is invalid (for exampleUnrecognized attribute: noop_with_empty_axes for operator ReduceMeanfrom opset 18 to 17), or ONNX Runtime's where it does not support the target (an IR version above its own). (#6134)Two
to_onnxexports change in ways a caller can see:- An
EdgeDetectorwhoseResizePostProcessorresizes withinterpolation_mode="area"now raises aValueErrorinto_onnxwith the pre- and post-processor, and so does a directtorch.onnx.export(detector, ...)on the TorchScript exporter and, from torch 2.9, on the dynamo exporter (inside that exporter's own error). It used to export a graph that returned the maps at the pre-processor's size."area"resizing is adaptive average pooling, which cannot be exported to the input's size: build the post-processor with"bilinear","bicubic","nearest"or"nearest-exact"to export the detector. Eagerforwardwith"area"is unchanged. ObjectDetector.to_onnx(include_pre_and_post_processor=False)of an RT-DETR model names its outputspred_logitsandpred_boxes. The logits used to be the graph'soutput, and the boxes came out under an exporter-generated name, such as2814from the TorchScript exporter, so code that readsoutputby name, for examplesession.run(["output"], ...), is now refused by ONNX Runtime. Readpred_logitsinstead, or passoutput_namestoto_onnxto choose both names.
(#6135)
- An
BoxFiltering.to_onnx()without aconfidence_thresholdon the legacy (TorchScript) exporter used to export a second float64 input,onnx::Cast_1, for the threshold, which the caller fed. The graph now has the boxes as its only input and filters at the eager default of0.0, so feeding two inputs raises; build the filter withconfidence_thresholdto export a different threshold. (#6159)zca_meanreturns, andZCAWhitening.fitstores, the mean and transforms in float32 for float16 and bfloat16 inputs; previously they were in the input dtype, whose rounding could corrupt rank-deficient whitening.linear_transform,zca_whiten, andZCAWhiteningstill return the input dtype, computing half-input transforms in float32. Callers applyingzca_meanresults directly must promote half inputs to float32 or uselinear_transform. Explicitly casting fitted buffers to half precision still discards their accuracy. (#6212)blur_pool2d,max_blur_pool2d,edge_aware_blur_pool2d,BlurPool2D,MaxBlurPool2DandEdgeAwareBlurPool2Draise aTypeCheckError(aTypeError) for an integer or bool input, naming the dtype. The blur pools are network layers and expect a floating feature map; unlike the image filters (#5669) they do not promote integer input. Before, the binomial kernel was cast to the input's dtype, which truncated every tap to 0. On CPU,BlurPool2DandMaxBlurPool2Dreturned an all-zero integer tensor without an error, and the functions raised aRuntimeErrordtype mismatch. On CUDA, every entry point raised aRuntimeErrorfrom cuDNN or the max pool.except RuntimeErrorno longer catches the error. The check is skipped underdisable_checks()in Python; scripted calls always validate, as in Kornia's core checks.BlurPool2DandMaxBlurPool2Dremain scriptable. Floating input is unchanged. (#6270)Kornia's minimum supported PyTorch version rises to 2.5.1. Previously the declared floor was 2.0.0; PR-time CI has only ever exercised 2.5.1 and newer, and this same change retires the scheduled-CI legs that tested anything older. Installing kornia now requires
torch>=2.5.1; atorchinstall below that version no longer satisfies the dependency, andpip/uvwill refuse to resolve it. (#4197)Non-maxima suppression applies one border rule at every window size.
NonMaximaSuppression2d/nms2dwith a window larger than(7, 7), andNonMaximaSuppression3d/nms3d, no longer report maxima inside the(k - 1) // 2border strip. Previously the general path replicate-padded its input, so a position whose window ran off an edge was judged against duplicated copies of the edge values, which both fabricated plateaus that suppressed genuine maxima and hid genuine neighbours that should have suppressed spurious ones; the(3, 3),(5, 5)and(7, 7)paths meanwhile rejected the strip outright, so the two disagreed about the same pixel. The explicit paths' rule is now the rule everywhere. The kornia detectors that callnms2dalready reject that strip: ALIKED zeroes itsnms_radiusborder by hand after the call, DISK and XFeat call it with a(5, 5)window by default, whose explicit path already had this rule, andMultiResolutionDetectorzeroes a 15 px border in its output, which is wider than the strip of its default(15, 15)window. No detector output changes with its default configuration. (#4239, #4242)Removed
kornia.to_tensorflow(),kornia.to_jax()andkornia.to_numpy(), along with the multi-framework-support advertising in the README and the docs landing page. These functions used to lazily transpile the library to TensorFlow, JAX or NumPy through the third-partyivypackage (an optionaldev/docsdependency, now also removed). Testing in September 2026 found the integration unreliable across all three targets — a checkout-path crash in Ivy's module walker, a torch/triton segfault whentransformersis also installed, an undocumentedflaxrequirement for JAX, and ajaxlib/numpyAPI-compatibility break — against Ivy's latest release (1.0.0.5, June 2025), with the upstream project showing little ongoing maintenance. The three names still import, at the top level and fromkornia.transpiler, sofrom kornia import to_jaxandhasattr(kornia, "to_jax")keep working; calling any of them raises aRuntimeErrorthat says what was removed and links the page below. Seeget-started/multi-framework-supportfor what was tested and why. (#4196)Removed the unused
preprocess_boxeshelper, which had no public export or caller. (#4181, #4321)The shape guards of
normalize_homographyanddenormalize_homographynow reject everything but a(3, 3)/(B, 3, 3)matrix, andnormalize_homography3d's everything but a(4, 4)/(B, 4, 4)one (#3999). A rank-4 input used to pass the guard and come back with its rank unchanged —normalize_homography(eye(3).expand(2, 4, 3, 3), (4, 5), (8, 9))returned a(2, 4, 3, 3)matrix and now raisesValueError. A wrong-sized input, such as a(B, 4, 4)to the 2-D functions, used to pass the guard and fail later insidematmul; it now raises at the guard, andnormalize_homography3d's message namesBx4x4instead ofBx3x3. Unbatched(3, 3)/(4, 4)matrices are still accepted and still promoted to a leading batch of 1.One side effect reaches tracing callers: the rewritten guard evaluates its shape comparison unconditionally, where the old
or-form short-circuited past it for a rank-3 input, sotorch.jit.traceof any of the three functions now emits aTracerWarningabout converting a tensor to a Python boolean that it did not emit before. The guard is a static check and the traced graph is unchanged — the warning is noise, not a correctness signal.AUTUMNis dropped fromkornia.color.__all__(#4143). The class was deprecated in 0.7.2 in favour ofColorMap(base='autumn')and removed by #3432, which left the__all__entry behind. Since that removalfrom kornia.color import AUTUMNhas raisedAttributeErrorandfrom kornia.color import *has failed on it, so nothing that works today stops working — the entry named a binding that no longer existed. Callers still reaching for the class should useColorMap(base='autumn').DescriptorMatcherWithSteerer(normalize=True),DiscreteSteerer.steer_descriptions(normalize=True)and theMKDdescriptors, likeSIFTDescriptorandHardNet, L2-normalise a float16 input in float32 and cast back, so an all-zero float16 descriptor normalises to zero instead of NaN (the 1e-12 guard underflows in float16) and a descriptor whose norm sits below the smallest float16 normal still normalises to one rather than being clamped.PatchDominantGradientOrientation, and with itLAFOrienter, take the gradient magnitude and orientation of a float16 patch through the same float32 stepSIFTDescriptoruses, so a flat patch yields a finite angle instead of a NaN LAF -- which reached a filled detection slot in a float16SIFTFeaturepipeline and poisoned that descriptor row.SIFTDescriptor(rootsift=True)andDenseSIFTDescriptor(rootsift=True)compute the RootSIFT square root in float32 for a float16 input: the float16-representable guard would have read every empty bin assqrt(6.1e-5)and biased the descriptor norm to ~1.004. Float32 and float64 outputs are unchanged.KimiVLBuilder.from_pretrained_hf()andSigLip2Builder.from_pretrained_hf()cache their checkpoint where every other kornia checkpoint lives.cache_dir=Noneused to mean the HuggingFace cache (~/.cache/huggingface/hub/models--<owner>--<name>/snapshots/<sha>/model.safetensors) and now means torch's hub directory (<torch hub dir>/checkpoints/<owner>--<name>--model.safetensors); an explicitcache_dirused to hold the samemodels--<owner>--<name>/…tree and now holds the flat<owner>--<name>--model.safetensorsfile. Either way the firstfrom_pretrained_hf()call after upgrading re-downloads the checkpoint (854 MB for KimiVL, ~1.5 GB for SigLIP2) even for users who already had it. (#4293)LocalFeatureMatcherno longer matches the zero-LAF slots with which a fixed-shape detector pads an under-filled result, and now forwards its documentedmask0/mask1inputs to feature extraction.nnandmnncallers can therefore receive fewer correspondences: identical descriptors sampled at padded origin frames are no longer reported as matches. Three-dimensional(B, H, W)masks keep working and are promoted to the detectors'(B, 1, H, W)form; four-dimensional masks are forwarded unchanged. Because the masks now reach the detector, they are subject to its check: a mask that is not at the image's spatial size, which used to be ignored, is rejected. A floating-point mask changes meaning inScaleSpaceDetector-based pipelines too; see the mask semantics entry under Bug fixes.MKDDescriptorruns infloat16andbfloat16. Its gradient-embedding and spatial-encoding stages were held in a plaindict, so.to(device, dtype)never reached their buffers and a half-precision input failed at the whitening matmul withexpected m1 and m2 to have the same dtype. They are now annn.ModuleDict; float32 and float64 outputs are byte-identical, andstate_dict()gains the stages' buffer keys (feats.<parametrization>.*). A state dict saved by an earlier release still loads withstrict=True: those buffers are derived from the constructor arguments, and when a state dict has nofeats.*key at all they are filled in from the module being loaded into (one that has some and lost one is reported bystrict=True, as for any other missing key). The reverse is not covered: a state dict saved by this release carries thefeats.*keys and failsstrict=Trueon an earlier kornia, which does not know them; load it withstrict=Falsethere.MultiResolutionDetectorandKeyNetDetectorchange their output: padded slots now read as a zero response and a zero LAF instead oftorch.finfo(dtype).min / 2and an arbitrary border coordinate; the previously inertmaskargument now suppresses detections, and must be(1 or B, 1, H, W)at the image size -- a(B, H, W)mask passed directly to either detector, which was accepted only because it went unread, is rejected; half-precision input yields half-precision LAFs; the returned shape is alwaysnum_features; a multi-channel response is rejected instead of producing invalid or duplicate LAFs; a negativescore_thresholdis rejected withValueError; anddetectenforces its documented(1, C, H, W)input. Themaskof both detectors is now "where a detection may be": a boolean or integer mask is binary (a 0/255 mask no longer scales the responses by 255), a floating-point mask weights the scores, it is resampled conservatively so a thin zero region survives the coarse levels, and it is applied to the non-maxima-suppression output, so its edge cannot manufacture maxima (#4102). A mask whose dtype differs from the image no longer promotes the response dtype, and a mask that is not(1 or B, 1, H, W)for the image is rejected instead of stretched or broadcast onto the wrong axis -- that includes an image-shaped(1, C, H, W)mask and a coarse(N, H/8, W/8)one, whichLocalFeatureMatcherused to accept and silently ignore (the old docstring said "same shape as the input image") and now forwards to the detector's check.ScaleSpaceDetectoradditionally stops returning its own top-K sentinel as a detection for a batch, no longer returns a frame for a candidate its border check rejected, and re-checks a sub-pixel-refined centre against the mask; a short result is sorted in both detectors.detect_features_on_single_level's newmaskparameter is keyword-only, and it now requires the response map to have the level's spatial size: a valid-convolution response net that returned a smaller map had every keypoint decoded one pixel off its peak, since a response index is read as a level pixel with no offset, and is rejected with a message rather than silently misplaced. See the entry under Bug fixes (#4089, #4090, #4091) for the details and the migration.PatchSequentialnow preserves the batch size in both padding modes.samepreserves the input spatial size andvalidkeeps only the complete, centred grid region. Previously, a(2,3,8,8)input on a(3,3)grid produced(2,3,7,7)withsame(now(2,3,8,8)) and(2,3,8,8)withvalid(now(2,3,6,6)). Withvalid, a(2,3,6,8)input on a(4,4)grid changed the batch size to produce(3,3,6,6); it now produces(2,3,4,8). Geometric children may move temporarily padded zeroes into the retained image.restore_from_patchesnow defaults toself.grid_sizeinstead of(4,4)and raisesValueErrorfor a mismatched patch count instead of inferring a different batch size or failing later in reshape.forward_parametersaccepts both image(B,C,H,W)and patch(B,N,C,h,w)shapes; parameter generation now coversB*Npatch rows rather thanB*C, so fixed-seed outputs and RNG consumption can change. Refs #4421. (#4460)SegmentationModelsBuilder.build()no longer importssegmentation_models_pytorch(smp). It used to takemodel_name,encoder_name,encoder_weights,in_channels,classes,activationand**kwargs, import smp lazily, instantiate the smp architecture and look up the encoder's preprocessing parameters itself. It now takes a constructednn.Moduleand the encoder's preprocessing-parameter dictionary (build(model, preproc_params=None, name="segmentation_model")), wherepreproc_paramsis whatsmp.encoders.get_preprocessing_params(encoder_name)returns; build the smp network and fetch its parameters yourself. Kornia no longer imports smp anywhere, andkornia.core.external.segmentation_models_pytorchis gone.SemanticSegmentationgained the__init__(model, pre_processor, post_processor, name=None)its siblings have, so the container the builder returns can be instantiated (it was abstract before). Theinput_range: [0, 255]preprocessing step is nowkornia.enhance.Rescale(255.0), a multiply by 255, instead of aNormalizeby a stored1/255: bfloat16 rounds that reciprocal to a ~254.0 multiplier (0.5 mapped to 127.0 instead of 127.5), and float32 outputs of that step move by at most one ulp. (#4301)create_meshgridandcreate_meshgrid3dreturn different normalized coordinates atfloat16andbfloat16. They used to evaluate(xs / (size - 1) - 0.5) * 2as three half-precision ops in eager, rounding after each, and to materialize the half ramp before the graph-capture branch widened it;torch.compileinstead computed the chain infloat32and rounded once, and folded the narrow-then-widen round trip away so that above2 ** pthe two paths divided different numerators. A half-precision grid therefore changed the moment a model was wrapped intorch.compile-- by up to 0.0117 in the[-1, 1]range atbfloat16width 300 and 0.0156 at width 6000. A normalized half-precision grid is now built and normalized infloat32and narrowed once, so eager, traced and compiled grids agree; the eager values move onto the correctly rounded side, which is the numeric change.float32,float64and integer grids and the pixel ramp are bit-for-bit unchanged, since none of them widen. On CUDA atfloat16up to one ulp of the coordinate dtype can still differ, because ATen's and triton'sfloat32division are not bit-identical;bfloat16absorbs it and the CPU kernels agree exactly. The Linux CPU half-precision baselines move with it.HomographyWarperbuilds its precomputed grid infloat32and its on-the-fly grid in the input dtype, and the two now agree, which fixestest_homography_warperat both dtypes andtest_translation[shape1]atfloat16. Atbfloat16test_translation[shape0]and[shape2]join theshape1andshape3entries already recorded: that test'satol=1e-4is out of reach for all four of its shapes there, and the two that passed did so only because the old grid's larger error round-tripped throughgrid_sample'sbfloat16unnormalize as an exact pixel index. Refs #4030. (#4231)ellipse_to_lafno longer raises on a degenerate ellipse. One whoseaorcis0after rounding to the input dtype makes the matrix being inverted singular; the batchedtorch.inverseit now replaces (see Bug fixes) failed the whole call withlinalg.LinAlgError, and the closed form returns non-finite values in that LAF instead, leaving the other rows of the batch usable. Callers that relied on the exception to reject bad input -- reading Oxford-format.ellipsefiles, say -- should test the result withkornia.feature.laf_is_valid, since an invalid LAF otherwise propagates silently throughget_laf_scaleand into matching. Detecting the degenerate rows up front would cost a device synchronisation and thefullgraph=Truecapture, so it is left to the caller. The in-repo affine estimators handle invalid candidates before nonlinear LAF operations.PatchAffineShapeEstimatorcomputes half-precision gradients, Gaussian weights, moments, and normalization infloat32, preserving valid anisotropic shapes that would otherwise underflow;LAFAffineShapeEstimatorsanitizes non-positive-definite ellipse coefficients before conversion; and both it andLAFAffNetShapeEstimatoruse a finite fallback with finite backward. The fallback is the input LAF whenpreserve_orientation=Trueand its upright form otherwise; a finite zero-scale input keeps its center and zero affine block.extract_patches_from_pyramidnow samples ordinary-sized inputs once from a packed pyramid atlas instead of sampling every LAF at every pyramid level. A statically selected levelwise fallback keeps atlases larger than 128 MiB from becoming a memory hazard. LAFs whose nominal level is coarser than the last usable pyramid level now sample that actual coarsest level; they previously returned an all-zero patch. Forfloat16andbfloat16inputs the whole pyramid -- padding,pyrdown, coordinate arithmetic and sampling -- runs infloat32and the patches are cast back, on every device: this avoids the normalized-coordinate precision loss caused by the wider atlas, keeps the extraction offreplication_pad2d/grid_sampler_2dkernels that old torch builds lack for half dtypes on the CPU (torch <= 2.5.1 would otherwise crash), and avoids recasting the full atlas on every sampling chunk.extract_patches_simplecomputes its sampling grid infloat32for reduced-precision inputs on every device for the same reason -- its output matches the pyramid extractor's level-0 output again. Half-precision patches therefore change on CUDA and MPS as well as the CPU, and floating-point results are not byte-identical to the former levelwise implementation. The universalfloat32sampling is a real cost where the native half kernels were fine: on CUDA,float16extract_patches_simpleis roughly 2x slower at high N, and peak CUDA memory rises at moderate N (the atlas plus the one-time upcast copy) even though the high-N peaks drop. Both extractors now reject an image/LAF batch-size mismatch at the boundary with a clear error: former releases raised an internalgrid_sampleerror for most batch mixes, except a smaller LAF batch, where both extractors silently returned patches for only the firstmin(B_img, B_laf)images. A LAF on another device is moved once to the image, while a different LAF dtype is promoted with the image dtype for grid arithmetic rather than rejected or rounded down; this preserves mixed-precision autocast pipelines and subpixel LAF coordinates. Patches still return with the image's dtype and device. Both extractors chunk their sampling along N, in the spirit ofbatched_forward, so the folded(B, N*PS, PS, 2)grid and channel-scaled sampled chunk each stay within a fixed 64 MiB budget (remap intermediates can still make the total peak a multiple of that). Batched high-N extraction now peaks below even the pre-batching per-image loop (468 MiB against 495 MiB onmainfor B=8, N=4000, PS=32 on a 512x512 float32 image, where the unchunked atlas peaked at 1.24 GiB), eager throughput stays within5% of the unchunked atlas, and float32/float64 patches are bitwise identical to it; a1.5x the unbounded atlas latency at B=8, N=2000 on CPU inductor, still ~10x faster than the per-level loop it replaces). Both extractors return an emptytorch.compiled call whose grid exceeds the budget splits into severalgrid_samplecalls ((B, N, CH, PS, PS)tensor forB == 0orN == 0instead of raising from insideaffine_grid--extract_patches_from_pyramidwithB == 0returned the empty result before the batched rewrite described under Bug fixes regressed it; every other empty combination raised on all prior releases.extract_patches_from_pyramidnow also accepts a LAF on a different device than the image, asextract_patches_simplealways has, and returns patches on the image's device; both extractors move the LAF to the image's device up front, so a cross-device call now samples on the image's device and matches the same-device result (extract_patches_simplepreviously built the full sampling grid on the LAF's device).kornia.contrib.BoxMotTrackeris removed, together with thekornia.contrib.boxmot_trackermodule. It wrapped the boxmot tracker zoo around a kornia detector, but called the boxmot 10.x API (boxmot.DeepOCSORT(model_weights=..., device=..., fp16=...)), and no boxmot release that installs alongside the torch versions kornia supports (torch>=2.5.1) provides it, so the class could not be instantiated on any supported stack (see #4320). Track with boxmot directly, feeding it the output of a kornia detector such asRTDETRDetectorBuilder.kornia.core.external.boxmotis gone with it. (#4301)kornia.core.external.transformerswas removed; it was aLazyLoaderhandle no kornia code used. Previouslyfrom kornia.core.external import transformersgave a lazy proxy that importedtransformerson first attribute access; that name no longer exists, so importtransformersdirectly instead. (#4301)kornia_rs>=0.2.0is required; the floor used to be 0.1.9. kornia_rs 0.1.11 relocated its image I/O and 0.1.12/0.1.13 lack the libjpeg-turbo reader, so no single call site works across 0.1.9-0.1.14; rather than dispatch per version, kornia calls the current layout. Runpip install -U kornia_rsin an environment that pins an older one. (#4326)nms2d(x, (1, 1))andnms3d(x, (1, 1, 1))returnxunchanged. A unit window has no neighbours, so nothing can be suppressed; the old 2-D result was an artifact of the zeroed centre tap of the convolution kernel summing to0.0, while the old 3-D path raised because of #4241. (#4242)
:rocket: [0.6.11] - 2022-03-28
:new: New Features
- add
DISKlocal feature by @jatentaki in https://github.com/kornia/kornia/pull/2285 - Add Joint Bilateral Filter by @gau-nernst https://github.com/kornia/kornia/pull/2244
- Add Bilateral Filter by @gau-nernst https://github.com/kornia/kornia/pull/2242
- Add random snow by @just1ce415 https://github.com/kornia/kornia/pull/2229
:rocket: [0.6.10] - 2022-02-17
:new: New Features
- add
depth_from_disparityfunction by @pri1311 in https://github.com/kornia/kornia/pull/2096 - Add Vector2 by @cjpurackal in https://github.com/kornia/kornia/pull/2134
- Add 3D-SSIM loss by @pri1311 in https://github.com/kornia/kornia/pull/2130
- [Feat] Initiate AutoAugment modules by @shijianjian in https://github.com/kornia/kornia/pull/2181
- Add Common Regression Losses by @ChristophReich1996 in https://github.com/kornia/kornia/pull/2109
- Add
integral_imageandintegral_tensorby @AnimeshMaheshwari22 in https://github.com/kornia/kornia/pull/1779
:lady_beetle: Bug fixes
- Fix AugmentationSequential to return list of boxes by @johnnv1 in https://github.com/kornia/kornia/pull/2114
- Fix support for (*, 3, H, W) tensors in yuv by @ChristophReich1996 in https://github.com/kornia/kornia/pull/2108
- fix TensorWrapper serialization by @edgarriba in https://github.com/kornia/kornia/pull/2132
- Split the half precision tests workflow by @johnnv1 in https://github.com/kornia/kornia/pull/2118
- Fixed DoG accuracy, add
upscale_doubleby @vicsyl in https://github.com/kornia/kornia/pull/2105 - Added Face detection Interactive demo by @jeffin07 in https://github.com/kornia/kornia/pull/2142
- Bump pytest from 7.2.0 to 7.2.1 by @dependabot in https://github.com/kornia/kornia/pull/2148
- add SSIM3D and
depth_from_disparityto docs by @pri1311 in https://github.com/kornia/kornia/pull/2150 - Explicitly cast output to input type to avoid type mismatch errors by @JanSellner in https://github.com/kornia/kornia/pull/1842
- Fix params computation for
LongestMaxSizeandSmallestMaxSizeby @johnnv1 in https://github.com/kornia/kornia/pull/2131 - torch_version_geq -> torch_version_ge according to todo by @ducha-aiki in https://github.com/kornia/kornia/pull/2157
- fix doc build -
sphinx-autodoc-typehints==1.21.3by @johnnv1 in https://github.com/kornia/kornia/pull/2159 - ScaleSpaceDetector -> Fast ScaleSpaceDetector by @ducha-aiki in https://github.com/kornia/kornia/pull/2154
- Improve losses tests, add
TestSSIM3d, andBaseTester.gradcheckby @johnnv1 in https://github.com/kornia/kornia/pull/2152 - modify comments of rgb and lab conversion by @gravitychen in https://github.com/kornia/kornia/pull/2153
- add repr and getitem to vector by @cjpurackal in https://github.com/kornia/kornia/pull/2163
- Fix adalam-config by @ducha-aiki in https://github.com/kornia/kornia/pull/2170
- Fix docs of
boxes,MultiResolutionDetector.apply colormap,AugmentationSequentialby @johnnv1 in https://github.com/kornia/kornia/pull/2167 - add exception test for se2 + small bug fix by @cjpurackal in https://github.com/kornia/kornia/pull/2160
- Fix MobileViT by @chinhsuanwu in https://github.com/kornia/kornia/pull/2172
- Fix output types of augmentations on autocast regions by @johnnv1 in https://github.com/kornia/kornia/pull/2168
- Fix planckian jitter for cuda by @johnnv1 in https://github.com/kornia/kornia/pull/2177
- Fix: resample method None default missing for inverse masks by @miquelmarti in https://github.com/kornia/kornia/pull/2185
- Move padding_size to device in pad for boxes by @miquelmarti in https://github.com/kornia/kornia/pull/2197
- Return boxes tensor directly if no boxes by @miquelmarti in https://github.com/kornia/kornia/pull/2196
- Make value an attribute of RandomErasing instances again by @miquelmarti in https://github.com/kornia/kornia/pull/2195
- TensorWrapper bug fix + add radd, rmul, rsub by @cjpurackal in https://github.com/kornia/kornia/pull/2190
- Fix/repr bug by @neyazbasheer in https://github.com/kornia/kornia/pull/2207
- Replace
assert_allclosebyassert_closeby @johnnv1 in https://github.com/kornia/kornia/pull/2210 - Fix random crop for keypoints on CUDA device by @johnnv1 in https://github.com/kornia/kornia/pull/2209
- Remove outdated augmentation example by @johnnv1 in https://github.com/kornia/kornia/pull/2206
- Fix CUDA failing tests of same device on
Augmentationsby @johnnv1 in https://github.com/kornia/kornia/pull/2215
:zap: Improvements
- add
PadToto docs by @johnnv1 in https://github.com/kornia/kornia/pull/2122 - add colormap and
apply_ColorMapfor integer tensor by @johnnv1 in https://github.com/kornia/kornia/pull/1996 - Fix numerical stability for binary focal loss by @zimka in https://github.com/kornia/kornia/pull/2125
- Add RandomGaussianBlur with instance-level gaussian kernel generation by @juliendenize in https://github.com/kornia/kornia/pull/1663
- add transparent pad to
CenterCropdocs example by @johnnv1 in https://github.com/kornia/kornia/pull/2124 - Ensure support to Python 3.9 and 3.10 by @johnnv1 in https://github.com/kornia/kornia/pull/2025
- improve
TestUpscaleDoubleby @johnnv1 in https://github.com/kornia/kornia/pull/2147 - DataKey: add 'image' as alias of 'input' by @adamjstewart in https://github.com/kornia/kornia/pull/2193
- add
fail-fast:falseas default on tests workflow by @johnnv1 in https://github.com/kornia/kornia/pull/2146 [enhance] improve flipping and cropping speed by @shijianjian in https://github.com/kornia/kornia/pull/2179 - Replace jit test method in favor of dynamo in
BaseTesterby @johnnv1 in https://github.com/kornia/kornia/pull/2120 - Small refactor on
filtersmodule: Dropping JIT support by @johnnv1 in https://github.com/kornia/kornia/pull/2187 - Augmentation Base Refactor by @shijianjian in https://github.com/kornia/kornia/pull/2117
Deprecation
- move kornia check api to kornia.core.check by @edgarriba in https://github.com/kornia/kornia/pull/2143
- Remove py 3.7 for nightly CI by @johnnv1 in https://github.com/kornia/kornia/pull/2204
:rocket: [0.6.9] - 2022-12-21
:new: New Features
- Feat/randombrightness contrast saturation hue by @duc12111 in https://github.com/kornia/kornia/pull/1955
- Liegroups by @edgarriba in https://github.com/kornia/kornia/pull/1887
- Add sepia by @johnnv1 in https://github.com/kornia/kornia/pull/1947
- Normalize with intrinsics by @ducha-aiki in https://github.com/kornia/kornia/pull/1727
- [feat] liegroup so2 by @cjpurackal in https://github.com/kornia/kornia/pull/1973
- [feat] adjoint for se2, so2 by @cjpurackal in https://github.com/kornia/kornia/pull/2101
- add trans, trans_x, trans_y + minor changes se2 by @cjpurackal in https://github.com/kornia/kornia/pull/2103
- Motion blur by @nitaifingerhut in https://github.com/kornia/kornia/pull/2075
- Add
HyperplaneandRayAPI by @edgarriba in https://github.com/kornia/kornia/pull/1963
:lady_beetle: Bug fixes
- Quaternion pow bug fix (div by zero) by @cjpurackal in https://github.com/kornia/kornia/pull/1946
- fix cuda init by @ducha-aiki in https://github.com/kornia/kornia/pull/1953
- Documentation: proper Sørensen–Dice coefficient by @sergiev in https://github.com/kornia/kornia/pull/1961
- quaternion, so3 and se3 as non batched by @edgarriba in https://github.com/kornia/kornia/pull/1997
- Bump pytest-mypy from 0.10.0 to 0.10.1 by @dependabot in https://github.com/kornia/kornia/pull/2005
- Join the gh-actions for docs by @johnnv1 in https://github.com/kornia/kornia/pull/2003
- [pre-commit.ci] pre-commit suggestions by @pre-commit-ci in https://github.com/kornia/kornia/pull/2010
- So2 bug fix by @cjpurackal in https://github.com/kornia/kornia/pull/2015
- Fix type annotation for torch 1.13.0 by @johnnv1 in https://github.com/kornia/kornia/pull/2023
- Fix an error in
match_smnnby @anstadnik in https://github.com/kornia/kornia/pull/2020 - Set equal_nan to False in assert_close by @edgarriba in https://github.com/kornia/kornia/pull/1986
:zap: Improvements
- minor improvements to So3 by @cjpurackal in https://github.com/kornia/kornia/pull/1966
- Add
TensorWrapper,Vector3,Scalarand improvements infit_planeby @edgarriba in https://github.com/kornia/kornia/pull/ - [feat] add vee to so2, se2 by @cjpurackal in https://github.com/kornia/kornia/pull/2091
- Remove deprecated code in
kornia.augmentationby @johnnv1 in https://github.com/kornia/kornia/pull/2052 - [feat] Implement se2 by @cjpurackal in https://github.com/kornia/kornia/pull/2019
- add quaternion to euler conversion by @edgarriba in https://github.com/kornia/kornia/pull/1994
- use resample instead of mode argument in RandomElasticTransform per default by @JanSellner in https://github.com/kornia/kornia/pull/2017
- replacing .repeat(...) with .expand(...) by @nitaifingerhut in https://github.com/kornia/kornia/pull/2059
- making
RandomGaussianNoiseplay nicely on GPU by @nitaifingerhut in https://github.com/kornia/kornia/pull/2050 - None for align_corners arg of resize op with nearest mode by @miquelmarti in https://github.com/kornia/kornia/pull/2049
- facedetector now returns a list of tensors containing the boxes x image by @lferraz in https://github.com/kornia/kornia/pull/2034
- add random for liegroups by @cjpurackal in https://github.com/kornia/kornia/pull/2041
- add rotation and translation classmethods in se3 and so3 by @edgarriba in https://github.com/kornia/kornia/pull/2001
- implement
kornia.geometry.linalg.euclidean_distanceby @edgarriba in https://github.com/kornia/kornia/pull/2000
Deprecation
- Drop pytorch 1.8 (LTS) support by @johnnv1 in https://github.com/kornia/kornia/pull/2024
:rocket: [0.6.8] - 2022-10-13
:new: New Features
- NeRF Implementation by @YanivHollander in https://github.com/kornia/kornia/pull/1911
- [Feat] Added AugmentationDispatcher by @shijianjian in https://github.com/kornia/kornia/pull/1914
- Add
EdgeDetectionapi by @edgarriba in https://github.com/kornia/kornia/pull/1483 - [feat] slerp implementation for Quaternion by @cjpurackal in https://github.com/kornia/kornia/pull/1931
- add laplacian pyramid by @lafith in https://github.com/kornia/kornia/pull/1816
- Added homography from line segment correspondences by @ducha-aiki in https://github.com/kornia/kornia/pull/1851
- [feat] Added Jigsaw Augmentation by @shijianjian in https://github.com/kornia/kornia/pull/1852
:lady_beetle: Bug fixes
- Fix svdvals usage by @ducha-aiki in https://github.com/kornia/kornia/pull/1926
- fix shift_rgb stack dimension by @nmichlo in https://github.com/kornia/kornia/pull/1930
- Update kernels.py by @farhankhot in https://github.com/kornia/kornia/pull/1940
- Quaternion.norm bug fix by @cjpurackal in https://github.com/kornia/kornia/pull/1935
- Fix quaternion doctests by @edgarriba in https://github.com/kornia/kornia/pull/1943
- Remove unnecessary CI jobs by @johnnv1 in https://github.com/kornia/kornia/pull/1933
- fix cuda tests failing by @ducha-aiki in https://github.com/kornia/kornia/pull/1941
- No crash in local feature matching if empty tensor output by @ducha-aiki in https://github.com/kornia/kornia/pull/1890
:zap: Improvements
- RANSAC improvements by @ducha-aiki in https://github.com/kornia/kornia/pull/1435
- Make AdaLAM output match confidence by @ducha-aiki in https://github.com/kornia/kornia/pull/1862
- Enlargen LoFTR positional encoding map if large images are input by @georg-bn in https://github.com/kornia/kornia/pull/1853
:rocket: [0.6.7] - 2022-08-30
:new: New Features
- Added FGINN matching by @ducha-aiki in https://github.com/kornia/kornia/pull/1813
- Added SOLD2 by @rpautrat https://github.com/kornia/kornia/pull/1507 https://github.com/kornia/kornia/pull/1844
- edge aware blur2d by @nitaifingerhut in https://github.com/kornia/kornia/pull/1822
- Adds conversions between graphics and vision coordinate frames by @ducha-aiki in https://github.com/kornia/kornia/pull/1823
- Add Quaternion API by @edgarriba in https://github.com/kornia/kornia/pull/1801
- AdaLAM match filtering by @ducha-aiki in https://github.com/kornia/kornia/pull/1831
- Init Mosaic Augmentation by @shijianjian in https://github.com/kornia/kornia/pull/1713
:lady_beetle: Bug fixes
- fix tests float16 module losses by @MrShevan in https://github.com/kornia/kornia/pull/1809
:zap: Improvements
- Allowing more than 3/4 dims for
total_variation+ addingreductionby @nitaifingerhut in https://github.com/kornia/kornia/pull/1815
:rocket: [0.6.6] - - 2022-07-16
:new: New Features
- Add
ParametrizedLineandfit_lineby @edgarriba in https://github.com/kornia/kornia/pull/1794 - Implement
projectandunprojectinPinholeCameraby @YanivHollander in https://github.com/kornia/kornia/pull/1729 - adding
rgb_to_yby @nitaifingerhut in https://github.com/kornia/kornia/pull/1734 - add
KORNIA_CHECK_SAME_DEVICESby @MrShevan in https://github.com/kornia/kornia/pull/1788
Deprecation
- deprecate
filter2Dfilter3Dapi by @edgarriba in https://github.com/kornia/kornia/pull/1725
:lady_beetle: Bug fixes
- fixes for half precision in imgwarp by @edgarriba in https://github.com/kornia/kornia/pull/1723
- Fix transforms for empty boxes and keypoints inputs by @hal-314 in https://github.com/kornia/kornia/pull/1741
- fixing doctest in pinhole by @edgarriba in https://github.com/kornia/kornia/pull/1743
- Fix/crop transforms by @hal-314 in https://github.com/kornia/kornia/pull/1739
- Fix Boxes.from_tensor(boxes, mode="vertices") by @hal-314 in https://github.com/kornia/kornia/pull/1740
- fix typing callable in load storage by @edgarriba in https://github.com/kornia/kornia/pull/1768
- Fix bug preventing sample wise augmentations by @ashnair1 in https://github.com/kornia/kornia/pull/1761
- Refactor and add tests in
get_perspective_transformby @edgarriba in https://github.com/kornia/kornia/pull/1767
:rocket: [0.6.5] - 2022-05-16
:new: New Features
- Create
kornia.ioand implementload_imagewith rust (#1701) - Implement
diamond_squareand plasma augmentations:RandomPlasmaBrightness,RandomPlasmaContrast,RandomPlasmaShadow(#1700) - Added
RandomRGBShiftaugmentations (#1694) - Added STE gradient estimator (#1666)
- More epipolar geometry metrics (+linalg utility) (#1674)
- Add Lovasz-Hinge/Softmax losses (#1682)
- Add
adjust_sigmoidandadjust_loginitial implementation (#1685) - Added distribution mapper (#1667)
pos_weightparam to focal loss (#1744)
:lady_beetle: Bug fixes
- Fixes filter2d's output shape shrink when padding='same' (#1661)
- fix: added eps in geometry/rotmat_to_quaternion (#1665)
- [fix] receive num_features as an arg to KeyNetDetector constructor (#1686
:zap: Improvements
- Add reduction option to
MS_SSIMLoss(#1655) - Making epipolar metrics work with volumetric tensors (#1656)
- Add get_safe_device util (#1662)
- Added antialiasing option to Resize augmentation (#1687)
- Use nearest neighbour interpolation for masks (#1630)
- grayscale to rgb for
torch.uint8(#1705) - Add
KORNIA_CHECK_SAME_DEVICES(#1775)
:rocket: [0.6.4] - 2022-03-19
:new: New Features
- Adds MS-SSIMLoss reconstruction loss function (#1551)
- Added HyNet descriptor (#1573)
- Add KeyNet detector (#1574)
- Add RandomPlanckianJitter in color augmentations (#1607)
- Add Jina AI QAbot to Kornia documentation (#1628)
- Add
draw_convex_polygon(#1636)
:lady_beetle: Bug fixes
- RandomCrop fix and improvement (#1571)
- Fix draw_line produce wrong output for coordinates larger than uint8
- Fix mask bug for loftr (#1580)
- Fix gradient bug for distance_transform (#1584)
- Fix translation sampling in AffineGenerator3D (#1581)
- Fix AugmentationSequential bbox keypoints transformation fix (#1570)
- Fix CombineTensorPatches (#1558)
- Fix overblur in AA (#1612)
:exclamation: Changes
- Deprecated
return_transform, enabled 3D augmentations in AugmentionSequential (#1590)
:zap: Improvements
- Making compute_correspond_epilines work with fundamental and point of volumetric tensor (#1585)
- Update batch shape when augmentations change size of image (#1609)
- Remap accepts arbitrary grid size (#1617)
- Rename variables named 'input' to 'sample' (in tests). (#1614)
- Remove half log2 in extract_patches (#1616)
- Add orientation-preserving option for AffNet and make it default (#1620)
- Add option for sampling_method in 2d perspective transform generation (#1591) (#1592)
- Fix adjust brightness (#1586)
- Added default params for laf construction from xy and new tensor shape check (#1633)
- Make nms2d jittable (#1637)
- Add fn to automatically compute padding (#1634)
- Add pillow_like option for ColorJitter to match torchvision. (#1611)
:rocket: [0.6.3] - 2022-01-30
:new: New Features
- Update CI to pytorch 1.10.1 (#1518)
- Added Hanning kernel, prepare for KCF tracking (#1519)
- Add distance transform implementation (#1490)
- Add Resize augmentation module (#1545)
:lady_beetle: Bug fixes
- Precompute padding parameters when RandomCrop aug in container (#1494)
- Padding error with RandomCrop #1520
- Fix correct shape after cropping when forwarding parameters (#1533)
- Fixed #1534 nested augmentation sequential bug (#1536)
- Fixes to device in augmentations (#1546)
- Bugfix for larger MotionBlur kernel size ranges (#1543)
- Fix RandomErasing applied to mask keys (#1541)
:exclamation: Changes
- Restructure augmentation package (#1515)
:zap: Improvements
- Add missing keepdims with fixed type (#1488)
- Allow to pass a second K to distort and undistort points (#1506)
- Augmentation Sequential with a list of bboxes as a batch (#1497)
- Adde Devcontainer for development (#1515)
- Improve the histogram_matching function (#1532)
:rocket: [0.6.2] - 2021-12-03
:new: New Features
- Add face detection API (#1469)
- Add
ObjectDetectorTrainer(#1414) - Add container operation weights and
OneOfdocumentation (#1443) - Add oriented constraint check to Homography RANSAC (#1453)
- Add background color selection in
warp_perspective(#1452) - Add
draw_lineimage utility (#1456) - Add Bounding Boxes API (#1304)
- Add histogram_matching functionality (#1395)
:lady_beetle: Bug fixes
- fix catch type for torch.svd error (#1431)
- Fix for nested AugmentationSequential containers (#1467)
- Use common bbox format xywh (#1472)
- Fix motion blur kernel size bug for larger random generator ranges (#1540)
:exclamation: Changes
- Add padding_mode for RandomElasticTransform augmentation (#1439)
- Expose inliers sum to HomographyTracker (#1463)
:zap: Improvements
- Switch to one-way error RANSAC for speed-up (#1454)
- Few improvements on homography tracking (#1434)
- Enable all bandit tests, add separate hook for tests (#1437)
- Merge homography_warp to warp_perspective (#1438)
- Random generator refactor (#1459)
:rocket: [0.6.1] - 2021-10-22
:lady_beetle: Bug fixes
- Fixes PyPI tarball missing required files #1421
- hotfix: remove mutable object in constructor #1423
:rocket: [0.6.0] - 2021-10-22
:new: New Features
- Add Training API (#1307)
- Added combine patches (#1309)
- Add semantic segmentation trainer (#1323)
- Add vanilla LO-RANSAC (#1335)
- Add Lambda function module (#1346)
- Add support for YUV420 and YUV422 to complement current YUV444 (#1360)
- Add raw to rgb color conversion (#1380)
- Implement separable_filter2d (#1385)
- Add MobileViT to contrib (#1388)
- Add solve_pnp_dlt (#1349)
- Add function image_list_to_tensor to utils (#1393)
- Add undistort_image function (#1303)
- Create kormia.metrics submodule (#1325)
- Add Image Stitching API (#1358)
- Add Homography Tracker API (#1389)
:exclamation: Changes
- Refactor library namespaces [pre-release][0.6-rc1] (#1412)
- deprecate 1.6/1.7 and add 1.9.1 (#1399)
:zap: Improvements
- Improve bbox_to_mask (#1351)
- Refactor unfold->conv for morphology backbone (#1107)
- Improve focal loss for numerical stability (#1362)
- Add more border_type options for filter2D (#1375)
- Replace deprecated torch.qr (#1376)
- Add special case hardcoded implementtion for local features speed up (#1387)
- Enable non/batched connected components (#1193)
- Remove warnings during testing (#1401)
:lady_beetle: Bug fixes
- Fix binary focal loss (#1313)
- Fix kornia.geometry.subpix.spatial_soft_argmax imports (#1318)
- Fixed a simple typo in init.py (#1319)
- Fix path to dev requirements file in a setup_dev_env.sh (#1324)
- Fix bug in create_meshgrid3d along depth (#1330)
- Fix anisotropic scale error (#1340)
- Fix rgb_to_hsv for onnx (#1329)
- Fixed useless return in ransac.py (#1352)
- Fixed classificationhead typo and leave out some of the guesswork (#1354)
- Fix clahe differentiability and tests (#1356)
- Fixes singular matrix inverse/solve for RANSAC and ConvQuad3d (#1408)
- Change intermediate datatype to fix imgwarp (#1413)
:rocket: [0.5.11] - 2021-08-30
:new: New Features
- Add Vision Transformer (ViT) (#1296)
- Add ImageRegistrator API (#1253)
- Add LoFTR inference (#1218)
- Added differentiable Hausdorff Distance (HD) loss (#1254)
- Add PadTo to kornia.augmentation (#1286)
:zap: Code refactor
- Return all learned modules by default in eval() mode (#1266)
- Enable ImageSequential and VideoSequential to AugmentationSequential (#1231)
- Specify that angles are in radians (#1287)
- Removed deprecated codes for v6.0 (#1281)
:lady_beetle: Bug fixes
- Fix save_pointcloud_ply fn counting point with inf coordinates (#1263)
- Fixes torch version parse and add temporal packaging dependency (#1284)
- Fix issue of image_histogram2d (#1295)
[0.5.10] - 2021-08-30
Added
- Added Basic pool request for DeFMO. (#1135)
- Added homography error metrics, and improved find_homography_iter (#1222)
Fixed
- Fixed wrong param name (#1197)
- Fixed NotImplementedError for the rtvec (#1215))
- Fixes warnings and add compatibility stub in torch solve (#1235)
Changed
- Ensure CenterCrop indices are integers (#1208)
- Added tests, fixed docstrings and made some other changes (#1211)
- Upgrade to modern Python syntax (#1213)
- Code health improvements [#1199, #1200, #1198, #1202, #1203, #1205, #1208, #1210, #1214, #1220]
- Enable pyupgrade as pre-commit (#1221)
- Add bandit tool in the pre-commit (#1228)
[0.5.8] - 2021-08-06
Added
- Add the connected components labeling algorithm (#1184)
Fixed
- Partial fix for horizontal and vertical flips (#1166)
- Fix even kernel and add test (#1183)
- Fix wrong source points for RandomThinPlateSpline (#1187)
- Fix RandomElasticTransform ignores same_on_batch (#1189)
- Fixed bugs in patchsequential. Remove fill_diagonal operation for better ONNX support (#1178)
Changed
- Differentiable image histogram using kernel density estimation (#1172)
[0.5.7] - 2021-07-27
Added
Fixed
- Fix checks on wrong tensor shape condition in depth.py (#1164)
[0.5.6] - 2021-07-12
Added
- Added mix augmentations in containers (#1139)
Fixed
- Fixed non-4-dim input error for sequential (#1146)
Changed
- Moving bbox-related functionality to bbox module (#1103)
- Optimized version of hls_to_rgb and rgb_to_hls (#1154)
Removed
- Remove numpy dependency (#1136)
[0.5.5] - 2021-06-26
Added
- Added Stereo camera class (#1102)
- Added auto-generated images in docs (#1105) (#1108) (#1127) (#1128) (#1129) (#1131)
- Added chinese version README (#1112)
- Added random_apply to augmentaton containers (#1125)
Changed
- Change GaussianBlur to RandomGaussianBlur (#1118)
- Update ci with pytorch 1.9.0 (#1120)
- Changed option for mean and std to be tuples in normalization (#987)
- Adopt torch.testing.assert_close (#1031)
Removed
- Remove numpy import (#1116)
[0.5.4] - 2021-06-11
Added
- Add Canny edge detection (#1020)
- Added Batched forward function (#1058)
- Added denormalize homography function (#1061)
- Added more augmentations containers (#1014)
- Added calibration module and Undistort 2D points function (#1026)
- Added patch augmentation container (#1095)
Fixed
- Remove lena (#1059) :)
Changed
- Resize regardless of number of dims, considering the last two dims as image (#1047)
- Raise error if converting to unit8 image to gray with float weights (#1057)
- Filter 2D->2d, 3D->3d (#1069)
- Removed augmentation functional module. (#1067)
- Make Morphology compatible with both OpenCV and Scipy (#1084)
[0.5.3] - 2021-05-29
Added
- Added inverse for augmentations (#1013)
- Add advanced augmentations: RandomFisheye, RandomElasticTransform, RandomThinPlateSpline, RandomBloxBlur (#1015
Fixed
- Correct Sobel test_noncontiguous. Nothing was tested before. (#1018)
- Fixing #795: find_homography_dlt_iterated sometimes fails (#1022)
Changed
- Refactorization of the morphology package (#1034)
- Optimised clipping in clahe and some other minor optimisation (#1035)
[0.5.2] - 2021-05-14
Added
- Added unsharp mask filtering (#1004)
Fixed
- Fixed angle axis to quaternion order bug (#926)
- Fixed type error for lab_to_rgb conversion when using coremltools. (#1002)
Changed
- Mask with unbatched motion from essential choose solution (#998)
[0.5.1] - 2021-04-30
Added
- Added dtype for create_mesh (#919)
- Added Hardnet8 (#955)
- Added normalize boolean for remap (#921)
- Added custom weights option for rgb2gray (#944)
- Added fp16 support (#963)
- Added ImageToTensor module and resize for non-batched images (#978)
- Add more augmentations (#960)
- Anti alias resize (#989)
Changed
- Improve kornia porphology (#965)
- Improve cuda ci workflow speed (#975)
- Refactor augmentation module (#948)
- Implement fast version of crop function in augmentations (#967)
- Implement missing jit ops in kornia.geometry.transform (#981)
Fixed
- Fixed RandomAffine translation range check (#917
- Fixed the issue of NaN gradients by adding epsilon in focal loss (#924)
- Allow crop size greater than input size. (#957)
- Fixed RandomCrop bug (#951)
Removed
- Deprecate some augmentation functionals (#943)
[0.4.1] - 2020-10-20
Added
- Update docs for
get_affine_matrix2dandget_affine_matrix3d(#618) - Added docs for
solarize,posterize,sharpness,equalize(#623) - Added tensor device conversion for solarize params (#624)
- Added rescale functional and transformation (#631)
- Added Mixup data augmentation (#609)
- Added
equalize3d(#639) - Added
decompose 3x4projection matrix(#650) - Added
normalize_min_maxfunctionality (#684) - Added
random equalize3d(#653) - Added 3D motion blur (#713)
- Added 3D volumetric crop implementation (#689)
warp_affine3dwarp_perspective3dget_perspective_transform3dcrop_by_boxes3dwarp_grid3d
Changed
- Replace convolution with
unfoldincontrib.extract_tensor_patches(#626) - Updates Affine scale with non-isotropic values (#646)
- Enabled param p for each augmentation (#664)
- Enabled RandomResizedCrop batch mode when same_on_batch=False (#683)
- Increase speed of transform_points (#687)
- Improves
find_homography_dltperformance improvement and weights params made optional (#690) - Enable variable side resizing in
kornia.resize(#628) - Added
Affinetransformation asnn.Module(#630) - Accelerate augmentations (#708)
Fixed
- Fixed error in normal_transform_pixel3d (#621)
- Fixed pipelining multiple augmentations return wrong transformation matrix (#645)(645)
- Fixed flipping returns wrong transformation matrices (#648)
- Fixed 3d augmentations return wrong transformation matrix (#665)
- Fix the SOSNet loading bug (#668)
- Fix/random perspective returns wrong transformation matrix (#667)
- Fixes Zca inverse transform (#695)
- Fixes Affine scale bug (#714)
Removed
- Removed
warp_projective(#689)