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

• AMSU: all satellites carrying it
• MHS: all satellites carrying it
• ATMS: all satellites carrying it
• AVHRR: NOAA 18, NOAA 19, METOP B, METOP C

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:

• The default (or specified in the satdump_cfg.json) calibration type, such as albedo, radiance or temperature
• The default (or specified in the satdump_cfg.json) range, for example for AVHRR channel 4 temperature, 0 equals to 232.2 K, 1 equals to 304.9 K.

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:

• Linux:
  • General config file: /usr/share/satdump/satdump_cfg.json
  • User config file: ~/.config/satdump/settings.json
• Windows:
  • General config file: C:\Program Files\SatDump\share\satdump\satdump_cfg.json
  • User config file: %appdata%\satdump\settings.json
• MacOS:
  • The general config file cannot be edited due to Apple restrictions.
  • User config file: ~/.config/satdump/settings.json

The basic syntax is as follows:

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

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.

• individual_equalize: histogram equalize each individual red, green, and blue component before combining them into an RGB output.
• equalize: combine red, green and blue components, then histogram equalize the result.
• white_balance: apply white balance to the result (useful for Meteor LRPT where black lines can sometimes mess up the equalization).
• median_blur: apply median blur (usually not needed).
• normalize: apply a normalising algorithm to the image.
• apply_lut: apply a LUT to the resulting RGB image. If only the red channel is specified, and all others are at zero, it will apply the LUT to the single channel as if it were a grayscale image.
• geo_correct: correct the output image to eliminate distortion caused by the Earth's curve.
• autogen: if set to false, it will prevent the autogeneration of this composite when SatDump processes the pipeline (so, the composite will only be available from the viewer).

Calibration parameters

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

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.

• type: selects the calibration type. Accepted values are radiance, albedo or temperature.
• min and max: select the range that is remapped from 0 to 1 in the viewer.

The units are Kelvin for temperature, W·sr⁻¹·m⁻² 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 :)

• width: the width of the resulting image (Not necessarily a power of 2!)
• height: the height of the resulting image (for best results it has to be half of the specified width).
• draw_map_overlay: if true, will draw a map overlay over the projection
• individual_equalize: see above (all the common parameters listed above can be used, independently from the ones specified in the section above - which are used in the viewer).
• type: selects the projection type:
  • mercator or equirectangular require no additional parameters.
  • azeq (azimuthial equidistant) requires lat and lon (latitude and longitude of the center point).
  • stereo requires lat, lon and scale (latitude, longitude of the center point, and zoom level (where 0.1 is a lot of zoom and 2 isn't). A value of 1 is good usually).
  • tpers requires alt, lat, lon, ang, azi (Altitude, Latitude, Longitude, Angle of observation, Azimuth).

Custom LUTs

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

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

• lut: the LUT file name and path relative to resources/
• channels: specified the 2 channels for the two dimensional LUT.

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

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