⭐ NEW: This tool has been featured in the 📺 first episode of the satellite-image-deep-learning podcast! ⭐

A PyTorch-based tool for simulating clouds in satellite images.

This tool allows for generating artificial clouds in an image using structural noise, such as Perlin noise; intended for applications where pairs of clear-sky and cloudy images are required or useful. For example, it can be used to generate training data for tasks such as cloud detection or cloud removal, or simply as a method of augmentation of satellite image data for other tasks.

The images must be in shape (channel, height, width) or (batch, channel, height, width) and are also returned in that format.

This tool is accompanied by the open access publication at https://www.mdpi.com/2072-4292/15/17/4138.

If you found this tool useful, please cite accordingly:

@Article{rs15174138,
  author = {Czerkawski, Mikolaj and Atkinson, Robert and Michie, Craig and Tachtatzis, Christos},
  title = {SatelliteCloudGenerator: Controllable Cloud and Shadow Synthesis for Multi-Spectral Optical Satellite Images},
  journal = {Remote Sensing},
  volume = {15},
  year = {2023},
  number = {17},
  article-number = {4138},
  url = {https://www.mdpi.com/2072-4292/15/17/4138},
  issn = {2072-4292},
  doi = {10.3390/rs15174138}
}

pip install git+https://github.com/strath-ai/SatelliteCloudGenerator

and then import:

import satellite_cloud_generator as scg

cloudy_img = scg.add_cloud_and_shadow(clear_img)

Basic usage, takes a clear image and returns a cloudy version along with a corresponding channel-specific transparency mask:

cloudy, mask = scg.add_cloud(clear,
                             min_lvl=0.0,
                             max_lvl=1.0
                         )

...resulting in the following:

The min_lvl and max_lvl control the range of values of the transparency mask.

You can also use a CloudGenerator object that binds a specific configuration (or a set of configurations) with the wrapped generation methods:

my_gen=scg.CloudGenerator(scg.WIDE_CONFIG,cloud_p=1.0,shadow_p=0.5)
my_gen(my_image) # will act just like add_cloud_and_shadow() but will preserve the same configuration!

Apart from synthesizing a random cloud, the tool provides several additional features (switched on by default) to make the appearance of the clouds more realistic, inspired by (Lee2019).

The cloud_color setting adjusts the color of the base added cloud based on the mean color of the clear ground image. (Disable by passing cloud_color=False)

Spatial offsets between individual cloud image channels can be achieved by setting channel_offset to a positive integer value. (Disable by passing channel_offset=0)

Blurring of the ground image based on the cloud thickness can be achieved by adjusting the blur_scaling parameter (with 0.0 disabling the effect). (Disable by passing blur_scaling=0)

⚠️ The blur operation significantly increases memory footprint (caused by the internal unfold operation).