Clarify documentation of orbital_parameters metadata

doc/source/dev_guide/custom_reader.rst

@@ -391,8 +391,8 @@ needs to implement a few methods:
    - the dataset info that is the description of the channel in the YAML file
 
   This method has to return an xarray.DataArray instance if the loading is
-  successful, containing the data and metadata of the loaded dataset, or
-  return None if the loading was unsuccessful.
+  successful, containing the data and :ref:`metadata <dataset_metadata>` of the
+  loaded dataset, or return None if the loading was unsuccessful.
 
  - the ``get_area_def`` method, that takes as single argument the dataset ID for which we want
    the area. For the data that cannot be geolocated with an area

doc/source/readers.rst

@@ -112,6 +112,8 @@ more information on the possible parameters.
 Metadata
 ========
 
+.. _dataset_metadata:
+
 The datasets held by a scene also provide vital metadata such as dataset name, units, observation time etc. The
 following attributes are standardized across all readers:
 
@@ -126,20 +128,26 @@ following attributes are standardized across all readers:
 
   * For *geostationary* satellites it is described using the following scalar attributes:
 
-    * ``satellite_actual_longitude/latitude/altitude``: Current position of the satellite at the time of observation in
-      geodetic coordinates (i.e. altitude is normal to the surface).
-    * ``satellite_nominal_longitude/latitude/altitude``: Centre of the station keeping box (a confined area in which
-      the satellite is actively maintained in using maneuvres). Inbetween major maneuvres, when the satellite
-      is permanently moved, the nominal position is constant.
-    * ``nadir_longitude/latitude``: Intersection of the instrument's Nadir with the surface of the earth. May differ
-      from the actual satellite position, if the instrument is poiting slightly off the axis (satellite, earth-centre).
-      If available, this should be used to compute viewing angles etc. Otherwise, use the actual satellite position.
-    * ``projection_longitude/latitude/altitude``: Projection centre of the re-projected data. This should be used to
-      compute lat/lon coordinates. Note that the projection centre can differ considerably from the actual satellite
-      position. For example MSG-1 was at times positioned at 3.4 degrees west, while the image data was re-projected
-      to 0 degrees.
-    * [DEPRECATED] ``satellite_longitude/latitude/altitude``: Current position of the satellite at the time of observation
-      in geodetic coordinates.
+    * ``satellite_actual_longitude/latitude/altitude``: Current position of the satellite at the
+      time of observation in geodetic coordinates (i.e. altitude is relative and normal to the
+      surface of the ellipsoid).
+    * ``satellite_nominal_longitude/latitude/altitude``: Centre of the station keeping box (a
+      confined area in which the satellite is actively maintained in using maneuvres). Inbetween
+      major maneuvres, when the satellite is permanently moved, the nominal position is constant.
+    * ``nadir_longitude/latitude``: Intersection of the instrument's Nadir with the surface of the
+      earth. May differ from the actual satellite position, if the instrument is poiting slightly
+      off the axis (satellite, earth-centre). If available, this should be used to compute viewing
+      angles etc. Otherwise, use the actual satellite position.
+    * ``projection_longitude/latitude/altitude``: Projection centre of the re-projected data. This
+      should be used to compute lat/lon coordinates. Note that the projection centre can differ
+      considerably from the actual satellite position. For example MSG-1 was at times positioned
+      at 3.4 degrees west, while the image data was re-projected to 0 degrees.
+    * [DEPRECATED] ``satellite_longitude/latitude/altitude``: Current position of the satellite at
+      the time of observation in geodetic coordinates.
+
+    .. note:: Longitudes and latitudes are given in degrees, altitude in meters. For use in
+              pyorbital, the altitude has to be converted to kilometers, see for example
+              `get_observer_look`_.
 
   * For *polar orbiting* satellites the readers usually provide coordinates and viewing angles of the swath as
     ancillary datasets. Additional metadata related to the satellite position include:
@@ -150,6 +158,8 @@ following attributes are standardized across all readers:
 
 Note that the above attributes are not necessarily available for each dataset.
 
+.. _get_observer_look: https://pyorbital.readthedocs.io/en/latest/#pyorbital.orbital.get_observer_look
+
 Coordinates
 ===========
 

satpy/readers/abi_l1b.py

@@ -60,7 +60,7 @@ def get_dataset(self, key, info):
                           'sensor': self.sensor,
                           'satellite_latitude': float(self['nominal_satellite_subpoint_lat']),
                           'satellite_longitude': float(self['nominal_satellite_subpoint_lon']),
-                          'satellite_altitude': float(self['nominal_satellite_height'])})
+                          'satellite_altitude': float(self['nominal_satellite_height']) * 1000.})
 
         # Add orbital parameters
         projection = self.nc["goes_imager_projection"]
@@ -70,7 +70,7 @@ def get_dataset(self, key, info):
             'projection_altitude': float(projection.attrs['perspective_point_height']),
             'satellite_nominal_latitude': float(self['nominal_satellite_subpoint_lat']),
             'satellite_nominal_longitude': float(self['nominal_satellite_subpoint_lon']),
-            'satellite_nominal_altitude': float(self['nominal_satellite_height']),
+            'satellite_nominal_altitude': float(self['nominal_satellite_height']) * 1000.,
             'yaw_flip': bool(self['yaw_flip_flag']),
         }
 

satpy/tests/reader_tests/test_abi_l1b.py

@@ -154,15 +154,15 @@ def test_get_dataset(self):
                'orbital_parameters': {'projection_altitude': 1.0,
                                       'projection_latitude': 0.0,
                                       'projection_longitude': -90.0,
-                                      'satellite_nominal_altitude': 35786.02,
+                                      'satellite_nominal_altitude': 35786020.,
                                       'satellite_nominal_latitude': 0.0,
                                       'satellite_nominal_longitude': -89.5,
                                       'yaw_flip': True},
                'orbital_slot': None,
                'platform_name': 'GOES-16',
                'platform_shortname': 'G16',
                'production_site': None,
-               'satellite_altitude': 35786.02,
+               'satellite_altitude': 35786020.,
                'satellite_latitude': 0.0,
                'satellite_longitude': -89.5,
                'scan_mode': 'M3',