Affine2d

class jwst.ami.utils.Affine2d(mx=None, my=None, sx=None, sy=None, xo=None, yo=None, rotradccw=None, name='Affine')

Bases: object

Implement the Bracewell Fourier 2D affine transformation theorem.

A class to help implement the Bracewell Fourier 2D affine transformation theorem to calculate appropriate coordinate grids in the Fourier domain (eg image space, momentum space), given an affine transformation of the original (eg pupil space, configuration space) space. This class provides the required normalization for the Fourier transform, and provides for a single way to set pixel pitch (including independent x and y scales) in the image plane.

The theorem states that if f(x,y) and F(u,v) are Fourier pairs, and g(x,y) = f(x’,y’), where:

x' = mx * x  +  sx * y  +  xo
y' = my * y  +  sy * x  +  yo,

then G(u,v), the Fourier transform of g(x,y), is given by:

G(u,v) = ( 1/|Delta| ) * exp { (2*Pi*i/Delta) *
                                  [ (my*xo - sx*yo) * u  +
                                    (mx*yo - sy*xo) * v  ] }  *
                         F{ ( my*u - sy*v) / Delta,
                            (-sx*u + mx*v) / Delta  }

where:

Delta = mx * my - sx * sy.

The reverse transformation, from (x’,y’) to (x,y) is given by:

x = (1/Delta) * ( my * x' - sx * y'  -  my * xo + sx * yo )
y = (1/Delta) * ( mx * y' - sy * x'  -  mx * yo + sy * xo )

For clarity we call (x,y) IDEAL coordinates, and (x’,y’) DISTORTED coordinates. We know the analytical form of F(u,v) from the literature, and need to calculate G(u,v) at a grid of points in the (u,v) space, with two lattice vectors a and b defining the grid. These lattice vectors have components a=(a_u,a_v) and b=(b_u,b_v) along the u and v axes.

Discussion with Randall Telfer (2018.05.18) clarified that:

These constants, properly applied to the analytical transform in a
"pitch matrix" instead of a scalar "pitch" variable, provide the PSF
sampled in radians on an imaginary detector that is perpendicular to
the chief ray.  The actual detector might be tilted in a different
manner, changing the x pitch and y pitch of the detector pixels
independent of the effects of pupil distortion.

We presume the main use of this object is to calculate intensity in the
detector, so we include a DetectorTilt object in this class, although
this object is constructed to have an 'identity' effect during the
initial development and use of the Affine2d class in NRM data analysis.
For most physical detector tilts we expect the DetectorTilt to have a
small effect on an image simulated using the Fourier transform.  There
are exceptions to this 'small effect' expectation (eg HST NICMOS 2 has
a detector tilt of a few tens of degrees).  As long as the detector is
small compared to the effective focal length (i.e. detector size <<<
nominal f-ratio * primary diameter) of the system, detector tilts will
change the pixel pitch (in radians) linearly across the field.

There may be an ambiguity between the 'detector tilt effect' on pixel
pitch and the diffractive effect (which results from pupil distortion
between a pupil stop and the primary).  This might have to be broken
using a pupil distortion from optical modelling such as ray tracing.
Or it could be broken by requiring the detector tilt effect to be
derived from optical models and known solid body models or metrology of
the instrument/telescope, and the optical pupil distortion found from
fitting on-sky data.

References

• Jean Baptiste Joseph Fourier 1768-1830

• Ron Bracewell 1921-2007

• Code by Anand Sivaramakrishnan 2018

Initialize with transformation constants.

Parameters:

mxfloat

Dimensionless x-magnification

myfloat

Dimensionless y-magnification

sxfloat

Dimensionless x shear

syfloat

Dimensionless y shear

xofloat

X-offset in pupil space

yofloat

Y-offset in pupil space

rotradccwfloat

A counter-clockwise rotation of THE VECTOR FROM THE ORIGIN TO A POINT, in a FIXED COORDINATE FRAME, by this angle (radians) (as viewed in ds9 or with fits NAXIS1 on X and NAXIS2 on Y); default is None

namestr, optional

Name of the Affine2d object to store in name attribute

Methods Summary

distort_f_args(u, v)	Implement the (u,v) to (u',v') change in arguments of F.
distortphase(u, v)	Calculate the phase term in the Bracewell Fourier 2D affine transformation theorem.
forward(point)	Create the forward affine transformation, in ideal-to-distorted coordinates.
get_rotd()	Calculate the rotation that was used to creat a pure rotation affine2d object.
reverse(point)	Create the reverse affine transformation, in distorted-to-ideal coordinates.

Methods Documentation

distort_f_args(u, v)

Implement the (u,v) to (u’,v’) change in arguments of F.

See class documentation of Bracewell Fourier 2D affine transformation theorem.

Parameters:

ufloat

1st argument of F

vfloat

2nd argument of F

Returns:

uprimefloat

1st transformed argument of F

vprimefloat

2nd transformed argument of F

distortphase(u, v)

Calculate the phase term in the Bracewell Fourier 2D affine transformation theorem.

The phase term is:

1/|Delta| * exp{(2*Pi*i/Delta) * [(my*xo- x*yo) * u + (mx*yo-sy*xo)*v]}

where u and v are in inverse length units.

Parameters:

ufloat

1st argument of F, in units of inverse length units

vfloat

2nd argument of F, in units of inverse length units

Returns:

phasecomplex array

Phase term divided by the determinant.

forward(point)

Create the forward affine transformation, in ideal-to-distorted coordinates.

Parameters:

pointfloat, float

Coordinates in ideal space, which to apply forward transform

Returns:

trans_pointfloat, float

Coordinates in distorted space

get_rotd()

Calculate the rotation that was used to creat a pure rotation affine2d object.

Returns:

rotdfloat

Rotation used to creat a pure rotation affine2d

reverse(point)

Create the reverse affine transformation, in distorted-to-ideal coordinates.

Parameters:

pointfloat, float

Coordinates in distorted space, which to apply reverse transform

Returns:

trans_pointfloat, float

Coordinates in ideal space