Jacopo's Lair


If you need a quick reference on how to produce new composites for SatDump, you've come to the right place!

Basics

Selecting a single channel

chX where X is the number of the channel

Selecting a single calibrated channel

Only for these satellites and instruments

cchX where X is the number of the channel.

The output value will be in the range of 0 to 1. The value of 0 and 1 depends on two things:

For more information on calibration, see the Advanced section below.

Simple RGB composite

chR, chG, chB (normal)

cchR, cchG, cchB (calibrated)

Math

Any math operator is supported, such as +, -, /, *, cos(), sin(), ln(), ^ and more.

Example: ch1^2.5, ch2, ch3 (raises ch1 by a power of 2,5).

The acceptable value range for the output of each channel is 0 to 1 (see above for notes regarding calibration).

Inverting a channel is simple, just subtract 1: 1-ch4 will invert channel 4.

Ternary operators

You can use a ternary operator to select a result based on a condition.

Syntax: input condition ? true : false

Example: cch1 < 0.5 ? 1 : 0

Explanation: If cch1 is less than 0.5, output 1 (white). If not, output 0.

Ternary operators support these conditions: <, >, >=, <=, == (less than, greater than, greater or equal than, equal to)

Ternary operators can be nested, but the algorithm will quickly become quite cumbersome to read. I recommend to use Lua for more complex algorithms.

Alpha Channel (RGBA)

By adding a fourth parameter to a RGB equation, it is possible to specify an alpha channel (this is useful in combination with the ternary operator).

Syntax: chR, chG, chB, chA.

It can be used for monochrome composites that are meant to be used together with the LUT option. In that case, the G and B parameters are set to 0.

Example: cch1, cch2, cch3, cch4 > 0.5 ? 1 : 0

Explanation: Output a RGB image composed by cch1 (red), cch2 (green), cch3 (blue). If cch4 is greater than 0.5, the alpha channel is 1 (totally opaque). If not, it's 0 (totally transparent).

The typical use case would be blending of sounder and imager data, for example to show a rainfall map from MHS on AVHRR.

Advanced

The advanced part covers syntax in the satdump_cfg.json configuration file, found in SatDump's configuration directory. Also, these settings can be added in the user-specific configuration file called settings.json.

The user-specific settings.json has priority over satdump_cfg.json, therefore editing settings.json can override the default composites, without needing to edit the configuration file.

Beware that sometimes the default composites get updated, such as when SatDump is updated, therefore if you override them unexpected behavior can occur. If this happens, please rename the settings.json and test again, to isolate the issue.

The files can be found:

The basic syntax is as follows:

"Composite Name": { "equation": "cch1, cch2, cch3" }

Additional parameters can be added (mind the commas!):

"Composite Name": { "equation": "cch1, cch2, cch3", "individual_equalize": true }

Common parameters:

All these parameters are boolean and accept either a true or a false.

If omitted, they will be treated as false (for example, if you don't specify "equalize": true, the image will not be equalized). Forcefully setting these parameters to false is redundant.

Calibration parameters

By adding a calib_cfg block as follows, it is possible to select many parameters regarding calibration.

"Composite Name": { "equation": "cch1, cch2, cch3", "calib_cfg": { "cch1": { "type": "albedo", "min": 0, "max": 40 }, "cch2": { "type": "radiance", "min": 0.5, "max": 2.2 }, "cch3": { "type": "temperature", "min": 220, "max": 460 }, }

Specific configurations can be applied for each channel independently. If a calibrated channel is used, but a specific configuration is not set, the default will be used.

The units are Kelvin for temperature, W·sr−1·m−2 for radiance, and percentage (%) of albedo. (All standard SI units)

Tip: if you want to work with Kelvin directly in the equation, set min to 0 and max to 1000. Then, 273K will be 0.273 in the equation.

Projection

It is possible to customise and automate projections for each composite. Do not enable this parameter by default if you want to do a pull request, as it will result in many unnecessary files and takes quite a lot to process. Only add it in your settings.json for your own convenience :)

"Composite Name": { "equation": "cch1, cch2, cch3", "project": { "width": 4096, "height": 2048, "draw_map_overlay": true, "individual_equalize": true, "config": { "type": "mercator" } } }

Custom LUTs

A custom square PNG LUT can be specified. It has to be put in the resources/lut folder of SatDump.

"Composite Name": { "lut": "lut/LUT_FileName.png" "channels": "cch1, cch2", }

All of the common parameters such as individual_equalize can be used, although they won't affect the LUT (apart from geo_correct).

LUTs can be either grayscale or color and are usually 256x256 pixels in size.

BD monochrome

Color NO


If you need help, feel free to hit me up on SatDump's Matrix!