EarthClouds1
============
:stem: latexmath
:source-highlighter: highlight.js

Keywords: clouds 

== Summary ==
This demo shows the use of the
http://www.dirsig.org/docs/new/earthmodels.html#FastClouds[FastClouds]
plugin that is an extension of the approach taken in the FastCloud2
demo to emulate clouds using a very simplified 2D representation.
That approach is generic and simply uses a material map (with mixing)
or a mixture map that is applied to a high altitude object (usually
a simple plate) and mixes free paths and opaque cloud reflectance.

The "FastClouds" plugin is meant to address the problem of effectively
defining very large, high altitude objects that might represent
clouds over many kilometers. Over a significant distance, we expect
a flat plate to deviate from a constant altitude due to the underlying
curvature of the Earth.  Instead, the plugin adapts to the WGS84
ellipsoids to maintain a constant altitude and generates a 2D
representation of clouds based on an input cloud fraction map.  The
plugin also gives the opportunity to add features (such as dynamics)
that might be difficult to represent with the generic approach.

The clouds being modeled by this plugin are intended to be generally
opaque (with some transmission at the edges) and as such are modeled
as varying between a nominal opaque cloud spectral reflectance and
a free path to the Earth.  They are also intended to be viewed from
a distance and well above the clouds themselves (given their two
dimensional nature). The input fraction map is used to describe the
amount of cloud versus the amount of transmitted radiance. A secondary
parameter allows a scaling of the fraction on the solar path (a
shadow path) to very approximately mimic multiple scattering
differences (i.e. effectively increase the amount of shadowing on
the solar path versus the amount of direct reflectance).

IMPORTANT: This plugin and demonstration are not intended to be accurate
           radiometric representations of clouds! They exist to be able
	   to efficiently add approximate cloud behavior over very
	   large areas where the focus is on 1) the shadowing of
	   the clouds on the ground and 2) the potential saturation
	   of the sensor by the high reflectance (scattering) of
	   the cloud itself. There is no attempt to capture water
	   droplet size distributions, self-shadowing, spectrally
	   varying directional scattering, or, of course, the
	   volumetric nature of clouds and their interactions.

== Related Materials ==
The following demos, manuals and tutorials can provide additional
information about the topics at the focus of this demo:

* Related Demos
** The
   http://www.dirsig.org/demos/index.html#FastCloud2[FastCloud2]
   demo.
* Related Manuals
** The http://www.dirsig.org/docs/new/earthmodels.html[Earth Models]
   manual  (both the Earth grid and fast clouds plugins).
* Related Tutorials
** N/A

== Details ==
The demonstration is constructed with two setups demonstrating different plugin options.

Both demonstrations use a simple RGB representation
of Denmark (roughly centered near the seaport of Kolding and derived
from cloudless Sentinel-2 imagery over a Copernicus DEM). Then, over the same extent, a
fraction map derived from the USGS Spatial Procedures for Automated
Removal of Cloud and Shadow (SPARCS) dataset is used to represent
the cloud cover. Note that the original cloud data was "quilted"
to create much larger coverage then edited to primarily show clouds
over landmasses.

The effective reflectance of the clouds is based on the nominal
opaque cloud reflectance curve shown here. It is stored internally
rather than being provided by the user.

.Spectral curve for the nominal cloud reflectance.
image::images/cloud_refl.png[width=512]

The first demo ("demo_basic.jsim") uses this fraction map to describe the cloud fully. The
cloud is either fully present (f=1, dc=255), fully absent (f=0, dc=0), or some mixing of those two values (i.e. a stocastic combination of paths to the ground or opaque cloud). This can lead to overly transmissive shadows for even relatively high fractions, so a correction factor ("shadow_correction", defaults to 2) is available to scale the amount of cloud for the solar paths. Alternatively, an explicit and secondary cloud scale map can be used to apply variations in reflectance to the map so that the fraction map can better handle opaque clouds.

