Add parallax correction via new ParallaxCorrectionModifier

.github/workflows/ci.yaml

@@ -115,7 +115,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

@@ -48,6 +48,8 @@ dependencies:
   - python-geotiepoints
   - pooch
   - pip
+  - skyfield
+  - astropy
   - pip:
     - trollsift
     - trollimage

doc/source/modifiers.rst

@@ -52,6 +52,53 @@ on those modifiers can be found in the linked API documentation.
       - Modifies solar channels to filter out the visual impact of rayleigh
         scattering.
 
+A complete list can be found in the ``etc/composites`` source code and
+in the :mod:`~satpy.modifiers` module documentation.
+
+Parallax correction
+-------------------
+
+Since early 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).
+
+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.
+
+.. versionadded:: 0.36
+
 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.