Affine#

Overview#

The affine module in SplineOps provides affine geometric transforms for 2-D or 3-D spatial data using spline interpolation. splineops.affine.affine_transform() accepts a general pull-back matrix and offset, splineops.affine.rotate() constructs rotation geometry, and splineops.affine.AffinePlan reuses fixed geometry across frames. Such operations are widely used in image processing, computer graphics, and scientific computing [1].

2D Rotation#

In 2D space, a point of coordinates \((x, y)\) can be rotated around a center point \((x_\mathrm{c}, y_\mathrm{c})\) by an angle \(\theta\) (in radians) using the rotation matrix.

\[\begin{split}\begin{pmatrix} x' \\ y' \end{pmatrix} = \begin{pmatrix} \cos\theta & -\sin\theta \\ \sin\theta & \cos\theta \end{pmatrix} \begin{pmatrix} x - x_\mathrm{c} \\ y - y_\mathrm{c} \end{pmatrix} + \begin{pmatrix} x_\mathrm{c} \\ y_\mathrm{c} \end{pmatrix}\end{split}\]

Here, \((x', y')\) are the coordinates of the rotated point.

3D Rotation#

For 3D data, a point \(\mathbf{v} = (x, y, z)\) can be rotated around an arbitrary axis defined by a unit vector \(\mathbf{u} = (u_\mathrm{x}, u_\mathrm{y}, u_\mathrm{z})\) by an angle \(\theta\) using Rodrigues’ rotation formula