The scaling approach is used in the second demo ("demo_advanced.jsim") along with a few other options. This time, rather than let the cloud map be stretched to the window size, the user provides and explicit pixel size (in degrees) in latitude and longitude. A window is still required (it dictates where clouds will appear), but now any remaining space in the window can be filled by "tiling" the original image(s). For the demo, a smaller, seamless image is used for both the cloud fraction map and the optional cloud scalar map. At the edged of the tile, the image is repeated (as is, without mirroring).

This tiling is especially useful for adding motion to the cloud map(s) using a wind source direction (i.e. the direction the wind is coming from, measured clockwise from North) and a windspeed (in m/s). The tiling is then used to fill in any areas that might have originally been covered by the map, but were left vacant after those clouds move away. 

More details about these options can be found https://dirsig.cis.rit.edu/docs/new/earthmodels.html#FastClouds[here].

== Important Files ==
This section highlights key files important to the simulation.

.Imagery of the Denmark region used for the scene and centered at approxiately 55.5 degrees North and 9.5 degrees East (Contains modified Copernicus Sentinel data [2024] processed by Sentinel Hub)
image::denmark.png[width=512]

.Cloud fraction map used for the basic scene derived from the SPARCS validation data set (https://www.usgs.gov/landsat-missions/spatial-procedures-automated-removal-cloud-and-shadow-sparcs-validation-data). Note that the map covers a much larger are than is present in the scene.
image::fraction_map.png[width=512]

.Cloud fraction map (tile) used for the advanced scene constructed from a portion of the SPARCS data set and the corresponding scale map.
[cols="a,a", frame=none, grid=none]
|===
|image::cloud_map.png[width=512]
|image::cloud_scale.png[width=512]
|===

=== The FastClouds Setup
The clouds are setup similarly to the Earth model type https://dirsig.cis.rit.edu/docs/new/earthmodels.html#EarthGird[plugins].
The time the fraction map (and optional scale map)
are provided as the input imagery and are defined over a
latitude/longitude box.

.The setup using the FastCloud plugin in the `demo_basic.jsim` file.
[source,json]
----
include::demo_basic.jsim[]
----

.The setup using the FastCloud plugin in the `demo_advanced.jsim` file.
[source,json]
----
include::demo_advanced.jsim[]
----


=== The Observing Sensor
The observing sensor in this simulation is a simple array setup
directly above the center of the Denmark scene either as an https://dirsig.cis.rit.edu/docs/new/orthoimage_plugin.html[orthograpic] camera or a traditional framing array.

.The BasicPlatform `demo.motion` setup stares at a geographic location at the center of the scenes.
[source,json]
----
include::demo.motion[]
----


=== The Atmosphere Setup
The atmospheric modeling setup in the "advanced" simulation uses the 
http://www.dirsig.org/docs/new/newatm_plugin.html#ClassicAtm[NewAtmosphere]
while the "basic" simulation uses the simplistic
http://www.dirsig.org/docs/new/basicatm_plugin.html#UniformAtm[UniformAtmosphere]
model.


== Simulations and Results ==
=== The Basic Single-Frame Simulation
The single-frame simulation (see `demo.jsim`) captures a single
image of a "zoomed-in" at the center of the scene. Since the clouds
currently require stochastic (noisy) mixing, a slightly higher
setting for convergence should be used than would be normal for the
same scene without the clouds.

----
$ dirsig5 --convergence=30,500,1.000e-06 demo_basic.jsim
----

Load the resulting `demo_basic.img` radiance file in the DIRSIG
image viewer and display the RGB bands using one of the high dynamic
range scaling options (e.g., "two sigma" or "two percent" scaling).
Alternatively, the `image_tool` can be used to directly to produce a 
min/max scaled PNG with the following syntax:

----
$ image_tool convert --bands=2,1,0 demo_basic.img
----

.The single-frame, basic simulation
image::images/demo_basic.png[]


=== The Advanced simulation
The advanced setup is designed to show a time-series of images over 50 seconds at 1 frame per second using the wind speed option and tiling. Those frames can be combined using a tool like https://www.ffmpeg.org/[ffmpeg] after the images are converted to RGB images.

.A longer (48s) video version of the advanced demo showing clouds moving in real time for the 13 m/s wind speed
video::images/demo_advanced.mp4[]

