hwoutils.transforms#

Image transformation utilities.

Flux-conserving resampling and sub-pixel image operations. All functions are JIT-compilable and differentiable.

Functions#

`ccw_rotation_matrix`(rotation_deg)	Return the counter-clockwise rotation matrix for a given angle.
`shift_image`(image, shift_y, shift_x[, order, mode, cval])	Shift an image with sub-pixel precision.
`resample_flux`(f_src, pixscale_src, pixscale_tgt, shape_tgt)	Resample an image onto a new grid while conserving total flux.
`_decompose_angle`(angle)	Split an angle into a (-45, 45] remainder plus a count of 90 deg turns.
`_rot90_traceable`(m, k[, axes])	Traceable `jnp.rot90` (`k` may be a tracer).
`_rotate_with_shear`(image, rot_deg)	Three-shear (x, y, x) Fourier rotation for \|rot_deg\| <= 45.
`rotate_image`(image, rotation_deg)	Rotate a square image about its center with Fourier-domain shears.
`downsample_psf`(psf, src_pixscale, target_shape)	Downsample a PSF to target shape while conserving total flux.
`downsample_psfs`(psfs, src_pixscale, target_shape)	Downsample a stack of PSFs to target shape while conserving total flux.

Module Contents#

hwoutils.transforms.ccw_rotation_matrix(rotation_deg)[source]#

Return the counter-clockwise rotation matrix for a given angle.

Args:: rotation_deg: Rotation angle in degrees. Positive = counter-clockwise.
Returns:: 2x2 rotation matrix as a JAX array.

Parameters:: rotation_deg (float)
Return type:: jax.Array

hwoutils.transforms.shift_image(image, shift_y, shift_x, order=3, mode='constant', cval=0.0)[source]#

Shift an image with sub-pixel precision.

Uses inverse mapping: to shift content by (+dy, +dx), sample from (y-dy, x-dx).

Args:

image: 2D input image. shift_y: Shift in Y direction (pixels). Positive = Down. shift_x: Shift in X direction (pixels). Positive = Right. order: Interpolation order passed to map_coordinates. Default

is 3, which uses the Keys cubic convolution kernel (see docs/interpolation.md).

mode: Boundary handling mode. cval: Value for ‘constant’ mode outside boundaries.

Returns:

Shifted image with same shape as input.

Parameters:

image (jax.Array)
shift_y (float)
shift_x (float)
order (int)
mode (str)
cval (float)

Return type:

jax.Array

hwoutils.transforms.resample_flux(f_src, pixscale_src, pixscale_tgt, shape_tgt, rotation_deg=0.0, order=3)[source]#

Resample an image onto a new grid while conserving total flux.

Performs an affine transformation (rotation and scaling) to map the source image onto a target grid. Converts to surface brightness, interpolates, then converts back to integrated flux per pixel.

Args:: f_src: Source image (2D) with integrated flux per pixel. pixscale_src: Pixel scale of source image. pixscale_tgt: Pixel scale of target image (same units as src). shape_tgt: Target shape (ny_tgt, nx_tgt). rotation_deg: CCW rotation angle in degrees. order: Interpolation order passed to map_coordinates. Default

is 3, which uses the Keys cubic convolution kernel – a true interpolant with partition of unity at integer grid spacing that conserves flux on integer downsampling of band-limited inputs. See docs/interpolation.md.
Returns:: Resampled image with total flux conserved. Shape: (ny_tgt, nx_tgt).

Parameters:

f_src (jax.Array)
pixscale_src (float)
pixscale_tgt (float)
shape_tgt (tuple[int, int])
rotation_deg (float)
order (int)

Return type:

jax.Array

hwoutils.transforms._decompose_angle(angle)[source]#

Split an angle into a (-45, 45] remainder plus a count of 90 deg turns.

The three-shear Fourier rotation is only well behaved for |angle| <= 45 deg, so larger rotations are handled by lossless 90 deg array rotations plus a small residual shear rotation.

Parameters:: angle (jax.Array)
Return type:: tuple[jax.Array, jax.Array]

hwoutils.transforms._rot90_traceable(m, k, axes=(0, 1))[source]#

Traceable jnp.rot90 (k may be a tracer).

Parameters:

m (jax.Array)
k (jax.Array)

Return type:

jax.Array

hwoutils.transforms._rotate_with_shear(image, rot_deg)[source]#

Three-shear (x, y, x) Fourier rotation for |rot_deg| <= 45.

Uses the Fourier-domain shear primitives from hwoutils.fft.

Parameters:

image (jax.Array)
rot_deg (jax.Array)

Return type:

jax.Array

hwoutils.transforms.rotate_image(image, rotation_deg)[source]#

Rotate a square image about its center with Fourier-domain shears.

Implements the three-shear rotation of Larkin et al. (1997): a rotation is decomposed into shear-x, shear-y, shear-x, each a phase ramp in the Fourier domain. Unlike interpolation-based rotation this introduces no resampling blur and conserves the band-limited signal, which is why it is the standard choice for de-rotating roll frames in angular differential imaging.

The image is assumed square. Positive rotation_deg is counter-clockwise (same convention as ccw_rotation_matrix()); rotations beyond (-45, 45] are handled by lossless 90 deg turns plus a residual shear rotation.

Args:: image: Source image (2D, square). rotation_deg: Rotation angle in degrees, positive = counter-clockwise.
Returns:: Rotated image, same shape as the input.

Parameters:

image (jax.Array)
rotation_deg (float)

Return type:

jax.Array

hwoutils.transforms.downsample_psf(psf, src_pixscale, target_shape)[source]#

Downsample a PSF to target shape while conserving total flux.

Args:

psf: The source PSF image (2D array). src_pixscale: The pixel scale of the source PSF (in lambda/D or

other consistent units).

target_shape: The target shape (ny_tgt, nx_tgt).

Returns:

Tuple of (resampled_psf, new_pixscale).

Parameters:

psf (jax.Array)
src_pixscale (float)
target_shape (tuple[int, int])

Return type:

tuple[jax.Array, float]

hwoutils.transforms.downsample_psfs(psfs, src_pixscale, target_shape)[source]#

Downsample a stack of PSFs to target shape while conserving total flux.

Args:: psfs: Stack of PSF images with shape (N, H, W). src_pixscale: The pixel scale of the source PSFs. target_shape: The target shape (ny_tgt, nx_tgt) for each PSF.
Returns:: Tuple of (resampled_psfs, new_pixscale).

Parameters:

psfs (jax.Array)
src_pixscale (float)
target_shape (tuple[int, int])

Return type:

tuple[jax.Array, float]