satpy.writers package

Submodules

Module contents

Shared objects of the various writer classes.

For now, this includes enhancement configuration utilities.

class satpy.writers.DecisionTree(decision_dicts, match_keys, multival_keys=None)[source]

Bases: object

Structure to search for nearest match from a set of parameters.

This class is used to find the best configuration section by matching a set of attributes. The provided dictionary contains a mapping of “section name” to “decision” dictionaries. Each decision dictionary contains the attributes that will be used for matching plus any additional keys that could be useful when matched. This class will search these decisions and return the one with the most matching parameters to the attributes passed to the find_match() method.

Note that decision sections are provided as a dict instead of a list so that they can be overwritten or updated by doing the equivalent of a current_dicts.update(new_dicts).

Examples

Decision sections are provided as a dictionary of dictionaries. The returned match will be the first result found by searching provided match_keys in order.

decisions = {
    'first_section': {
        'a': 1,
        'b': 2,
        'useful_key': 'useful_value',
    },
    'second_section': {
        'a': 5,
        'useful_key': 'other_useful_value1',
    },
    'third_section': {
        'b': 4,
        'useful_key': 'other_useful_value2',
    },
}
tree = DecisionTree(decisions, ('a', 'b'))
tree.find_match(a=5, b=2)  # second_section dict
tree.find_match(a=1, b=2)  # first_section dict
tree.find_match(a=5, b=4)  # second_section dict
tree.find_match(a=3, b=2)  # no match

Init the decision tree.

Parameters

decision_dicts (dict) – Dictionary of dictionaries. Each sub-dictionary contains key/value pairs that can be matched from the find_match method. Sub-dictionaries can include additional keys outside the match_keys provided to act as the “result” of a query. The keys of the root dict are arbitrary.
match_keys (list) – Keys of the provided dictionary to use for matching.
multival_keys (list) – Keys of match_keys that can be provided as multiple values. A multi-value key can be specified as a single value (typically a string) or a set. If a set, it will be sorted and converted to a tuple and then used for matching. When querying the tree, these keys will be searched for exact multi-value results (the sorted tuple) and if not found then each of the values will be searched individually in alphabetical order.

add_config_to_tree(*decision_dicts)[source]: Add a configuration to the tree.

any_key = None

find_match(**query_dict)[source]

Find a match.

Recursively search through the tree structure for a path that matches the provided match parameters.

class satpy.writers.EnhancementDecisionTree(*decision_dicts, **kwargs)[source]

Bases: DecisionTree

The enhancement decision tree.

Init the decision tree.

add_config_to_tree(*decision_dict)[source]: Add configuration to tree.

find_match(**query_dict)[source]: Find a match.

class satpy.writers.Enhancer(enhancement_config_file=None)[source]

Bases: object

Helper class to get enhancement information for images.

Initialize an Enhancer instance.

Parameters: enhancement_config_file – The enhancement configuration to apply, False to leave as is.

add_sensor_enhancements(sensor)[source]: Add sensor-specific enhancements.

apply(img, **info)[source]: Apply the enhancements.

get_sensor_enhancement_config(sensor)[source]: Get the sensor-specific config.

class satpy.writers.ImageWriter(name=None, filename=None, base_dir=None, enhance=None, **kwargs)[source]

Bases: Writer

Base writer for image file formats.

Initialize image writer object.

Parameters

name (str) – A name for this writer for log and error messages. If this writer is configured in a YAML file its name should match the name of the YAML file. Writer names may also appear in output file attributes.
filename (str) –
Filename to save data to. This filename can and should specify certain python string formatting fields to differentiate between data written to the files. Any attributes provided by the .attrs of a DataArray object may be included. Format and conversion specifiers provided by the trollsift package may also be used. Any directories in the provided pattern will be created if they do not exist. Example:
```
{platform_name}_{sensor}_{name}_{start_time:%Y%m%d_%H%M%S}.tif
```
base_dir (str) – Base destination directories for all created files.
enhance (bool or Enhancer) – Whether to automatically enhance data to be more visually useful and to fit inside the file format being saved to. By default, this will default to using the enhancement configuration files found using the default Enhancer class. This can be set to False so that no enhancments are performed. This can also be an instance of the Enhancer class if further custom enhancement is needed.
kwargs (dict) – Additional keyword arguments to pass to the Writer base class.

