Making use of the mpop
package¶
The mpop
package is the heart of mpop: here are defined the core classes
which the user will then need to build satellite composites.
Conventions about satellite names¶
Throughout the document, we will use the following conventions:
platform name is the name of an individual satellite following the OSCAR naming scheme, e.g. “NOAA-19”.
- variant will be used to differentiate the same data (from the same
satellite and instrument) coming in different flavours. For example, we use variant to distinguish data coming from the satellite Metop-B from direct readout (no variant), regional coverage (EARS) or global coverage (GDS).
All the satellite configuration files in PPP_CONFIG_DIR should be named <variant><platform name>.cfg, e.g. NOAA-19.cfg or GDSMetop-B.cfg.
Creating a scene object¶
Creating a scene object can be done calling the create_scene function of a
factory, (for example mpop.satellites.GenericFactory.create_scene()
).
The reader is refered to the documentation of the
mpop.scene.SatelliteInstrumentScene()
for a description of the input
arguments.
Such a scene object is roughly a container for mpop.channel.Channel
objects, which hold the actual data and information for each band.
Loading the data¶
Loading the data is done through the
mpop.scene.SatelliteInstrumentScene.load()
method. Calling it effectively
loads the data from disk into memory, so it can take a while depending on the
volume of data to load and the performance of the host computer. The channels
listed as arguments become loaded, and cannot be reloaded: a subsequent call to
the method will not reload the data from disk.
Re-projecting data¶
Once the data is loaded, one might need to re-project the data. The scene
objects can be projected onto other areas if the pyresample software is
installed, thanks to the mpop.scene.SatelliteInstrumentScene.project()
method. As input, this method takes either a Definition object (see
pyresample’s documentation) or string identificator for the area. In the latter
case, the referenced region has to be defined in the area file. The name and
location of this file is defined in the mpop.cfg configuration file, itself
located in the directory pointed by the PPP_CONFIG_DIR environment variable.
For more information about the internals of the projection process, take a look
at the mpop.projector
module.
Geo-localisation of the data¶
Once the data is loaded, each channel should have an area attribute
containing a pyresample area object, if the pyresample package is
available. These area objects should implement the get_lonlats()
method,
returning the longitudes and latitudes of the channel data. For more
information on this matter, the reader is then referred to the documentation of
the aforementioned package.
Image composites¶
Methods building image composites are distributed in different modules, taking advantage of the hierarchical structure offered by OOP.
The image composites common to all visir instruments are defined in the
mpop.instruments.visir
module. Some instrument modules, like
mpop.instruments.avhrr
or mpop.instruments.seviri
overload these
methods to adapt better for the instrument at hand.
For instructions on how to write a new composites, see Geographic images.
Adding a new satellite: configuration file¶
A satellite configuration file looks like the following (here Meteosat-7, mviri instrument):
The configuration file must hold a satellite section, the list of channels for the needed instruments (here mviri-n sections), and how to read the data in mipp (mviri-level1) and how to read it in mpop (mviri-level2).
Using this template we can define new satellite and instruments.
Adding a new satellite: python code¶
Another way of adding satellites and instruments to mpop is to write the correponding python code.
Here are example of such code:
The mpop
API¶
Satellite scenes¶
Scene objects to hold satellite data.
-
class
mpop.scene.
Scene
(filenames=None, ppp_config_dir=None, reader_name=None, base_dir=None, **info)¶ The almighty scene class.
-
available_composites
()¶ Return the list of available composites for the current scene.
-
available_datasets
(reader_name=None)¶ Return the available datasets, globally or just for reader_name if specified.
-
compute
(*requirements)¶ Compute all the composites contained in requirements.
-
get_writer
(writer='geotiff', **kwargs)¶
-
get_writer_by_ext
(extension, **kwargs)¶
-
images
()¶ Generate images for all the datasets from the scene.
-
load
(wishlist, calibration=None, resolution=None, polarization=None, metadata=None, **kwargs)¶ Read, compute and unload.
-
load_writer_config
(config_files, **kwargs)¶
-
read
(dataset_keys, calibration=None, resolution=None, polarization=None, metadata=None, **kwargs)¶ Read the composites called dataset_keys or their prerequisites.
-
resample
(destination, datasets=None, compute=True, unload=True, **kwargs)¶ Resample the datasets and return a new scene.
-
save_dataset
(dataset_id, filename=None, writer=None, **kwargs)¶ Save the dataset_id to file using writer (geotiff by default).
-
save_datasets
(writer='geotiff', **kwargs)¶ Save all the datasets present in a scene to disk using writer.
-
show
(dataset_id)¶ Show the dataset on screen as an image.
-
unload
(keepables=None)¶ Unload all loaded composites.
-
Instrument channels¶
This module defines satellite instrument channels as a generic class, to be inherited when needed.
-
class
mpop.channel.
Channel
(name=None, resolution=0, wavelength_range=[0, 0, 0], data=None, calibration_unit=None)¶ This is the satellite channel class. It defines satellite channels as a container for calibrated channel data.
The resolution sets the resolution of the channel, in meters. The wavelength_range is a triplet, containing the lowest-, center-, and highest-wavelength values of the channel. name is simply the given name of the channel, and data is the data it should hold.
-
as_image
(stretched=True)¶ Return the channel as a
mpop.imageo.geo_image.GeoImage
object. The stretched argument set to False allows the data to remain untouched (as opposed to crude stretched by default to obtain the same output asshow()
).
-
check_range
(min_range=1.0)¶ Check that the data of the channels has a definition domain broader than min_range and return the data, otherwise return zeros.
-
data
¶ Getter for channel data.
-
get_data
()¶ Getter for channel data.
-
get_reflectance
(tb11, sun_zenith=None, tb13_4=None)¶ Get the reflectance part of an NIR channel
-
is_loaded
()¶ Tells if the channel contains loaded data.
-
project
(coverage_instance)¶ Make a projected copy of the current channel using the given coverage_instance.
See also the
mpop.projector
module.
-
set_data
(data)¶ Setter for channel data.
-
shape
¶ Shape of the channel.
-
show
()¶ Display the channel as an image.
-
sunzen_corr
(time_slot, lonlats=None, limit=80.0, mode='cos')¶ Perform Sun zenith angle correction for the channel at time_slot (datetime.datetime() object) and return the corrected channel. The parameter limit can be used to set the maximum zenith angle for which the correction is calculated. For larger angles, the correction is the same as at the limit (default: 80.0 degrees). Coordinate values can be given as a 2-tuple or a two-element list lonlats of numpy arrays; if None, the coordinates will be read from the channel data. Parameter mode is a placeholder for other possible illumination corrections. The name of the new channel will be original_chan.name+’_SZC’, eg. “VIS006_SZC”. This name is also stored to the info dictionary of the originating channel.
-
-
class
mpop.channel.
GenericChannel
(name=None)¶ This is an abstract channel class. It can be a super class for calibrated channels data or more elaborate channels such as cloudtype or CTTH.
-
area
¶ Getter for area.
-
-
exception
mpop.channel.
NotLoadedError
¶ Exception to be raised when attempting to use a non-loaded channel.
The VisIr instrument class¶
Projection facility¶
Satellite class loader¶
Miscellaneous tools¶
Helper functions for eg. performing Sun zenith angle correction.
-
mpop.tools.
sunzen_corr_cos
(data, cos_zen, limit=80.0)¶ Perform Sun zenith angle correction to the given data using cosine of the zenith angle (cos_zen). The correction is limited to limit degrees (default: 80.0 degrees). For larger zenith angles, the correction is the same as at the limit. Both data and cos_zen are given as 2-dimensional Numpy arrays or Numpy MaskedArrays, and they should have equal shapes.