satpy.modifiers.parallax module
Parallax correction.
Routines related to parallax correction using datasets involving height, such as cloud top height.
The geolocation of (geostationary) satellite imagery is calculated by agencies or in satpy readers with the assumption of a clear view from the satellite to the geoid. When a cloud blocks the view of the Earth surface or the surface is above sea level, the geolocation is not accurate for the cloud or mountain top. This module contains routines to correct imagery such that pixels are shifted or interpolated to correct for this parallax effect.
Parallax correction is currently only supported for (cloud top) height
that arrives on an AreaDefinition
, such
as is standard for geostationary satellites. Parallax correction with
data described by a SwathDefinition
,
such as is common for polar satellites, is not (yet) supported.
See also the Modifiers page in the documentation for an introduction to parallax correction as a modifier in Satpy.
- exception satpy.modifiers.parallax.IncompleteHeightWarning[source]
Bases:
UserWarning
Raised when heights only partially overlap with area to be corrected.
- exception satpy.modifiers.parallax.MissingHeightError[source]
Bases:
ValueError
Raised when heights do not overlap with area to be corrected.
- class satpy.modifiers.parallax.ParallaxCorrection(base_area, debug_mode=False)[source]
Bases:
object
Parallax correction calculations.
This class contains higher-level functionality to wrap the parallax correction calculations in
get_parallax_corrected_lonlats()
. The class is initialised using a base area, which is the area for which a corrected geolocation will be calculated. The resulting object is a callable. Calling the object with an array of (cloud top) heights returns aSwathDefinition
describing the new , corrected geolocation. The cloud top height should cover at least the area for which the corrected geolocation will be calculated.Note that the
ctth
dataset must contain satellite location metadata, such as set in theorbital_parameters
dataset attribute that is set by many Satpy readers. It is essential that the datasets to be corrected are coming from the same platform as the provided cloud top height.A note on the algorithm and the implementation. Parallax correction is inherently an inverse problem. The reported geolocation in satellite data files is the true location plus the parallax error. Therefore, this class first calculates the true geolocation (using
get_parallax_corrected_lonlats()
), which gives a shifted longitude and shifted latitude on an irregular grid. The difference between the original and the shifted grid is the parallax error or shift. The magnitude of this error can be estimated withget_surface_parallax_displacement()
. With this difference, we need to invert the parallax correction to calculate the corrected geolocation. Due to parallax correction, high clouds shift a lot, low clouds shift a little, and cloud-free pixels shift not at all. The shift may result in zero, one, two, or more source pixel onto a destination pixel. Physically, this corresponds to the situation where a narrow but high cloud is viewed at a large angle. The cloud may occupy two or more pixels when viewed at a large angle, but only one when viewed straight from above. To accurately reproduce this perspective, the parallax correction uses theBucketResampler
class, specifically theget_abs_max()
method, to retain only the largest absolute shift (corresponding to the highest cloud) within each pixel. Any other resampling method at this step would yield incorrect results. When cloud moves over clear-sky, the clear-sky pixel is unshifted and the shift is located exactly in the centre of the grid box, so nearest-neighbour resampling would lead to such shifts being deselected. Other resampling methods would average large shifts with small shifts, leading to unpredictable results. Now the reprojected shifts can be applied to the original lat/lon, returning a newSwathDefinition
. This is is the object returned bycorrected_area()
.This procedure can be configured as a modifier using the
ParallaxCorrectionModifier
class. However, the modifier can only be applied to one dataset at the time, which may not provide optimal performance, although dask should reuse identical calculations between multiple channels.Initialise parallax correction class.
- Parameters
base_area (
AreaDefinition
) – Area for which calculated geolocation will be calculated.debug_mode (bool) – Store diagnostic information in self.diagnostics. This attribute always apply to the most recently applied operation only.
- corrected_area(cth_dataset, cth_resampler='nearest', cth_radius_of_influence=50000, lonlat_chunks=1024)[source]
Return the parallax corrected SwathDefinition.
Using the cloud top heights provided in
cth_dataset
, calculate thepyresample.geometry.SwathDefinition
that estimates the geolocation for each pixel if it had been viewed from straight above (without parallax error). The cloud top height will first be resampled onto the area passed upon class initialisation in__init__()
. Pixels that are invisible after parallax correction are not retained but get geolocation NaN.- Parameters
cth_dataset (
DataArray
) – Cloud top height in meters. The variable attributes must contain anarea
attribute describing the geolocation in a pyresample-aware way, and they must contain satellite orbital parameters. The dimensions must be(y, x)
. For best performance, this should be a dask-basedDataArray
.cth_resampler (string, optional) – Resampler to use when resampling the (cloud top) height to the base area. Defaults to “nearest”.
cth_radius_of_influence (number, optional) – Radius of influence to use when resampling the (cloud top) height to the base area. Defaults to 50000.
lonlat_chunks (int, optional) – Chunking to use when calculating lon/lats. Probably the default (1024) should be fine.
- Returns
SwathDefinition
describing parallax corrected geolocation.
- class satpy.modifiers.parallax.ParallaxCorrectionModifier(name, prerequisites=None, optional_prerequisites=None, **kwargs)[source]
Bases:
ModifierBase
Modifier for parallax correction.
Apply parallax correction as a modifier. Uses the
ParallaxCorrection
class, which in turn uses theget_parallax_corrected_lonlats()
function. See the documentation there for details on the behaviour.To use this, add to
composites/visir.yaml
withinSATPY_CONFIG_PATH
something like:sensor_name: visir modifiers: parallax_corrected: modifier: !!python/name:satpy.modifiers.parallax.ParallaxCorrectionModifier prerequisites: - "ctth_alti" dataset_radius_of_influence: 50000 composites: parallax_corrected_VIS006: compositor: !!python/name:satpy.composites.SingleBandCompositor prerequisites: - name: VIS006 modifiers: [parallax_corrected]
Here,
ctth_alti
is CTH provided by thenwcsaf-geo
reader, so to use it one would have to pass both on scene creation:sc = Scene({"seviri_l1b_hrit": files_l1b, "nwcsaf-geo": files_l2}) sc.load(["parallax_corrected_VIS006"])
The modifier takes optional global parameters, all of which are optional. They affect various steps in the algorithm. Setting them may impact performance:
- cth_resampler
Resampler to use when resampling (cloud top) height to the base area. Defaults to “nearest”.
- cth_radius_of_influence
Radius of influence to use when resampling the (cloud top) height to the base area. Defaults to 50000.
- lonlat_chunks
Chunk size to use when obtaining longitudes and latitudes from the area definition. Defaults to 1024. If you set this to None, then parallax correction will involve premature calculation. Changing this may or may not make parallax correction slower or faster.
- dataset_radius_of_influence
Radius of influence to use when resampling the dataset onto the swathdefinition describing the parallax-corrected area. Defaults to 50000. This always uses nearest neighbour resampling.
Alternately, you can use the lower-level API directly with the
ParallaxCorrection
class, which may be more efficient if multiple datasets need to be corrected. RGB Composites cannot be modified in this way (i.e. you can’t replace “VIS006” by “natural_color”). To get a parallax corrected RGB composite, create a new composite where each input has the modifier applied. The parallax calculation should only occur once, because calculations are happening via dask and dask should reuse the calculation.Initialise the compositor.
- satpy.modifiers.parallax.get_parallax_corrected_lonlats(sat_lon, sat_lat, sat_alt, lon, lat, height)[source]
Calculate parallax corrected lon/lats.
Satellite geolocation generally assumes an unobstructed view of a smooth Earth surface. In reality, this view may be obstructed by clouds or mountains.
If the view of a pixel at location (lat, lon) is blocked by a cloud at height h, this function calculates the (lat, lon) coordinates of the cloud above/in front of the invisible surface.
For scenes that are only partly cloudy, the user might set the cloud top height for clear-sky pixels to NaN. This function will return a corrected lat/lon as NaN as well. The user can use the original lat/lon for those pixels or use the higher level
ParallaxCorrection
class.This function assumes a spherical Earth.
Note
Be careful with units! This code expects
sat_alt
andheight
to be in meter above the Earth’s surface. You may have to convert your input correspondingly. Cloud Top Height is usually reported in meters above the Earth’s surface, rarely in km. Satellite altitude may be reported in either m or km, but orbital parameters are usually in relation to the Earth’s centre. The Earth radius from pyresample is reported in km.- Parameters
sat_lon (number) – Satellite longitude in geodetic coordinates [degrees]
sat_lat (number) – Satellite latitude in geodetic coordinates [degrees]
sat_alt (number) – Satellite altitude above the Earth surface [m]
lon (array or number) – Longitudes of pixel or pixels to be corrected, in geodetic coordinates [degrees]
lat (array or number) – Latitudes of pixel/pixels to be corrected, in geodetic coordinates [degrees]
height (array or number) – Heights of pixels on which the correction will be based. Typically this is the cloud top height. [m]
- Returns
- Corrected geolocation
Corrected geolocation
(lon, lat)
in geodetic coordinates for the pixel(s) to be corrected. [degrees]
- Return type
- satpy.modifiers.parallax.get_surface_parallax_displacement(sat_lon, sat_lat, sat_alt, lon, lat, height)[source]
Calculate surface parallax displacement.
Calculate the displacement due to parallax error. Input parameters are identical to
get_parallax_corrected_lonlats()
.- Returns
parallax displacement in meter
- Return type
number or array