Add NDVI-scaled hybrid green correction

satpy/composites/spectral.py

@@ -16,55 +16,165 @@
 """Composite classes for spectral adjustments."""
 
 import logging
+import warnings
+
+import dask.array as da
 
 from satpy.composites import GenericCompositor
 from satpy.dataset import combine_metadata
 
 LOG = logging.getLogger(__name__)
 
 
-class GreenCorrector(GenericCompositor):
-    """Corrector of the FCI or AHI green band.
-
-    The green band in FCI and AHI deliberately misses the chlorophyll peak
-    in order to focus on aerosol and ash rather than on vegetation.  This
-    affects true colour RGBs, because vegetation looks brown rather than green.
-    To make vegetation look greener again, this corrector allows
-    to simulate the green band as a fraction of two or more other channels.
+class SpectralBlender(GenericCompositor):
+    """Construct new channel by blending contributions from a set of channels.
 
-    To be used, the composite takes two or more input channels and a parameter
-    ``fractions`` that should be a list of floats with the same length as the
-    number of channels.
+    This class can be used to compute weighted average of different channels.
+    Primarily it's used to correct the green band of AHI and FCI in order to
+    allow for proper true color imagery.
 
-    For example, to simulate an FCI corrected green composite, one could use
-    a combination of 93% from the green band (vis_05) and 7% from the
-    near-infrared 0.8 µm band (vis_08)::
+    Below is an example used to generate a corrected green channel for AHI using a weighted average from
+    three channels, with 63% contribution from the native green channel (B02), 29% from the red channel (B03)
+    and 8% from the near-infrared channel (B04)::
 
       corrected_green:
-        compositor: !!python/name:satpy.composites.ahi.GreenCorrector
-        fractions: [0.93, 0.07]
+        compositor: !!python/name:satpy.composites.spectral.SpectralBlender
+        fractions: [0.63, 0.29, 0.08]
         prerequisites:
-          - name: vis_05
+          - name: B02
             modifiers: [sunz_corrected, rayleigh_corrected]
-          - name: vis_08
+          - name: B03
+            modifiers: [sunz_corrected, rayleigh_corrected]
+          - name: B04
             modifiers: [sunz_corrected, rayleigh_corrected]
         standard_name: toa_bidirectional_reflectance
 
