rotations

A collection of basic routines for performing rotation calculations.

Authors

Colin Cox Johannes Sahlmann

pysiaf.utils.rotations.attitude(v2, v3, ra, dec, pa)

Return rotation matrix that transforms from v2,v3 to RA,Dec.

Makes a 3D rotation matrix which rotates a unit vector representing a v2,v3 position to a unit vector representing an RA, Dec pointing with an assigned position angle Described in JWST-STScI-001550, SM-12, section 5.1.

Parameters:

v2float

a position measured in arc-seconds

v3float

a position measured in arc-seconds

rafloat

Right Ascension on the sky in degrees

decfloat

Declination on the sky in degrees

pafloat

Position angle in degrees measured from North to V3 axis in North to East direction.

Returns:

mnumpy matrix

A (3 x 3) matrix represents the attitude of the telescope which points the given V2V3 position to the indicated RA and Dec and with the V3 axis rotated by position angle pa

pysiaf.utils.rotations.attitude_matrix(nu2, nu3, ra, dec, pa, convention='JWST')

Return attitude matrix.

Makes a 3D rotation matrix that transforms between telescope frame and sky. It rotates a unit vector on the idealized focal sphere (specified by the spherical coordinates nu2, nu3) to a unit vector representing an RA, Dec pointing with an assigned position angle measured at nu2, nu3. See JWST-STScI-001550, SM-12, section 5.1.

Parameters:

nu2float

an euler angle (default unit is arc-seconds)

nu3float

an euler angle (default unit is arc-seconds)

rafloat

Right Ascension on the sky in degrees

decfloat

Declination on the sky in degrees

pafloat

Position angle of V3 axis at nu2,nu3 measured from North to East (default unit is degree)

Returns:

mnumpy matrix

the attitude matrix

pysiaf.utils.rotations.axial_rotation(ax, phi, vector)

Apply direct rotation to a vector using Rodrigues’ formula.

Parameters:

axfloat array of size 3

a unit vector represent a rotation axis

phifloat

angle in degrees to rotate original vector

vectorfloat

array of size 3 representing any vector

Returns:

vfloat

array of size 3 representing the rotated vectot

pysiaf.utils.rotations.convert_quantity(x_in, to_unit, factor=1.0)

Check if astropy quantity and apply conversion factor

Parameters:

x_infloat or quantity

input

to_unitastropy.units unit

unit to convert to

factorfloat

Factor to apply if input is not a quantity

Returns:

x_outfloat

converted value

pysiaf.utils.rotations.cross(a, b)

Return cross product of two vectors c = a X b.

The order is significant. Reversing the order changes the sign of the result.

Parameters:

afloat array or list of length 3

first vector

bfloat array or list of length 3

second vector

Returns:

c float array of length 3

the product vector

pysiaf.utils.rotations.getv2v3(attitude, ra, dec)

Return v2,v3 position of any RA and Dec using the inverse of attitude matrix.

Parameters:

attitude3 by 3 float array

the telescope attitude matrix

rafloat

RA of sky position

decfloat

Dec of sky position

Returns:

v2,v3tuple of floats

V2,V3 value at matching position

pysiaf.utils.rotations.idl_to_tel_rotation_matrix(V2Ref_arcsec, V3Ref_arcsec, V3IdlYAngle_deg)

Return 3D rotation matrix for ideal to telescope transformation.

Parameters:

V2Ref_arcsec

V3Ref_arcsec

V3IdlYAngle_deg

Returns:

pysiaf.utils.rotations.pointing(attitude, v2, v3, positive_ra=True, input_cartesian=False)

Calculate where a v2v3 position points on the sky using the attitude matrix.

Parameters:

attitude3 by 3 float array

the telescope attitude matrix

v2float or array of floats

V2 coordinate in arc-seconds

v3float or array of floats

V3 coordinate in arc-seconds

positive_rabool.

If True forces ra value to be positive

Returns:

rdtuple of floats

(ra, dec) - RA and Dec in degrees

pysiaf.utils.rotations.polar_angles(vector, positive_azimuth=False)

Compute polar coordinates of an unit vector.

Parameters:

vectorfloat list or array of length 3

3-component unit vector

positive_azimuthbool

If True, the returned nu2 value is forced to be positive.

Returns:

nu2, nu3tuple of floats with astropy quantity

The same position represented by polar coordinates

pysiaf.utils.rotations.posangle(attitude, v2, v3)

Return the V3 angle at arbitrary v2,v3 using the attitude matrix.

This is the angle measured from North to V3 in an anti-clockwise direction i.e. North to East. Formulae from JWST-STScI-001550, SM-12, section 6.2. Subtract 1 from each index in the text to allow for python zero indexing.

Parameters:

attitude3 by 3 float array

the telescope attitude matrix

v2float

V2 coordinate in arc-seconds

v3float

V3 coordinate in arc-seconds

Returns:

pafloat

Angle in degrees - the position angle at (V2,V3)

pysiaf.utils.rotations.radec(vector, positive_ra=False)

Return RA and Dec in degrees corresponding to the unit vector vector.

Parameters:

vectora float array or list of length 3

represents a unit vector so should have unit magnitude if not, the normalization is forced within the method

positive_rabool

indicating whether to force ra to be positive

Returns:

ra , dectuple of floats

RA and Dec in degrees corresponding to the unit vector vector

pysiaf.utils.rotations.rodrigues(attitude)