Changed in version 0.10: Deprecated enhancement_config_file and ‘enhancer’ in favor of enhance. Pass an instance of the Enhancer class to enhance instead.

save_dataset(dataset, filename=None, fill_value=None, overlay=None, decorate=None, compute=True, **kwargs)[source]

Save the dataset to a given filename.

This method creates an enhanced image using get_enhanced_image(). The image is then passed to save_image(). See both of these functions for more details on the arguments passed to this method.

save_image(img: XRImage, filename: Optional[str] = None, compute: bool = True, **kwargs)[source]

Save Image object to a given filename.

Parameters

img (trollimage.xrimage.XRImage) – Image object to save to disk.
filename (str) – Optionally specify the filename to save this dataset to. It may include string formatting patterns that will be filled in by dataset attributes.
compute (bool) – If True (default), compute and save the dataset. If False return either a Dask Delayed object or tuple of (source, target). See the return values below for more information.
**kwargs – Other keyword arguments to pass to this writer.

Returns

Value returned depends on compute. If compute is True then the return value is the result of computing a Dask Delayed object or running dask.array.store(). If compute is False then the returned value is either a Dask Delayed object that can be computed using delayed.compute() or a tuple of (source, target) that should be passed to dask.array.store(). If target is provided the the caller is responsible for calling target.close() if the target has this method.

classmethod separate_init_kwargs(kwargs)[source]: Separate the init kwargs.

class satpy.writers.Writer(name=None, filename=None, base_dir=None, **kwargs)[source]

Bases: Plugin, DataDownloadMixin

Base Writer class for all other writers.

A minimal writer subclass should implement the save_dataset method.

Initialize the writer object.

Parameters

name (str) – A name for this writer for log and error messages. If this writer is configured in a YAML file its name should match the name of the YAML file. Writer names may also appear in output file attributes.
filename (str) –
Filename to save data to. This filename can and should specify certain python string formatting fields to differentiate between data written to the files. Any attributes provided by the .attrs of a DataArray object may be included. Format and conversion specifiers provided by the trollsift package may also be used. Any directories in the provided pattern will be created if they do not exist. Example:
```
{platform_name}_{sensor}_{name}_{start_time:%Y%m%d_%H%M%S}.tif
```
base_dir (str) – Base destination directories for all created files.
kwargs (dict) – Additional keyword arguments to pass to the Plugin class.

create_filename_parser(base_dir)[source]: Create a trollsift.parser.Parser object for later use.

get_filename(**kwargs)[source]

Create a filename where output data will be saved.

Parameters: kwargs (dict) – Attributes and other metadata to use for formatting the previously provided filename.

save_dataset(dataset, filename=None, fill_value=None, compute=True, **kwargs)[source]

Save the dataset to a given filename.

This method must be overloaded by the subclass.

Parameters

dataset (xarray.DataArray) – Dataset to save using this writer.
filename (str) – Optionally specify the filename to save this dataset to. If not provided then filename which can be provided to the init method will be used and formatted by dataset attributes.
fill_value (int or float) – Replace invalid values in the dataset with this fill value if applicable to this writer.
compute (bool) – If True (default), compute and save the dataset. If False return either a Dask Delayed object or tuple of (source, target). See the return values below for more information.
**kwargs – Other keyword arguments for this particular writer.

Returns

Value returned depends on compute. If compute is True then the return value is the result of computing a Dask Delayed object or running dask.array.store(). If compute is False then the returned value is either a Dask Delayed object that can be computed using delayed.compute() or a tuple of (source, target) that should be passed to dask.array.store(). If target is provided the caller is responsible for calling target.close() if the target has this method.

save_datasets(datasets, compute=True, **kwargs)[source]

Save all datasets to one or more files.

Subclasses can use this method to save all datasets to one single file or optimize the writing of individual datasets. By default this simply calls save_dataset for each dataset provided.

Parameters

datasets (iterable) – Iterable of xarray.DataArray objects to save using this writer.
compute (bool) – If True (default), compute all the saves to disk. If False then the return value is either a Dask Delayed object or two lists to be passed to a dask.array.store() call. See return values below for more details.
**kwargs – Keyword arguments to pass to save_dataset. See that documentation for more details.