-    Other examples can be found in the ``fci.yaml`` and ``ahi.yaml`` composite
-    files in the satpy distribution.
+    Other examples can be found in the``ahi.yaml`` composite file in the satpy distribution.
     """
 
-    def __init__(self, *args, fractions=(0.85, 0.15), **kwargs):
+    def __init__(self, *args, fractions=(), **kwargs):
         """Set default keyword argument values."""
-        # XXX: Should this be 0.93 and 0.07
         self.fractions = fractions
-        super(GreenCorrector, self).__init__(*args, **kwargs)
+        super().__init__(*args, **kwargs)
 
     def __call__(self, projectables, optional_datasets=None, **attrs):
-        """Boost vegetation effect thanks to NIR (0.8µm) band."""
-        LOG.info('Boosting vegetation on green band')
+        """Blend channels in projectables using the weights in self.fractions."""
+        if len(self.fractions) != len(projectables):
+            raise ValueError("fractions and projectables must have the same length.")
 
         projectables = self.match_data_arrays(projectables)
-        new_green = sum(fraction * value for fraction, value in zip(self.fractions, projectables))
-        new_green.attrs = combine_metadata(*projectables)
-        return super(GreenCorrector, self).__call__((new_green,), **attrs)
+        new_channel = sum(fraction * value for fraction, value in zip(self.fractions, projectables))
+        new_channel.attrs = combine_metadata(*projectables)
+        return super().__call__((new_channel,), **attrs)
+
+
+class HybridGreen(SpectralBlender):
+    """Corrector of the FCI or AHI green band.
+
+    The green band in FCI and AHI (and other bands centered at 0.51 microns) deliberately
+    misses the chlorophyll spectral reflectance local maximum at 0.55 microns
+    in order to focus on aerosol and ash rather than on vegetation. This
+    affects true colour RGBs, because vegetation looks brown rather than green
+    and barren surface types typically gets a reddish hue.
+
+    To correct for this the hybrid green approach proposed by Miller et al. (2016, :doi:`10.1175/BAMS-D-15-00154.2`)
+    is used. The basic idea is to include some contribution also from the 0.86 micron
+    channel, which is known for its sensitivity to vegetation. The formula used for this is::
+
+      hybrid_green = (1 - F) * R(0.51) + F * R(0.86)
+
+    where F is a constant value, that is set to 0.15 by default in Satpy.
+
+    For example, the HybridGreen compositor can be used as follows to construct a hybrid green channel for
+    AHI, with 15% contibution from the near-infrared 0.85 µm band (B04) and the remaining 85% from the native
+    green 0.51 µm band (B02)::
+
+      hybrid_green:
+        compositor: !!python/name:satpy.composites.spectral.HybridGreen
+        fraction: 0.15
+        prerequisites:
+          - name: B02
+            modifiers: [sunz_corrected, rayleigh_corrected]
+          - name: B04
+            modifiers: [sunz_corrected, rayleigh_corrected]
+        standard_name: toa_bidirectional_reflectance
+
+    Other examples can be found in the ``ahi.yaml`` and ``ami.yaml`` composite
+    files in the satpy distribution.
+    """
+
+    def __init__(self, *args, fraction=0.15, **kwargs):
+        """Set default keyword argument values."""
+        fractions = (1 - fraction, fraction)
+        super().__init__(fractions=fractions, *args, **kwargs)
+
+
+class NDVIHybridGreen(SpectralBlender):
+    """Construct a NDVI-weighted hybrid green channel.
+
+    This green band correction follows the same approach as the HybridGreen compositor, but with a dynamic blend
+    factor `f` that depends on the pixel-level Normalized Differece Vegetation Index (NDVI). The higher the NDVI, the
+    smaller the contribution from the nir channel will be, following a liner relationship between the two ranges
+    `[ndvi_min, ndvi_max]` and `limits`.
+
+    As an example, a new green channel using e.g. FCI data and the NDVIHybridGreen compositor can be defined like::
+
+      ndvi_hybrid_green:
+        compositor: !!python/name:satpy.composites.spectral.NDVIHybridGreen
+        ndvi_min: 0.0
+        ndvi_max: 1.0
+        limits: [0.15, 0.05]
+        prerequisites:
+          - name: vis_05
+            modifiers: [sunz_corrected, rayleigh_corrected]
+          - name: vis_06
+            modifiers: [sunz_corrected, rayleigh_corrected]
+          - name: vis_08
+            modifiers: [sunz_corrected ]
+        standard_name: toa_bidirectional_reflectance
+
+    In this example, pixels with NDVI=0.0 will be a weighted average with 15% contribution from the
+    near-infrared vis_08 channel and the remaining 85% from the native green vis_05 channel, whereas
+    pixels with NDVI=1.0 will be a weighted average with 5% contribution from the near-infrared
+    vis_08 channel and the remaining 95% from the native green vis_05 channel. For other values of
+    NDVI a linear interpolation between these values will be performed.
+    """
+
+    def __init__(self, *args, ndvi_min=0.0, ndvi_max=1.0, limits=(0.15, 0.05), **kwargs):
+        """Initialize class and set the NDVI limits and the corresponding blending fraction limits."""
+        self.ndvi_min = ndvi_min
+        self.ndvi_max = ndvi_max
+        self.limits = limits
+        super().__init__(*args, **kwargs)
+
+    def __call__(self, projectables, optional_datasets=None, **attrs):
+        """Construct the hybrid green channel weighted by NDVI."""
+        ndvi_input = self.match_data_arrays([projectables[1], projectables[2]])
+
+        ndvi = (ndvi_input[1] - ndvi_input[0]) / (ndvi_input[1] + ndvi_input[0])
+
+        ndvi.data = da.where(ndvi > self.ndvi_min, ndvi, self.ndvi_min)
+        ndvi.data = da.where(ndvi < self.ndvi_max, ndvi, self.ndvi_max)
+
+        fraction = (ndvi - self.ndvi_min) / (self.ndvi_max - self.ndvi_min) * (self.limits[1] - self.limits[0]) \
+            + self.limits[0]
+        self.fractions = (1 - fraction, fraction)
+
+        return super().__call__([projectables[0], projectables[2]], **attrs)
+
+
+class GreenCorrector(SpectralBlender):
+    """Previous class used to blend channels for green band corrections.
+
+    This method has been refactored to make it more generic. The replacement class is 'SpectralBlender' which computes
+    a weighted average based on N number of channels and N number of corresponding weights/fractions. A new class
+    called 'HybridGreen' has been created, which performs a correction of green bands centered at 0.51 microns
+    following Miller et al. (2016, :doi:`10.1175/BAMS-D-15-00154.2`) in order to improve true color imagery.
+    """
+
+    def __init__(self, *args, fractions=(0.85, 0.15), **kwargs):
+        """Set default keyword argument values."""
+        warnings.warn(
+            "'GreenCorrector' is deprecated, use 'SpectralBlender' instead, or 'HybridGreen' for hybrid green"
+            " correction following Miller et al. (2016).", RuntimeWarning)
+        super().__init__(fractions=fractions, *args, **kwargs)

satpy/etc/composites/ahi.yaml

@@ -16,9 +16,50 @@ modifiers:
 
 composites:
   green:
+    # Deprecated green composite using deprecated class 'GreenCorrector'. Use 'hybrid_green' instead.
     compositor: !!python/name:satpy.composites.spectral.GreenCorrector
     # FUTURE: Set a wavelength...see what happens. Dependency finding
     #         probably wouldn't work.
+    prerequisites:
+      # should we be using the most corrected or least corrected inputs?
+      # what happens if something requests more modifiers on top of this?
+      - wavelength: 0.51
+        modifiers: [sunz_corrected, rayleigh_corrected]
+      - wavelength: 0.85
+        modifiers:  [sunz_corrected]
+    standard_name: toa_bidirectional_reflectance
+
+  green_true_color_reproduction:
+    # Deprecated green composite using deprecated class 'GreenCorrector'. Use 'reproduced_green' instead.
+    # JMA True Color Reproduction green band
+    # http://www.jma.go.jp/jma/jma-eng/satellite/introduction/TCR.html
+    compositor: !!python/name:satpy.composites.spectral.GreenCorrector
+    fractions: [0.6321, 0.2928, 0.0751]
+    prerequisites:
+      - name: B02
+        modifiers: [sunz_corrected, rayleigh_corrected]
+      - name: B03
+        modifiers: [sunz_corrected, rayleigh_corrected]
+      - name: B04
+        modifiers: [sunz_corrected]
+    standard_name: none
+
+  green_nocorr:
+    # Deprecated green composite using deprecated class 'GreenCorrector'. Use 'hybrid_green_nocorr' instead.
+    compositor: !!python/name:satpy.composites.spectral.GreenCorrector
+    # FUTURE: Set a wavelength...see what happens. Dependency finding
+    #         probably wouldn't work.
+    prerequisites:
+      # should we be using the most corrected or least corrected inputs?
+      # what happens if something requests more modifiers on top of this?
+      - wavelength: 0.51
+      - wavelength: 0.85
+    standard_name: toa_reflectance
+
+  hybrid_green:
+    compositor: !!python/name:satpy.composites.spectral.HybridGreen
+    # FUTURE: Set a wavelength...see what happens. Dependency finding
+    #         probably wouldn't work.
     prerequisites:
     # should we be using the most corrected or least corrected inputs?
     # what happens if something requests more modifiers on top of this?
@@ -28,10 +69,10 @@ composites:
       modifiers: [sunz_corrected]
     standard_name: toa_bidirectional_reflectance
 
-  green_true_color_reproduction:
+  reproduced_green:
     # JMA True Color Reproduction green band
     # http://www.jma.go.jp/jma/jma-eng/satellite/introduction/TCR.html
-    compositor: !!python/name:satpy.composites.spectral.GreenCorrector
+    compositor: !!python/name:satpy.composites.spectral.SpectralBlender
     fractions: [0.6321, 0.2928, 0.0751]
     prerequisites:
     - name: B02
@@ -42,8 +83,8 @@ composites:
       modifiers: [sunz_corrected]
     standard_name: none
 
-  green_nocorr:
-    compositor: !!python/name:satpy.composites.spectral.GreenCorrector
+  hybrid_green_nocorr:
+    compositor: !!python/name:satpy.composites.spectral.HybridGreen
     # FUTURE: Set a wavelength...see what happens. Dependency finding
     #         probably wouldn't work.
     prerequisites:
@@ -53,6 +94,17 @@ composites:
     - wavelength: 0.85
     standard_name: toa_reflectance
 
+  ndvi_hybrid_green:
+    compositor: !!python/name:satpy.composites.spectral.NDVIHybridGreen
+    prerequisites:
+    - name: B02
+      modifiers: [sunz_corrected, rayleigh_corrected]
+    - name: B03
+      modifiers: [sunz_corrected, rayleigh_corrected]
+    - name: B04
+      modifiers: [sunz_corrected]
+    standard_name: toa_bidirectional_reflectance
+
   airmass:
     # PDF slides: https://www.eumetsat.int/website/home/News/ConferencesandEvents/DAT_2833302.html
     # Under session 2 by Akihiro Shimizu (JMA)
@@ -204,7 +256,18 @@ composites:
     prerequisites:
     - name: B03
       modifiers: [sunz_corrected, rayleigh_corrected]
-    - name: green
+    - name: hybrid_green
+    - name: B01
+      modifiers: [sunz_corrected, rayleigh_corrected]
+    high_resolution_band: red
+    standard_name: true_color
+
+  true_color_ndvi_green:
+    compositor: !!python/name:satpy.composites.SelfSharpenedRGB
+    prerequisites:
+    - name: B03
+      modifiers: [sunz_corrected, rayleigh_corrected]
+    - name: ndvi_hybrid_green
     - name: B01
       modifiers: [sunz_corrected, rayleigh_corrected]
     high_resolution_band: red
@@ -223,7 +286,7 @@ composites:
     compositor: !!python/name:satpy.composites.SelfSharpenedRGB
     prerequisites:
     - name: B03
-    - name: green_nocorr
+    - name: hybrid_green_nocorr
     - name: B01
     high_resolution_band: red
     standard_name: true_color
@@ -235,7 +298,7 @@ composites:
     prerequisites:
       - name: B03
         modifiers: [sunz_corrected, rayleigh_corrected]
-      - name: green_true_color_reproduction
+      - name: reproduced_green
       - name: B01
         modifiers: [sunz_corrected, rayleigh_corrected]
     standard_name: true_color_reproduction