\[\mathbf{v}' = \mathbf{v} \cos\theta + (\mathbf{u} \times \mathbf{v}) \sin\theta + \mathbf{u} \left( \mathbf{u} \cdot \mathbf{v} \right) (1 - \cos\theta)\]

Alternatively, the rotation can be expressed with the rotation matrix

\[\begin{split}\mathbf{R} = \begin{pmatrix} \cos\theta + u_{\mathrm{x}}^2\,(1 - \cos\theta) & u_{\mathrm{x}}\,u_{\mathrm{y}}\,(1 - \cos\theta) - u_{\mathrm{z}}\,\sin\theta & u_{\mathrm{x}}\,u_{\mathrm{z}}\,(1 - \cos\theta) + u_{\mathrm{y}}\,\sin\theta \\[6pt] u_{\mathrm{y}}\,u_{\mathrm{x}}\,(1 - \cos\theta) + u_{\mathrm{z}}\,\sin\theta & \cos\theta + u_{\mathrm{y}}^2\,(1 - \cos\theta) & u_{\mathrm{y}}\,u_{\mathrm{z}}\,(1 - \cos\theta) - u_{\mathrm{x}}\,\sin\theta \\[6pt] u_{\mathrm{z}}\,u_{\mathrm{x}}\,(1 - \cos\theta) - u_{\mathrm{y}}\,\sin\theta & u_{\mathrm{z}}\,u_{\mathrm{y}}\,(1 - \cos\theta) + u_{\mathrm{x}}\,\sin\theta & \cos\theta + u_{\mathrm{z}}^2\,(1 - \cos\theta) \end{pmatrix}\end{split}\]

The rotated point is calculated as

\[\begin{split}\begin{pmatrix} x' \\ y' \\ z' \end{pmatrix} = \mathbf{R} \begin{pmatrix} x - x_\mathrm{c} \\ y - y_\mathrm{c} \\ z - z_\mathrm{c} \end{pmatrix} + \begin{pmatrix} x_\mathrm{c} \\ y_\mathrm{c} \\ z_\mathrm{c} \end{pmatrix}\end{split}\]

Affine Transformation by Resampling#

The rotated coordinates may not coincide with the original data grid, so spline interpolation is employed for the resampling of the rotated data. The approach documented here uses standard interpolation, which leverages tensor-product B-splines for smooth, accurate results across multiple dimensions while minimizing artifacts like aliasing. The process asks one to first recenter the coordinates so that the rotation center coincides with the origin, then to apply the appropriate 2D or 3D rotation matrix to the recentered coordinates, followed by a translation of the rotated recentered coordinates back to their original reference frame, to compensate for the recentering step, and finally to use spline interpolation to determine the data values at these new positions.

affine_transform follows the pull-back convention \(x_\mathrm{input}=A x_\mathrm{output}+b\). rotate builds that geometry about the array center by default, or about an explicit center in array-axis coordinates. Rotation keeps the spatial input shape; a general affine transform may request another spatial output shape. The default boundary mode is "zero"; pass mode="mirror" for whole-sample mirror extension. Degrees 0 through 7 are supported. Degrees 0 through 5 in two and three dimensions are tested against equivalently configured scipy.ndimage.affine_transform (SciPy’s maximum spline order is 5). The NumPy reference and float32 SciPy path generate coordinates in bounded tiles; float64 SciPy evaluation computes them in its native affine kernel.

Evaluation backends#

AffinePlan, affine_transform, and rotate accept backend="auto" (default), "numpy", or "scipy". Automatic selection uses compiled SciPy evaluation for degrees 1–5, float32/float64, and the named zero, mirror, and periodic modes. Degree 0 retains the reference’s rounding at boundary ties; degrees 6–7, custom mode objects, and other precisions also use the NumPy reference. Explicit backend="scipy" rejects unsupported configurations. plan.backend reports the selected evaluator.

Both backends use the same SplineOps coefficient prefilter. Evaluation passes those coefficients to SciPy with prefilter=False. Zero coefficient extension maps to SciPy’s grid-constant with zero fill, whole-sample mirror maps to mirror, and periodic extension maps to grid-wrap. These are not interchangeable with SciPy’s constant or wrap conventions.

Float32 evaluation keeps the reference’s rounded affine coordinates and uses tiled map_coordinates; float64 uses affine_transform directly. Results are numerically equivalent rather than promised bitwise identical, since polynomial evaluation and accumulation order differ. Use backend="numpy" for direct comparison with the reference. Coefficient fields and saved archives remain compatible across backends with matching numerical contracts.

Automatic selection follows this compatibility policy; it does not benchmark the available backends. For repeated geometry, compare both backends on your workload. Cached NumPy evaluation can be faster, while SciPy plans retain no support-geometry cache. See Performance evidence for measured wins and losses.

General and repeated transforms#

Use the function for one transform and a plan when geometry is reused:

import numpy as np
from splineops.affine import AffinePlan, affine_transform

matrix = np.array([[1.0, 0.15], [0.0, 1.0]])
offset = np.array([-4.0, 0.0])
first = affine_transform(
    image,
    matrix,
    offset,
    degree=3,
    mode="mirror",
)

plan = AffinePlan(
    image.shape,
    matrix,
    offset,
    degree=3,
    mode="mirror",
    max_retained_bytes=256 * 1024**2,
)
output = np.empty(image.shape, dtype=np.float64)
plan.apply(next_image, out=output)

NumPy plans can retain support indexes and weights. SciPy plans use the affine matrix without retaining support arrays or a zero-valued spline template; geometry_cached is false and geometry/template retained bytes are zero. cache_geometry and its memory budget apply to the NumPy cache. Both paths still perform the coefficient prefilter for each new frame. If one frame is sent through several compatible affine geometries, call prepare_coefficients once and pass its result to each plan’s apply_coefficients method:

field = plan.prepare_coefficients(frame)
first = plan.apply_coefficients(field)
second = another_compatible_plan.apply_coefficients(field)

An splineops.affine.AffineCoefficientField is immutable and records the input shape, spatial axes, degree, boundary mode, and precision. Applying it through an incompatible plan fails explicitly. Matrix and output shape are not part of the coefficient contract, which is exactly what permits reuse across affine geometries. prefilter continues to return a raw array and supports out= for lower-level workflows, but raw arrays cannot carry a provenance check. Tagged fields can be persisted without object pickles and validated on load:

field.save("frame-coefficients.npz")
restored = another_compatible_plan.load_coefficients(
    "frame-coefficients.npz"
)

The schema-2 archive stores portable little-endian numeric values and JSON metadata. Saving flushes a same-directory temporary file and then atomically replaces the destination, so an interrupted write cannot partially update an existing field. Loading checks its schema, input shape, spatial axes, degree, canonical boundary implementation, and precision against the receiving plan; schema-1 archives remain readable. Immutable fields and plans may be reused concurrently by threads or loaded independently by spawned processes; each application allocates or writes only its own output. See Reusable workflow recipes and Stability-soak workflows for complete examples. Set cache_geometry=False for bounded-memory streaming with no retained query geometry. Plan construction raises MemoryError rather than exceeding max_retained_bytes for geometry storage.

retained_bytes includes both cached geometry and the reusable spline template; geometry_retained_bytes and template_retained_bytes report the components. configuration returns a copy of the fixed numerical contract.

Batch and channel axes#

For an array with non-spatial dimensions, select exactly two or three spatial_axes. Every remaining slice is transformed independently in the mathematical sense, while coefficient filtering and support evaluation operate on the batch together with memory-bounded query tiles:

# NCHW data: rotate the height and width axes of every batch/channel plane.
rotated = rotate(batch, 12.0, spatial_axes=(-2, -1), mode="mirror")

TensorSpline itself remains a scalar continuous N-D model; affine owns this batch/channel orchestration so the module boundaries stay clear.

Note

The geometry of the transform (center, axis, angle) is identical across methods; what changes is the spline used for resampling. Different spline degrees trade sharpness for smoothness (e.g., degree 0/nearest → blocky but fast; degree 1/linear → slight blur; degree 3/cubic → smoother, higher-quality edges).

Note

This module preserves SplineOps coefficient and boundary conventions while using compiled SciPy evaluation where supported. One-shot calls improved in the recorded backend comparisons, but repeated calls can favor cached NumPy evaluation. See Performance evidence for workload-specific evidence.

The following figure from Rotate Image shows an image rotated around a user-defined center using cubic interpolation. The red marker indicates the chosen center of rotation.

../_images/sphx_glr_01_rotate_image_001.png

Rotation Animation#

Here a more comprehensive animation exported from the example Rotation Animation, using different values of rotation angles and spline degrees.

Rotate Examples#

References#