Returns

Value returned depends on compute keyword argument. If compute is True the value is the result of either a dask.array.store() operation or a Dask Delayed compute, typically this is None. If compute is False then the result is either a Dask Delayed object that can be computed with delayed.compute() or a two element tuple of sources and targets to be passed to dask.array.store(). If targets is provided then it is the caller’s responsibility to close any objects that have a “close” method.

classmethod separate_init_kwargs(kwargs)[source]

Help separating arguments between init and save methods.

Currently the Scene is passed one set of arguments to represent the Writer creation and saving steps. This is not preferred for Writer structure, but provides a simpler interface to users. This method splits the provided keyword arguments between those needed for initialization and those needed for the save_dataset and save_datasets method calls.

Writer subclasses should try to prefer keyword arguments only for the save methods only and leave the init keyword arguments to the base classes when possible.

satpy.writers.add_decorate(orig, fill_value=None, **decorate)[source]

Decorate an image with text and/or logos/images.

This call adds text/logos in order as given in the input to keep the alignment features available in pydecorate.

An example of the decorate config:

decorate = {
    'decorate': [
        {'logo': {'logo_path': <path to a logo>, 'height': 143, 'bg': 'white', 'bg_opacity': 255}},
        {'text': {'txt': start_time_txt,
                  'align': {'top_bottom': 'bottom', 'left_right': 'right'},
                  'font': <path to ttf font>,
                  'font_size': 22,
                  'height': 30,
                  'bg': 'black',
                  'bg_opacity': 255,
                  'line': 'white'}}
    ]
}

Any numbers of text/logo in any order can be added to the decorate list, but the order of the list is kept as described above.

Note that a feature given in one element, eg. bg (which is the background color) will also apply on the next elements unless a new value is given.

align is a special keyword telling where in the image to start adding features, top_bottom is either top or bottom and left_right is either left or right.

satpy.writers.add_logo(orig, dc, img, logo)[source]

Add logos or other images to an image using the pydecorate package.

All the features of pydecorate’s add_logo are available. See documentation of Welcome to the Pydecorate documentation! for more info.

satpy.writers.add_overlay(orig_img, area, coast_dir, color=None, width=None, resolution=None, level_coast=None, level_borders=None, fill_value=None, grid=None, overlays=None)[source]

Add coastline, political borders and grid(graticules) to image.

Uses color for feature colors where color is a 3-element tuple of integers between 0 and 255 representing (R, G, B).

Warning

This function currently loses the data mask (alpha band).

resolution is chosen automatically if None (default), otherwise it should be one of:

‘f’	Full resolution	0.04 km
‘h’	High resolution	0.2 km
‘i’	Intermediate resolution	1.0 km
‘l’	Low resolution	5.0 km
‘c’	Crude resolution	25 km

grid is a dictionary with key values as documented in detail in pycoast

eg. overlay={‘grid’: {‘major_lonlat’: (10, 10),: ‘write_text’: False, ‘outline’: (224, 224, 224), ‘width’: 0.5}}

Here major_lonlat is plotted every 10 deg for both longitude and latitude, no labels for the grid lines are plotted, the color used for the grid lines is light gray, and the width of the gratucules is 0.5 pixels.

For grid if aggdraw is used, font option is mandatory, if not write_text is set to False:

font = aggdraw.Font('black', '/usr/share/fonts/truetype/msttcorefonts/Arial.ttf',
                    opacity=127, size=16)

satpy.writers.add_scale(orig, dc, img, scale)[source]

Add scale to an image using the pydecorate package.

All the features of pydecorate’s add_scale are available. See documentation of Welcome to the Pydecorate documentation! for more info.

satpy.writers.add_text(orig, dc, img, text)[source]

Add text to an image using the pydecorate package.

All the features of pydecorate’s add_text are available. See documentation of Welcome to the Pydecorate documentation! for more info.

satpy.writers.available_writers(as_dict=False)[source]

Available writers based on current configuration.

Parameters: as_dict (bool) – Optionally return writer information as a dictionary. Default: False

Returns: List of available writer names. If as_dict is True then: a list of dictionaries including additionally writer information is returned.

satpy.writers.compute_writer_results(results)[source]

