Add parallax correction via new ParallaxCorrectionModifier

.github/workflows/ci.yaml

@@ -103,7 +103,8 @@ jobs:
           git+https://github.com/Unidata/cftime \
           git+https://github.com/mapbox/rasterio \
           git+https://github.com/pydata/bottleneck \
-          git+https://github.com/pydata/xarray;
+          git+https://github.com/pydata/xarray \
+          git+https://github.com/astropy/astropy;
 
       - name: Install satpy
         shell: bash -l {0}

AUTHORS.md

@@ -25,13 +25,13 @@ The following people have made contributions to this project:
 - [Adam Dybbroe (adybbroe)](https://github.com/adybbroe)
 - [Ulrik Egede (egede)](https://github.com/egede)
 - [Joleen Feltz (joleenf)](https://github.com/joleenf)
-- [Stephan Finkensieper (sfinkens)](https://github.com/sfinkens)
+- [Stephan Finkensieper (sfinkens)](https://github.com/sfinkens) - Deutscher Wetterdienst
 - [Andrea Grillini (AppLEaDaY)](https://github.com/AppLEaDaY)
 - [Blanka Gvozdikova (gvozdikb)](https://github.com/gvozdikb)
 - [Nina Håkansson (ninahakansson)](https://github.com/ninahakansson)
 - [Ulrich Hamann](https://github.com/)
 - [Mitch Herbertson (mherbertson)](https://github.com/mherbertson)
-- [Gerrit Holl (gerritholl)](https://github.com/gerritholl)
+- [Gerrit Holl (gerritholl)](https://github.com/gerritholl) - Deutscher Wetterdienst
 - [David Hoese (djhoese)](https://github.com/djhoese)
 - [Marc Honnorat (honnorat)](https://github.com/honnorat)
 - [Mikhail Itkin (mitkin)](https://github.com/mitkin)
@@ -42,7 +42,8 @@ The following people have made contributions to this project:
 - [Janne Kotro (jkotro)](https://github.com/jkotro)
 - [Ralph Kuehn (ralphk11)](https://github.com/ralphk11)
 - [Panu Lahtinen (pnuu)](https://github.com/pnuu)
-- [Thomas Leppelt (m4sth0)](https://github.com/m4sth0)
+- [Jussi Leinonen (jleinonen)](https://github.com/jleinonen) - meteoswiss
+- [Thomas Leppelt (m4sth0)](https://github.com/m4sth0) - Deutscher Wetterdienst
 - [Lu Liu (yukaribbba)](https://github.com/yukaribbba)
 - [Andrea Meraner (ameraner)](https://github.com/ameraner)
 - [Aronne Merrelli (aronnem)](https://github.com/aronnem)

continuous_integration/environment.yaml

@@ -17,7 +17,7 @@ dependencies:
   - scipy
   - pyyaml
   - pyproj
-  - pyresample
+  - pyresample>=1.24
   - coveralls
   - coverage
   - codecov
@@ -49,6 +49,8 @@ dependencies:
   - python-geotiepoints
   - pooch
   - pip
+  - skyfield
+  - astropy
   - pip:
     - trollsift
     - trollimage

doc/source/modifiers.rst

@@ -55,3 +55,84 @@ on those modifiers can be found in the linked API documentation.
 A complete list can be found in the `etc/composites
 <https://github.com/pytroll/satpy/tree/main/satpy/etc/composites>`_
 source code and in the :mod:`~satpy.modifiers` module documentation.
+
+Parallax correction
+-------------------
+
+.. warning::
+
+    The Satpy parallax correction is experimental and subject to change.
+
+Since version 0.37 (mid 2022), Satpy has included a
+modifier for parallax correction, implemented in the
+:class:`~satpy.modifiers.parallax.ParallaxCorrectionModifier` class.
+This modifier is important for some applications, but not applied
+by default to any Satpy datasets or composites, because it can be
+applied to any input dataset and used with any source of (cloud top)
+height.  Therefore, users wishing to apply the parallax correction
+semi-automagically have to define their own modifier and then apply
+that modifier for their datasets.  An example is included
+with the :class:`~satpy.modifiers.parallax.ParallaxCorrectionModifier`
+API documentation.  Note that Satpy cannot apply modifiers to
+composites, so users wishing to apply parallax correction to a composite
+will have to use a lower level API or duplicate an existing composite
+recipe to use modified inputs.
+
+The parallax correction is directly calculated from the cloud top height.
+Information on satellite position is obtained from cloud top height
+metadata.  If no orbital parameters are present in the cloud top height
+metadata, Satpy will attempt to calculate orbital parameters from the
+platform name and start time.  The backup calculation requires skyfield
+and astropy to be installed.  If the metadata include neither orbital
+parameters nor platform name and start time, parallax calculation will
+fail.  Because the cloud top height metadata are used, it is essential
+that the cloud top height data are derived from the same platform as
+the measurements to be corrected are taken by.
+
+The parallax error moves clouds away from the observer.  Therefore, the
+parallax correction shifts clouds in the direction of the observer.  The
+space left behind by the cloud will be filled with fill values.  As the
+cloud is shifted toward the observer, it may occupy less pixels than before,
+because pixels closer to the observer have a smaller surface area.  It can
+also be deformed (a "rectangular" cloud may get the shape of a parallelogram).
+
+.. figure:: https://figshare.com/ndownloader/files/36422616/preview/36422616/preview.jpg
+   :width: 512
+   :height: 512
+   :alt: Satellite image without parallax correction.
+
+   SEVIRI view of southern Sweden, 2021-11-30 12:15Z, without parallax correction.
+   This is the ``natural_color`` composite as built into Satpy.
+
+
+.. figure:: https://figshare.com/ndownloader/files/36422613/preview/36422613/preview.jpg
+   :width: 512
+   :height: 512
+   :alt: Satellite image with parallax correction.
+
+   The same satellite view with parallax correction.  The most obvious change
+   are the gaps left behind by the parallax correction, shown as black pixels.
+   Otherwise it shows that clouds have "moved" south-south-west in the direction
+   of the satellite.  To view the images side-by-side or alternating, look at
+   `the figshare page <https://figshare.com/articles/figure/20211130121510-Meteosat-11-seviri-sswe-parallax_corrected_natural_color_jpg/20377203>`_
+
+The utility function :func:`~satpy.modifiers.parallax.get_surface_parallax_displacement` allows to calculate the magnitude of the parallax error.  For a cloud with a cloud top height of 10 km:
+
+.. figure:: https://figshare.com/ndownloader/files/36462435/preview/36462435/preview.jpg
+   :width: 512
+   :height: 512
+   :alt: Figure showing magnitude of parallax effect.
+
+   Magnitude of the parallax error for a fictitious cloud with a cloud top
+   height of 10 km for the GOES-East (GOES-16) full disc.
+
+The parallax correction is currently experimental and subject to change.
+Although it is covered by tests, there may be cases that yield unexpected
+or incorrect results.  It does not yet perform any checks that the
+provided (cloud top) height covers the area of the dataset for which
+the parallax correction shall be applied.
+
+For more general background information and web routines related to the
+parallax effect, see also `this collection at the CIMSS website <https://cimss.ssec.wisc.edu/goes/webapps/parallax/>_`.
+
+.. versionadded:: 0.37