update unit tests and documentation

Author: jamesgrimmett

skyfield/documentation/earth-satellites.rst

@@ -518,22 +518,22 @@ position in the line-of-sight:
 
 * :meth:`~skyfield.toposlib.Geoid.intersection_of()`
 
-For example, first contruct an inertial :data:`~skyfield.framelib.LVLH` frame
-for the satellite position, then use the frame to define an attitude vector:
+For example, `roll`, `pitch`, and `yaw` angles can be provided to the
+:meth:`~skyfield.sgp4lib.EarthSatellite._attitude()` method, which will return
+a :class:`~skyfield.positionlib.ICRF` position vector representing
+the satellite's line-of-sight. The `target` and `center` attributes store the
+attitude vector and the satellite position, respectively;
 
 .. testcode::
 
-    from skyfield.framelib import LVLH
-
-    satellite_lvlh = LVLH(geocentric)
-    attitude = satellite_lvlh.icrf_looking_vector(pitch=0.0, roll=0.0)
-    print('Frame:', satellite_lvlh)
-    print('Attitude:', attitude)
+    attitude = satellite._attitude(t=t, roll=0.0, pitch=0.0, yaw=0.0)
+    print('Attitude.target:', attitude.target)
+    print('Attitude.center:', attitude.center)
 
 .. testoutput::
 
-    Frame: <LVLH> Center (399) Pointing Local Vertical Local Horizontal reference frame.
-    Attitude: [ 0.57745914  0.2781511  -0.76757599]
+    Attitude.target: [ 0.57745914  0.2781511  -0.76757599]
+    Attitude.center: <Geocentric ICRS position and velocity at date t center=399 target=-125544>
 
 In this case we have set the pitch and roll to zero, so the attitude vector
 is pointing toward the center of mass of the Earth, i.e., a unit vector
@@ -555,7 +555,7 @@ use the :meth:`~skyfield.toposlib.Geoid.intersection_of()` method:
 
 .. testcode::
 
-    intersection = wgs84.intersection_of(geocentric, attitude)
+    intersection = wgs84.intersection_of(attitude)
     print('Latitude:', intersection.latitude)
     print('Longitude:', intersection.longitude)
 

skyfield/tests/test_earth_satellites.py

@@ -220,7 +220,7 @@ def test_neutral_attitude():
         a = sat._attitude(t)
         # Attitude should be the negative of position vector.
         neg_p = -array(p) / length_of(array(p))
-        assert allclose(a.center.au, p)
+        assert allclose(a.center.xyz.au, p)
         assert allclose(a.target, neg_p)
 
 def test_attitude():
@@ -232,17 +232,37 @@ def test_attitude():
 
     for angle in angles:
         abs_angle = abs(angle)
+        # Angle between attitude and position vector after pitch or roll should
+        # be equal to the provided angle.
         a = sat._attitude(t, roll=angle)
         assert isclose(angle_between(a.target, -pos), abs_angle)
 
         a = sat._attitude(t, pitch=angle)
         assert isclose(angle_between(a.target, -pos), abs_angle)
 
+        # Yaw without other rotations should not change attitude.
         a = sat._attitude(t, yaw=angle)
         assert isclose(angle_between(a.target, -pos), 0.0)
 
-        a = sat._attitude(t, pitch=angle, yaw=angle)
-        assert allclose(angle_between(a.target, -pos), abs_angle)
+        # Angle between attitude and position vector after yaw with pitch or
+        # or roll should be equal to the provided angle, regardless of order.
+        a = sat._attitude(t, pitch=angle, yaw=angle, rotation_order="yz")
+        assert isclose(angle_between(a.target, -pos), abs_angle)
+
+        a = sat._attitude(t, pitch=angle, yaw=angle, rotation_order="zy")
+        assert isclose(angle_between(a.target, -pos), abs_angle)
+
+        a = sat._attitude(t, roll=angle, yaw=angle, rotation_order="xz")
+        assert isclose(angle_between(a.target, -pos), abs_angle)
+
+        a = sat._attitude(t, roll=angle, yaw=angle, rotation_order="zx")
+        assert isclose(angle_between(a.target, -pos), abs_angle)
 
-        a = sat._attitude(t, roll=angle, yaw=angle)
-        assert allclose(angle_between(a.target, -pos), abs_angle)
+        # Rotations applied in reverse will result in different attitudes,
+        # but the angle between attitude and position vector should be equal.
+        axyz = sat._attitude(t, roll=angle, pitch=angle, yaw=angle)
+        azyx = sat._attitude(t, roll=angle, pitch=angle, yaw=angle,
+                             rotation_order="zyx")
+        assert isclose(
+            angle_between(axyz.target, -pos), angle_between(azyx.target, -pos)
+            )