Compute all the given dask graphs results so that the files are saved.

Parameters: results (iterable) – Iterable of dask graphs resulting from calls to scn.save_datasets(…, compute=False)

satpy.writers.configs_for_writer(writer=None)[source]

Generate writer configuration files for one or more writers.

Parameters: writer (Optional[str]) – Yield configs only for this writer

Returns: Generator of lists of configuration files

satpy.writers.get_enhanced_image(dataset, enhance=None, overlay=None, decorate=None, fill_value=None)[source]

Get an enhanced version of dataset as an XRImage instance.

Parameters

dataset (xarray.DataArray) – Data to be enhanced and converted to an image.
enhance (bool or Enhancer) – Whether to automatically enhance data to be more visually useful and to fit inside the file format being saved to. By default, this will default to using the enhancement configuration files found using the default Enhancer class. This can be set to False so that no enhancments are performed. This can also be an instance of the Enhancer class if further custom enhancement is needed.
overlay (dict) – Options for image overlays. See add_overlay() for available options.
decorate (dict) – Options for decorating the image. See add_decorate() for available options.
fill_value (int or float) – Value to use when pixels are masked or invalid. Default of None means to create an alpha channel. See finalize() for more details. Only used when adding overlays or decorations. Otherwise it is up to the caller to “finalize” the image before using it except if calling img.show() or providing the image to a writer as these will finalize the image.

satpy.writers.group_results_by_output_file(sources, targets)[source]

Group results by output file.

For writers that return sources and targets for compute=False, split the results by output file.

When not only the data but also GeoTIFF tags are dask arrays, then save_datasets(..., compute=False)` returns a tuple of flat lists, where the second list consists of a mixture of RIOTag and RIODataset objects (from trollimage). In some cases, we may want to get a seperate delayed object for each file; for example, if we want to add a wrapper to do something with the file as soon as it’s finished. This function unflattens the flat lists into a list of (src, target) tuples.

For example, to close files as soon as computation is completed:

>>> @dask.delayed
>>> def closer(obj, targs):
...     for targ in targs:
...         targ.close()
...     return obj
>>> (srcs, targs) = sc.save_datasets(writer="ninjogeotiff", compute=False, **ninjo_tags)
>>> for (src, targ) in group_results_by_output_file(srcs, targs):
...     delayed_store = da.store(src, targ, compute=False)
...     wrapped_store = closer(delayed_store, targ)
...     wrapped.append(wrapped_store)
>>> compute_writer_results(wrapped)

In the wrapper you can do other useful tasks, such as writing a log message or moving files to a different directory.

Warning

Adding a callback may impact runtime and RAM. The pattern or cause is unclear. Tests with FCI data show that for resampling with high RAM use (from around 15 GB), runtime increases when a callback is added. Tests with ABI or low RAM consumption rather show a decrease in runtime. More information, see these GitHub comments Users who find out more are encouraged to contact the Satpy developers with clues.

Parameters

sources – List of sources (typically dask.array) as returned by Scene.save_datasets().
targets – List of targets (should be RIODataset or RIOTag) as returned by Scene.save_datasets().

Returns

List of Tuple(List[sources], List[targets]) with a length equal to the number of output files planned to be written by Scene.save_datasets().

satpy.writers.load_writer(writer, **writer_kwargs)[source]: Find and load writer writer in the available configuration files.

satpy.writers.load_writer_configs(writer_configs, **writer_kwargs)[source]: Load the writer from the provided writer_configs.

satpy.writers.read_writer_config(config_files, loader=<class 'yaml.loader.UnsafeLoader'>)[source]: Read the writer config_files and return the info extracted.

satpy.writers.show(dataset, **kwargs)[source]: Display the dataset as an image.

satpy.writers.split_results(results)[source]

Split results.

Get sources, targets and delayed objects to separate lists from a list of results collected from (multiple) writer(s).

satpy.writers.to_image(dataset)[source]

Convert dataset into a XRImage instance.

Convert the dataset into an instance of the XRImage class. This function makes no other changes. To get an enhanced image, possibly with overlays and decoration, see get_enhanced_image().

Parameters: dataset (xarray.DataArray) – Data to be converted to an image.
Returns: Instance of XRImage.