Interpret rotation matrix as a single rotation by angle phi around unit length axis.

Return axis, angle and matching quaternion. The quaternion is given in a slightly irregular order with the angle value preceding the axis information. Most of the literature shows the reverse order but JWST flight software uses the order given here.

Parameters:

attitude3 by 3 float array

the telescope attitude matrix

Returns:

axisfloat array of length 3

a unit vector which is the rotation axis

phifloat

angle of rotation in degrees

qfloat array of length 4

the equivalent quaternion

pysiaf.utils.rotations.rotate(axis, angle)

Implement fundamental 3D rotation matrices.

Rotate a vector by an angle measured in degrees, about axis 1 2 or 3 in the inertial frame. This is an anti-clockwise rotation when sighted along the axis, commonly called a right-handed rotation.

Parameters:

axisint

axis number, 1, 2, or 3

anglefloat

angle of rotation in degrees

Returns:

rfloat array

a (3 x 3) matrix which performs the specified rotation.

pysiaf.utils.rotations.rv(v2, v3)

Rotate from v2,v3 position to V1 axis.

Rotate so that a V2,V3 position ends up where V1 started.

Parameters:

v2float

V2 position in arc-sec

v3float

V3 position in arc-sec

Returns:

rva (3 x 3) array

matrix which performs the rotation described.

pysiaf.utils.rotations.sky_posangle(attitude, ra, dec)

Return the V3 angle at arbitrary RA and Dec using the attitude matrix.

This is the angle measured from North to V3 in an anti-clockwise direction.

Parameters:

attitude3 by 3 float array

the telescope attitude matrix

rafloat

RA position in degrees

decfloat

Dec position in degrees

Returns:

pafloat

resulting position angle in degrees

pysiaf.utils.rotations.sky_to_tel(attitude, ra, dec, verbose=False)

Transform from sky (RA, Dec) to telescope (nu2, nu3) angles.

Return nu2,nu3 position on the idealized focal sphere of any RA and Dec using the inverse of attitude matrix.

Parameters:

attitude3 by 3 float array

The attitude matrix.

rafloat (default unit is degree)

RA of sky position

decfloat (default unit is degree)

Dec of sky position

Returns:

nu2, nu3tuple of floats with quantity

spherical coordinates at matching position on the idealized focal sphere

pysiaf.utils.rotations.slew(v2t, v3t, v2a, v3a)

Calculate matrix which slews from target (v2t,v3t) to aperture position (v2a, v3a) without a roll change.

Useful for target acquisition calculations.

Parameters:

v2tfloat

Initial V2 position in arc-sec

v3tfloat

Initial V3 position in arc-sec

v2afloat

Final V2 position in arc-sec

v3afloat

Final V3 position in arc-sec

Returns:

mva (3 x 3) float array

The matrix that performs the rotation described

pysiaf.utils.rotations.tel_to_sky(attitude, nu2, nu3, positive_ra=True)

Calculate where a nu2,nu3 position points on the sky.

Parameters:

attitude3 by 3 float array

the telescope attitude matrix

nu2float or array of floats (default unit is arcsecond)

V2 coordinate in arc-seconds

nu3float or array of floats (default unit is arcsecond)

V3 coordinate in arc-seconds

positive_rabool.

If True forces ra value to be positive

Returns:

rdtuple of floats with quantity

(ra, dec) - RA and Dec

pysiaf.utils.rotations.unit(ra, dec)

Convert inertial frame vector expressed in polar coordinates / Euler angles to unit vector components.

See Section 5 of JWST-STScI-001550 and Equation 4.1 of JWST-PLAN-006166.

Parameters:

rafloat or array of floats

RA of sky position in degrees

decfloat or array of floats

Dec of sky position in degrees

Returns:

vectorfloat array of length 3

the equivalent unit vector in the inertial frame

pysiaf.utils.rotations.unit_vector_from_cartesian(x=None, y=None, z=None)

Return unit vector corresponding to two cartesian coordinates.

Array inputs are supported.

Parameters:

xfloat or quantity

cartesian unit vector X coordinate in radians

yfloat or quantity

cartesian unit vector Y coordinate in radians

zfloat or quantity

cartesian unit vector Z coordinate in radians

Returns:

unit_vectornumpy.ndarray

Unit vector

pysiaf.utils.rotations.unit_vector_hst_fgs_object(rho, phi)

Return unit vector on the celestial sphere.

This is according to the HST object space angle definitions, CSC/TM-82/6045 1987, Section 4.1.2.2.4

Parameters:

rhofloat or array of floats (default unit is degree)

RA of sky position

phifloat or array of floats (default unit is degree)

Dec of sky position

Returns:

vectorfloat array of length 3

the equivalent unit vector in the inertial frame

pysiaf.utils.rotations.unit_vector_sky(ra, dec)

Return unit vector on the celestial sphere.

Parameters:

rafloat or array of floats (default unit is degree)

RA of sky position

decfloat or array of floats (default unit is degree)

Dec of sky position

Returns:

vectorfloat array of length 3

the equivalent unit vector in the inertial frame

pysiaf.utils.rotations.v2v3(vector)

Compute v2,v3 polar coordinates corresponding to a unit vector in the rotated (telescope) frame.

See Section 5 of JWST-STScI-001550.

Parameters:

vectorfloat list or array of length 3

unit vector of cartesian coordinates in the rotated (telescope) frame

Returns:

v2, v3tuple of floats

The same position represented by V2, V3 values in arc-sec.