Warping API
Coordinate and region maps (canonical and log-polar), the image_warp adapter and its KernelAbstractions resampler, and the BoundedMap decorator. See the Transforms guide.
Coordinate and Region Maps
CoordinateTransformations.AffineMap — Method
AffineMap(circle::Circle) -> AffineMapAffineMap from canonical [-1,1]² to a circle's coordinate frame (isotropic scaling by radius + translation to centre).
CoordinateTransformations.AffineMap — Method
AffineMap(ellipse::Ellipse) -> AffineMapAffineMap from canonical [-1,1]² to an ellipse's coordinate frame (rotation + anisotropic scaling, then translation to centre).
CoordinateTransformations.AffineMap — Method
AffineMap(rect::HyperRectangle{2}) -> AffineMapAffineMap from canonical [-1,1]² to a 2D rectangle's coordinate frame.
VisualGeometryToolkitCore.EuclideanMap — Method
EuclideanMap(::Type{PixelFrame{From}}, ::Type{PixelFrame{To}}) -> EuclideanMap{2}Origin-convention conversion between two pixel frames, as a LABELED rigid map: identity rotation, constant translation, Src = PixelFrame{From}, Dst = PixelFrame{To} (monogram X_{To,From}). Registered origins: :opencv, :colmap, :julia — see the table in the PixelFrame docstring. This constructor-as-factory on the frame TYPES is the only origin-conversion API (the 0.6-era ImageOrigin value surface is removed in 0.7).
The returned map is UNITLESS (Vec2{Float64} translation): origin conversion is a compute-side operation and compute runs on stripped values (units are enforced at construction and stripped at the region gate). Apply it to plain-Float64 points; strip united data first (ustrip.(px, ...)).
For identical frames the translation is zero (≡ identity). inv swaps the frames; composition against other labeled 2D maps is frame-checked, and the map fuses in image_warp chains like any EuclideanMap{2}.
Examples
T = EuclideanMap(PixelFrame{:colmap}, PixelFrame{:julia})
T.t == Vec2(0.5, 0.5) # true
pt_julia = T(pt_colmap) # pt_colmap unitless
inv(T) isa EuclideanMap{2, <:Any, <:Any, <:Any, PixelFrame{:julia}, PixelFrame{:colmap}}VisualGeometryToolkitCore.CartesianToLogPolar — Type
CartesianToLogPolar{T<:Real} <: CoordinateTransformations.TransformationThe inverse of LogPolarToCartesian (inv(t)): Cartesian (x, y) to the log-polar unit square, the angle on [-1, 1) (θ ∈ [0, 2π)), the radius's log mapped affinely from [log_inner_radius, 0] to [-1, 1]. Through it inv(logpolar_map(geometry, rect, inner_radius)) takes an image point to its log-polar patch coordinates.
VisualGeometryToolkitCore.LogPolarToCartesian — Type
LogPolarToCartesian{T<:Real} <: CoordinateTransformations.TransformationTransformation from log-polar to Cartesian coordinates in normalized unit space. Subtypes CoordinateTransformations.Transformation so it composes into a ComposedTransformation (not Base.ComposedFunction) — required for the BoundedMap(::Transformation, ::Rect) constructor used by image_warp.
VisualGeometryToolkitCore.canonical_map — Method
canonical_map(geom, size::Integer; bound=1.0, align_corners=false) -> AffineMapSize-form convenience: builds the COLMAP-math patch-domain rect for a size × size patch internally, then delegates to canonical_map(geom, rect; bound). See the rect-form for full details.
VisualGeometryToolkitCore.logpolar_map — Method
logpolar_map(geometry::Union{Circle, Ellipse}, logpolar_rect::HyperRectangle{2}, inner_radius::Real) -> FunctionCreate a composed transformation that maps from log-polar patch coordinates to image coordinates via a circle or ellipse.
This is a convenience function that composes three transformations:
logpolar_rect→CANONICAL_SQUARE(normalize patch coordinates)CANONICAL_SQUARE→UNIT_CIRCLEvia log-polar transformUNIT_CIRCLE→geometry(map to target circle/ellipse in image)
The resulting transformation can be used with warp to extract log-polar patches.
Arguments
geometry::Union{Circle, Ellipse}: Target geometry in image coordinateslogpolar_rect::HyperRectangle{2}: Rectangle defining the log-polar patch domaininner_radius::Real: Minimum radius for log-polar transform (avoids singularity at origin)
Returns
Function: Composed transformationlogpolar_rect → geometry
Broadcasting
This function is designed to be broadcastable across multiple geometries:
# Extract patches from multiple circles
transforms = logpolar_map.(circles, Ref(logpolar_rect), Ref(inner_radius))Example
using VisualGeometryToolkitCore
using GeometryBasics: Circle, Point2
# Define target circle and log-polar patch size
circle = Circle(Point2(100.0, 200.0), 50.0)
ix, iy = 1:512, 1:256 # x-axis (scale), y-axis (rotation)
logpolar_rect = Rect((ix..., iy...))
inner_radius = 0.01
# Create transformation and resample through the fused warp
transform = logpolar_map(circle, logpolar_rect, inner_radius)
bm = image_warp(transform, Rect(0, 0, 512, 256))
patch = Matrix{Float32}(undef, 256, 512)
image_warp!(patch, bm, image; fillvalue=0.5f0)See Also
AffineMap: canonical → primitive coordinate mapping (constructor)logpolar_to_cartesian: Log-polar to Cartesian transformation
VisualGeometryToolkitCore.logpolar_map — Method
logpolar_map(geom, size::Integer, inner_radius; align_corners=false) -> ComposedFunctionSize-form convenience: builds the COLMAP-math patch-domain rect for a size × size log-polar patch internally, then delegates to logpolar_map(geom, rect, inner_radius).
VisualGeometryToolkitCore.logpolar_to_cartesian — Function
logpolar_to_cartesian(inner_radius=0.01) -> LogPolarToCartesianConstruct a LogPolarToCartesian transformation. Maps points in unit space [-1,1]² interpreted as (log_r, θ) to Cartesian (x, y) in the unit circle.
Coordinate Convention
- x-axis (horizontal/columns) = scale (radius)
- y-axis (vertical/rows) = rotation (angle)
Mapping
- Input x-coordinate in [-1,1] → radius from inner_radius to 1.0 (logarithmically)
- Input y-coordinate in [-1,1] → angle from 0 to 2π
- Output: Cartesian (x, y) in unit circle (radius ≤ 1.0)
Arguments
inner_radius::Real: Minimum radius (default: 0.01, avoids singularity at origin)
Example
transform = logpolar_to_cartesian()
transform(Point2(0.0, 0.0)) # mid-radius, π angle
transform(Point2(-1.0, -1.0)) # min radius, 0
transform(Point2(1.0, 1.0)) # max radius (1.0), 2πCoordinateTransformations.AffineMap — Method
(am::AffineMap)(l::Line2D) -> Line2DTransform a 2D line through an affine map. Lines stay lines under affine transforms.
CoordinateTransformations.Translation — Method
(t::Translation{<:StaticVector{2}})(c::Circle) -> CircleTranslate a circle by shifting its center. Returns a Circle (translation preserves shape).
CoordinateTransformations.Translation — Method
(t::Translation{<:StaticVector{2}})(e::Ellipse) -> EllipseTranslate an ellipse by shifting its center. Returns an Ellipse (translation preserves shape).
CoordinateTransformations.Translation — Method
(t::Translation{<:StaticVector{2}})(l::Line2D) -> Line2DTranslate a 2D line. For line ax + by + c = 0, translating by (tx, ty) gives: ax + by + (c - atx - bty) = 0
VisualGeometryToolkitCore.SimilarityMap — Method
(S::SimilarityMap{2})(x) -> same type as x
(E::EuclideanMap{2})(x) -> same type as xThe similarity (or rigid) action on a Circle, an Ellipse, a Line2D or a feature frame (PointFrame, Disc, OrientedDisc, EllipticFrame, AffineFrame), exact in its class: see the class table above. A rotation or a uniform scaling LinearMap acts through its SimilarityMap.
VisualGeometryToolkitCore.SimilarityMap — Method
(S::SimilarityMap{2})(r::Rect{2}) -> Rect{2, Float64}
(S::SimilarityMap{2})(s::RegionIntersection) -> RegionIntersection
(S::SimilarityMap{2})(P::PolygonRegion) -> PolygonRegionThe similarity's action on a region: a Rect's image is the axis-aligned Rect of its mapped corners, defined when the rotation is exactly a multiple of 90° (its matrix entries are 0 and ±1: the scalings, translations and quarter turns of the pixel-frame maps, a Bayer plane's map among them). Its widths are s times the widths (swapped by a quarter turn), exactly. Any other rotation turns a rectangle off the axes, which a Rect cannot hold: an ArgumentError. A PolygonRegion (a decentred lens's valid domain) maps vertex by vertex with its centre, a star polygon about the mapped centre. An intersection maps part by part (S(a ∩ b) = S(a) ∩ S(b), each part by its own action, so p ∈ s ⟺ S(p) ∈ S(s) up to rounding), and with the Ellipse, Circle, polygon and WholePlane actions every region pixel_mask reads maps without testing its type.
VisualGeometryToolkitCore.SimilarityMap — Method
(S::SimilarityMap{2})(w::WholePlane) -> WholePlaneThe whole plane maps to itself under any similarity: the identity on the region a lens without an image circle images (valid_domain), beside the Circle and Ellipse actions, so a region is mapped without testing its type.
VisualGeometryToolkitCore.transfer — Method
transfer(m, f::FeatureFrame) -> FeatureFrameA feature frame carried through ANY point map m of the plane (a framed or plain affine, PerspectiveMap() ∘ h of a homography, a camera's lens or plane_map stage — anything callable on a 2-vector): the centre moves by m. A PointFrame is a point, so that is all of it, exact for every map. A scaled frame's shape moves by the map's Jacobian at the centre, its first-order image: an AffineFrame(m(c), J·F) (F its shape_factor) — except through a similarity (SimilarityMap{2}, EuclideanMap{2}, a rotation or uniform-scaling LinearMap), which keeps every frame's class exactly, m(f). A camera is no map of the plane (it images 3-D points): transfer(camera, f) is an ArgumentError naming its plane stages. Plain-number frames; the Jacobian is ForwardDiff's, static and allocation-free. An uncertain frame moves with its covariance by propagate.
Image Warping
Two bilinear lookups with two contracts: bilinear_sample reads a texture in its unit-square (half-texel) chart, extends its edges, returns several channels and differentiates in the position (a printed board's albedo under ForwardDiff); bilinear_sample_clamped reads 1-based array positions, rejects one off the image, and is exact at integers (a pixel scan). bilinear_weights is bilinear_sample's texel block and fractions for a caller that spreads a position itself, and is_inside_texel_centres says whether a position needs no edge extension (for a caller that drops it instead). image_sample! is image_warp!'s tap at points the caller holds (the projections of a set of directions), with its boundary.
VisualGeometryToolkitCore.FramedImage — Type
FramedImage(data, rect)A resampled canvas TOGETHER with its placement: rect is the window of the source pixel frame (COLMAP convention — origin at the window's top-left corner, widths its footprint) that data covers; the sampling density is widths(rect) ./ size(data) (reversed: array is row-major). Named rect — not extent — deliberately: VGC's extent(camera) is a SIZE (Size2{Int}), while this is a POSITIONED window. This is the warp layer's currency at the return boundary — a bare matrix loses exactly the information every consumer then has to carry by hand (the ext + σ pair the rect form of undistort used to drop), and misplacing a rectified image by its offset or scale is the half-pixel bug class the frame conventions exist to kill.
imshow(pos, ci::FramedImage) (Makie extension) is self-placing: it draws data over rect, so a rectified view lands in the same axes as the raw frame — principal point, footprint and all — with nothing supplied alongside.
Produced by the rect form of undistort; construct directly for any canvas rendered over a known window of a pixel frame.
VisualGeometryToolkitCore.bilinear_sample — Method
bilinear_sample(img::AbstractMatrix, uv::StaticVector{2}) -> value
bilinear_sample(img::AbstractArray{T, 3}, Val(C), uv::StaticVector{2}) -> SVector{C}Bilinear lookup of a texture at uv in its unit-square chart, the half-texel convention: img[i, j] (row i of H, column j of W) is the texel centred at uv = ((j − ½)/W, (i − ½)/H), so (0, 0) is the outer corner of img[1, 1] and (1, 1) that of img[H, W]. A position off the centres' rectangle EXTENDS the edge (clamp to edge, never a rejection), and a non-finite position reads the corner texel img[1, 1]. The image needs at least 2 × 2 texels (an ArgumentError otherwise).
A matrix returns one value (any element type that scales and adds: numbers, SVectors); a 3-D array (H, W, C) returns its first C channels as an SVector{C} — RGB, or a signed distance and its orientation tensor. Allocation-free and generic: under ForwardDiff the texel is chosen on the position's value and the derivative flows through the weights, which are continuous across texels (the value is C⁰).
The other bilinear lookup, bilinear_sample_clamped, addresses 1-based array positions and rejects positions off the image.
VisualGeometryToolkitCore.bilinear_sample_clamped — Method
bilinear_sample_clamped(::Type{Ta}, img, yf, xf, H::Int32, W::Int32) -> (in_bounds::Bool, value::Ta)Bilinear sample of img at the 1-based array position (yf, xf) with the OTHER boundary policy from _bilinear_sample's fill: a position whose floor cell lies outside 1:H × 1:W is rejected ((false, 0)), and the +1 neighbour is clamped to the last row/column, so the border pixel is sampled exactly rather than blended with a fill value. Exact (no interpolation error) at integer positions, which is what keeps an integer-step scan bit-identical to a pixel loop. Device-safe (Int32 indices, no allocation); hoisted verbatim from BlobBoards' adaptation kernels (2026-09).
VisualGeometryToolkitCore.bilinear_weights — Method
bilinear_weights(uv::StaticVector{2}, (W, H)) -> (i, j, fx, fy)The texel block and blend fractions bilinear_sample reads at uv on a W × H texture (W columns, H rows) in its unit-square, half-texel chart: the 1-based column i and row j of the block's first texel (img[j, i]; its four texels are img[j, i], img[j, i + 1], img[j + 1, i], img[j + 1, i + 1]) and the fractions fx, fy ∈ [0, 1] along x and y, so the four weights are (1 − fx)(1 − fy), fx (1 − fy), (1 − fx) fy and fx fy. The same policy as the lookup: a position off the centres' rectangle extends the edge (its block clamped to the edge, its fraction to 0 or 1), a non-finite coordinate reads the corner, and the texture needs at least 2 × 2 texels (an ArgumentError otherwise; its message is a literal, so it compiles in a GPU kernel). The block is chosen on the position's value under every ForwardDiff Dual layer and the fractions carry the partials. For a caller that spreads one position over the four texels itself (a footprint's rows, a scatter) instead of reading values.
VisualGeometryToolkitCore.fuse — Method
fuse(t) -> TransformationFlatten every run of matrix-representable links in a composition chain into a single link. Translation/LinearMap/AffineMap/EuclideanMap/RCSwap runs merge into one AffineMap; runs containing a HomographyMap merge into one HomographyMap; an affine link immediately left of a PerspectiveMap is pulled through the division into the homography. Nonlinear links (log-polar, lens models, …) are preserved in place. Semantically a no-op; structurally the difference between five closure calls per pixel and one matrix multiply.
fuse(bm::BoundedMap) fuses the wrapped map and keeps the rect.
VisualGeometryToolkitCore.image_warp! — Method
image_warp!(dst::AbstractArray{<:Any, 3}, warps::Tuple{Vararg{BoundedMap}}, src::AbstractArray{<:Any, 3}; fillvalue=0) -> dstA multi-plane image warped plane by plane, each plane through its own warp: plane p of dst is plane p of src sampled through warps[p] — the 2-D image_warp! of each plane, on the backend that owns dst. For an image whose planes are sampled at different points (a Bayer image's R, G and B), each plane's warp composes that plane's own frame map: image_warp(T, inv(plane_map_p) ∘ math, rect). One warp per plane (DimensionMismatch otherwise).
VisualGeometryToolkitCore.image_warp! — Method
image_warp!(dst, bm::BoundedMap, src; fillvalue=0) -> dstResample src into dst through the warp bm (built by image_warp): for each (row, col) of dst, bilinearly sample src at bm((row, col)). Runs the shared KernelAbstractions kernel on the backend that owns dst — supply CuArrays for GPU execution (the warp math evaluates on-device: bm's device form, Adapt.adapt(backend, bm), which moves a link holding arrays — a spline lens's controls — beside dst, is isbits; the workgroup is the backend's).
dst and src may differ in eltype: samples accumulate in float and store back through the destination eltype (UInt8 rounds saturating, colorants clamp to [0, 1]). fillvalue is the out-of-bounds tap value, in the float accumulation domain.
VisualGeometryToolkitCore.image_warp — Method
image_warp([T=Float64], math, n::Integer) -> BoundedMapConvenience overload for a square n × n output array. Equivalent to image_warp(T, math, Rect(0, 0, n, n)). Typically paired with the size-form math builders (canonical_map(geom, n; …), logpolar_map(geom, n, r; …)) for the common case where the patch domain and output array share n.
VisualGeometryToolkitCore.image_warp — Method
image_warp([T=Float64], math, output_rect::Rect{2}) -> BoundedMapWrap a math-space Transformation into a fused BoundedMap callable from Julia array indices. Composes (left-to-right when reading a call sequence):
_RC_SWAP ∘ _OUT_BRIDGE ∘ math ∘ _IN_BRIDGE ∘ _RC_SWAPthen flattens the chain with fuse. Perspective division is injected automatically when math is projective (is_projective) and doesn't already divide.
The output BoundedMap consumes (row, col) indices into the OUTPUT array and returns (sr, sc) indices into the SOURCE array — both Julia 1-indexed. The internal bridge pair — the typed frame maps EuclideanMap(PixelFrame{:julia}, PixelFrame{:colmap}) and its reverse — converts to/from VGC's package-wide COLMAP math convention.
Arguments
T— optional leading element type of the fused warp math (the standardrand(Float32, …)-style convention).image_warp(Float32, …)keeps the per-pixel math single-precision on GPU backends.math— anyCoordinateTransformations.Transformation. Assumed COLMAP-math.output_rect::Rect{2}— the output region in array coords (e.g.,Rect(0, 0, width, height)).
Example
math = canonical_map(ellipse, 64; bound=1.0)
bm = image_warp(math, 64)
patch = Matrix{Float32}(undef, 64, 64)
image_warp!(patch, bm, img_f32; fillvalue=0.5f0)VisualGeometryToolkitCore.image_warp_batch_to! — Method
image_warp_batch_to!(out, warps, src; fillvalue=0) -> outSample src once per output pixel of every warp in warps, writing into the pre-allocated 3D stack out::AbstractArray{T, 3} of shape (P_r, P_c, N) where N = length(warps). Each warps[k] is a BoundedMap produced by image_warp. Same kernel and backend dispatch as image_warp! — supply CuArrays (including the warp vector) for GPU execution.
Example (CPU)
warps = [image_warp(canonical_map(d, 64; bound=1.0), 64) for d in discs]
out = Array{Float32}(undef, 64, 64, length(warps))
image_warp_batch_to!(out, warps, src; fillvalue=Float32(0.5))Example (GPU)
d_warps = CuArray(warps)
d_src = CuArray(src_f32)
d_out = CUDA.zeros(Float32, 64, 64, length(warps))
image_warp_batch_to!(d_out, d_warps, d_src; fillvalue=0.5f0)VisualGeometryToolkitCore.is_inside_texel_centres — Method
is_inside_texel_centres(uv::StaticVector{2}, (W, H)) -> BoolWhether uv lies in the closed rectangle of the texel centres of a W × H texture in bilinear_sample's unit-square, half-texel chart ((½/W, ½/H) to (1 − ½/W, 1 − ½/H), edges and centres included): exactly the positions where bilinear_weights interpolates and does not extend the edge, so its four weights reproduce uv. false off it and for a non-finite coordinate. The same chart and the same check as bilinear_weights (at least 2 × 2 texels, an ArgumentError otherwise), read on the position's value under every ForwardDiff Dual layer. For a caller that drops a position rather than extending the texture (a footprint off the grid).
VisualGeometryToolkitCore.is_projective — Method
is_projective(t) -> Booltrue when t contains a projective stage (a HomographyMap) anywhere in its composition tree — i.e. its output is only defined up to scale unless a perspective division is applied somewhere downstream. Recurses through BOTH sides of Base.ComposedFunction and CT.ComposedTransformation (the predecessor needs_perspective_division only checked the inner side, and missed CT-typed compositions entirely).
VisualGeometryToolkitCore.image_sample! — Method
image_sample!(dst, src::AbstractMatrix, points; fillvalue = 0) -> dstBilinearly sample src at points[i] into dst[i], for every index of points (an array of StaticVector{2} of any shape; dst of the same size): points are COLMAP coordinates in src's pixel frame — (x, y), the centre of src[i, j] at (j − ½, i − ½) — the frame every Core map speaks, and the one image_warp's math lands in. The tap and its boundary are image_warp!'s: a tap off the image reads fillvalue, so a point within half a pixel outside the centres' rectangle blends toward it and a point farther out, or a non-finite one (a map's "not imaged"), is fillvalue.
Runs one KernelAbstractions kernel on the backend that owns dst: supply device arrays (dst, src and points on one device) for GPU execution. dst and src may differ in eltype, as in image_warp!; fillvalue is in the float accumulation domain.
VisualGeometryToolkitCore.BoundedMap — Type
BoundedMap{M<:CT.Transformation, R<:Rect{2,Int}} <: CT.TransformationDecorator that pairs a CT.Transformation with an output Rect{2,Int}. The rect is the codomain extent — typically the destination region of a warp or the valid pixel area of a homography.
Fields
map::M— the inner transform (the math)rect::R— the output region (decoration)
Trait
bounds_trait(::BoundedMap) = HasBounds(). extent(bm) returns bm.rect.
Example
H = HomographyMap(K * [r1 r2 t])
bm = BoundedMap(H, Rect(0, 0, 1920, 1080))
extent(bm) # Rect(0, 0, 1920, 1080)
to_homogeneous(bm) === H.forward # forwards throughIndex
CoordinateTransformations.AffineMapCoordinateTransformations.AffineMapCoordinateTransformations.AffineMapCoordinateTransformations.AffineMapCoordinateTransformations.TranslationCoordinateTransformations.TranslationCoordinateTransformations.TranslationVisualGeometryToolkitCore.BoundedMapVisualGeometryToolkitCore.CartesianToLogPolarVisualGeometryToolkitCore.EuclideanMapVisualGeometryToolkitCore.FramedImageVisualGeometryToolkitCore.LogPolarToCartesianVisualGeometryToolkitCore.SimilarityMapVisualGeometryToolkitCore.SimilarityMapVisualGeometryToolkitCore.SimilarityMapVisualGeometryToolkitCore.bilinear_sampleVisualGeometryToolkitCore.bilinear_sample_clampedVisualGeometryToolkitCore.bilinear_weightsVisualGeometryToolkitCore.canonical_mapVisualGeometryToolkitCore.fuseVisualGeometryToolkitCore.image_sample!VisualGeometryToolkitCore.image_warpVisualGeometryToolkitCore.image_warpVisualGeometryToolkitCore.image_warp!VisualGeometryToolkitCore.image_warp!VisualGeometryToolkitCore.image_warp_batch_to!VisualGeometryToolkitCore.is_inside_texel_centresVisualGeometryToolkitCore.is_projectiveVisualGeometryToolkitCore.logpolar_mapVisualGeometryToolkitCore.logpolar_mapVisualGeometryToolkitCore.logpolar_to_cartesianVisualGeometryToolkitCore.transfer